Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 2875


Ignore:
Timestamp:
Mar 31, 2009, 2:14:09 PM (15 years ago)
Author:
bknecht
Message:

(Doxygen) Documentation added for GUIManager and some GameState classes.

Location:
code/branches/gui/src/orxonox
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • code/branches/gui/src/orxonox/gamestates/GSGraphics.cc

    r2869 r2875  
    2323 *      Reto Grieder
    2424 *   Co-authors:
    25  *      ...
    26  *
     25 *      Benjamin Knecht
     26 *
     27 */
     28
     29/**
     30    @file
     31    @brief Implementation of Graphics GameState class.
    2732 */
    2833
    … …  
    7176    }
    7277
     78    /**
     79    @brief
     80        this function does nothing
     81
     82        Indeed. Here goes nothing.
     83    */
    7384    void GSGraphics::setConfigValues()
    7485    {
    7586    }
    7687
     88    /**
     89    @brief
     90        This function is called when we enter this game state.
     91
     92        Since graphics is very important for our game this function does quite a lot:
     93        \li starts graphics manager
     94        \li loads debug overlay
     95        \li manages render window
     96        \li creates input manager
     97        \li loads master key bindings
     98        \li loads ingame console
     99        \li loads GUI interface (GUIManager)
     100        \li creates console command to toggle GUI
     101    */
    77102    void GSGraphics::activate()
    78103    {
    … …  
    90115        Loader::open(debugOverlay_);
    91116
    92         // Calls the InputManager which sets up the input devices.
    93117        // The render window width and height are used to set up the mouse movement.
    94         inputManager_ = new InputManager();
    95118        size_t windowHnd = 0;
    96119        Ogre::RenderWindow* renderWindow = GraphicsManager::getInstance().getRenderWindow();
    97120        renderWindow->getCustomAttribute("WINDOW", &windowHnd);
     121
     122        // Calls the InputManager which sets up the input devices.
     123        inputManager_ = new InputManager();
    98124        inputManager_->initialise(windowHnd, renderWindow->getWidth(), renderWindow->getHeight(), true);
    99125
     126        // load master key bindings
    100127        masterInputState_ = InputManager::getInstance().createInputState<SimpleInputState>("master", true);
    101128        masterKeyBinder_ = new KeyBinder();
    … …  
    111138        guiManager_->initialise(renderWindow);
    112139
     140        // add console command to toggle GUI
    113141        FunctorMember<GSGraphics>* functor = createFunctor(&GSGraphics::toggleGUI);
    114142        functor->setObject(this);
    … …  
    116144        CommandExecutor::addConsoleCommandShortcut(this->ccToggleGUI_);
    117145
    118 
     146        // enable master input
    119147        InputManager::getInstance().requestEnterState("master");
    120148    }
    121149
     150    /**
     151    @brief
     152        This function is called when the game state is left
     153
     154        Created references, input states and console commands are deleted.
     155    */
    122156    void GSGraphics::deactivate()
    123157    {
    … …  
    147181    }
    148182
     183    /**
     184    @brief
     185        Toggles the visibility of the current GUI
     186
     187        This function just executes a Lua function in the main script of the GUI by accessing the GUIManager.
     188        For more details on this function check out the Lua code.
     189    */
    149190    void GSGraphics::toggleGUI()
    150191    {

  • code/branches/gui/src/orxonox/gamestates/GSGraphics.h

    r2869 r2875  
    2323 *      Reto Grieder
    2424 *   Co-authors:
    25  *      ...
     25 *      Benjamin Knecht (documentation)
    2626 *
    2727 */
     28
     29 /**
     30    @file
     31    @brief Declaration of the Graphics GameState class.
     32  */
    2833
    2934#ifndef _GSGraphics_H__
    … …  
    3641namespace orxonox
    3742{
     43    /**
     44    @class GSGraphics
     45    @brief
     46        Game state used when displaying graphics of any kind
     47
     48        This game state is only left out if we start a dedicated server where no graphics are present.
     49    */
    3850    class _OrxonoxExport GSGraphics : public GameState, public WindowEventListener
    3951    {
    … …  
    5567
    5668        // managed singletons
    57         InputManager*         inputManager_;
     69        InputManager*         inputManager_;        //!< Reference to input management
    5870        InGameConsole*        console_;
    59         GUIManager*           guiManager_;
    60         GraphicsManager*      graphicsManager_;       //!< Interface to Ogre
     71        GUIManager*           guiManager_;          //!< Interface to GUI
     72        GraphicsManager*      graphicsManager_;     //!< Interface to Ogre
    6173
    62         KeyBinder*            masterKeyBinder_;
    63         SimpleInputState*     masterInputState_;
     74        KeyBinder*            masterKeyBinder_;     //!< Key binder for master key bindings
     75        SimpleInputState*     masterInputState_;    //!< Special input state for master input
    6476        XMLFile*              debugOverlay_;
    65         ConsoleCommand*       ccToggleGUI_;
     77        ConsoleCommand*       ccToggleGUI_;         //!< Console command to toggle GUI
    6678    };
    6779}

  • code/branches/gui/src/orxonox/gamestates/GSLevel.cc

    r2869 r2875  
    2424 *   Co-authors:
    2525 *      Fabian 'x3n' Landau
     26 *      Benjamin Knecht
    2627 *
    2728 */
    … …  
    5657
    5758    SetCommandLineArgument(level, "presentation.oxw").shortcut("l");
    58     SetConsoleCommand(GSLevel, showIngameGUI, true).keybindMode(KeybindMode::OnPress).keybindMode(KeybindMode::OnRelease);
     59    SetConsoleCommand(GSLevel, showIngameGUI, true);
    5960
    6061    GSLevel::GSLevel(const std::string& name)

  • code/branches/gui/src/orxonox/gamestates/GSLevel.h

    r2869 r2875  
    2323 *      Reto Grieder
    2424 *   Co-authors:
    25  *      ...
     25 *      Benjamin Knecht
    2626 *
    2727 */
    … …  
    6464        Radar*                radar_;                   //!< represents the Radar (not the HUD part)
    6565        XMLFile*              startFile_;               //!< current hard coded default level
    66         CameraManager*        cameraManager_;
    67         LevelManager*         levelManager_;
    68         PlayerManager*        playerManager_;
     66        CameraManager*        cameraManager_;           //!< camera manager for this level
     67        LevelManager*         levelManager_;            //!< global level manager
     68        PlayerManager*        playerManager_;           //!< player manager for this level
    6969
    7070        //##### ConfigValues #####

  • code/branches/gui/src/orxonox/gui/GUIManager.cc

    r2869 r2875  
    2222 *   Author:
    2323 *      Reto Grieder
     24 *      Benjamin Knecht
    2425 *   Co-authors:
    25  *      Benjamin Knecht
     26 *
    2627 *
    2728 */
    … …  
    7576    }
    7677
     78    /**
     79    @brief
     80        Deconstructor of the GUIManager
     81
     82        Basically shuts down CEGUI and destroys the Lua engine and afterwards the interface to the Ogre engine.
     83    */
    7784    GUIManager::~GUIManager()
    7885    {
    … …  
    96103    }
    97104
     105    /**
     106    @brief
     107        Initialises the GUIManager by starting up CEGUI
     108    @param renderWindow
     109        Ogre's render window. Without this, the GUI cannot be displayed.
     110    @return true if success, otherwise false
     111
     112        Before this call the GUIManager won't do anything, but can be accessed.
     113
     114        Creates the interface to Ogre, sets up the CEGUI renderer and the Lua script module together with the Lua engine.
     115        The log is set up and connected to the CEGUILogger.
     116        After Lua setup tolua++-elements are linked to Lua-state to give Lua access to C++-code.
     117        Finally initial Lua code is executed (maybe we can do this with the CEGUI startup script automatically).
     118    */
    98119    bool GUIManager::initialise(Ogre::RenderWindow* renderWindow)
    99120    {
    … …  
    151172    }
    152173
     174    /**
     175    @brief
     176        Calls main Lua script
     177    @todo
     178        Replace loadGUI.lua with loadGUI_2.lua after merging this back to trunk.
     179        However CEGUI is able to execute a startup script. We could maybe put this call in this startup code.
     180
     181        This function calls the main Lua script for our GUI.
     182
     183        Additionally we set the datapath variable in Lua. This is needed so Lua can access the data used for the GUI.
     184    */
    153185    void GUIManager::loadLuaCode()
    154186    {
    155187        try
    156188        {
     189            // call main Lua script
    157190            this->scriptModule_->executeScriptFile("loadGUI_2.lua", "GUI");
     191            // set datapath for GUI data
    158192            lua_pushfstring(this->scriptModule_->getLuaState(), Core::getMediaPathString().c_str());
    159193            lua_setglobal(this->scriptModule_->getLuaState(), "datapath");
    … …  
    170204    }
    171205
     206    /**
     207    @brief
     208        used to tick the GUI
     209    @param time
     210        clock which provides time value for the GUI System
     211
     212        Ticking the GUI means updating it with a certain regularity.
     213        The elapsed time since the last call is given in the time value provided by the clock.
     214        This time value is then used to provide a fluent animation of the GUI.
     215    */
    172216    void GUIManager::update(const Clock& time)
    173217    {
    … …  
    176220    }
    177221
     222    /**
     223    @brief
     224        Executes Lua code
     225    @param str
     226        reference to string object holding the Lua code which is to be executed
     227
     228        This function gives total access to the GUI. You can execute ANY Lua code here.
     229    */
    178230    void GUIManager::executeCode(const std::string& str)
    179231    {
    … …  
    181233    }
    182234
     235    /**
     236    @brief
     237        Tells the GUIManager which SceneManager to use
     238    @param camera
     239        The current camera on which the GUI should be displayed on.
     240
     241        In fact the GUIManager needs the SceneManager and not the Camera to display the GUI.
     242        This means the GUI is not bound to a camera but rather to the SceneManager.
     243        Hidding the GUI when needed can therefore not be solved by just NOT setting the current camera.
     244    */
    183245    void GUIManager::setCamera(Ogre::Camera* camera)
    184246    {
    … …  
    186248    }
    187249
     250    /**
     251    @brief
     252        Debug function to give CEGUI the possibility to output on our console
     253    @param
     254        String to be displaed in CEGUI's name
     255
     256        This function should be removed as it only provides a quick (and dirty) possibility to access the output on the console.
     257        CEGUI's output should be put into the cegui.log using the CEGUI Logger.
     258    */
    188259    void GUIManager::testOutput(std::string& str)
    189260    {
    … …  
    191262    }
    192263
     264    /**
     265    @brief
     266        Displays specified GUI on screen
     267    @param name
     268        The name of the GUI
     269
     270        The function executes the Lua function with the same name in case the GUIManager is ready.
     271        For more details check out loadGUI_2.lua where the function presides.
     272    */
    193273    void GUIManager::showGUI(const std::string& name)
    194274    {
    … …  
    215295    }
    216296
     297    /**
     298    @brief
     299        Function receiving a mouse button pressed event.
     300    @param id
     301        ID of the mouse button which got pressed
     302
     303        This function is inherited by MouseHandler and injects the event into CEGUI.
     304        It is for CEGUI to process the event.
     305    */
    217306    void GUIManager::mouseButtonPressed(MouseButtonCode::ByEnum id)
    218307    {
    … …  
    228317    }
    229318
     319    /**
     320    @brief
     321        Function receiving a mouse button released event.
     322    @param id
     323        ID of the mouse button which got released
     324
     325        This function is inherited by MouseHandler and injects the event into CEGUI.
     326        It is for CEGUI to process the event.
     327    */
    230328    void GUIManager::mouseButtonReleased(MouseButtonCode::ByEnum id)
    231329    {
    … …  
    241339    }
    242340
    243 
     341    /**
     342    @brief
     343        converts mouse event code to CEGUI event code
     344    @param button
     345        code of the mouse button as we use it in Orxonox
     346    @return
     347        code of the mouse button as it is used by CEGUI
     348
     349        Simple convertion from mouse event code in Orxonox to the one used in CEGUI.
     350     */
    244351    inline CEGUI::MouseButton GUIManager::convertButton(MouseButtonCode::ByEnum button)
    245352    {

  • code/branches/gui/src/orxonox/gui/GUIManager.h

    r2853 r2875  
    2323 *      Reto Grieder
    2424 *   Co-authors:
    25  *      ...
     25 *      Benjamin Knecht
    2626 *
    2727 */
    … …  
    4949{
    5050    /**
     51    @class GUIManager
    5152    @brief
    52         Provides a simple interface to CEGUI with tolua methods and console commands
     53        Provides a simple interface to CEGUI with tolua methods and console commands. It also acts as a key and mouse handler.
     54
     55        The GUIManager is a singleton and can be called anywhere when access on the GUI is needed.
     56        Creation of the GUIManager is therefore not possible and the cunstructor is private.
     57
     58        Since the GUI needs user input, the GUIManager implements the functions needed to act as a key and/or mouse handler.
     59        Those input events are then injected into CEGUI in Lua.
    5360    */
    5461    class _OrxonoxExport GUIManager
    … …  
    5966// tolua_end
    6067    public:
     68        /**
     69        @enum State
     70            The current state of the GUIManager. There should maybe be more (or we can omit this totally).
     71        */
    6172        enum State
    6273        {
    63             Uninitialised,
    64             Ready,
    65             OnDisplay
     74            Uninitialised,  //!< Initial state of the GUIManager
     75            Ready,          //!< State after initialisation if ready
     76            OnDisplay       //!< State if GUI is displayed
    6677        };
    6778
    … …  
    8495
    8596    private:
    86         GUIManager(const GUIManager& instance);
     97        GUIManager(const GUIManager& instance);                 //!< private constructor (this is a singleton class)
    8798
    8899        void loadLuaCode();
    89100
     101        // keyHandler functions
    90102        void keyPressed (const KeyEvent& evt)
    91         { guiSystem_->injectKeyDown(evt.key); guiSystem_->injectChar(evt.text); }
     103            { guiSystem_->injectKeyDown(evt.key); guiSystem_->injectChar(evt.text); }
    92104        void keyReleased(const KeyEvent& evt)
    93         { guiSystem_->injectKeyUp(evt.key); }
    94         void keyHeld    (const KeyEvent& evt)
    95         { }
     105            { guiSystem_->injectKeyUp(evt.key); }
     106        void keyHeld    (const KeyEvent& evt) { }
    96107
     108        // mouseHandler functions
    97109        void mouseButtonPressed (MouseButtonCode::ByEnum id);
    98110        void mouseButtonReleased(MouseButtonCode::ByEnum id);
    99         void mouseButtonHeld    (MouseButtonCode::ByEnum id)
    100         { }
     111        void mouseButtonHeld    (MouseButtonCode::ByEnum id) { }
    101112        void mouseMoved         (IntVector2 abs, IntVector2 rel, IntVector2 clippingSize)
    102         { guiSystem_->injectMouseMove(rel.x, rel.y); }
     113            { guiSystem_->injectMouseMove(rel.x, rel.y); }
    103114        void mouseScrolled      (int abs, int rel)
    104         { guiSystem_->injectMouseWheelChange(rel);}
     115            { guiSystem_->injectMouseWheelChange(rel);}
    105116
    106         void updateInput(float dt) { }
    107         void updateKey(float dt) { }
    108         void updateMouse(float dt) { }
    109 
    110         Ogre::RenderWindow*       renderWindow_;
    111         CEGUI::OgreCEGUIRenderer* guiRenderer_;
    112         CEGUI::ResourceProvider*  resourceProvider_;
    113         CEGUI::LuaScriptModule*   scriptModule_;
    114         CEGUI::DefaultLogger*     ceguiLogger_;
    115         CEGUI::System*            guiSystem_;
    116         CEGUI::Imageset*          backgroundImage_;
    117         lua_State*                luaState_;
    118 
    119         State state_;
     117        void updateInput(float dt)  { }
     118        void updateKey  (float dt)  { }
     119        void updateMouse(float dt)  { }
    120120
    121121        static CEGUI::MouseButton convertButton(MouseButtonCode::ByEnum button);
    122122
    123         static GUIManager*        singletonRef_s;
     123        Ogre::RenderWindow*         renderWindow_;      //!< Ogre's render window to give CEGUI access to it
     124        CEGUI::OgreCEGUIRenderer*   guiRenderer_;       //!< CEGUI's interface to the Ogre Engine
     125        CEGUI::ResourceProvider*    resourceProvider_;  //!< CEGUI's resource provider
     126        CEGUI::LuaScriptModule*     scriptModule_;      //!< CEGUI's script module to use Lua
     127        CEGUI::DefaultLogger*       ceguiLogger_;       //!< CEGUI's logger to be able to log CEGUI errors in our log
     128        CEGUI::System*              guiSystem_;         //!< CEGUI's main system
     129        lua_State*                  luaState_;          //!< Lua state, access point to the Lua engine
     130
     131        State                       state_;             //!< reflects state of the GUIManager
     132
     133        static GUIManager*          singletonRef_s;     //!< Singleton reference to GUIManager
    124134    }; // tolua_export
    125135} // tolua_export
Note: See TracChangeset for help on using the changeset viewer.