Documentation

BansheeEditor/BansheeEditor.vcxproj.filters

@@ -138,9 +138,6 @@
     <ClInclude Include="Include\BsDockManagerLayout.h">
       <Filter>Header Files\Editor</Filter>
     </ClInclude>
-    <ClInclude Include="Include\BsDockManagerLayoutRTTI.h">
-      <Filter>Header Files\Editor</Filter>
-    </ClInclude>
     <ClInclude Include="Include\BsEditorWidgetLayout.h">
       <Filter>Header Files\Editor</Filter>
     </ClInclude>
@@ -285,6 +282,9 @@
     <ClInclude Include="Include\BsDropDownWindowManager.h">
       <Filter>Header Files\Editor</Filter>
     </ClInclude>
+    <ClInclude Include="Include\BsDockManagerLayoutRTTI.h">
+      <Filter>Header Files\Editor\RTTI</Filter>
+    </ClInclude>
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="Source\BsEditorWidgetContainer.cpp">

BansheeEditor/Include/BsBuildManager.h

@@ -7,6 +7,10 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Contains build information for a specific platform to be
+	 *			used by the build manager.
+	 */
 	class BS_ED_EXPORT BuildData : public IReflectable
 	{
 	public:
@@ -24,23 +28,63 @@ namespace BansheeEngine
 		virtual RTTITypeBase* getRTTI() const;
 	};
 
+	/**
+	 * @brief	Handles building of the game executable and related files.
+	 */
 	class BS_ED_EXPORT BuildManager : public Module<BuildManager>
 	{
 	public:
 		BuildManager();
 
+		/**
+		 * @brief	Returns a list of available platforms the executable can be built for.
+		 */
 		const Vector<PlatformType>& getAvailablePlatforms() const;
+
+		/**
+		 * @brief	Returns the currently active platform.
+		 */
 		PlatformType getActivePlatform() const;
+
+		/**
+		 * @brief	Changes the active build platform. Might cause asset reimport.
+		 */
 		void setActivePlatform(PlatformType type);
 
+		/**
+		 * @brief	Gets stored build setting for the active platform.
+		 */
 		SPtr<PlatformInfo> getActivePlatformInfo() const;
+
+		/**
+		 * @brief	Gets stored build setting for a specific platform.
+		 */
 		SPtr<PlatformInfo> getPlatformInfo(PlatformType type) const;
 
+		/**
+		 * @brief	Returns a list of file names of all .NET assemblies 
+		 *			required for a specific platform.
+		 */
 		Vector<WString> getFrameworkAssemblies(PlatformType type) const;
+
+		/**
+		 * @brief	Returns the location of the pre-built executable for the specified platform.
+		 */
 		Path getMainExecutable(PlatformType type) const;
+
+		/**
+		 * @brief	Returns a list of script defines for a specific platform.
+		 */
 		WString getDefines(PlatformType type) const;
 
+		/**
+		 * @brief	Stores build settings for all platforms in the specified file.
+		 */
 		void save(const Path& outFile);
+
+		/**
+		 * @brief	Loads a previously stored list of build settings.
+		 */
 		void load(const Path& inFile);
 
 	private:

BansheeEditor/Include/BsBuiltinEditorResources.h

@@ -15,12 +15,18 @@ namespace BansheeEngine
 		Folder, Mesh, Font, Texture, PlainText, ScriptCode, SpriteTexture, Shader, ShaderInclude, Material, Prefab
 	};
 
+	/**
+	 * @brief	Contains a set of built-in resources used by the editor.
+	 */
 	class BS_ED_EXPORT BuiltinEditorResources : public BansheeEngine::Module<BuiltinEditorResources>
 	{
 	public:
 		BuiltinEditorResources();
 		~BuiltinEditorResources();
 
+		/**
+		 * @brief	Returns the default editor GUI skin.
+		 */
 		const HGUISkin& getSkin() const { return mSkin; }
 
 		/**

BansheeEditor/Include/BsDockManager.h

@@ -6,14 +6,18 @@
 
 namespace BansheeEngine
 {
-	enum class DockLocation
-	{
-		Left, Right, Top, Bottom, Center
-	};
-
+	/**
+	 * @brief	GUI element that allows editor widgets to be docked in it using arbitrary
+	 *			layouts. Docked widgets can be resized, undocked, maximizes or closed as needed.
+	 */
 	class DockManager : public GUIElementContainer
 	{
 	public:
+		/**
+		 * @brief	Contains information about a single dock area. Each container can be a parent to
+		 *			two other containers or may contain a widget, which results in a container hierarchy. 
+		 *			Two children can be split vertically or horizontally at an user-defined point.
+		 */
 		class DockContainer
 		{
 		public:
@@ -21,32 +25,116 @@ namespace BansheeEngine
 			DockContainer(DockManager* manager, DockContainer* parent);
 			~DockContainer();
 
+			/**
+			 * @brief	Determines the position and size of the container, relative to the parent dock manager.
+			 */
 			void setArea(INT32 x, INT32 y, UINT32 width, UINT32 height);
+
+			/**
+			 * @brief	Transforms the container from non-leaf (parent to other containers)
+			 *			to leaf (parent to widgets). This involves creating a widget container to
+			 *			which you can dock widgets to.
+			 *
+			 * @param	widgetParent	GUI widget of the parent dock manager.
+			 * @param	parentWindow	Editor window of the parent dock manager.
+			 */
 			void makeLeaf(GUIWidget* widgetParent, EditorWindowBase* parentWindow);
+
+			/**
+			 * @brief	Transforms the container from non-leaf (parent to other containers)
+			 *			to leaf (parent to widgets). Unlike the other overload this one accepts
+			 *			a previously created widget container.
+			 *
+			 * @param	existingContainer	An existing widget container that may be used for docking widgets.
+			 */
 			void makeLeaf(EditorWidgetContainer* existingContainer);
+
+			/**
+			 * @brief	Splits a leaf container containing a widget container (or may be empty in the case of root with no elements) 
+			 *			into a container parent to two other containers.
+			 *
+			 * @param	horizontal			Whether the split is horizontal (true) or vertical (false.
+			 * @param	newChildIsFirst		Determines to which child should the widget container from this object be moved to.
+			 *								If the new child is first, then bottom or right (for horizontal and vertical respectively)
+			 *								will receive the current widget container, and opposite if it's not first.
+			 * @param	splitPosition		Determines at what position(in percent) should this container be split. User can modify this later
+			 *								via a dock slider.
+			 */
 			void splitContainer(bool horizontal, bool newChildIsFirst, float splitPosition = 0.5f);
-			void makeSplit(GUIWidget* widgetParent, DockManager::DockContainer* first, DockManager::DockContainer* second, bool horizontal, float splitPosition);
+
+			/**
+			 * @brief	Splits a leaf container containing a widget container (or may be empty in the case of root with no elements)
+			 *			into a container parent to two other containers. Unlike "splitContainer" new containers aren't created automatically
+			 *			but you must provide existing ones. If this container is non-leaf its widget container will be destroyed.
+			 *
+			 * @param	first			Container to insert into the first child slot (left if vertical split, top if horizontal split).
+			 * @param	second			Container to insert into the second child slot (right if vertical split, bottom if horizontal split).
+			 * @param	horizontal		Whether the split is horizontal (true) or vertical (false.
+			 * @param	splitPosition	Determines at what position(in percent) should this container be split. User can modify this later
+			 *							via a dock slider.
+			 */
+			void makeSplit(DockContainer* first, DockContainer* second, bool horizontal, float splitPosition);
+
+			/**
+			 * @brief	Adds a new widget to the left side of the container. If the container is leaf it will
+			 *			be split into two containers vertically.
+			 */
 			void addLeft(EditorWidgetBase* widget);
+
+			/**
+			 * @brief	Adds a new widget to the right side of the container. If the container is leaf it will
+			 *			be split into two containers vertically.
+			 */
 			void addRight(EditorWidgetBase* widget);
+
+			/**
+			 * @brief	Adds a new widget to the top side of the container. If the container is leaf it will
+			 *			be split into two containers horizontally.
+			 */
 			void addTop(EditorWidgetBase* widget);
+
+			/**
+			 * @brief	Adds a new widget to the bottom side of the container. If the container is leaf it will
+			 *			be split into two containers horizontally.
+			 */
 			void addBottom(EditorWidgetBase* widget);
 
+			/**
+			 * @brief	Adds an existing widget to this leaf container.
+			 */
 			void addWidget(EditorWidgetBase* widget);
+
+			/**
+			 * @brief	Attempts to find a widget with the specified name, opens it
+			 *			and adds it to this leaf container.
+			 */
 			void addWidget(const String& name);
 
+			/**
+			 * @brief	Update to be called once per frame. Calls updates on all child widgets.
+			 */
 			void update();
 
+			/**
+			 * @brief	Attempts to find an existing leaf dock container with the specified
+			 *			widget container. Returns null if one cannot be found.
+			 */
 			DockContainer* find(EditorWidgetContainer* widgetContainer);
 
 			/**
-			 * @brief	Searches for a DockContainer at the specified position.
+			 * @brief	Searches for a container at the specified position. Call this at this top-most
+			 *			container in order to search them all.
 			 *
-			 * @param	pos	Position in the same space as DockContainer. 
+			 * @param	pos	Position is relative to the container area. 
 			 *
 			 * @return	null if it fails, else the found DockContainer at position.
 			 */
 			DockContainer* findAtPos(const Vector2I& pos);
 
+			/**
+			 * @brief	Returns the bounds of the container that are to be considered
+			 *			dockable and interactable.
+			 */
 			Rect2I getContentBounds() const;
 
 			bool mIsLeaf;
@@ -63,12 +151,26 @@ namespace BansheeEngine
 			static const UINT32 MIN_CHILD_SIZE;
 
 		private:
+			/**
+			 * @brief	Updates sizes and positions of all child containers. 
+			 *			Normally called when parent area changes.
+			 */
 			void updateChildAreas();
 
+			/**
+			 * @brief	Triggered whenever the user drags the GUI slider belonging to this container.
+			 */
 			void sliderDragged(const Vector2I& delta);
+
+			/**
+			 * @brief	Triggered whenever the user closes or undocks a widget belonging to this container.
+			 */
 			void widgetRemoved();
 		};
 
+		/**
+		 * @brief	Available dock locations for the dock manager.
+		 */
 		enum class DockLocation
 		{
 			Top,
@@ -78,6 +180,9 @@ namespace BansheeEngine
 			None
 		};
 	public:
+		/**
+		 * @brief	Creates a new dock manager for the specified window.
+		 */
 		static DockManager* create(EditorWindowBase* parentWindow);
 
 		/**
@@ -85,23 +190,42 @@ namespace BansheeEngine
 		 */
 		void update();
 
-		void render(const Viewport* viewport, DrawList& renderQueue);
+		/**
+		 * @brief	Inserts a new widget at the specified location.
+		 *
+		 * @param	relativeTo		Container relative to which to insert the widget. Can be null in which case
+		 *							the widget is inserted at the root.
+		 * @param	widgetToInsert	Widget we want to insert into the dock layout.
+		 * @param	location		Location to insert the widget at, relative to "relativeTo" container. 
+		 *							If "relativeTo" is null this is ignored.
+		 */
 		void insert(EditorWidgetContainer* relativeTo, EditorWidgetBase* widgetToInsert, DockLocation location);
 
+		/**
+		 * @brief	Returns a saved layout of all the currently docked widgets and their positions
+		 *			and areas.
+		 */
 		DockManagerLayoutPtr getLayout() const;
+
+		/**
+		 * @brief	Sets a previously saved layout of docked widgets. This will close all currently active
+		 *			widgets and open and position new ones according to the layout.
+		 */
 		void setLayout(const DockManagerLayoutPtr& layout);
 
+		/**
+		 * @brief	Changes the position and size of the dock manager.
+		 */
 		void setArea(INT32 x, INT32 y, UINT32 width, UINT32 height);
 
+		/**
+		 * @brief	Closes all docked widgets.
+		 */
 		void closeAll();
 
-	protected:
-		~DockManager();
-
-		void updateClippedBounds();
-
 	private:
 		DockManager(EditorWindowBase* parentWindow, const GUIDimensions& dimensions);
+		~DockManager();
 
 		static const Color TINT_COLOR;
 		static const Color HIGHLIGHT_COLOR;
@@ -124,9 +248,37 @@ namespace BansheeEngine
 
 		HEvent mRenderCallback;
 
+		/**
+		 * @brief	Render callback that allows the dock manager to render its overlay when needed.
+		 *			Called once per frame by the renderer.
+		 */
+		void render(const Viewport* viewport, DrawList& renderQueue);
+
+		/**
+		 * @brief	Updates the dock overlay mesh that is displayed when user is dragging a widget
+		 *			over a certain area.
+		 */
 		void updateDropOverlay(INT32 x, INT32 y, UINT32 width, UINT32 height);
 
-		bool _mouseEvent(const GUIMouseEvent& event);
+		/**
+		 * @brief	Checks is the provided point inside the provided polygon.
+		 *
+		 * @param	polyPoints	Points of the polygon to test against.
+		 * @param	numPoints	Number of points in "polyPoints".
+		 * @param	point		Point to check if it's in the polygon.
+		 *
+		 * @returns	True if the point is in the polygon.
+		 */
 		bool insidePolygon(Vector2* polyPoints, UINT32 numPoints, Vector2 point) const;
+
+		/**
+		 * @copydoc GUIElementBase::updateClippedBounds
+		 */
+		void updateClippedBounds() override;
+
+		/**
+		 * @copydoc GUIElementBase::_mouseEvent
+		 */
+		bool _mouseEvent(const GUIMouseEvent& event) override;
 	};
 }

BansheeEditor/Include/BsDockManagerLayout.h

@@ -6,17 +6,43 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Used for storing a layout of widgets in a dock manager. 
+	 *
+	 * @see		DockManager
+	 */
 	class DockManagerLayout : public IReflectable
 	{
 	public:
+		/**
+		 * @brief	A single entry in the dock layout which may contain
+		 *			references to two other entries (non-leaf) or may contain
+		 *			multiple widgets (leaf).
+		 */
 		struct Entry
 		{
 		public:
 			Entry();
 			~Entry();
 
+			/**
+			 * @brief	Creates a new leaf entry with the specified widgets.
+			 *
+			 * @param	parent		Parent of this leaf entry. Can be null for root.
+			 * @param	childIdx	Index of this entry in the parents child list. Can be 0 or 1.
+			 * @param	widgetNames	A list of all widgets opened in this entry, listed by name.
+			 */
 			static Entry* createLeaf(Entry* parent, UINT32 childIdx, 
 				const Vector<String>& widgetNames);
+
+			/**
+			 * @brief	Creates a new container entry with the specified split data.
+			 *
+			 * @param	parent				Parent of this leaf entry. Can be null for root.
+			 * @param	childIdx			Index of this entry in the parents child list. Can be 0 or 1.
+			 * @param	splitPosition		Determines at what position(in percent) should this container be split. 
+			 * @param	horizontalSplit		Whether the split is horizontal (true) or vertical (false).
+			 */
 			static Entry* createContainer(Entry* parent, UINT32 childIdx, float splitPosition, 
 				bool horizontalSplit);
 
@@ -32,7 +58,15 @@ namespace BansheeEngine
 	public:
 		~DockManagerLayout();
 
+		/**
+		 * @brief	Returns the root entry in the saved dock manager hierarchy.
+		 */
 		Entry& getRootEntry() { return mRootEntry; }
+
+		/**
+		 * @brief	Removes widgets that can no longer be found (their names no longer reference a widget),
+		 *			and removes containers with no widgets.
+		 */
 		void pruneInvalidLeaves();
 
 	private:
@@ -45,6 +79,6 @@ namespace BansheeEngine
 	public:
 		friend class DockManagerLayoutRTTI;
 		static RTTITypeBase* getRTTIStatic();
-		virtual RTTITypeBase* getRTTI() const;	
+		virtual RTTITypeBase* getRTTI() const override;	
 	};
 }

BansheeEditor/Include/BsDropDownWindowManager.h

@@ -5,12 +5,29 @@
 
 namespace BansheeEngine
 {
+	/**
+	 * @brief	Handles opening and closing of a drop down window. Only a single drop down window
+	 *			can be open at a time.
+	 */
 	class BS_ED_EXPORT DropDownWindowManager : public Module <DropDownWindowManager>
 	{
 	public:
 		DropDownWindowManager();
 		~DropDownWindowManager();
 
+		/**
+		 * @brief	Opens a new drop down window with the specified type and arguments.
+		 *
+		 * @param	parent		Render window parent in which to open the drop down window.
+		 * @param	target		Viewport parent in which to open the drop down window.
+		 * @param	position	Position relative to the viewport at which to open the drop down window.
+		 * @param	...args		A set of arguments to be passed along to the drop down window constructor.
+		 *
+		 * @returns	An instance of the newly created drop down window.
+		 *
+		 * @note	This method will automatically close any existing drop down windows before opening
+		 *			a new one.
+		 */
 		template<class T, class... Args>
 		T* open(const RenderWindowPtr& parent, Viewport* target,
 			const Vector2I& position, Args &&...args)
@@ -21,8 +38,16 @@ namespace BansheeEngine
 			return static_cast<T*>(mOpenWindow);
 		}
 
+		/**
+		 * @brief	Closes a drop down window if one is open.
+		 */
 		void close();
 
+		/**
+		 * @brief	To be called once per frame.
+		 *
+		 * @note	Internal method.
+		 */
 		void update();
 	protected:
 		DropDownWindow* mOpenWindow;

BansheeEditor/Source/BsDockManager.cpp

@@ -209,10 +209,10 @@ namespace BansheeEngine
 		children[idxB]->makeLeaf(mWidgets);
 
 		mWidgets = nullptr;
-		makeSplit(mManager->_getParentWidget(), children[0], children[1], horizontal, splitPosition);
+		makeSplit(children[0], children[1], horizontal, splitPosition);
 	}
 
-	void DockManager::DockContainer::makeSplit(GUIWidget* widgetParent, DockManager::DockContainer* first, DockManager::DockContainer* second, bool horizontal, float splitPosition)
+	void DockManager::DockContainer::makeSplit(DockManager::DockContainer* first, DockManager::DockContainer* second, bool horizontal, float splitPosition)
 	{
 		mChildren[0] = first;
 		mChildren[1] = second;
@@ -234,7 +234,7 @@ namespace BansheeEngine
 		}
 
 		mSlider = GUIDockSlider::create(horizontal, "DockSliderBtn");
-		widgetParent->getPanel()->addElement(mSlider);
+		mManager->_getParentWidget()->getPanel()->addElement(mSlider);
 		mSlider->onDragged.connect(std::bind(&DockManager::DockContainer::sliderDragged, this, _1));
 
 		setArea(mArea.x, mArea.y, mArea.width, mArea.height);
@@ -309,7 +309,7 @@ namespace BansheeEngine
 				}
 				else
 				{
-					mParent->makeSplit(mManager->_getParentWidget(), sibling->mChildren[0], sibling->mChildren[1], sibling->mIsHorizontal, sibling->mSplitPosition);
+					mParent->makeSplit(sibling->mChildren[0], sibling->mChildren[1], sibling->mIsHorizontal, sibling->mSplitPosition);
 
 					sibling->mChildren[0]->mParent = mParent;
 					sibling->mChildren[1]->mParent = mParent;

TODO.txt

@@ -59,8 +59,6 @@ Code quality improvements:
 Polish stage 1
 
 Handles:
-In some cases it's really hard to rotate or the rotation twitches
-When rotating the handle (and sometimes immediately in global mode) the rotation direction is opposite of move movement
 Move plane handles could be more precise
 Investigate scale and its issues
 Check multi-select move/Rotate/scale