Fixed karts selection screen messed up after a resolution switch; added some refactor to allow easier fixing of such problems in the future. Documented many more methods along the way.

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

src/guiengine/abstract_state_manager.cpp

@@ -104,6 +104,7 @@ void AbstractStateManager::pushMenu(std::string name)
 
 void AbstractStateManager::pushScreen(Screen* screen)
 {
+    if (!screen->isLoaded()) screen->loadFromFile();
     pushMenu(screen->getName());
     screen->init();
 }

src/guiengine/engine.cpp

@@ -378,6 +378,11 @@
  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.
  
+ Note that the same instance of your object may be unloaded then loaded back later. It is thus important to
+ do set-up in the 'loadedFromFile' callback rather than in the constructor (after the creation of Screen
+ object, it may be unloaded then loaded back at will, this is why it's important to not rely on the constructor
+ to perform set-up).
+ 
  You can also explore the various methods in GUIEngine::Screen to discover more optional callbacks you
  can use.
  
@@ -531,14 +536,11 @@ void switchToScreen(const char* screen_name)
         }
     }
     
-    // screen not found in list of existing ones, so let's create it
+    // screen not found in list of existing ones
     if (g_current_screen == NULL)
     {
         assert(false);
         return;
-        //GUIEngine::Screen* new_screen = new GUIEngine::Screen(screen_name);
-        //g_loaded_screens.push_back(new_screen);
-        //g_current_screen = new_screen;
     }
     
     
@@ -566,9 +568,10 @@ void cleanUp()
 {
     if (g_skin != NULL) delete g_skin;
     g_skin = NULL;
+
     for (int i=0; i<g_loaded_screens.size(); i++)
     {
-        g_loaded_screens[i].forgetWhatWasLoaded();
+        g_loaded_screens[i].unload();
     }
     
     g_current_screen = NULL;

src/guiengine/screen.cpp

@@ -40,33 +40,60 @@ using namespace io;
 using namespace gui;
 using namespace GUIEngine;
 
+// -----------------------------------------------------------------------------
+
 Screen::Screen(const char* file)
 {
-    m_magic_number = 0xCAFEC001;
+    m_magic_number   = 0xCAFEC001;
 
-    m_throttle_FPS = true;
-    
     this->m_filename = file;
-    m_loaded = false;
-    loadFromFile();
-    m_render_3d = false;
+    m_throttle_FPS   = true;
+    m_render_3d      = false;
+    m_loaded         = false;
 }
 
+// -----------------------------------------------------------------------------
+
 Screen::Screen()
 {
     m_magic_number = 0xCAFEC001;
 
-    m_loaded = false;
-    m_render_3d = false;
+    m_loaded       = false;
+    m_render_3d    = false;
 }
 
+// -----------------------------------------------------------------------------
+
 Screen::~Screen()
 {
     assert(m_magic_number == 0xCAFEC001);
     m_magic_number = 0xDEADBEEF;
 }
 
-void Screen::forgetWhatWasLoaded()
+// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+
+#if 0
+#pragma mark -
+#pragma mark Load/Init
+#endif
+
+
+void Screen::loadFromFile()
+{
+    assert(m_magic_number == 0xCAFEC001);
+    IrrXMLReader* xml = irr::io::createIrrXMLReader( (file_manager->getGUIDir() + "/" + m_filename).c_str() );
+    parseScreenFileDiv(xml, m_widgets);
+    m_loaded = true;
+    calculateLayout();
+    
+    // invoke callback so that the class deriving from Screen is aware of this event
+    loadedFromFile();
+}
+
+// -----------------------------------------------------------------------------
+
+void Screen::unload()
 {
     assert(m_magic_number == 0xCAFEC001);
     for (int n=0; n<m_widgets.size(); n++)
@@ -76,23 +103,13 @@ void Screen::forgetWhatWasLoaded()
     
     m_loaded = false;
     m_widgets.clearAndDeleteAll();
+    
+    // invoke callback so that the class deriving from Screen is aware of this event
+    unloaded();
 }
 
-#if 0
-#pragma mark -
-#pragma mark Load/Init
-#endif
+// -----------------------------------------------------------------------------
 
-// -----------------------------------------------------------------------------
-void Screen::loadFromFile()
-{
-    assert(m_magic_number == 0xCAFEC001);
-    IrrXMLReader* xml = irr::io::createIrrXMLReader( (file_manager->getGUIDir() + "/" + m_filename).c_str() );
-    parseScreenFileDiv(xml, m_widgets);
-    m_loaded = true;
-    calculateLayout();
-}
-// -----------------------------------------------------------------------------
 /* small shortcut so this method can be called without arguments */
 void Screen::calculateLayout()
 {
@@ -100,12 +117,9 @@ void Screen::calculateLayout()
     // build layout
     calculateLayout( m_widgets );
 }
+
 // -----------------------------------------------------------------------------
-/*
- * Recursive call that lays out children widget within parent (or screen if none)
- * Manages 'horizontal-row' and 'vertical-row' layouts, along with the proportions
- * of the remaining children, as well as absolute sizes and locations.
- */
+
 void Screen::calculateLayout(ptr_vector<Widget>& widgets, Widget* parent)
 {
     assert(m_magic_number == 0xCAFEC001);

src/guiengine/screen.hpp

@@ -85,9 +85,15 @@ namespace GUIEngine
         
         bool m_loaded;
         std::string m_filename;
-        void loadFromFile();
         
         static void addWidgetsRecursively(ptr_vector<Widget>& widgets, Widget* parent=NULL);
+        
+        /**
+          * @brief Recursive call that lays out children widget within parent (or screen if none).
+          *
+          * Manages 'horizontal-row' and 'vertical-row' layouts, along with the proportions
+          * of the remaining children, as well as absolute sizes and locations.
+          */
         void calculateLayout(ptr_vector<Widget>& widgets, Widget* parent=NULL);
         
         /** Will be called to determine if the 3D scene must be rendered when at this screen. */
@@ -126,6 +132,12 @@ namespace GUIEngine
         
         bool operator ==(const char* filename) const { return m_filename == filename; }
         
+        /** \brief loads this Screen from the file passed to the constructor */
+        void loadFromFile();
+        
+        /** \return whether this screen is currently loaded */
+        bool isLoaded() const { return m_loaded; }
+        
         /** returns an object by name, or NULL if not found */
         Widget* getWidget(const char* name);
         
@@ -177,7 +189,7 @@ namespace GUIEngine
         
         /** Next time this menu needs to be shown, don't use cached values, re-calculate everything.
          (useful e.g. on reschange, when sizes have changed and must be re-calculated) */
-        virtual void forgetWhatWasLoaded();
+        virtual void unload();
         
         /** Will be called to determine if the 3D scene must be rendered when at this screen */
         bool needs3D() { return m_render_3d; }
@@ -192,10 +204,34 @@ namespace GUIEngine
           */
         void setNeeds3D(bool needs3D) { m_render_3d = needs3D; }
         
+        /** 
+          * \brief callback invoked when loading this menu
+          *
+          * \precondition Children widgets of this menu have been created by the time this callback
+          *               is invoked.
+          * \note this method is not called everytime the screen is shown. Screen::init is.
+          *       use this method for persistent setup code (namely, that deals with settupping
+          *       children widget objects and needs not be done everytime we visit the screen).
+          * \note a Screen object instance may be unloaded then loaded back. This method might thus
+          *       be called more than once in the lifetime of a Screen object, however there will always
+          *       be an 'unload' event in-between calls to this method.
+          */
+        virtual void loadedFromFile() = 0;
+        
+        /**
+          * \brief callback invoked when this screen is being unloaded
+          * Override this method in children classes if you need to be notified of this.
+          * \note a Screen object instance may be unloaded then loaded back at will.
+          * \note an unloaded Screen object does not have its children widgets anymore, it only
+          *       retains its members (most importantly the path to its GUI file) so that it can be
+          *       loaded back later.
+          */
+        virtual void unloaded() {}
+        
         /** 
           * \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
+          * \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.
           */
@@ -217,7 +253,7 @@ namespace GUIEngine
         virtual bool onEscapePressed() { return true; }
         
         /**
-         * will be called everytime sometimes happens.
+         * \brief 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 anmes "init" and "tearDown", called respectively when a screen is being made visible and when it's
@@ -225,6 +261,9 @@ namespace GUIEngine
          */
         virtual void eventCallback(Widget* widget, const std::string& name, const int playerID) = 0;
         
+        /**
+          * \brief optional callback you can override to be notified at every frame.
+          */
         virtual void onUpdate(float dt, irr::video::IVideoDriver*) { };
         
         

src/states_screens/arenas_screen.cpp

@@ -40,6 +40,12 @@ const char* ALL_ARENA_GROUPS_ID = "all";
 // ------------------------------------------------------------------------------------------------------
 
 ArenasScreen::ArenasScreen() : Screen("arenas.stkgui")
+{
+}
+
+// ------------------------------------------------------------------------------------------------------
+
+void ArenasScreen::loadedFromFile()
 {
     // Dynamically add tabs
     RibbonWidget* tabs = this->getWidget<RibbonWidget>("trackgroups");

src/states_screens/arenas_screen.hpp

@@ -36,6 +36,9 @@ class ArenasScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton
 
 public:
     
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
     /** \brief implement callback from parent class GUIEngine::Screen */
     virtual void init();
     

src/states_screens/challenges.cpp

@@ -50,6 +50,12 @@ ChallengesScreen::ChallengesScreen() : Screen("challenges.stkgui")
 
 // ------------------------------------------------------------------------------------------------------
 
+void ChallengesScreen::loadedFromFile()
+{
+}
+
+// ------------------------------------------------------------------------------------------------------
+
 void ChallengesScreen::onUpdate(float elapsed_time, irr::video::IVideoDriver*)
 {
 }

src/states_screens/challenges.hpp

@@ -35,10 +35,19 @@ class ChallengesScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingl
     
 public:
 
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement optional callback from parent class GUIEngine::Screen */
     void onUpdate(float dt, irr::video::IVideoDriver*);
     
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void tearDown();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
 };
 

src/states_screens/credits.cpp

@@ -38,6 +38,8 @@ using namespace GUIEngine;
 const float TIME_SECTION_FADE = 0.8f;
 const float ENTRIES_FADE_TIME = 0.3f;
 
+// ---------------------------------------------------------------------------------------------------
+
 class CreditsEntry
 {
 public:
@@ -50,6 +52,7 @@ public:
     }
 };
 
+// ---------------------------------------------------------------------------------------------------
 
 class CreditsSection
 {
@@ -72,11 +75,15 @@ public:
     }
 };
 
+// ---------------------------------------------------------------------------------------------------
+
 CreditsSection* CreditsScreen::getCurrentSection()
 {
     return m_sections.get(m_sections.size()-1);
 }
 
+// ---------------------------------------------------------------------------------------------------
+
 bool getWideLine(std::ifstream& file, stringw* out)
 {
     if (!file.good())
@@ -124,7 +131,21 @@ bool getWideLine(std::ifstream& file, stringw* out)
     return true;
 }
 
+// ---------------------------------------------------------------------------------------------------
+// ---------------------------------------------------------------------------------------------------
+
+#if 0
+#pragma mark -
+#pragma mark CreditsScreen
+#endif
+
 CreditsScreen::CreditsScreen() : Screen("credits.stkgui")
+{
+}
+
+// ---------------------------------------------------------------------------------------------------
+
+void CreditsScreen::loadedFromFile()
 {
     reset();
     
@@ -178,6 +199,25 @@ CreditsScreen::CreditsScreen() : Screen("credits.stkgui")
     
 }
 
+// ---------------------------------------------------------------------------------------------------
+
+void CreditsScreen::init()
+{
+    Widget* w = getWidget<Widget>("animated_area");
+    assert(w != NULL);
+    
+    reset();
+    setArea(w->x, w->y, w->w, w->h);
+}
+
+// ---------------------------------------------------------------------------------------------------
+
+void CreditsScreen::tearDown()
+{
+}
+
+// ---------------------------------------------------------------------------------------------------
+
 void CreditsScreen::setArea(const int x, const int y, const int w, const int h)
 {
     this->x = x;
@@ -188,6 +228,8 @@ void CreditsScreen::setArea(const int x, const int y, const int w, const int h)
     m_section_rect = core::rect< s32 >( x, y, x+w, y+h/6 );
 }
 
+// ---------------------------------------------------------------------------------------------------
+
 void CreditsScreen::reset()
 {
     m_curr_section = 0;
@@ -196,6 +238,8 @@ void CreditsScreen::reset()
     m_time_element = 2.5f;
 }
 
+// ---------------------------------------------------------------------------------------------------
+
 void CreditsScreen::onUpdate(float elapsed_time, irr::video::IVideoDriver*)
 {
     time_before_next_step -= elapsed_time*0.8f; // multiply by 0.8 to slow it down a bit as a whole
@@ -315,18 +359,7 @@ void CreditsScreen::onUpdate(float elapsed_time, irr::video::IVideoDriver*)
      */
 }
 
-void CreditsScreen::init()
-{
-    Widget* w = getWidget<Widget>("animated_area");
-    assert(w != NULL);
-    
-    reset();
-    setArea(w->x, w->y, w->w, w->h);
-}
-
-void CreditsScreen::tearDown()
-{
-}
+// ---------------------------------------------------------------------------------------------------
 
 void CreditsScreen::eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID)
 {
@@ -336,3 +369,5 @@ void CreditsScreen::eventCallback(GUIEngine::Widget* widget, const std::string&
     }
 }
 
+// ---------------------------------------------------------------------------------------------------
+

src/states_screens/credits.hpp

@@ -56,10 +56,19 @@ public:
     // start from beginning again
     void reset();
     
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement optional callback from parent class GUIEngine::Screen */
     void onUpdate(float dt, irr::video::IVideoDriver*);
     
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void tearDown();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
 };
 

src/states_screens/feature_unlocked.cpp

@@ -90,6 +90,12 @@ FeatureUnlockedCutScene::FeatureUnlockedCutScene() : Screen("feature_unlocked.st
 
 // -------------------------------------------------------------------------------------
 
+void FeatureUnlockedCutScene::loadedFromFile()
+{
+}
+
+// -------------------------------------------------------------------------------------
+
 void FeatureUnlockedCutScene::addUnlockedKart(KartProperties* unlocked_kart, irr::core::stringw msg)
 {
     assert(unlocked_kart != NULL);

src/states_screens/feature_unlocked.hpp

@@ -83,9 +83,16 @@ class FeatureUnlockedCutScene : public GUIEngine::Screen, public GUIEngine::Scre
     
 public:
 
+    /** \brief implement optional callback from parent class GUIEngine::Screen */
     void onUpdate(float dt, irr::video::IVideoDriver*);
     
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void tearDown();
     
     void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);

src/states_screens/grand_prix_over.cpp

@@ -34,7 +34,12 @@ GrandPrixOver::GrandPrixOver() : Screen("grand_prix_over.stkgui")
     setNeeds3D(true);
     
     m_throttle_FPS = false;
-    
+}
+
+// -------------------------------------------------------------------------------------
+
+void GrandPrixOver::loadedFromFile()
+{
     m_kart_node[0] = NULL;
     m_kart_node[1] = NULL;
     m_kart_node[2] = NULL;

src/states_screens/grand_prix_over.hpp

@@ -43,14 +43,22 @@ class GrandPrixOver : public GUIEngine::Screen, public GUIEngine::ScreenSingleto
     
 public:
 
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement optional callback from parent class GUIEngine::Screen */
     void onUpdate(float dt, irr::video::IVideoDriver*);
     
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void tearDown();
     
-    void setKarts(const std::string idents[3]);
-    
+    /** \brief implement callback from parent class GUIEngine::Screen */
     void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    void setKarts(const std::string idents[3]);
 
 };
 

src/states_screens/help_screen_1.cpp

@@ -35,6 +35,12 @@ HelpScreen1::HelpScreen1() : Screen("help1.stkgui")
 
 // ------------------------------------------------------------------------------------------------------
 
+void HelpScreen1::loadedFromFile()
+{
+}
+
+// ------------------------------------------------------------------------------------------------------
+
 void HelpScreen1::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
     if (name == "category")

src/states_screens/help_screen_1.hpp

@@ -33,9 +33,17 @@ class HelpScreen1 : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<
     
 public:
 
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    void init();
-    void tearDown();
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
 };
 
 #endif

src/states_screens/help_screen_2.cpp

@@ -35,6 +35,12 @@ HelpScreen2::HelpScreen2() : Screen("help2.stkgui")
 
 // ------------------------------------------------------------------------------------------------------
 
+void HelpScreen2::loadedFromFile()
+{
+}
+
+// ------------------------------------------------------------------------------------------------------
+
 void HelpScreen2::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
     if (name == "category")

src/states_screens/help_screen_2.hpp

@@ -33,9 +33,17 @@ class HelpScreen2 : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<
     
 public:
     
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    void init();
-    void tearDown();
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
 };
 
 #endif

src/states_screens/help_screen_3.cpp

@@ -35,6 +35,12 @@ HelpScreen3::HelpScreen3() : Screen("help3.stkgui")
 
 // ------------------------------------------------------------------------------------------------------
 
+void HelpScreen3::loadedFromFile()
+{
+}
+
+// ------------------------------------------------------------------------------------------------------
+
 void HelpScreen3::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
     if (name == "category")

src/states_screens/help_screen_3.hpp

@@ -34,9 +34,17 @@ class HelpScreen3 : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<
     
 public:
     
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    void init();
-    void tearDown();
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
 };
 
 #endif

src/states_screens/kart_selection.cpp

@@ -707,7 +707,14 @@ KartHoverListener* karthoverListener = NULL;
 #endif
     
 // -----------------------------------------------------------------------------
+
 KartSelectionScreen::KartSelectionScreen() : Screen("karts.stkgui")
+{
+}
+
+// -----------------------------------------------------------------------------
+
+void KartSelectionScreen::loadedFromFile()
 {
     g_dispatcher = new FocusDispatcher(this);
     m_player_confirmed = false;
@@ -721,6 +728,7 @@ KartSelectionScreen::KartSelectionScreen() : Screen("karts.stkgui")
     const std::vector<std::string>& groups = kart_properties_manager->getAllGroups();
     
     const int group_amount = groups.size();
+    
     for (int n=0; n<group_amount; n++)
     {
         //FIXME: group name not translated
@@ -802,10 +810,8 @@ void KartSelectionScreen::tearDown()
 
 // -----------------------------------------------------------------------------
 
-void KartSelectionScreen::forgetWhatWasLoaded()
-{    
-    Screen::forgetWhatWasLoaded();
-    
+void KartSelectionScreen::unloaded()
+{        
     // these pointers are no more valid (have been deleted along other widgets)
     g_dispatcher = NULL;
     karthoverListener = NULL;

src/states_screens/kart_selection.hpp

@@ -73,24 +73,27 @@ class KartSelectionScreen : public GUIEngine::Screen, public GUIEngine::ScreenSi
     
 public:
     
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
     /** Called when a player hits 'fire' on his device to join the game */
     bool playerJoin(InputDevice* device, bool firstPlayer);
     
     /** Called when a player hits 'rescue' on his device to leave the game */
     bool playerQuit(StateManager::ActivePlayer* player);
     
-    /** Standard 'Screen' callback before screen is entered */
-    void init();
+     /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
     
-    /** Standard 'Screen' callback before screen is left */
-    void tearDown();
+     /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
     
-    /** Standard 'Screen' callback when an event occurs*/
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
     
-    /** Standard 'Screen' callback every frame */
-    void onUpdate(float dt, irr::video::IVideoDriver*);
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void onUpdate(float dt, irr::video::IVideoDriver*);
     
-    /** overload */
-    virtual void forgetWhatWasLoaded();
+    /** \brief implement optional callback from parent class GUIEngine::Screen */
+    virtual void unloaded();
 };

src/states_screens/main_menu_screen.cpp

@@ -49,6 +49,12 @@ MainMenuScreen::MainMenuScreen() : Screen("main.stkgui")
 
 // ------------------------------------------------------------------------------------------------------
 
+void MainMenuScreen::loadedFromFile()
+{
+}
+
+// ------------------------------------------------------------------------------------------------------
+
 void MainMenuScreen::init()
 {
     // reset in case we're coming back from a race

src/states_screens/main_menu_screen.hpp

@@ -31,9 +31,18 @@ class MainMenuScreen : public GUIEngine::Screen, public GUIEngine::ScreenSinglet
     friend class GUIEngine::ScreenSingleton<MainMenuScreen>;
     MainMenuScreen();
 public:
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    void init();
-    void tearDown();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
 };
 
 #endif

src/states_screens/options_screen_av.cpp

@@ -48,6 +48,13 @@ OptionsScreenAV::OptionsScreenAV() : Screen("options_av.stkgui")
 
 // -----------------------------------------------------------------------------
 
+void OptionsScreenAV::loadedFromFile()
+{
+    m_inited = false;
+}
+
+// -----------------------------------------------------------------------------
+
 void OptionsScreenAV::init()
 {
     RibbonWidget* ribbon = this->getWidget<RibbonWidget>("options_choice");
@@ -237,9 +244,8 @@ void OptionsScreenAV::tearDown()
 
 // -----------------------------------------------------------------------------
 
-void OptionsScreenAV::forgetWhatWasLoaded()
+void OptionsScreenAV::unloaded()
 {
-    Screen::forgetWhatWasLoaded();
     m_inited = false;
 }
 

src/states_screens/options_screen_av.hpp

@@ -40,12 +40,20 @@ class OptionsScreenAV : public GUIEngine::Screen, public GUIEngine::ScreenSingle
 public:
     friend class GUIEngine::ScreenSingleton<OptionsScreenAV>;
     
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-        
-    void init();
-    void tearDown();
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
     
-    virtual void forgetWhatWasLoaded();
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+        
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
+    
+    /** \brief implement optional callback from parent class GUIEngine::Screen */
+    virtual void unloaded();
 };
 
 #endif

src/states_screens/options_screen_input.cpp

@@ -50,6 +50,13 @@ OptionsScreenInput::OptionsScreenInput() : Screen("options_input.stkgui")
 
 // -----------------------------------------------------------------------------
 
+void OptionsScreenInput::loadedFromFile()
+{
+    m_inited = false;
+}
+
+// -----------------------------------------------------------------------------
+
 void OptionsScreenInput::updateInputButtons(DeviceConfig* config)
 {
     
@@ -520,9 +527,8 @@ void OptionsScreenInput::eventCallback(Widget* widget, const std::string& name,
 
 // -----------------------------------------------------------------------------
 
-void OptionsScreenInput::forgetWhatWasLoaded()
+void OptionsScreenInput::unloaded()
 {
-    Screen::forgetWhatWasLoaded();
     m_inited = false;
 }
 

src/states_screens/options_screen_input.hpp

@@ -45,15 +45,32 @@ class OptionsScreenInput : public GUIEngine::Screen, public GUIEngine::ScreenSin
 public:
     friend class GUIEngine::ScreenSingleton<OptionsScreenInput>;
     
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
     
-    void gotSensedInput(Input* sensedInput);
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    /** \brief implement optional callback from parent class GUIEngine::Screen */
+    virtual void unloaded();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
+    
+    /** 
+     * \brief invoke if the list of devices changed after the creation of this screen.
+     * This will cause the displayed list to be updated accordingly with the data in the device manager.
+     */
     void rebuildDeviceList();
-
-    virtual void forgetWhatWasLoaded();
     
-    void init();
-    void tearDown();
+    /**
+      * \brief invoke in "input sensing" mode, when input was sensed.
+      * Updates the input bindings accordingly with the sensed input.
+      */
+    void gotSensedInput(Input* sensedInput);
 };
 
 #endif

src/states_screens/options_screen_players.cpp

@@ -49,6 +49,12 @@ OptionsScreenPlayers::OptionsScreenPlayers() : Screen("options_players.stkgui")
 
 // -----------------------------------------------------------------------------
 
+void OptionsScreenPlayers::loadedFromFile()
+{
+}
+
+// -----------------------------------------------------------------------------
+
 void OptionsScreenPlayers::init()
 {
     RibbonWidget* tabBar = this->getWidget<RibbonWidget>("options_choice");

src/states_screens/options_screen_players.hpp

@@ -40,17 +40,24 @@ class OptionsScreenPlayers : public GUIEngine::Screen, public GUIEngine::ScreenS
 public:
     friend class GUIEngine::ScreenSingleton<OptionsScreenPlayers>;
     
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
     
     /**
-     * Adds a new player (if 'player' is NULL) or renames an existing player (if 'player' is not NULL)
-     * @return  whether adding was successful (can fail e.g. if trying to add a duplicate)
+     * \brief Adds a new player (if 'player' is NULL) or renames an existing player (if 'player' is not NULL)
+     * \return  whether adding was successful (can fail e.g. if trying to add a duplicate)
      */
     bool gotNewPlayerName(const irr::core::stringw& newName,  PlayerProfile* player=NULL);
     void deletePlayer(PlayerProfile* player);
     
-    void init();
-    void tearDown();
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
 };
 
 #endif

src/states_screens/race_setup_screen.cpp

@@ -60,6 +60,12 @@ RaceSetupScreen::RaceSetupScreen() : Screen("racesetup.stkgui")
 
 // -----------------------------------------------------------------------------
 
+void RaceSetupScreen::loadedFromFile()
+{
+}
+
+// -----------------------------------------------------------------------------
+
 void RaceSetupScreen::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
     if (name == "difficulty")

src/states_screens/race_setup_screen.hpp

@@ -40,9 +40,18 @@ class RaceSetupScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingle
     void onGameModeChanged();
     
 public:
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    void init();
-    void tearDown();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
 };
 
 #endif

src/states_screens/tracks_screen.cpp

@@ -42,6 +42,12 @@ DEFINE_SCREEN_SINGLETON( TracksScreen );
 // -----------------------------------------------------------------------------------------------
 
 TracksScreen::TracksScreen() : Screen("tracks.stkgui")
+{
+}
+
+// -----------------------------------------------------------------------------------------------
+
+void TracksScreen::loadedFromFile()
 {
     // Dynamically add tabs
     RibbonWidget* tabs = this->getWidget<RibbonWidget>("trackgroups");

src/states_screens/tracks_screen.hpp

@@ -37,9 +37,18 @@ class TracksScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton
     void buildTrackList();
     
 public:
-    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    void init();
-    void tearDown();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void loadedFromFile();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void init();
+    
+    /** \brief implement callback from parent class GUIEngine::Screen */
+    virtual void tearDown();
     
     void setFocusOnTrack(const std::string& trackName);
     void setFocusOnGP(const std::string& gpName);