[Orxonox-commit 205] r2875 - in branches/gui/src/orxonox: gamestates gui
bknecht at orxonox.net
bknecht at orxonox.net
Tue Mar 31 14:14:09 CEST 2009
Author: bknecht
Date: 2009-03-31 12:14:09 +0000 (Tue, 31 Mar 2009)
New Revision: 2875
Modified:
branches/gui/src/orxonox/gamestates/GSGraphics.cc
branches/gui/src/orxonox/gamestates/GSGraphics.h
branches/gui/src/orxonox/gamestates/GSLevel.cc
branches/gui/src/orxonox/gamestates/GSLevel.h
branches/gui/src/orxonox/gui/GUIManager.cc
branches/gui/src/orxonox/gui/GUIManager.h
Log:
(Doxygen) Documentation added for GUIManager and some GameState classes.
Modified: branches/gui/src/orxonox/gamestates/GSGraphics.cc
===================================================================
--- branches/gui/src/orxonox/gamestates/GSGraphics.cc 2009-03-31 10:10:42 UTC (rev 2874)
+++ branches/gui/src/orxonox/gamestates/GSGraphics.cc 2009-03-31 12:14:09 UTC (rev 2875)
@@ -22,10 +22,15 @@
* Author:
* Reto Grieder
* Co-authors:
- * ...
+ * Benjamin Knecht
*
*/
+/**
+ @file
+ @brief Implementation of Graphics GameState class.
+ */
+
#include "OrxonoxStableHeaders.h"
#include "GSGraphics.h"
@@ -70,10 +75,30 @@
{
}
+ /**
+ @brief
+ this function does nothing
+
+ Indeed. Here goes nothing.
+ */
void GSGraphics::setConfigValues()
{
}
+ /**
+ @brief
+ This function is called when we enter this game state.
+
+ Since graphics is very important for our game this function does quite a lot:
+ \li starts graphics manager
+ \li loads debug overlay
+ \li manages render window
+ \li creates input manager
+ \li loads master key bindings
+ \li loads ingame console
+ \li loads GUI interface (GUIManager)
+ \li creates console command to toggle GUI
+ */
void GSGraphics::activate()
{
GameMode::setShowsGraphics(true);
@@ -89,14 +114,16 @@
this->debugOverlay_ = new XMLFile((Core::getMediaPath() / "overlay" / "debug.oxo").string());
Loader::open(debugOverlay_);
- // Calls the InputManager which sets up the input devices.
// The render window width and height are used to set up the mouse movement.
- inputManager_ = new InputManager();
size_t windowHnd = 0;
Ogre::RenderWindow* renderWindow = GraphicsManager::getInstance().getRenderWindow();
renderWindow->getCustomAttribute("WINDOW", &windowHnd);
+
+ // Calls the InputManager which sets up the input devices.
+ inputManager_ = new InputManager();
inputManager_->initialise(windowHnd, renderWindow->getWidth(), renderWindow->getHeight(), true);
+ // load master key bindings
masterInputState_ = InputManager::getInstance().createInputState<SimpleInputState>("master", true);
masterKeyBinder_ = new KeyBinder();
masterKeyBinder_->loadBindings("masterKeybindings.ini");
@@ -110,15 +137,22 @@
guiManager_ = new GUIManager();
guiManager_->initialise(renderWindow);
+ // add console command to toggle GUI
FunctorMember<GSGraphics>* functor = createFunctor(&GSGraphics::toggleGUI);
functor->setObject(this);
this->ccToggleGUI_ = createConsoleCommand(functor, "toggleGUI");
CommandExecutor::addConsoleCommandShortcut(this->ccToggleGUI_);
-
+ // enable master input
InputManager::getInstance().requestEnterState("master");
}
+ /**
+ @brief
+ This function is called when the game state is left
+
+ Created references, input states and console commands are deleted.
+ */
void GSGraphics::deactivate()
{
@@ -146,6 +180,13 @@
GameMode::setShowsGraphics(false);
}
+ /**
+ @brief
+ Toggles the visibility of the current GUI
+
+ This function just executes a Lua function in the main script of the GUI by accessing the GUIManager.
+ For more details on this function check out the Lua code.
+ */
void GSGraphics::toggleGUI()
{
GUIManager::getInstance().executeCode("toggleGUI()");
Modified: branches/gui/src/orxonox/gamestates/GSGraphics.h
===================================================================
--- branches/gui/src/orxonox/gamestates/GSGraphics.h 2009-03-31 10:10:42 UTC (rev 2874)
+++ branches/gui/src/orxonox/gamestates/GSGraphics.h 2009-03-31 12:14:09 UTC (rev 2875)
@@ -22,10 +22,15 @@
* Author:
* Reto Grieder
* Co-authors:
- * ...
+ * Benjamin Knecht (documentation)
*
*/
+ /**
+ @file
+ @brief Declaration of the Graphics GameState class.
+ */
+
#ifndef _GSGraphics_H__
#define _GSGraphics_H__
@@ -35,6 +40,13 @@
namespace orxonox
{
+ /**
+ @class GSGraphics
+ @brief
+ Game state used when displaying graphics of any kind
+
+ This game state is only left out if we start a dedicated server where no graphics are present.
+ */
class _OrxonoxExport GSGraphics : public GameState, public WindowEventListener
{
public:
@@ -54,15 +66,15 @@
void windowFocusChanged();
// managed singletons
- InputManager* inputManager_;
+ InputManager* inputManager_; //!< Reference to input management
InGameConsole* console_;
- GUIManager* guiManager_;
- GraphicsManager* graphicsManager_; //!< Interface to Ogre
+ GUIManager* guiManager_; //!< Interface to GUI
+ GraphicsManager* graphicsManager_; //!< Interface to Ogre
- KeyBinder* masterKeyBinder_;
- SimpleInputState* masterInputState_;
+ KeyBinder* masterKeyBinder_; //!< Key binder for master key bindings
+ SimpleInputState* masterInputState_; //!< Special input state for master input
XMLFile* debugOverlay_;
- ConsoleCommand* ccToggleGUI_;
+ ConsoleCommand* ccToggleGUI_; //!< Console command to toggle GUI
};
}
Modified: branches/gui/src/orxonox/gamestates/GSLevel.cc
===================================================================
--- branches/gui/src/orxonox/gamestates/GSLevel.cc 2009-03-31 10:10:42 UTC (rev 2874)
+++ branches/gui/src/orxonox/gamestates/GSLevel.cc 2009-03-31 12:14:09 UTC (rev 2875)
@@ -23,6 +23,7 @@
* Reto Grieder
* Co-authors:
* Fabian 'x3n' Landau
+ * Benjamin Knecht
*
*/
@@ -55,7 +56,7 @@
AddGameState(GSLevel, "level");
SetCommandLineArgument(level, "presentation.oxw").shortcut("l");
- SetConsoleCommand(GSLevel, showIngameGUI, true).keybindMode(KeybindMode::OnPress).keybindMode(KeybindMode::OnRelease);
+ SetConsoleCommand(GSLevel, showIngameGUI, true);
GSLevel::GSLevel(const std::string& name)
: GameState(name)
Modified: branches/gui/src/orxonox/gamestates/GSLevel.h
===================================================================
--- branches/gui/src/orxonox/gamestates/GSLevel.h 2009-03-31 10:10:42 UTC (rev 2874)
+++ branches/gui/src/orxonox/gamestates/GSLevel.h 2009-03-31 12:14:09 UTC (rev 2875)
@@ -22,7 +22,7 @@
* Author:
* Reto Grieder
* Co-authors:
- * ...
+ * Benjamin Knecht
*
*/
@@ -63,9 +63,9 @@
SimpleInputState* guiKeysOnlyInputState_; //!< input state if we only need the keys to use the GUI
Radar* radar_; //!< represents the Radar (not the HUD part)
XMLFile* startFile_; //!< current hard coded default level
- CameraManager* cameraManager_;
- LevelManager* levelManager_;
- PlayerManager* playerManager_;
+ CameraManager* cameraManager_; //!< camera manager for this level
+ LevelManager* levelManager_; //!< global level manager
+ PlayerManager* playerManager_; //!< player manager for this level
//##### ConfigValues #####
std::string keyDetectorCallbackCode_;
Modified: branches/gui/src/orxonox/gui/GUIManager.cc
===================================================================
--- branches/gui/src/orxonox/gui/GUIManager.cc 2009-03-31 10:10:42 UTC (rev 2874)
+++ branches/gui/src/orxonox/gui/GUIManager.cc 2009-03-31 12:14:09 UTC (rev 2875)
@@ -21,9 +21,10 @@
*
* Author:
* Reto Grieder
+ * Benjamin Knecht
* Co-authors:
- * Benjamin Knecht
*
+ *
*/
/**
@@ -74,6 +75,12 @@
singletonRef_s = this;
}
+ /**
+ @brief
+ Deconstructor of the GUIManager
+
+ Basically shuts down CEGUI and destroys the Lua engine and afterwards the interface to the Ogre engine.
+ */
GUIManager::~GUIManager()
{
if (guiSystem_)
@@ -95,6 +102,20 @@
singletonRef_s = 0;
}
+ /**
+ @brief
+ Initialises the GUIManager by starting up CEGUI
+ @param renderWindow
+ Ogre's render window. Without this, the GUI cannot be displayed.
+ @return true if success, otherwise false
+
+ Before this call the GUIManager won't do anything, but can be accessed.
+
+ Creates the interface to Ogre, sets up the CEGUI renderer and the Lua script module together with the Lua engine.
+ The log is set up and connected to the CEGUILogger.
+ After Lua setup tolua++-elements are linked to Lua-state to give Lua access to C++-code.
+ Finally initial Lua code is executed (maybe we can do this with the CEGUI startup script automatically).
+ */
bool GUIManager::initialise(Ogre::RenderWindow* renderWindow)
{
using namespace CEGUI;
@@ -150,11 +171,24 @@
return true;
}
+ /**
+ @brief
+ Calls main Lua script
+ @todo
+ Replace loadGUI.lua with loadGUI_2.lua after merging this back to trunk.
+ However CEGUI is able to execute a startup script. We could maybe put this call in this startup code.
+
+ This function calls the main Lua script for our GUI.
+
+ Additionally we set the datapath variable in Lua. This is needed so Lua can access the data used for the GUI.
+ */
void GUIManager::loadLuaCode()
{
try
{
+ // call main Lua script
this->scriptModule_->executeScriptFile("loadGUI_2.lua", "GUI");
+ // set datapath for GUI data
lua_pushfstring(this->scriptModule_->getLuaState(), Core::getMediaPathString().c_str());
lua_setglobal(this->scriptModule_->getLuaState(), "datapath");
}
@@ -169,27 +203,73 @@
}
}
+ /**
+ @brief
+ used to tick the GUI
+ @param time
+ clock which provides time value for the GUI System
+
+ Ticking the GUI means updating it with a certain regularity.
+ The elapsed time since the last call is given in the time value provided by the clock.
+ This time value is then used to provide a fluent animation of the GUI.
+ */
void GUIManager::update(const Clock& time)
{
assert(guiSystem_);
guiSystem_->injectTimePulse(time.getDeltaTime());
}
+ /**
+ @brief
+ Executes Lua code
+ @param str
+ reference to string object holding the Lua code which is to be executed
+
+ This function gives total access to the GUI. You can execute ANY Lua code here.
+ */
void GUIManager::executeCode(const std::string& str)
{
this->scriptModule_->executeString(str);
}
+ /**
+ @brief
+ Tells the GUIManager which SceneManager to use
+ @param camera
+ The current camera on which the GUI should be displayed on.
+
+ In fact the GUIManager needs the SceneManager and not the Camera to display the GUI.
+ This means the GUI is not bound to a camera but rather to the SceneManager.
+ Hidding the GUI when needed can therefore not be solved by just NOT setting the current camera.
+ */
void GUIManager::setCamera(Ogre::Camera* camera)
{
this->guiRenderer_->setTargetSceneManager(camera->getSceneManager());
}
+ /**
+ @brief
+ Debug function to give CEGUI the possibility to output on our console
+ @param
+ String to be displaed in CEGUI's name
+
+ This function should be removed as it only provides a quick (and dirty) possibility to access the output on the console.
+ CEGUI's output should be put into the cegui.log using the CEGUI Logger.
+ */
void GUIManager::testOutput(std::string& str)
{
COUT(0) << "*** CEGUI: " << str << std::endl;
}
+ /**
+ @brief
+ Displays specified GUI on screen
+ @param name
+ The name of the GUI
+
+ The function executes the Lua function with the same name in case the GUIManager is ready.
+ For more details check out loadGUI_2.lua where the function presides.
+ */
void GUIManager::showGUI(const std::string& name)
{
if (state_ != Uninitialised)
@@ -214,6 +294,15 @@
}
}
+ /**
+ @brief
+ Function receiving a mouse button pressed event.
+ @param id
+ ID of the mouse button which got pressed
+
+ This function is inherited by MouseHandler and injects the event into CEGUI.
+ It is for CEGUI to process the event.
+ */
void GUIManager::mouseButtonPressed(MouseButtonCode::ByEnum id)
{
try
@@ -227,6 +316,15 @@
}
}
+ /**
+ @brief
+ Function receiving a mouse button released event.
+ @param id
+ ID of the mouse button which got released
+
+ This function is inherited by MouseHandler and injects the event into CEGUI.
+ It is for CEGUI to process the event.
+ */
void GUIManager::mouseButtonReleased(MouseButtonCode::ByEnum id)
{
try
@@ -240,7 +338,16 @@
}
}
+ /**
+ @brief
+ converts mouse event code to CEGUI event code
+ @param button
+ code of the mouse button as we use it in Orxonox
+ @return
+ code of the mouse button as it is used by CEGUI
+ Simple convertion from mouse event code in Orxonox to the one used in CEGUI.
+ */
inline CEGUI::MouseButton GUIManager::convertButton(MouseButtonCode::ByEnum button)
{
switch (button)
Modified: branches/gui/src/orxonox/gui/GUIManager.h
===================================================================
--- branches/gui/src/orxonox/gui/GUIManager.h 2009-03-31 10:10:42 UTC (rev 2874)
+++ branches/gui/src/orxonox/gui/GUIManager.h 2009-03-31 12:14:09 UTC (rev 2875)
@@ -22,7 +22,7 @@
* Author:
* Reto Grieder
* Co-authors:
- * ...
+ * Benjamin Knecht
*
*/
@@ -48,8 +48,15 @@
namespace orxonox
{
/**
+ @class GUIManager
@brief
- Provides a simple interface to CEGUI with tolua methods and console commands
+ Provides a simple interface to CEGUI with tolua methods and console commands. It also acts as a key and mouse handler.
+
+ The GUIManager is a singleton and can be called anywhere when access on the GUI is needed.
+ Creation of the GUIManager is therefore not possible and the cunstructor is private.
+
+ Since the GUI needs user input, the GUIManager implements the functions needed to act as a key and/or mouse handler.
+ Those input events are then injected into CEGUI in Lua.
*/
class _OrxonoxExport GUIManager
// tolua_end
@@ -58,11 +65,15 @@
{
// tolua_end
public:
+ /**
+ @enum State
+ The current state of the GUIManager. There should maybe be more (or we can omit this totally).
+ */
enum State
{
- Uninitialised,
- Ready,
- OnDisplay
+ Uninitialised, //!< Initial state of the GUIManager
+ Ready, //!< State after initialisation if ready
+ OnDisplay //!< State if GUI is displayed
};
GUIManager();
@@ -83,44 +94,43 @@
static GUIManager* getInstancePtr() { return singletonRef_s; }
private:
- GUIManager(const GUIManager& instance);
+ GUIManager(const GUIManager& instance); //!< private constructor (this is a singleton class)
void loadLuaCode();
+ // keyHandler functions
void keyPressed (const KeyEvent& evt)
- { guiSystem_->injectKeyDown(evt.key); guiSystem_->injectChar(evt.text); }
+ { guiSystem_->injectKeyDown(evt.key); guiSystem_->injectChar(evt.text); }
void keyReleased(const KeyEvent& evt)
- { guiSystem_->injectKeyUp(evt.key); }
- void keyHeld (const KeyEvent& evt)
- { }
+ { guiSystem_->injectKeyUp(evt.key); }
+ void keyHeld (const KeyEvent& evt) { }
+ // mouseHandler functions
void mouseButtonPressed (MouseButtonCode::ByEnum id);
void mouseButtonReleased(MouseButtonCode::ByEnum id);
- void mouseButtonHeld (MouseButtonCode::ByEnum id)
- { }
+ void mouseButtonHeld (MouseButtonCode::ByEnum id) { }
void mouseMoved (IntVector2 abs, IntVector2 rel, IntVector2 clippingSize)
- { guiSystem_->injectMouseMove(rel.x, rel.y); }
+ { guiSystem_->injectMouseMove(rel.x, rel.y); }
void mouseScrolled (int abs, int rel)
- { guiSystem_->injectMouseWheelChange(rel);}
+ { guiSystem_->injectMouseWheelChange(rel);}
- void updateInput(float dt) { }
- void updateKey(float dt) { }
- void updateMouse(float dt) { }
+ void updateInput(float dt) { }
+ void updateKey (float dt) { }
+ void updateMouse(float dt) { }
- Ogre::RenderWindow* renderWindow_;
- CEGUI::OgreCEGUIRenderer* guiRenderer_;
- CEGUI::ResourceProvider* resourceProvider_;
- CEGUI::LuaScriptModule* scriptModule_;
- CEGUI::DefaultLogger* ceguiLogger_;
- CEGUI::System* guiSystem_;
- CEGUI::Imageset* backgroundImage_;
- lua_State* luaState_;
+ static CEGUI::MouseButton convertButton(MouseButtonCode::ByEnum button);
- State state_;
+ Ogre::RenderWindow* renderWindow_; //!< Ogre's render window to give CEGUI access to it
+ CEGUI::OgreCEGUIRenderer* guiRenderer_; //!< CEGUI's interface to the Ogre Engine
+ CEGUI::ResourceProvider* resourceProvider_; //!< CEGUI's resource provider
+ CEGUI::LuaScriptModule* scriptModule_; //!< CEGUI's script module to use Lua
+ CEGUI::DefaultLogger* ceguiLogger_; //!< CEGUI's logger to be able to log CEGUI errors in our log
+ CEGUI::System* guiSystem_; //!< CEGUI's main system
+ lua_State* luaState_; //!< Lua state, access point to the Lua engine
- static CEGUI::MouseButton convertButton(MouseButtonCode::ByEnum button);
+ State state_; //!< reflects state of the GUIManager
- static GUIManager* singletonRef_s;
+ static GUIManager* singletonRef_s; //!< Singleton reference to GUIManager
}; // tolua_export
} // tolua_export
More information about the Orxonox-commit
mailing list