More work on user manuals

Documentation/Doxygen/doxystyle.css

@@ -312,6 +312,10 @@ div.fragment {
 	margin: 4px 8px 14px 2px;
 }
 
+blockquote {
+	margin-bottom: 1em;
+}
+
 #menuSegment {
     padding: 0;
     border-bottom: 5px solid #ffb028;

Documentation/Manuals/Native/User/guiElements.md

@@ -27,30 +27,185 @@ mainPanel->addElement(label);
 
 At this point our GUI element will be displayed.
 
-@ref TODO_IMAGE
+![Simple GUI](guiBasic.png) 
 
 # Customizing GUI elements
+All GUI elements share a common set of methods you can use to customize their position, size, color and other properties.
+
 ## Changing position
-// TODO
+You can change the position of a GUI element by calling @ref bs::GUIElement::setPosition "GUIElement::setPosition". The position is in pixels, relative to the top left corner of the render target.
+
+~~~~~~~~~~~~~{.cpp}
+// Moves the displayed text to coordinates (50, 50)
+label->setPosition(50, 50);
+~~~~~~~~~~~~~
 
 ## Changing size
-// TODO
+Element size can be changed by calling @ref bs::GUIElement::setSize "GUIElement::setSize".
+
+~~~~~~~~~~~~~{.cpp}
+// Make the label 30 pixels high, and 100 pixels wide
+label->setSize(100, 30);
+~~~~~~~~~~~~~
+
+You can also set both position and size at the same time by calling @ref bs::GUIElement::setBounds "GUIElement::setBounds".
+
+~~~~~~~~~~~~~{.cpp}
+// Make the label 30 pixels high, and 100 pixels wide, and position it at (50, 50)
+label->setBounds(Rect2I(50, 50, 100, 30));
+~~~~~~~~~~~~~
 
 ## Changing color
-// TODO
+You can change the tint of the GUI element with @ref bs::GUIElement::setTint "GUIElement::setTint". By default an all-white tint is used for all elements. 
+
+~~~~~~~~~~~~~{.cpp}
+// Make the label text green
+label->setTint(Color::Green);
+~~~~~~~~~~~~~
 
 ## Hiding
-// TODO (Both active and visible)
+You can temporarily hide an element with @ref bs::GUIElement::setVisible "GUIElement::setVisible". As the name implies hidden element will not be displayed, and cannot be interacted with.
+
+~~~~~~~~~~~~~{.cpp}
+// Hide the label
+label->setVisible(false);
+
+// Show the label
+label->setVisible(true);
+~~~~~~~~~~~~~
 
 # GUI element types
+Banshee provides a large library of existing GUI element types. We'll focus on explaining the most important ones, but you can find an exhaustive list in @ref GUI.
+
 ## Label
-// TODO
+A label is the most basic of GUI elements, that allows no user interaction and just displays a textual string. It is created with @ref bs::GUILabel::create "GUILabel::create", which accepts a string as input.
+
+~~~~~~~~~~~~~{.cpp}
+GUILabel* label = GUILabel::create(HString(L"Hello!"));
+mainPanel->addElement(label);
+~~~~~~~~~~~~~
+
+Once created you can optionally change the displayed text with @ref bs::GUILabel::setContent "GUILabel::setContent".
+
+~~~~~~~~~~~~~{.cpp}
+label->setContent(HString(L"New text!"));
+~~~~~~~~~~~~~
+
+> You can use *setContent* function on most GUI elements, so we won't mention it further for each individual element.
+
+![Label](guiLabel.png) 
+
+## Texture
+A texture is another basic GUI element that allows no interaction. All it does is display a **SpriteTexture** on the screen.
+
+To create a GUI texture element, call @ref bs::GUITexture::create "GUITexture::create" which accepts three parameters: 
+ - **SpriteTexture** - Determines which texture to draw.
+ - @ref bs::TextureScaleMode "TextureScaleMode" - Determines how to scale the texture in the available area.
+ - Transparency flag - Should transparency be enabled, allowing elements behind the texture to render.
 
+~~~~~~~~~~~~~{.cpp}
+// Create a sprite texture for use
+HTexture tex = gImporter().import<Texture>("BansheLogoRoundSmall.png");
+HSpriteTexture spriteTexture = SpriteTexture::create(tex);
+
+// Create the texture GUI element with our sprite texture and default scaling/transparency
+GUITexture* guiTexture = GUITexture::create(spriteTexture);
+
+// Position the texture
+guiTexture->setPosition(250, 90);
+guiTexture->setSize(150, 150);
+
+mainPanel->addElement(guiTexture);
+~~~~~~~~~~~~~ 
+ 
+![Texture](guiTexture.png) 
+ 
 ## Button
-// TODO
+A button GUI element displays a textural string or an image and reports events about user interaction with the button.
+
+GUI elements that can have either text or image contents (or both) accept a @ref bs::GUIContent "GUIContent" structure in their *create* and *setContent* functions. It is just a container and constructed simply:
+
+~~~~~~~~~~~~~{.cpp}
+// Contents containing only text
+GUIContent textContents(HString(L"Click me!"));
+
+// Contents containing only an image
+HTexture tex = gImporter().import<Texture>("BansheLogoRoundSmall.png");
+HSpriteTexture spriteTexture = SpriteTexture::create(tex);
+		
+GUIContent imageContents(spriteTexture);
+~~~~~~~~~~~~~
+
+To create a button, call @ref bs::GUIButton::create "GUIButton::create".
+~~~~~~~~~~~~~{.cpp}
+GUIButton* textButton = GUIButton::create(textContents);
+GUIButton* imageButton = GUIButton::create(imageContents);
+
+mainPanel->addElement(textButton);
+mainPanel->addElement(imageButton);
+~~~~~~~~~~~~~
+
+Once created, user can interact with the button by mousing over it or clicking on it. **GUIButton** provides a set of callbacks that notify the developer when user interacts with the button:
+ - @ref bs::GUIButton::onClick "GUIButton::onClick" - Triggers when the user clicks the button.
+ - @ref bs::GUIButton::onHover "GUIButton::onHover" - Triggers when the mouse cursor hovers over a button.
+ - @ref bs::GUIButton::onOut "GUIButton::onOut" - Triggers when the mouse cursor leaves the button area.
+ - @ref bs::GUIButton::onDoubleClick "GUIButton::onDoubleClick" - Triggers when the user clicks the button twice in a quick succession.
+ 
+~~~~~~~~~~~~~{.cpp}
+auto buttonClicked = []()
+{
+	gDebug().logDebug("Button clicked!");
+}
+
+// Print a message "Button clicked!" whenever user clicks the button
+imageButton->onClick.connect(buttonClicked);
+~~~~~~~~~~~~~
+
+![GUI buttons](guiButton.png) 
 
 ## Toggle
-// TODO
+Toggle buttons are very similar to normal buttons, with the main difference being that they remain in a toggled state after they have been pressed. Multiple toggle buttons can also be grouped so that only one of them can be toggled at a time. Other than that they share the same interface as **GUIButton**, so we'll focus only on the additional functionality.
+
+To create an individual toggle button call @ref bs::GUIToggle::create "GUIToggle::create".
+~~~~~~~~~~~~~{.cpp}
+GUIToggle* toggle = GUIButton::create(HString());
+
+mainPanel->addElement(toggle);
+~~~~~~~~~~~~~
+
+To create a set of toggle buttons call **GUIToggle::create** overload with the @ref bs::GUIToggleGroup "GUIToggleGroup" parameter. All toggles sharing the same toggle group will allow only one of the buttons to be active at a time. This allows you to create a "pick one out of many" element.
+
+To create a toggle group call @ref bs::GUIToggle::createToggleGroup "GUIToggle::createToggleGroup". After that just create the toggle elements as normal, and provide the group as a parameter.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<GUIToggleGroup> group = GUIToggle::createToggleGroup();
+
+GUIToggle* radio0 = GUIButton::create(HString(), group);
+GUIToggle* radio1 = GUIButton::create(HString(), group);
+GUIToggle* radio2 = GUIButton::create(HString(), group);
+
+mainPanel->addElement(radio0);
+mainPanel->addElement(radio1);
+mainPanel->addElement(radio2);
+~~~~~~~~~~~~~
+
+> Note that we aren't giving any textual labels to the toggle buttons. This is because their default style is a small box, in which we cannot fit any text. If you wish to add labels you need to either use a different style (discussed later), or use a separate **GUILabel** element next to the **GUIToggle** element.
+
+Once created you can subscribe to the @ref bs::GUIToggle::onToggled "GUIToggle::onToggled" event, as well as all previously mentioned **GUIButton** events. **GUIToggle::onToggled** triggers whenever the toggle state of the element changes.
+
+~~~~~~~~~~~~~{.cpp}
+auto elementToggled = [](bool toggled)
+{
+	if(toggled)
+		gDebug().logDebug("Toggled!");
+	else
+		gDebug().logDebug("Untoggled!");
+}
+
+toggle->onClick.connect(elementToggled);
+~~~~~~~~~~~~~
+
+![GUI toggle](guiToggle.png) 
 
 ## Input box
 // TODO
@@ -58,9 +213,6 @@ At this point our GUI element will be displayed.
 ## List box
 // TODO
 
-## Texture
-// TODO
-
 ## Slider
 // TODO
 

Documentation/Manuals/Native/User/guiSetup.md

@@ -19,6 +19,12 @@ HSceneObject guiSO = SceneObject::create("GUI");
 HGUIWidget gui = guiSO->addComponent<CGUIWidget>(camera);
 ~~~~~~~~~~~~~
 
+Before a widget is usable we must first assign it a **GUISkin**. A skin defines how is every element on this particular widget rendered (its texture(s), fonts, size, etc.). We'll talk about skins and styles in detail later, but for now it's enough to assign the built-in skin available from **BuiltinResources**.
+
+~~~~~~~~~~~~~{.cpp}
+gui->setSkin(BuiltinResources::instance().getGUISkin());
+~~~~~~~~~~~~~
+
 You can now use the GUI widget to add GUI elements to it
 ~~~~~~~~~~~~~{.cpp}
 // Shows the text "Hello!" on the screen

Documentation/Manuals/Native/User/spriteTextures.md

@@ -0,0 +1,39 @@
+Sprite textures									{#spriteTextures}
+===============
+
+Before we get started with GUI, let's first introduce the concept of sprite textures. They are very similar to normal textures, with the main difference being that they reference a specific sub-area on a **Texture**. This means multiple sprite textures can reference different parts of a single texture.
+
+They are used primarily by 2D elements, like GUI or sprites. Their primary purpose is to improve performance by ensuring 2D elements can be batched together when rendering, since all batched elements need to use the same underlying texture (also known as a texture atlas).
+
+They are represented with the @ref bs::SpriteTexture "SpriteTexture" class and are a **Resource**, same as normal textures. 
+
+They're created by calling @ref bs::SpriteTexture::create "SpriteTexture::create". As a parameter it expects the source **Texture**, and an optional set of UV coordinates that map to a specific area on the texture. If no coordinates are provided the sprite texture maps to the entirety of the texture, acting the same as a normal texture.
+
+UV coordinates begin in the top left corner, and are in range [0, 1], where top left is (0, 0), and bottom right (1, 1).
+
+~~~~~~~~~~~~~{.cpp}
+HTexture texture = gImporter().import<Texture>("myTexture.jpg");
+
+// Sprite texture covering the entire area of "texture"
+HSpriteTexture spriteTexComplete = SpriteTexture::create(texture);
+
+// Sprite texture covering the bottom right quadrant of the "texture"
+Vector2 offset(0.5f, 0.5f);
+Vector2 size(0.5f, 0.5f);
+HSpriteTexture spriteTexPartial = SpriteTexture::create(offset, size, texture)
+~~~~~~~~~~~~~
+
+Once created, you can get the actual width/height of the mapped area by calling @ref bs::SpriteTexture::getWidth "SpriteTexture::getWidth" and @ref bs::SpriteTexture::getHeight "SpriteTexture::getHeight".
+
+~~~~~~~~~~~~~{.cpp}
+// If our original texture was 1024x1024, this will be 512x512, since it's just a
+// single quadrant (quarter of the size)
+UINT32 width = spriteTexPartial->getWidth();
+UINT32 height = spriteTexPartial->getHeight();
+~~~~~~~~~~~~~
+
+You can also always retrieve the underlying texture by calling @ref bs::SpriteTexture::getTexture "SpriteTexture::getTexture".
+
+~~~~~~~~~~~~~{.cpp}
+HTexture texture = spriteTexPartial->getTexture();
+~~~~~~~~~~~~~

Documentation/Manuals/Native/manuals.md

@@ -31,6 +31,7 @@ Manuals									{#manuals}
  - [Input polling](@ref inputPolling) 
  - [Input events](@ref inputEvents)  
 - **GUI**
+ - [Sprite textures](@ref spriteTextures)
  - [Basic setup](@ref guiSetup)
  - [Elements](@ref guiElements)
  - [Layouts](@ref guiLayouts)

Source/BansheeEngine/Include/BsGUIButton.h

@@ -67,7 +67,7 @@ namespace bs
 		 */
 
 		/** @copydoc GUIElement::_getElementType */
-		virtual ElementType _getElementType() const override { return ElementType::Button; }
+		ElementType _getElementType() const override { return ElementType::Button; }
 
 		/** @} */
 	private:

Source/BansheeEngine/Include/BsGUIElementBase.h

@@ -69,6 +69,9 @@ namespace bs
 		/**	Sets element height in pixels. */
 		void setHeight(UINT32 height);
 
+		/** Sets width and height of a GUI element in pixels. */
+		void setSize(UINT32 width, UINT32 height);
+
 		/**
 		 * Sets element height in pixels. Element will be resized according to its contents and parent layout but will 
 		 * always stay within the provided range. If maximum height is zero, the element is allowed to expand as much as

Source/BansheeEngine/Include/BsGUIToggle.h

@@ -140,7 +140,7 @@ namespace bs
 		 */
 
 		/** @copydoc GUIButtonBase::_getElementType */
-		virtual ElementType _getElementType() const override { return ElementType::Toggle; }
+		ElementType _getElementType() const override { return ElementType::Toggle; }
 
 		/** Sets a toggle group of the toggle button. Toggling one button in a group will automatically untoggle others. */
 		void _setToggleGroup(SPtr<GUIToggleGroup> toggleGroup);
@@ -154,7 +154,7 @@ namespace bs
 			SPtr<GUIToggleGroup> toggleGroup, const GUIDimensions& dimensions);
 
 		/** @copydoc GUIButtonBase::_mouseEvent */
-		virtual bool _mouseEvent(const GUIMouseEvent& ev) override;
+		bool _mouseEvent(const GUIMouseEvent& ev) override;
 
 	protected:
 		SPtr<GUIToggleGroup> mToggleGroup;

Source/BansheeEngine/Source/BsGUIElementBase.cpp

@@ -62,6 +62,22 @@ namespace bs
 		_markLayoutAsDirty();
 	}
 
+	void GUIElementBase::setSize(UINT32 width, UINT32 height)
+	{
+		bool isFixedBefore = (mDimensions.flags & GUIDF_FixedWidth) != 0 && (mDimensions.flags & GUIDF_FixedHeight) != 0;
+
+		mDimensions.flags |= GUIDF_FixedWidth | GUIDF_OverWidth | GUIDF_FixedHeight | GUIDF_OverHeight;
+		mDimensions.minWidth = mDimensions.maxWidth = width;
+		mDimensions.minHeight = mDimensions.maxHeight = height;
+
+		bool isFixedAfter = (mDimensions.flags & GUIDF_FixedWidth) != 0 && (mDimensions.flags & GUIDF_FixedHeight) != 0;
+
+		if (isFixedBefore != isFixedAfter)
+			refreshChildUpdateParents();
+
+		_markLayoutAsDirty();
+	}
+
 	void GUIElementBase::setWidth(UINT32 width)
 	{
 		bool isFixedBefore = (mDimensions.flags & GUIDF_FixedWidth) != 0 && (mDimensions.flags & GUIDF_FixedHeight) != 0;