More documentation

BansheeEngine/Include/BsGUIButtonBase.h

@@ -9,75 +9,128 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Type of GUI button states.
+	 */
 	enum class GUIButtonState
 	{
-		Normal = 0x01,
-		Hover = 0x02,
-		Active = 0x04,
-		Focused = 0x08,
-		NormalOn = 0x11,
-		HoverOn = 0x12,
-		ActiveOn = 0x14,
-		FocusedOn = 0x18
+		Normal = 0x01, /**< Normal state when button is not being iteracted with. */
+		Hover = 0x02, /**< State when pointer is hovering over the button. */
+		Active = 0x04, /**< State when button is being clicked. */
+		Focused = 0x08, /**< State when button has been selected. */
+		NormalOn = 0x11, /**< Normal state when button is not being iteracted with and is in "on" state. */
+		HoverOn = 0x12, /**< State when pointer is hovering over the button and is in "on" state. */
+		ActiveOn = 0x14, /**< State when button is being clicked and is in "on" state. */
+		FocusedOn = 0x18 /**< State when button has been selected and is in "on" state. */
 	};
 
+	/**
+	 * @brief	Base class for a clickable GUI button element.
+	 */	
 	class BS_EXPORT GUIButtonBase : public GUIElement
 	{
 	public:
+		/**
+		 * @brief	Change content displayed by the button.
+		 */
 		void setContent(const GUIContent& content);
 
+		/**
+		 * @brief	Change the button "on" state. This state determines
+		 *			whether the button uses normal or "on" fields specified
+		 *			in the GUI style.
+		 */
 		void _setOn(bool on);
+
+		/**
+		 * @brief	Retrieves the button "on" state. This state determines
+		 *			whether the button uses normal or "on" fields specified
+		 *			in the GUI style.
+		 */
 		bool _isOn() const;
 
+		/**
+		 * @copydoc	GUIElement::_getOptimalSize
+		 */
 		virtual Vector2I _getOptimalSize() const;
 
+		/**
+		 * @brief	Triggered when button is clicked.
+		 */
 		Event<void()> onClick;
+
+		/**
+		 * @brief	Triggered when pointer hovers over the button.
+		 */
 		Event<void()> onHover;
+
+		/**
+		 * @brief	Triggered when pointer that was previously hovering leaves the button.
+		 */
 		Event<void()> onOut;
 	protected:
 		GUIButtonBase(const String& styleName, const GUIContent& content, const GUILayoutOptions& layoutOptions);
 		virtual ~GUIButtonBase();
 
 		/**
-		 * @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();
 
+		/**
+		 * @copydoc GUIElement::mouseEvent
+		 */
 		virtual bool mouseEvent(const GUIMouseEvent& ev);
 
+		/**
+		 * @copydoc GUIElement::_getRenderElementDepth
+		 */
 		virtual UINT32 _getRenderElementDepth(UINT32 renderElementIdx) const;
 
+		/**
+		 * @brief	Gets the text sprite descriptor used for creating/updating the internal text sprite.
+		 */
 		TEXT_SPRITE_DESC getTextDesc() const;
 
+		/**
+		 * @brief	Change the internal button state, changing the button look depending on set style.
+		 */
 		void setState(GUIButtonState state);
+
+		/**
+		 * @brief	Retrieves interal button state.
+		 */
 		GUIButtonState getState() const { return mActiveState; }
 
+		/**
+		 * @brief	Returns the active sprite texture, depending on the current state.
+		 */
 		const HSpriteTexture& getActiveTexture() const;
 	private:
 		ImageSprite* mImageSprite;

BansheeEngine/Include/BsGUICommandEvent.h

@@ -4,12 +4,19 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Type of valid command events.
+	 */
 	enum class GUICommandEventType
 	{
 		Redraw, FocusLost, FocusGained, MoveLeft, MoveRight, MoveUp, MoveDown, 
 		SelectLeft, SelectRight, SelectUp, SelectDown, Escape, Delete, Backspace, Return
 	};
 
+	/**
+	 * @brief	Holds data about a GUI command event. Command events are special events
+	 *			with a more specific purpose than general input events.
+	 */
 	class BS_EXPORT GUICommandEvent
 	{
 	public:
@@ -17,12 +24,18 @@ namespace BansheeEngine
 			:mType(GUICommandEventType::Redraw)
 		{ }
 
+		/**
+		 * @brief	Returns type describing what kind of event this is.
+		 */
 		GUICommandEventType getType() const { return mType; }
 	private:
 		friend class GUIManager;
 
-		GUICommandEventType mType;
-
+		/**
+		 * @brief	Sets type describing what kind of event this is.
+		 */
 		void setType(GUICommandEventType type) { mType = type; }
+
+		GUICommandEventType mType;
 	};
 }

BansheeEngine/Include/BsGUIContent.h

@@ -3,21 +3,61 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Holds data used for displaying content in a GUIElement. 
+	 *			Content can consist of a string, image, a tooltip or none of those.
+	 */
 	class BS_EXPORT GUIContent
 	{
 	public:
+		/**
+		 * @brief	Constructs an empty content.
+		 */
 		GUIContent();
+
+		/**
+		 * @brief	Constructs content with just a string.
+		 */
 		explicit GUIContent(const HString& text);
+
+		/**
+		 * @brief	Constructs content with a string and a tooltip.
+		 */
 		GUIContent(const HString& text, const HString& tooltip);
 
+		/**
+		 * @brief	Constructs content with just an image.
+		 */
 		explicit GUIContent(const HSpriteTexture& image);
+
+		/**
+		 * @brief	Constructs content with an image and a tooltip.
+		 */
 		GUIContent(const HSpriteTexture& image, const HString& tooltip);
 
+		/**
+		 * @brief	Constructs content with a string and an image.
+		 */
 		GUIContent(const HString& text, const HSpriteTexture& image);
+
+		/**
+		 * @brief	Constructs content with a string, an image and a tooltip.
+		 */
 		GUIContent(const HString& text, const HSpriteTexture& image, const HString& tooltip);
 
+		/**
+		 * @brief	Returns string content (if any).
+		 */
 		const HString& getText() const { return mText; }
+
+		/**
+		 * @brief	Returns image content (if any).
+		 */
 		const HSpriteTexture& getImage() const { return mImage; }
+
+		/**
+		 * @brief	Returns tooltip content (if any).
+		 */
 		const HString& getTooltip() const { return mTooltipText; }
 
 	private:

BansheeEngine/Include/BsGUIContextMenu.h

@@ -5,18 +5,36 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Manages display and logic for a context menu.
+	 *			Context menus can be opened anywhere within the GUI
+	 *			and can contain a hierarchy of menu items. 
+	 */
 	class BS_EXPORT GUIContextMenu : public GUIMenu
 	{
 	public:
 		GUIContextMenu();
 		~GUIContextMenu();
 
+		/**
+		 * @brief	Opens a context menu at the specified position relative
+		 *			to the provided widget.
+		 */
 		void open(const Vector2I& position, GUIWidget& widget);
 
 	private:
-		bool mContextMenuOpen;
-
+		/**
+		 * @brief	Closes the context menu if open.
+		 */
 		void close();
+
+		/**
+		 * @brief	Called when the context menu is closed externally
+		 *			(e.g. when user selects an item or clicks outside it).
+		 */
 		void onMenuClosed();
+
+	private:
+		bool mContextMenuOpen;
 	};
 }

BansheeEngine/Include/BsGUIDropDownBox.h

@@ -7,12 +7,18 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains items used for initializing one level in a drop down box hierarchy.
+	 */
 	struct BS_EXPORT GUIDropDownData
 	{
 		Vector<GUIDropDownDataEntry> entries;
 		UnorderedMap<WString, HString> localizedNames;
 	};
 
+	/**
+	 * @brief	Represents a single entry in a drop down box.
+	 */
 	class BS_EXPORT GUIDropDownDataEntry
 	{
 		enum class Type
@@ -23,15 +29,46 @@ namespace BansheeEngine
 		};
 
 	public:
+		/**
+		 * @brief	Creates a new separator entry.
+		 */
 		static GUIDropDownDataEntry separator();
+
+		/**
+		 * @brief	Creates a new button entry with the specified callback that is triggered
+		 *			when button is selected.
+		 */
 		static GUIDropDownDataEntry button(const WString& label, std::function<void()> callback);
+
+		/**
+		 * @brief	Creates a new sub-menu entry that will open the provided drop down data
+		 *			sub-menu when activated.
+		 */
 		static GUIDropDownDataEntry subMenu(const WString& label, const GUIDropDownData& data);
 
+		/**
+		 * @brief	Check is the entry a separator.
+		 */
 		bool isSeparator() const { return mType == Type::Separator; }
+
+		/**
+		 * @brief	Check is the entry a sub menu.
+		 */
 		bool isSubMenu() const { return mType == Type::SubMenu; }
 
+		/**
+		 * @brief	Returns display label of the entry (if an entry is a button or a sub-menu).
+		 */
 		const WString& getLabel() const { return mLabel; }
+
+		/**
+		 * @brief	Returns a button callback if the entry (if an entry is a button).
+		 */
 		std::function<void()> getCallback() const { return mCallback; }
+
+		/**
+		 * @brief	Returns sub-menu data that is used for creating a sub-menu (if an entry is a sub-menu).
+		 */
 		const GUIDropDownData& getSubMenuData() const { return mChildData; }
 	private:
 		GUIDropDownDataEntry() { }
@@ -43,7 +80,7 @@ namespace BansheeEngine
 	};
 
 	/**
-	 * @brief	Determines how will the drop down box be placed. Usually the system will attempt to position
+	 * @brief	Determines how will the drop down box be positioned. Usually the system will attempt to position
 	 * 			the drop box in a way so all elements can fit, and this class allows you to specify some limitations
 	 * 			on how that works. 
 	 * 			
@@ -53,6 +90,9 @@ namespace BansheeEngine
 	class BS_EXPORT GUIDropDownAreaPlacement
 	{
 	public:
+		/**
+		 * @brief	Determines how will the drop down box be positioned.
+		 */
 		enum class Type
 		{
 			Position,
@@ -81,8 +121,21 @@ namespace BansheeEngine
 		 */
 		static GUIDropDownAreaPlacement aroundBoundsHorz(const RectI& bounds);
 
+		/**
+		 * @brief	Returns drop down box positioning type.
+		 */
 		Type getType() const { return mType; }
+
+		/**
+		 * @brief	Returns bounds around which to position the drop down box
+		 *			if one of the bounds positioning types is used.
+		 */
 		const RectI& getBounds() const { return mBounds; }
+
+		/**
+		 * @brief	Returns position around which to position the drop down box
+		 *			if position positioning type is used.
+		 */
 		const Vector2I& getPosition() const { return mPosition; }
 
 	private:
@@ -93,6 +146,9 @@ namespace BansheeEngine
 		Vector2I mPosition;
 	};
 
+	/**
+	 * @brief	Type of drop down box types.
+	 */
 	enum class GUIDropDownType
 	{
 		ListBox,
@@ -107,13 +163,89 @@ namespace BansheeEngine
 	class BS_EXPORT GUIDropDownBox : public GUIWidget
 	{
 	public:
+		/**
+		 * @brief	Creates a new drop down box widget.
+		 *
+		 * @param	parent			Parent scene object to attach the drop down box to.
+		 * @param	target			Viewport on which to open the drop down box.
+		 * @param	placement		Determines how is the drop down box positioned in the visible area.
+		 * @param	dropDownData	Data to use for initializing menu items of the drop down box.
+		 * @param	skin			Skin to use for drop down box GUI elements.
+		 * @param	type			Specific type of drop down box to display.
+		 */
 		GUIDropDownBox(const HSceneObject& parent, Viewport* target, const GUIDropDownAreaPlacement& placement,
 			const GUIDropDownData& dropDownData, const GUISkin& skin, GUIDropDownType type);
 		~GUIDropDownBox();
 
 	private:
+		/**
+		 * @brief	Contains data about a single drop down box sub-menu
+		 */
 		struct DropDownSubMenu
 		{
+		public:
+			/**
+			 * @brief	Creates a new drop down box sub-menu
+			 *
+			 * @param	owner			Owner drop down box this sub menu belongs to.
+			 * @param	placement		Determines how is the sub-menu positioned in the visible area.
+			 * @param	availableBounds	Available bounds (in pixels) in which the sub-menu may be opened.
+			 * @param	dropDownData	Data to use for initializing menu items of the sub-menu.
+			 * @param	skin			Skin to use for sub-menu GUI elements.
+			 * @param	depthOffset		How much to offset the sub-menu depth. We want deeper levels of the
+			 *							sub-menu hierarchy to be in front of lower levels, so you should
+			 *							increase this value for each level of the sub-menu hierarchy.
+			 */
+			DropDownSubMenu(GUIDropDownBox* owner, const GUIDropDownAreaPlacement& placement, 
+				const RectI& availableBounds, const GUIDropDownData& dropDownData, GUIDropDownType type, UINT32 depthOffset);
+			~DropDownSubMenu();
+
+			/**
+			 * @brief	Recreates all internal GUI elements for the entries of the current sub-menu page.
+			 */
+			void updateGUIElements();
+
+			/**
+			 * @brief	Moves the sub-menu to the previous page and displays its elements, if available.
+			 */
+			void scrollDown();
+
+			/**
+			 * @brief	Moves the sub-menu to the next page and displays its elements, if available.
+			 */
+			void scrollUp();
+
+			/**
+			 * @brief	Returns height of a menu element at the specified index, in pixels.
+			 */
+			UINT32 getElementHeight(UINT32 idx) const;
+
+			/**
+			 * @brief	Called when the user clicks an element with the specified index.
+			 */
+			void elementClicked(UINT32 idx);
+
+			/**
+			 * @brief	Called when the user wants to open a sub-menu with the specified index.
+			 */
+			void openSubMenu(GUIButton* source, UINT32 elementIdx);
+
+			/**
+			 * @brief	Called when the user wants to close the currently open sub-menu.
+			 */
+			void closeSubMenu();
+
+			/**
+			 * @brief	Returns actual visible bounds of the sub-menu.
+			 */
+			RectI getVisibleBounds() const { return mVisibleBounds; }
+
+			/**
+			 * @brief	Get localized name of a menu item element with the specified index.
+			 */
+			HString getElementLocalizedName(UINT32 idx) const;
+
+		public:
 			GUIDropDownBox* mOwner;
 
 			GUIDropDownType mType;
@@ -138,27 +270,25 @@ namespace BansheeEngine
 			GUILayout* mContentLayout;
 
 			DropDownSubMenu* mSubMenu;
+		};
 
-			DropDownSubMenu(GUIDropDownBox* owner, const GUIDropDownAreaPlacement& placement, 
-				const RectI& availableBounds, const GUIDropDownData& dropDownData, GUIDropDownType type, UINT32 depthOffset);
-			~DropDownSubMenu();
-
-			void updateGUIElements();
-
-			void scrollDown();
-			void scrollUp();
-
-			UINT32 getElementHeight(UINT32 idx) const;
-
-			void elementClicked(UINT32 idx);
-			void openSubMenu(GUIButton* source, UINT32 elementIdx);
-			void closeSubMenu();
+	private:
+		/**
+		 * @brief	Called when the specified sub-menu is opened.
+		 */
+		void notifySubMenuOpened(DropDownSubMenu* subMenu);
 
-			RectI getVisibleBounds() const { return mVisibleBounds; }
+		/**
+		 * @brief	Called when the specified sub-menu is opened.
+		 */
+		void notifySubMenuClosed(DropDownSubMenu* subMenu);
 
-			HString getElementLocalizedName(UINT32 idx) const;
-		};
+		/**
+		 * @brief	Called when the drop down box loses focus (and should be closed).
+		 */
+		void dropDownFocusLost();
 
+	private:
 		static const UINT32 DROP_DOWN_BOX_WIDTH;
 
 		String mScrollUpStyle;
@@ -179,9 +309,5 @@ namespace BansheeEngine
 
 		UnorderedMap<WString, HString> mLocalizedEntryNames;
 
-		void notifySubMenuOpened(DropDownSubMenu* subMenu);
-		void notifySubMenuClosed(DropDownSubMenu* subMenu);
-
-		void dropDownFocusLost();
 	};
 }