More documentation improvements to GUI code. Fixed a couple old comments that were no longer valid and thus misleading.

git-svn-id: svn+ssh://svn.code.sf.net/p/supertuxkart/code/main/trunk@5266 178a84e3-b1eb-0310-8ba1-8eac791a3b58

src/guiengine/engine.cpp

@@ -363,9 +363,24 @@
  Once you have instanciated your state manager class, call GUIEngine::init and pass it as argument.
  One of the most important callbacks is 'eventCallback', which will be called everytime sometimes happens.
  Events are generally a widget state change. In this case, a pointer to the said widget is passed along its
- name, so you get its new state and/or act. There are two special events, passed with a NULL widget, and which
- bear the names "init" and "tearDown", called respectively when a screen is being made visible and when it's
- being left, allowing for setup/clean-up.
+ name, so you get its new state and/or act.
+ 
+ When you have described the general layout of a Screen in a XML file, as described above, you may use it
+ in the code by creating a class deriving from GUIEngine::Screen, passing the name of the XML file to the
+ constructor of the base class. The derived class will most notably be used for event callbacks, to allow
+ creating interactive menus. The derived class must also implement the GUIEngine::Screen::init and
+ GUIEngine::Screen::tearDown methods, that will be called, respectively, when a menu is entered/left. For
+ simple menus, it is not unexpected that those methods do nothing.
+ 
+ Note that the same instance of your object may be entered/left more than once, so make sure that one instance
+ of your object can be used several times if the same screen is visited several times.
+ 
+ You can also explore the various methods in GUIEngine::Screen to discover more optional callbacks you
+ can use.
+ 
+ You can also create dialogs by deriving from GUIEngine::ModalDialog. Unfortunately, it is currently not
+ possible to specify modal dialogs through XML files (FIXME), so you will need to simulate the init
+ sequence of a GUI screen, which I admit is not too easy. This is to improve in the future.
  
  */
 

src/guiengine/engine.hpp

@@ -34,6 +34,8 @@
 /**
  * \ingroup guiengine
  * \brief Contains all GUI engine related classes and functions
+ *
+ * See \ref gui_overview for more information.
  */
 namespace GUIEngine
 {    

src/guiengine/screen.hpp

@@ -119,8 +119,16 @@ namespace GUIEngine
          (useful e.g. on reschange, when sizes have changed and must be re-calculated) */
         virtual void forgetWhatWasLoaded();
         
-        Screen(); /**< creates a dummy incomplete object; only use to override behaviour in sub-class */
+        /** \brief creates a dummy incomplete object; only use to override behaviour in sub-class */
+        Screen();
+        
+        /** 
+          * \brief          creates a screen populated by the widgets described in a STK GUI file
+          * \param filename name of the XML file describing the screen. this is NOT a path.
+          *                 The passed file name will be searched for in the STK data/gui directory
+          */
         Screen(const char* filename);
+        
         virtual ~Screen();
         
         bool operator ==(const char* filename) const { return m_filename == filename; }
@@ -147,25 +155,58 @@ namespace GUIEngine
         Widget* getFirstWidget(ptr_vector<Widget>* within_vector=NULL);
         Widget* getLastWidget(ptr_vector<Widget>* within_vector=NULL);
         
-        virtual void addWidgets();
-        virtual void calculateLayout();
+        /** \brief adds the irrLicht widgets corresponding to this screen to the IGUIEnvironment */
+        void addWidgets();
         
+        /** called after all widgets have been added. namely expands layouts into absolute positions */
+        void calculateLayout();
+        
+        /** \brief can be used for custom purposes for which the load-screen-from-XML code won't make it */
         void manualAddWidget(Widget* w);
+        
+        /** \brief can be used for custom purposes for which the load-screen-from-XML code won't make it */
         void manualRemoveWidget(Widget* w);
         
+        /** \return the name of this menu (which is the name of the file) */
         const std::string& getName() const { return m_filename; }
         
         void elementsWereDeleted(ptr_vector<Widget>* within_vector = NULL);
         
         /** Will be called to determine if the 3D scene must be rendered when at this screen */
         bool needs3D() { return m_render_3d; }
+        
+        /** \brief invoke this method for screens that use a 3D scene as background
+          *
+          * (if this method is not invoked with 'true' as parameter, the menu background will
+          *  be rendered instead).
+          *
+          * \note to create the 3D background, use the facilities provided by the irrLicht scene
+          *       manager, this class will not set up any 3D scene.
+          */
         void setNeeds3D(bool needs3D) { m_render_3d = needs3D; }
         
+        /** 
+          * \brief callback invoked when entering this menu
+          *
+          * @note the same instance of your object may be entered/left more than once, so make sure that
+          * one instance of your object can be used several times if the same screen is visited several
+          * times.
+          */
         virtual void init() = 0;
+        
+        /** 
+          * \brief callback invoked before leaving this menu
+          *
+          * @note the same instance of your object may be entered/left more than once, so make sure that
+          * one instance of your object can be used several times if the same screen is visited several
+          * times.
+          */
         virtual void tearDown() = 0;
         
-        /** Called when escape is pressed.
-         * @return true if the screen should be closed, false if you handled the press another way */
+        /** 
+          * \brief  Called when escape is pressed.
+          * \return true if the screen should be closed, false if you handled the press another way
+          */
         virtual bool onEscapePressed() { return true; }
         
         /**

src/guiengine/widget.cpp

@@ -135,9 +135,10 @@ void Widget::elementRemoved()
 namespace GUIEngine
 {
     // IDs must not start at 0, since it appears their GUI engine hardcodes some ID values... xD
+    /** Used to assign irrLicht IDs to widgets dynamically */
     static unsigned int id_counter = 100;
     
-    /** // for items that can't be reached with keyboard navigation but can be clicked */
+    /** for items that can't be reached with keyboard navigation but can be clicked */
     static unsigned int id_counter_2 = 1000;
 }