More documentation

BansheeEngine/Include/BsGUILabel.h

@@ -7,61 +7,115 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	GUI element that displays text and optionally a content image.
+	 */
 	class BS_EXPORT GUILabel : public GUIElement
 	{
 	public:
+		/**
+		 * Returns type name of the GUI element used for finding GUI element styles. 
+		 */
 		static const String& getGUITypeName();
 
+		/**
+		 * Creates a new label with the specified text.
+		 *
+		 * @param	text			Text to display.
+		 * @param	styleName		Optional style to use for the element. Style will be retrieved
+		 *							from GUISkin of the GUIWidget the element is used on. If not specified
+		 *							default button style is used.
+		 */
 		static GUILabel* create(const HString& text, const String& styleName = StringUtil::BLANK);
+
+		/**
+		 * Creates a new label with the specified text.
+		 *
+		 * @param	text			Text to display.
+		 * @param	layoutOptions	Options that allows you to control how is the element positioned in
+		 *							GUI layout. This will override any similar options set by style.
+		 * @param	styleName		Optional style to use for the element. Style will be retrieved
+		 *							from GUISkin of the GUIWidget the element is used on. If not specified
+		 *							default button style is used.
+		 */
 		static GUILabel* create(const HString& text, const GUIOptions& layoutOptions, const String& styleName = StringUtil::BLANK);
 
+		/**
+		 * Creates a new label with the specified content (text + optional image).
+		 *
+		 * @param	text			Content to display.
+		 * @param	styleName		Optional style to use for the element. Style will be retrieved
+		 *							from GUISkin of the GUIWidget the element is used on. If not specified
+		 *							default button style is used.
+		 */
 		static GUILabel* create(const GUIContent& content, const String& styleName = StringUtil::BLANK);
+
+		/**
+		 * Creates a new label with the specified content (text + optional image).
+		 *
+		 * @param	text			Content to display.
+		 * @param	layoutOptions	Options that allows you to control how is the element positioned in
+		 *							GUI layout. This will override any similar options set by style.
+		 * @param	styleName		Optional style to use for the element. Style will be retrieved
+		 *							from GUISkin of the GUIWidget the element is used on. If not specified
+		 *							default button style is used.
+		 */
 		static GUILabel* create(const GUIContent& content, const GUIOptions& layoutOptions, const String& styleName = StringUtil::BLANK);
 
+		/**
+		 * Changes the active content of the label.
+		 */
 		void setContent(const GUIContent& content);
 
+		/**
+		 * @copydoc	GUIElement::_getOptimalSize
+		 */
 		virtual Vector2I _getOptimalSize() const;
+
+		/**
+		 * @copydoc	GUIElement::getElementType
+		 */
 		virtual ElementType getElementType() const { return ElementType::Label; }
 	protected:
 		~GUILabel();
 
 		/**
-		 * @copydoc GUIElement::getNumRenderElements()
+		 * @copydoc GUIElement::getNumRenderElements
 		 */
 		virtual UINT32 getNumRenderElements() const;
 
 		/**
-		 * @copydoc GUIElement::getMaterial()
+		 * @copydoc GUIElement::getMaterial
 		 */
 		virtual const GUIMaterialInfo& getMaterial(UINT32 renderElementIdx) const;
 
 		/**
-		 * @copydoc GUIElement::getNumQuads()
+		 * @copydoc GUIElement::getNumQuads
 		 */
 		virtual UINT32 getNumQuads(UINT32 renderElementIdx) const;
 
 		/**
-		 * @copydoc GUIElement::fillBuffer()
+		 * @copydoc GUIElement::fillBuffer
 		 */
 		virtual void fillBuffer(UINT8* vertices, UINT8* uv, UINT32* indices, UINT32 startingQuad, 
 			UINT32 maxNumQuads, UINT32 vertexStride, UINT32 indexStride, UINT32 renderElementIdx) const;
 
 		/**
-		 * @copydoc GUIElement::updateRenderElementsInternal()
+		 * @copydoc GUIElement::updateRenderElementsInternal
 		 */
 		virtual void updateRenderElementsInternal();
 
 		/**
-		 * @copydoc GUIElement::updateBounds()
+		 * @copydoc GUIElement::updateBounds
 		 */
 		virtual void updateClippedBounds();
 	private:
+		GUILabel(const String& styleName, const GUIContent& content, const GUILayoutOptions& layoutOptions);
+
 		TextSprite* mTextSprite;
 		GUIContent mContent;
 		HEvent mLocStringUpdatedConn;
 
 		TEXT_SPRITE_DESC mDesc;
-		
-		GUILabel(const String& styleName, const GUIContent& content, const GUILayoutOptions& layoutOptions);
 	};
 }

BansheeEngine/Include/BsGUILayout.h

@@ -6,39 +6,117 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Base class for layout GUI element. Layout element positions and sizes
+	 *			any child elements according to element styles and layout options.
+	 */
 	class BS_EXPORT GUILayout : public GUIElementBase
 	{
 	public:
 		GUILayout();
 		virtual ~GUILayout();
 
+		/**
+		 * @brief	Adds a new element to the layout after all existing elements.
+		 */
 		void addElement(GUIElement* element);
+
+		/**
+		 * @brief	Removes the specified element from the layout.
+		 */
 		void removeElement(GUIElement* element);
+
+		/**
+		 * @brief	Inserts a GUI element before the element at the specified index.
+		 */
 		void insertElement(UINT32 idx, GUIElement* element);
 
+		/**
+		 * @brief	Adds a new horizontal layout as a child of this layout.
+		 */
 		GUILayout& addLayoutX() { return addLayoutXInternal(this); }
+
+		/**
+		 * @brief	Adds a new vertical layout as a child of this layout.
+		 */
 		GUILayout& addLayoutY() { return addLayoutYInternal(this); }
+
+		/**
+		 * @brief	Removes the specified child layout.
+		 */
 		void removeLayout(GUILayout& layout) { removeLayoutInternal(layout); }
+
+		/**
+		 * @brief	Inserts a horizontal layout before the element at the specified index.
+		 */
 		GUILayout& insertLayoutX(UINT32 idx) { return insertLayoutXInternal(this, idx); }
+
+		/**
+		 * @brief	Inserts a vertical layout before the element at the specified index.
+		 */
 		GUILayout& insertLayoutY(UINT32 idx) { return insertLayoutYInternal(this, idx); }
 
+		/**
+		 * @brief	Adds a fixed space as a child of this layout. Size of space is specified in pixels.
+		 */
 		GUIFixedSpace& addSpace(UINT32 size);
+
+		/**
+		 * @brief	Removes an existing space from the layout.
+		 */
 		void removeSpace(GUIFixedSpace& space);
+
+		/**
+		 * @brief	Inserts a fixed space of "size" pixels before the element at the specified index.
+		 */
 		GUIFixedSpace& insertSpace(UINT32 idx, UINT32 size);
 
+		/**
+		 * @brief	Adds a flexible space as a child of this layout. Flexible space will grow/shrink
+		 *			depending on elements around it, but it will always allow elements to keep their
+		 *			optimal size.
+		 */
 		GUIFlexibleSpace& addFlexibleSpace();
+
+		/**
+		 * @brief	Removes an existing flexible space from the layout.
+		 */
 		void removeFlexibleSpace(GUIFlexibleSpace& space);
+
+		/**
+		 * @brief	Inserts a flexible space before an element at the specified index. Flexible space 
+		 *			will grow/shrink depending on elements around it, but it will always allow elements 
+		 *			to keep their optimal size.
+		 */
 		GUIFlexibleSpace& insertFlexibleSpace(UINT32 idx);
 
+		/**
+		 * @brief	Returns number of child elements in the layout.
+		 */
 		UINT32 getNumChildren() const { return (UINT32)mChildren.size(); }
+
+		/**
+		 * @brief	Removes a child element at the specified index.
+		 */
 		void removeChildAt(UINT32 idx);
 
+		/**
+		 * @copydoc	GUIElementBase::_getOptimalSize
+		 */
 		Vector2I _getOptimalSize() const { return Vector2I(mOptimalWidth, mOptimalHeight); }
+
+		/**
+		 * @copydoc	GUIElementBase::_getPadding
+		 */
 		const RectOffset& _getPadding() const;
+
+		/**
+		 * @copydoc	GUIElementBase::_getType
+		 */
 		Type _getType() const { return GUIElementBase::Type::Layout; }
 
 		/**
-		 * @brief	Gets an actual width of all the child elements in the layout.
+		 * @brief	Gets an actual width (in pixels) of all the child elements in the layout.
 		 *
 		 * @note	updateLayoutInternal must be called whenever layout or its children change,
 		 * 			otherwise this method will return an incorrect value.
@@ -48,7 +126,7 @@ namespace BansheeEngine
 		UINT32 _getActualWidth() const { return mActualWidth; }
 
 		/**
-		 * @brief	Gets an actual height of all the child elements in the layout.
+		 * @brief	Gets an actual height (in pixels) of all the child elements in the layout.
 		 *
 		 * @note	updateLayoutInternal must be called whenever layout or its children change,
 		 * 			otherwise this method will return an incorrect value.

BansheeEngine/Include/BsGUILayoutOptions.h

@@ -9,11 +9,22 @@ namespace BansheeEngine
 	 */
 	struct BS_EXPORT GUILayoutOptions
 	{
+		/**
+		 * @brief	Creates new default layout options.
+		 */
 		static GUILayoutOptions create();
+
+		/**
+		 * @brief	Creates layout options with user defined options.
+		 */
 		static GUILayoutOptions create(const GUIOptions& options);
 
 		GUILayoutOptions();
 
+		/**
+		 * @brief	Updates layout options from the provided style. If user has not manually
+		 *			set a specific layout property, that property will be inherited from style.
+		 */
 		void updateWithStyle(const GUIElementStyle* style);
 
 		UINT32 width, height;

BansheeEngine/Include/BsGUILayoutX.h

@@ -5,14 +5,32 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Represents a horizontal layout that will layout out its child elements
+	 *			left to right.
+	 */
 	class BS_EXPORT GUILayoutX : public GUILayout
 	{
 	public:
 		GUILayoutX() {};
 		~GUILayoutX() {};
 
+		/**
+		 * @brief	Calculate optimal sizes of all child layout elements.
+		 */
 		void _updateOptimalLayoutSizes();
 	protected:
+		/**
+		 * @brief	Positions/size all child layout elements based on the provided settings and their (previously calculated) optimal sizes.
+		 *
+		 * @brief	x			Start X coordinate of the layout area. First element will be placed here. Relative to parent widget.
+		 * @brief	y			Start Y coordinate of the layout area. First element will be placed here. Relative to parent widget.
+		 * @brief	width		Maximum width of the layout in pixels. Elements will be optimized so they best fit within this width if possible.
+		 * @brief	height		Maximum height of the layout in pixels. Elements will be optimized so they best fit within this height if possible.
+		 * @brief	clipRect	Rectagle to clip all child elements to. Relative to parent widget. Usually equal to specified x, y, width, height parameters.
+		 * @brief	widgetDepth	Depth of the parent widget. Determines depth at which child elements will be placed on. Takes priority over any other depth.
+		 * @brief	areaDepth	Depth of the parent area. Determines depth at which child elements will be placed on. Takes priority over element-specific depth.
+		 */
 		void _updateLayoutInternal(INT32 x, INT32 y, UINT32 width, UINT32 height, RectI clipRect, UINT8 widgetDepth, UINT16 areaDepth);
 	};
 }

BansheeEngine/Include/BsGUILayoutY.h

@@ -5,14 +5,32 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Represents a vertical layout that will layout out its child elements
+	 *			top to bottom.
+	 */
 	class BS_EXPORT GUILayoutY : public GUILayout
 	{
 	public:
 		GUILayoutY() {};
 		~GUILayoutY() {};
 
+		/**
+		 * @brief	Calculate optimal sizes of all child layout elements.
+		 */
 		void _updateOptimalLayoutSizes();
 	protected:
+		/**
+		 * @brief	Positions/size all child layout elements based on the provided settings and their (previously calculated) optimal sizes.
+		 *
+		 * @brief	x			Start X coordinate of the layout area. First element will be placed here. Relative to parent widget.
+		 * @brief	y			Start Y coordinate of the layout area. First element will be placed here. Relative to parent widget.
+		 * @brief	width		Maximum width of the layout in pixels. Elements will be optimized so they best fit within this width if possible.
+		 * @brief	height		Maximum height of the layout in pixels. Elements will be optimized so they best fit within this height if possible.
+		 * @brief	clipRect	Rectagle to clip all child elements to. Relative to parent widget. Usually equal to specified x, y, width, height parameters.
+		 * @brief	widgetDepth	Depth of the parent widget. Determines depth at which child elements will be placed on. Takes priority over any other depth.
+		 * @brief	areaDepth	Depth of the parent area. Determines depth at which child elements will be placed on. Takes priority over element-specific depth.
+		 */
 		void _updateLayoutInternal(INT32 x, INT32 y, UINT32 width, UINT32 height, RectI clipRect, UINT8 widgetDepth, UINT16 areaDepth);
 	};
 }