More documentation

BansheeEngine/Include/BsGUIElement.h

@@ -185,29 +185,34 @@ namespace BansheeEngine
 		/**
 		 * @brief	Sets a clip rectangle that GUI element sprite will be clipped to. 
 		 *			Rectangle is in local coordinates. (Relative to GUIElement position)
+		 *
+		 * @note	Internal method.
 		 */
 		void _setClipRect(const RectI& clipRect);
 
 		/**
-		 * @brief	Changes the active GUI element widget. This allows you to move an element
-		 *			to a different viewport, or change element style by using a widget with a different skin.
-		 *			You are allowed to pass null here, but elements with no parent will be unmanaged. You will be
-		 *			responsible for deleting them manually, and they will not render anywhere.
+		 * @copydoc	GUIElementBase::_changeParentWidget
 		 */
 		virtual void _changeParentWidget(GUIWidget* widget);
 
 		/**
 		 * @brief	Returns width of the element in pixels.
+		 *
+		 * @note	Internal method.
 		 */
 		UINT32 _getWidth() const { return mWidth; }
 
 		/**
 		 * @brief	Returns height of the element in pixels.
+		 *
+		 * @note	Internal method.
 		 */
 		UINT32 _getHeight() const { return mHeight; }
 
 		/**
 		 * @brief	Returns position of the element, relative to parent GUI widget origin.
+		 *
+		 * @note	Internal method.
 		 */
 		Vector2I _getOffset() const { return mOffset; }
 
@@ -215,6 +220,8 @@ namespace BansheeEngine
 		 * @brief	Returns depth for a specific render element. This contains a combination
 		 *			of widget depth (8 bit(, area depth (16 bit) and render element depth (8 bit)
 		 *
+		 * @note	Internal method.
+		 *
 		 * @see		getNumRenderElements
 		 */
 		virtual UINT32 _getRenderElementDepth(UINT32 renderElementIdx) const { return _getDepth(); }
@@ -222,82 +229,112 @@ namespace BansheeEngine
 		/**
 		 * @brief	Gets internal element style representing the exact type of GUI element
 		 *			in this object.
+		 *
+		 * @note	Internal method.
 		 */
 		Type _getType() const { return GUIElementBase::Type::Element; }
 
 		/**
 		 * @brief	Checks if element has been destroyed and is queued for deletion.
+		 *
+		 * @note	Internal method.
 		 */
 		bool _isDestroyed() const { return mIsDestroyed; }
 
 		/**
 		 * @brief	Update element style based on active GUI skin and style name.
+		 *
+		 * @note	Internal method.
 		 */
 		void _refreshStyle();
 
 		/**
 		 * @brief	Gets the currently active element style.
+		 *
+		 * @note	Internal method.
 		 */
 		const GUIElementStyle* _getStyle() const { return mStyle; }
 
 		/**
 		 * @brief	Gets GUI element bounds relative to parent widget, clipped by specified clip rect.
+		 *
+		 * @note	Internal method.
 		 */
 		const RectI& _getClippedBounds() const { return mClippedBounds; }
 
 		/**
 		 * @brief	Returns clip rect used for clipping the GUI element and related sprites
 		 *			to a specific region. Clip rect is relative to GUI element origin.
+		 *
+		 * @note	Internal method.
 		 */
 		const RectI& _getClipRect() const { return mClipRect; }
 
 		/**
 		 * @brief	Returns GUI element padding. Padding is modified by changing element style and determines
 		 *			minimum distance between different GUI elements.
+		 *
+		 * @note	Internal method.
 		 */
 		const RectOffset& _getPadding() const;
 
 		/**
 		 * @brief	Returns GUI element depth. This includes widget and area depth, but does not
 		 *			include specific per-render-element depth.
+		 *
+		 * @note	Internal method.
 		 */
 		UINT32 _getDepth() const { return mDepth; }
 
 		/**
 		 * @brief	Checks is the specified position within GUI element bounds. Position is relative to
 		 *			parent GUI widget.
+		 *
+		 * @note	Internal method.
 		 */
 		virtual bool _isInBounds(const Vector2I position) const;
 
 		/**
 		 * @brief	Checks if the GUI element has a custom cursor and outputs the cursor type if it does.
+		 *
+		 * @note	Internal method.
 		 */
 		virtual bool _hasCustomCursor(const Vector2I position, CursorType& type) const { return false; }
 
 		/**
 		 * @brief	Checks if the GUI element accepts a drag and drop operation of the specified type.
+		 *
+		 * @note	Internal method.
 		 */
 		virtual bool _acceptDragAndDrop(const Vector2I position, UINT32 typeId) const { return false; }
 
 		/**
 		 * @brief	Returns a context menu if a GUI element has one. Otherwise returns nullptr.
+		 *
+		 * @note	Internal method.
 		 */
 		virtual GUIContextMenu* getContextMenu() const { return nullptr; }
 
 		/**
 		 * @brief	Returns a clip rectangle relative to the element, used for offsetting
 		 * 			the input text.
+		 *
+		 * @note	Internal method.
 		 */
 		virtual Vector2I _getTextInputOffset() const { return Vector2I(); }
 
 		/**
 		 * @brief	Returns a clip rectangle relative to the element, used for clipping
 		 * 			the input text.
+		 *
+		 * @note	Internal method.
 		 */
 		virtual RectI _getTextInputRect() const { return RectI(); }
 
 		/**
 		 * @brief	Returns layout options that determine how is the element positioned within a GUILayout.
+		 *
+		 * @note	Internal method.
 		 */
 		const GUILayoutOptions& _getLayoutOptions() const { return mLayoutOptions; }
 	protected:

BansheeEngine/Include/BsGUIElementBase.h

@@ -9,9 +9,15 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Base class for all GUI elements (visible or layout).
+	 */
 	class BS_EXPORT GUIElementBase
 	{
 	public:
+		/**
+		 * @brief	Valid types of GUI base elements.
+		 */
 		enum class Type
 		{
 			Layout,
@@ -39,31 +45,132 @@ namespace BansheeEngine
 		/************************************************************************/
 
 		/**
-		 * @brief	Re-arranges the elements to fit the layout. (Internal use only)
+		 * @brief	Updates child elements positions, sizes, clip rectanges and depths so they
+		 *			fit into the provided bounds, while respecting their layout options. 
+		 *
+		 * @param	x			X position of the area to start laying out the elements. Relative to parent widget.
+		 * @param	y			Y position of the area to start laying out the elements. Relative to parent widget.
+		 * @param	width		Width of the area to lay out the elements, in pixels.
+		 * @param	height		Height of the area to lay out the elements, in pixels.
+		 * @param	clipRect	Rectangle to use for clipping of GUI elements. Any element outside of this rectangle will have its
+		 *						visible geometry clipped. In coordinates relative to parent widget.
+		 * @param	widgetDepth	Depth of the parent widget, will be set for all child elements.
+		 * @param	areaDepth	Depth of the parent area, will be set for all child elements.
+		 *
+		 * @note	Internal method.
 		 */
 		virtual void _updateLayout(INT32 x, INT32 y, UINT32 width, UINT32 height, 
 			RectI clipRect, UINT8 widgetDepth, UINT16 areaDepth);
+
+		/**
+		 * @brief	Calculates optimal sizes of all child elements, as determined by their style and layout options.
+		 *
+		 * @note	Internal method.
+		 */
 		virtual void _updateOptimalLayoutSizes();
+
+		/**
+		 * @copydoc	_updateLayout
+		 *
+		 * @note	Internal method.
+		 */
 		virtual void _updateLayoutInternal(INT32 x, INT32 y, UINT32 width, UINT32 height,
 			RectI clipRect, UINT8 widgetDepth, UINT16 areaDepth);
 
+		/**
+		 * @brief	Sets a new parent for this element.
+		 *
+		 * @note	Internal method.
+		 */
 		void _setParent(GUIElementBase* parent);
 
+		/**
+		 * @brief	Returns previously calculated optimal size for this element.
+		 *
+		 * @note	Internal method.
+		 */
 		virtual Vector2I _getOptimalSize() const = 0;
+
+		/**
+		 * @brief	Returns element padding that determines how far apart to space out this element
+		 *			from other elements in a layout.
+		 *
+		 * @note	Internal method.
+		 */
 		virtual const RectOffset& _getPadding() const = 0;
+
+		/**
+		 * @brief	Returns specific sub-type of this object.
+		 *
+		 * @note	Internal method.
+		 */
 		virtual Type _getType() const = 0;
+
+		/**
+		 * @brief	Returns parent GUI base element.
+		 *
+		 * @note	Internal method.
+		 */
 		GUIElementBase* _getParent() const { return mParentElement; }
+
+		/**
+		 * @brief	Returns parent GUI widget, can be null.
+		 *
+		 * @note	Internal method.
+		 */
 		GUIWidget* _getParentWidget() const { return mParentWidget; }
 
+		/**
+		 * @brief	Marks the internal data as clean, usually called after an external
+		 *			system has registered the internal data change.
+		 *
+		 * @note	Internal method.
+		 */
 		void _markAsClean() { mIsDirty = 0; }
 
+		/**
+		 * @brief	Returns true if render elements need to be recalculated by calling updateRenderElements.
+		 *
+		 * @note	Internal method.
+		 */
 		bool _isContentDirty() const;
+
+		/**
+		 * @brief	Returns true if mesh has changed and fillBuffers needs to be called.
+		 *
+		 * @note	Internal method.
+		 */
 		bool _isMeshDirty() const; 
+
+		/**
+		 * @brief	Returns true if element is disabled and won't be visible or interactable.
+		 *
+		 * @note	Internal method.
+		 */
 		bool _isDisabled() const { return mIsDisabled; }
 
+		/**
+		 * @brief	Changes the active GUI element widget. This allows you to move an element
+		 *			to a different viewport, or change element style by using a widget with a different skin.
+		 *			You are allowed to pass null here, but elements with no parent will be unmanaged. You will be
+		 *			responsible for deleting them manually, and they will not render anywhere.
+		 *
+		 * @note	Internal method.
+		 */
 		virtual void _changeParentWidget(GUIWidget* widget);
 
+		/**
+		 * @brief	Registers a new child element.
+		 *
+		 * @note	Internal method.
+		 */
 		void _registerChildElement(GUIElement* element);
+
+		/**
+		 * @brief	Unregisters an existing child element.
+		 *
+		 * @note	Internal method.
+		 */
 		void _unregisterChildElement(GUIElement* element);
 
 	protected:
@@ -78,10 +185,31 @@ namespace BansheeEngine
 		 */
 		void markMeshAsDirty();
 
+		/**
+		 * @brief	Creates and adds a new horizontal layout to the specified "parent" element.
+		 */
 		GUILayout& addLayoutXInternal(GUIElementBase* parent);
+
+		/**
+		 * @brief	Creates and adds a new vertical layout to the specified "parent" element.
+		 */
 		GUILayout& addLayoutYInternal(GUIElementBase* parent);
+
+		/**
+		 * @brief	Removes an existing layout from this element.
+		 */
 		void removeLayoutInternal(GUILayout& layout);
+
+		/**
+		 * @brief	Creates and adds a new horizontal layout to the specified "parent" element,
+		 *			at a specific child index. Caller must ensure index is in valid range.
+		 */
 		GUILayout& insertLayoutXInternal(GUIElementBase* parent, UINT32 idx);
+
+		/**
+		 * @brief	Creates and adds a new vertical layout to the specified "parent" element,
+		 *			at a specific child index. Caller must ensure index is in valid range.
+		 */
 		GUILayout& insertLayoutYInternal(GUIElementBase* parent, UINT32 idx);
 
 		GUIWidget* mParentWidget;

Polish.txt

@@ -28,7 +28,8 @@ DISREGARD MONITOR INDEX ON DX9
 
 Rename CamelotOIS external library
 
-Refactor GUIElement 
+Refactor GUIElement & GUIElementBase
  - Sprite rendering methods should probably be marked as internal (possibly others too)
+  - A lot could be made private
  - Has two methods for retrieveing ElementType
  - getVisibleBounds doesn't make sense