From 7bf60c086e174e74917929672b21251b6b623698 Mon Sep 17 00:00:00 2001
From: Ykkrosh <philip@wildfiregames.com>
Date: Wed, 21 Jul 2010 17:53:38 +0000
Subject: [PATCH] Update GUI documentation

This was SVN commit r7777.
---
 docs/doxygen/config     |  2 +-
 source/gui/CGUI.h       | 37 ++++++++++++++++++++-----------
 source/gui/GUIManager.h | 49 ++++++++++++++++++++++++++++++++++-------
 source/gui/IGUIObject.h | 10 ++++-----
 4 files changed, 71 insertions(+), 27 deletions(-)

diff --git a/docs/doxygen/config b/docs/doxygen/config
index 64d5bb8fbc..f7b493e266 100644
--- a/docs/doxygen/config
+++ b/docs/doxygen/config
@@ -3,7 +3,7 @@ PROJECT_NUMBER         = trunk
 
 TAB_SIZE               = 4
 
-INPUT                  = ../../source/simulation2 ../../source/scriptinterface ../../source/network
+INPUT                  = ../../source/simulation2 ../../source/scriptinterface ../../source/network ../../source/gui
 INCLUDE_PATH           = ../../source
 EXAMPLE_PATH           = ../../source
 RECURSIVE              = YES
diff --git a/source/gui/CGUI.h b/source/gui/CGUI.h
index 228f15c24b..7033a93177 100644
--- a/source/gui/CGUI.h
+++ b/source/gui/CGUI.h
@@ -119,7 +119,8 @@ public:
 	void Initialize();
 	
 	/**
-	 * Performs processing that should happen every frame (including the "Tick" event)
+	 * Performs processing that should happen every frame
+	 * (including sending the "Tick" event to scripts)
 	 */
 	void TickObjects();
 
@@ -386,7 +387,7 @@ private:
 	void Xeromyces_ReadRootSprites(XMBElement Element, CXeromyces* pFile);
 
 	/**
-	 * Reads in the root element <styles> (the DOMElement).
+	 * Reads in the root element \<styles\> (the DOMElement).
 	 *
 	 * @param Element	The Xeromyces object that represents
 	 *					the styles-tag.
@@ -412,7 +413,7 @@ private:
 	/**
 	 * Notice! Recursive function!
 	 *
-	 * Read in an <object> (the XMBElement) and stores it
+	 * Read in an \<object\> (the XMBElement) and stores it
 	 * as a child in the pParent.
 	 *
 	 * It will also check the object's children and call this function
@@ -434,14 +435,14 @@ private:
 	void Xeromyces_ReadObject(XMBElement Element, CXeromyces* pFile, IGUIObject *pParent, const std::vector<std::pair<CStr, CStr> >& NameSubst, std::set<VfsPath>& Paths);
 
 	/**
-	 * Reads in the element <repeat>, which repeats its child <object>s
+	 * Reads in the element \<repeat\>, which repeats its child \<object\>s
 	 * 'count' times, replacing the string "[n]" in its descendants' names
 	 * with "[0]", "[1]", etc.
 	 */
 	void Xeromyces_ReadRepeat(XMBElement Element, CXeromyces* pFile, IGUIObject *pParent, std::set<VfsPath>& Paths);
 
 	/**
-	 * Reads in the element <script> (the XMBElement) and executes
+	 * Reads in the element \<script\> (the XMBElement) and executes
 	 * the script's code.
 	 *
 	 * @param Element	The Xeromyces object that represents
@@ -453,7 +454,7 @@ private:
 	void Xeromyces_ReadScript(XMBElement Element, CXeromyces* pFile, std::set<VfsPath>& Paths);
 
 	/**
-	 * Reads in the element <sprite> (the XMBElement) and stores the
+	 * Reads in the element \<sprite\> (the XMBElement) and stores the
 	 * result in a new CGUISprite.
 	 *
 	 * @param Element	The Xeromyces object that represents
@@ -465,7 +466,7 @@ private:
 	void Xeromyces_ReadSprite(XMBElement Element, CXeromyces* pFile);
 
 	/**
-	 * Reads in the element <image> (the XMBElement) and stores the
+	 * Reads in the element \<image\> (the XMBElement) and stores the
 	 * result within the CGUISprite.
 	 *
 	 * @param Element	The Xeromyces object that represents
@@ -477,11 +478,21 @@ private:
 	 */
 	void Xeromyces_ReadImage(XMBElement Element, CXeromyces* pFile, CGUISprite &parent);
 
-	// TODO: Documentation. (I'm feeling lazy at the moment.)
+	/**
+	 * Reads in the element \<effect\> (the XMBElement) and stores the
+	 * result within the SGUIImageEffects.
+	 *
+	 * @param Element	The Xeromyces object that represents
+	 *					the image-tag.
+	 * @param pFile		The Xeromyces object for the file being read
+	 * @param effects	Effects object to add this effect to.
+	 *
+	 * @see LoadXmlFile()
+	 */
 	void Xeromyces_ReadEffects(XMBElement Element, CXeromyces* pFile, SGUIImageEffects &effects);
 
 	/**
-	 * Reads in the element <style> (the XMBElement) and stores the
+	 * Reads in the element \<style\> (the XMBElement) and stores the
 	 * result in m_Styles.
 	 *
 	 * @param Element	The Xeromyces object that represents
@@ -493,7 +504,7 @@ private:
 	void Xeromyces_ReadStyle(XMBElement Element, CXeromyces* pFile);
 
 	/**
-	 * Reads in the element <scrollbar> (the XMBElement) and stores the
+	 * Reads in the element \<scrollbar\> (the XMBElement) and stores the
 	 * result in m_ScrollBarStyles.
 	 *
 	 * @param Element	The Xeromyces object that represents
@@ -505,7 +516,7 @@ private:
 	void Xeromyces_ReadScrollBarStyle(XMBElement Element, CXeromyces* pFile);
 
 	/**
-	 * Reads in the element <icon> (the XMBElement) and stores the
+	 * Reads in the element \<icon\> (the XMBElement) and stores the
 	 * result in m_Icons.
 	 *
 	 * @param Element	The Xeromyces object that represents
@@ -517,7 +528,7 @@ private:
 	void Xeromyces_ReadIcon(XMBElement Element, CXeromyces* pFile);
 	
 	/**
-	 * Reads in the element <tooltip> (the XMBElement) and stores the
+	 * Reads in the element \<tooltip\> (the XMBElement) and stores the
 	 * result as an object with the name __tooltip_#.
 	 *
 	 * @param Element	The Xeromyces object that represents
@@ -529,7 +540,7 @@ private:
 	void Xeromyces_ReadTooltip(XMBElement Element, CXeromyces* pFile);
 
 	/**
-	 * Reads in the element <color> (the XMBElement) and stores the
+	 * Reads in the element \<color\> (the XMBElement) and stores the
 	 * result in m_PreDefinedColors
 	 *
 	 * @param Element	The Xeromyces object that represents
diff --git a/source/gui/GUIManager.h b/source/gui/GUIManager.h
index 90865dcd07..d6b456e2f6 100644
--- a/source/gui/GUIManager.h
+++ b/source/gui/GUIManager.h
@@ -77,28 +77,61 @@ public:
 	 */
 	void DisplayMessageBox(int width, int height, const CStrW& title, const CStrW& message);
 
-	// Hotload pages when their .xml files have changed
+	/**
+	 * Call when a file has bee modified, to hotload pages if their .xml files changed.
+	 */
 	LibError ReloadChangedFiles(const VfsPath& path);
 
-	// Handle input events
+	/**
+	 * Pass input events to the currently active GUI page.
+	 */
 	InReaction HandleEvent(const SDL_Event_* ev);
 
-	// These functions are all equivalent to the CGUI functions of the same
-	// name, applied to the currently active GUI page:
-
+	/**
+	 * See CGUI::GetPreDefinedColor; applies to the currently active page.
+	 */
 	bool GetPreDefinedColor(const CStr& name, CColor& output);
+
+	/**
+	 * See CGUI::IconExists; applies to the currently active page.
+	 */
 	bool IconExists(const CStr& str) const;
+
+	/**
+	 * See CGUI::GetIcon; applies to the currently active page.
+	 */
 	SGUIIcon GetIcon(const CStr& str) const;
 
+	/**
+	 * See CGUI::FindObjectByName; applies to the currently active page.
+	 */
 	IGUIObject* FindObjectByName(const CStr& name) const;
 
+	/**
+	 * See CGUI::SendEventToAll; applies to the currently active page.
+	 */
 	void SendEventToAll(const CStr& eventName);
-	void TickObjects();
-	void Draw();
-	void UpdateResolution();
 
+	/**
+	 * See CGUI::GetScriptObject; applies to the currently active page.
+	 */
 	JSObject* GetScriptObject();
 
+	/**
+	 * See CGUI::TickObjects; applies to @em all loaded pages.
+	 */
+	void TickObjects();
+
+	/**
+	 * See CGUI::Draw; applies to @em all loaded pages.
+	 */
+	void Draw();
+
+	/**
+	 * See CGUI::UpdateResolution; applies to @em all loaded pages.
+	 */
+	void UpdateResolution();
+
 private:
 	struct SGUIPage
 	{
diff --git a/source/gui/IGUIObject.h b/source/gui/IGUIObject.h
index 24dac2442e..f707a38322 100644
--- a/source/gui/IGUIObject.h
+++ b/source/gui/IGUIObject.h
@@ -99,8 +99,8 @@ enum EGUISettingType
 
 /**
  * A GUI Setting is anything that can be inputted from XML as
- * <object>-attributes (with exceptions). For instance:
- * <object style="null">
+ * \<object\>-attributes (with exceptions). For instance:
+ * \<object style="null"\>
  *
  * "style" will be a SGUISetting.
  */
@@ -432,8 +432,8 @@ protected:
 	CPos GetMousePos() const;
 
 	/**
-	 * Handle additional children to the <object>-tag. In IGUIObject, this function does
-	 * nothing. In CList and CDropDown, it handles the <item>, used to build the data.
+	 * Handle additional children to the \<object\>-tag. In IGUIObject, this function does
+	 * nothing. In CList and CDropDown, it handles the \<item\>, used to build the data.
 	 *
 	 * Returning false means the object doesn't recognize the child. Should be reported.
 	 * Notice 'false' is default, because an object not using this function, should not
@@ -525,7 +525,7 @@ protected:
 	 *
 	 * A true means the setting has been manually set in the file when
 	 * read. This is important to know because I don't want to force
-	 * the user to include its <styles>-XML-files first, so somehow
+	 * the user to include its \<styles\>-XML-files first, so somehow
 	 * the GUI needs to know which settings were set, and which is meant
 	 * to 
 	 */