More documentation

BansheeEngine/Include/BsDragAndDropManager.h

@@ -8,15 +8,25 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Holds data returned by DragAndDropManager callbacks.
+	 */
 	struct BS_EXPORT DragCallbackInfo
 	{
 		DragCallbackInfo()
-		:processed(false)
+			:processed(false)
 		{ }
 
 		bool processed;
 	};
 
+	/**
+	 * @brief	Handles GUI drag and drop operations. When active GUI elements
+	 *			will be notified of any drag events and will be able to retrieve
+	 *			dragged data.
+	 *
+	 * @note	Sim thread only.
+	 */
 	class BS_EXPORT DragAndDropManager : public Module<DragAndDropManager>
 	{
 	public:
@@ -27,7 +37,7 @@ namespace BansheeEngine
 		 * 			drag and drop related events and they may choose to handle them.
 		 *
 		 * @param	typeId					Type of the drag and drop operation that other objects may query and decide if they want
-		 * 									to handle it.
+		 * 									to handle it. User defined.
 		 * @param 	data					Some operation specific data that is just passed through to however needs it.
 		 * @param	dropCallback			The drop callback that gets triggered whenever mouse button is released and drag operation ends.
 		 * 									You should perform any cleanup here.
@@ -38,18 +48,74 @@ namespace BansheeEngine
 		 *									Additionally this will determine the cursor displayed (whether or not it can have a "denied" state).
 		 */
 		void startDrag(UINT32 typeId, void* data, std::function<void(bool)> dropCallback, bool needsValidDropTarget = false);
+
+		/**
+		 * @brief	Returns true if drag is currently in progress.
+		 */
 		bool isDragInProgress() const { return mIsDragInProgress; }
+
+		/**
+		 * @brief	Get type ID of drag currently in progress. Only valid if drag is in progress.
+		 */
 		UINT32 getDragTypeId() const { return mDragTypeId; }
+
+		/**
+		 * @brief	Gets drag specific data specified when the drag started. Only valid if drag is in progress.
+		 */
 		void* getDragData() const { return mData; }
+
+		/**
+		 * @brief	Determines whether the drop operation may happen anywhere or does the GUI element need to specifically
+		 * 			accept the drag of this type. If false all GUI elements we mouse over will receive drag/drop events, otherwise only
+		 * 			those that specifically subscribe to the specified drag operation of this typeId will.
+		 * 									
+		 *			Additionally this will determine the cursor displayed (whether or not it can have a "denied" state).
+		 */
 		bool needsValidDropTarget() const { return mNeedsValidDropTarget; }
+
+		/**
+		 * @brief	Registers a new callback that will be triggered when dragged item is dropped.
+		 *			Provided parameter specifies if the drop operation was handled by anyone or not.
+		 */
 		void addDropCallback(std::function<void(bool)> dropCallback);
 
 		/**
-		 * @brief	Called once per frame. Internal method.
+		 * @brief	Called once per frame.
+		 *
+		 * @note	Internal method.
 		 */
-		void update();
+		void _update();
 
+		/**
+		 * @brief	Triggers a callback when user releases the pointer and the drag operation ends.
+		 *			Provided parameters inform the subscriber where the pointer was released, and allows
+		 *			the subscriber to note whether the drag operation was processed or not.
+		 *
+		 * @note	Internal event. You should use addDropCallback for normal use.
+		 */
 		Event<void(const PointerEvent&, DragCallbackInfo&)> onDragEnded;
+	private:
+
+		/**
+		 * @brief	Triggers any drop callbacks and clears callback data.
+		 */
+		void endDrag(bool processed);
+
+		/**
+		 * @brief	Called by the core thread whenever mouse capture state changes.
+		 *			This can happen when window loses focus (e.g. alt+tab). In that 
+		 *			case we want to end the drag even if the user is still holding 
+		 *			the dragged item.
+		 *
+		 * @note	Core thread.
+		 */
+		void mouseCaptureChanged();
+
+		/**
+		 * @brief	Called by the input system when pointer is released.
+		 */
+		void cursorReleased(const PointerEvent& event);
+
 	private:
 		UINT32 mDragTypeId;
 		void* mData;
@@ -59,9 +125,5 @@ namespace BansheeEngine
 
 		std::atomic<bool> mCaptureChanged;
 		std::atomic<int> mCaptureActive;
-
-		void endDrag(bool processed);
-		void mouseCaptureChanged();
-		void cursorReleased(const PointerEvent& event);
 	};
 }

BansheeEngine/Include/BsGUIArea.h

@@ -4,71 +4,202 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	GUIArea represents a freely positionable GUI panel with a GUILayout child.
+	 *			This is one of the top GUI elements (aside from GUIWidget) and all layouts
+	 *			must belong to a single GUIArea.
+	 *
+	 * @note	GUIAreas are automatically cleaned when their parent GUIWidget is destroyed so you
+	 *			dont need to worry about their cleanup.
+	 */
 	class BS_EXPORT GUIArea
 	{
 	public:
 		~GUIArea();
 
 		/**
-		 * @brief	Sets up a new GUI area. All the layouts used in the area will be placed
-		 * 			within the specified bounds.
+		 * Creates a new GUI area. All the layouts used in the area will be placed
+		 * within the specified bounds.
+		 *
+		 * @param	widget	Widget parent of the GUIArea.
+		 * @param	x		X position relative to parent widget position, in pixels.
+		 * @param	y		Y position relative to parent widget position, in pixels.
+		 * @param	width	Width of the area, in pixels. If 0 then the area will be of unlimited width.
+		 * @param	height	Height of the area, in pixels. If 0 then the area will be of unlimited height.
+		 * @param	depth	Depth of the area. This is relative to the depth of parent widget. Depth determines in what
+		 *					order are overlapping GUIAreas drawn. Areas with lower depth will be drawn in front of areas
+		 *					with higher depth.
 		 */
 		static GUIArea* create(GUIWidget& widget, INT32 x, INT32 y, UINT32 width = 0, UINT32 height = 0, UINT16 depth = 0);
 
 		/**
-		 * @brief	Sets up a new GUI area. All the layouts used in the area will be placed
-		 * 			within the specified bounds.
+		 * Creates a new GUI area. All the layouts used in the area will be placed
+		 * within the specified bounds.
 		 * 			
-		 *			This kind of GUI area will always stretch to completely fill the parent widget, while respecting the
-		 *			provided offsets. 
+		 * This kind of GUI area will always stretch to completely fill the parent widget, 
+		 * while respecting the provided offsets (in pixels). 
+		 *
+		 * @param	widget			Widget parent of the GUIArea.
+		 * @param	offsetLeft		Offset to keep from the left of the parent widget, in pixels.
+		 * @param	offsetRight		Offset to keep from the right of the parent widget, in pixels.
+		 * @param	offsetTop		Offset to keep from the top of the parent widget, in pixels.
+		 * @param	offsetBottom	Offset to keep from the bottom of the parent widget, in pixels.
+		 * @param	depth			Depth of the area. This is relative to the depth of parent widget. Depth determines in what
+		 *							order are overlapping GUIAreas drawn. Areas with lower depth will be drawn in front of areas
+		 *							with higher depth.
 		 */
 		static GUIArea* createStretchedXY(GUIWidget& widget, UINT32 offsetLeft, 
 			UINT32 offsetRight, UINT32 offsetTop, UINT32 offsetBottom, UINT16 depth = 0);
 
 		/**
-		 * @brief	Sets up a new GUI area. All the layouts used in the area will be placed
-		 * 			within the specified bounds.
+		 * Creates a new GUI area. All the layouts used in the area will be placed
+		 * within the specified bounds.
 		 * 			
-		 *			This kind of GUI area will always stretch in X dimension to completely fill the parent widget, while respecting the
-		 *			provided offsets. 
+		 * This kind of GUI area will always stretch to completely fill the parent widget width, 
+		 * while respecting the provided offsets (in pixels). 
+		 *
+		 * @param	widget			Widget parent of the GUIArea.
+		 * @param	offsetLeft		Offset to keep from the left of the parent widget, in pixels.
+		 * @param	offsetRight		Offset to keep from the right of the parent widget, in pixels.
+		 * @param	y				Y position relative to parent widget position, in pixels.
+		 * @param	height			Height of the area, in pixels. If 0 then the area will be of unlimited height.
+		 * @param	depth			Depth of the area. This is relative to the depth of parent widget. Depth determines in what
+		 *							order are overlapping GUIAreas drawn. Areas with lower depth will be drawn in front of areas
+		 *							with higher depth.
 		 */
 		static GUIArea* createStretchedX(GUIWidget& widget, UINT32 offsetLeft, 
-			UINT32 offsetRight, UINT32 offsetTop, UINT32 height, UINT16 depth = 0);
+			UINT32 offsetRight, UINT32 y, UINT32 height, UINT16 depth = 0);
 
 		/**
-		 * @brief	Sets up a new GUI area. All the layouts used in the area will be placed
-		 * 			within the specified bounds.
+		 * Creates a new GUI area. All the layouts used in the area will be placed
+		 * within the specified bounds.
 		 * 			
-		 *			This kind of GUI area will always stretch in Y dimension to completely fill the parent widget, while respecting the
-		 *			provided offsets. 
+		 * This kind of GUI area will always stretch to completely fill the parent widget height, 
+		 * while respecting the provided offsets (in pixels). 
+		 *
+		 * @param	widget			Widget parent of the GUIArea.
+		 * @param	offsetTop		Offset to keep from the top of the parent widget, in pixels.
+		 * @param	offsetBottom	Offset to keep from the bottom of the parent widget, in pixels.
+		 * @param	x				X position relative to parent widget position, in pixels.
+		 * @param	width			Width of the area, in pixels. If 0 then the area will be of unlimited width.
+		 * @param	depth			Depth of the area. This is relative to the depth of parent widget. Depth determines in what
+		 *							order are overlapping GUIAreas drawn. Areas with lower depth will be drawn in front of areas
+		 *							with higher depth.
 		 */
 		static GUIArea* createStretchedY(GUIWidget& widget, UINT32 offsetTop, 
-			UINT32 offsetBottom, UINT32 offsetLeft, UINT32 width, UINT16 depth = 0);
+			UINT32 offsetBottom, UINT32 x, UINT32 width, UINT16 depth = 0);
 
+		/**
+		 * @brief	Destroys a GUI area and removes it from the parent GUIWidget.
+		 *			Any child layouts are also destroyed so make sure you aren't 
+		 *			not referencing any of them.
+		 *
+		 * @note	Attached GUIElements are not destroyed, you must destroy them manually or
+		 *			they will be destroyed when parent GUIWidget is destroyed.
+		 */
 		static void destroy(GUIArea* area);
 
+		/**
+		 * @brief	Returns primary layout for the GUI area. Use this to
+		 *			attach GUI elements or other layouts.
+		 */
 		GUILayout& getLayout() const { return *mLayout; }
 
+		/**
+		 * @brief	Returns depth of the GUI area. This is relative to the depth of parent widget. 
+		 *			Depth determines in what order are overlapping GUIAreas drawn. Areas with lower 
+		 *			depth will be drawn in front of areas with higher depth.
+		 */
 		UINT16 getDepth() const { return mDepth; }
+
+		/**
+		 * @brief	Sets depth of the GUI area. This is relative to the depth of parent widget. 
+		 *			Depth determines in what order are overlapping GUIAreas drawn. Areas with lower 
+		 *			depth will be drawn in front of areas with higher depth.
+		 */
 		void setDepth(UINT16 depth) { mDepth = depth; }
 
+		/**
+		 * @brief	Changes the position of the GUI area relative to the parent widget, in pixels.
+		 */
 		void setPosition(INT32 x, INT32 y);
+
+		/**
+		 * @brief	Changes the size of the GUI area, in pixels. If sizes are zero, size is
+		 *			considered to be unlimited.
+		 */
 		void setSize(UINT32 width, UINT32 height);
 
+		/**
+		 * @brief	Hides the area and any child elements.
+		 */
 		void disable();
+
+		/**
+		 * @brief	Shows the area and any child elements.
+		 */
 		void enable();
 
+		/**
+		 * @brief	Changes the parent widget of the GUI area. This may be null
+		 *			but caller is then responsible for properly cleaning up the area.
+		 *			(Since it's normally done by the parent widget). Areas will
+		 *			null parent won't be rendered.
+		 */
 		void changeParentWidget(GUIWidget* widget);
 
+		/**
+		 * @brief	X position of the GUI area, in pixels relative to parent widget.
+		 */
 		INT32 x() const { return mLeft; }
+
+		/**
+		 * @brief	Y position of the GUI area, in pixels relative to parent widget.
+		 */
 		INT32 y() const { return mTop; }
+
+		/**
+		 * @brief	Width of the GUI area, in pixels. If zero with is unlimited.
+		 */
 		UINT32 width() const { return mWidth; }
+
+		/**
+		 * @brief	Height of the GUI area, in pixels. If zero with is unlimited.
+		 */
 		UINT32 height() const { return mHeight; }
 
+		/**
+		 * @brief	Called once per frame. Updates any child layouts if dirty.
+		 *
+		 * @note	Internal method.
+		 */
 		void _update();		
 	private:
 		friend class GUIWidget;
 
+		/**
+		 * @brief	Constructs the area with the specified parent widget (cannot be null),
+		 *			position relative to the parent widget in pixels, and depth relative to
+		 *			parent widget (smaller depth means closer).
+		 */
+		GUIArea(GUIWidget* widget, INT32 x, INT32 y, UINT16 depth);
+
+		/**
+		 * @brief	Check if any of the area properties changed since the last update.
+		 */
+		bool isDirty() const;
+
+		/**
+		 * @brief	Update area size based on parent size and set offsets (if area is set to be stretched).
+		 */
+		void updateSizeBasedOnParent(UINT32 parentWidth, UINT32 parentHeight);
+
+		/**
+		 * @brief	Destroys the area without unregistering it from the parent (assumed to have done that earlier).
+		 */
+		static void destroyInternal(GUIArea* area);
+
+	private:
 		GUIWidget* mWidget;
 		INT32 mLeft, mRight, mTop, mBottom;
 		UINT32 mWidth, mHeight;
@@ -79,12 +210,5 @@ namespace BansheeEngine
 		bool mIsDisabled;
 
 		GUILayout* mLayout;
-
-		GUIArea(GUIWidget* widget, INT32 x, INT32 y, UINT16 depth);
-
-		bool isDirty() const;
-		void updateSizeBasedOnParent(UINT32 parentWidth, UINT32 parentHeight);
-
-		static void destroyInternal(GUIArea* area);
 	};
 }

BansheeEngine/Source/BsDragAndDropManager.cpp

@@ -32,7 +32,7 @@ namespace BansheeEngine
 		Platform::captureMouse(*gCoreApplication().getPrimaryWindow());
 	}
 
-	void DragAndDropManager::update()
+	void DragAndDropManager::_update()
 	{
 		if(!mIsDragInProgress)
 			return;
@@ -76,5 +76,7 @@ namespace BansheeEngine
 
 			endDrag(info.processed);
 		}
+		else
+			endDrag(false);
 	}
 }