History: QuickGUI Beginner Tutorial 1

Source of version: 4 (current)

{maketoc}

!Getting Started
!!Header files
To start using QuickGUI in your programs, you must include "QuickGUI.h" in your project.

!!QuickGUI configuration parser
QuickGUI comes with its own parser, which needs to be registered with Ogre before the resource groups have been initialized.

!!STEP 1 : Registering the configuration parser
The parser Initialisation needs to be called before the call to ''Ogre::ResourceGroupManager::initialiseResourceGroups()'', the reason is simple, the Ogre initialisation loads up all resources, so if the parser has not been registered, ogre will not be able to properly interpret QuickGUI configurations of skin files.

To register the parser, the following line should be called:

{CODE(wrap="1", colors="c++")} QuickGUI::registerScriptReader();
{CODE}
If you are following the Example Framework (ExampleApplication.h), a suitable place to make this call could be inside the __void setupResources(void)__ function. Basically call this anywhere before '__Ogre::ResourceGroupManager::initialiseResourceGroups()'__ is called.

!!STEP 2 : create QuickGUI Root
The next step after registering the ScriptReader is to create the Root class. The root class is a Singleton class, and manages creation, access, and destruction of GUIManagers. It also creates and manages other Managers needed by QuickGUI. This call can go anywhere, I place it after Ogre has been fully initialized:

{CODE(wrap="1", colors="c++")}  new QuickGUI::Root();
{CODE}
Make sure to destroy the Root as part of the cleanup process when quitting your application:

{CODE(wrap="1", colors="c++")}  delete QuickGUI::Root::getSingletonPtr();
{CODE}
!!STEP 3 : Loading Widget Skins


With the creation of the Root, the SkinTypeManager has been created. In step one we registered the ScriptReader, and after initialization all *.skinType files were parsed and stored.

In order to use the skins, we have to create SkinType objects. This is done by calling the following:

{CODE(wrap="1", colors="c++")}  QuickGUI::SkinTypeManager::getSingleton().loadTypes();
{CODE}
This iterates through all the script definitions previously loaded, and creates SkinType instances, to allow Widgets to get drawn correctly, according to Skin definitions. Next up, the QuickGUI GUIManager!

!!STEP 4 : Creating GUIManager(s)
Once the Root has been created and the Skins have been loaded, its time to create and use QuickGUI::GUIManager. QuickGUI supports use of Multiple Render Windows. The GUIManager requires an Ogre::Viewport to render to, so this would theoretically support multiple managers in the same window, in different viewports. (not fully tested yet!)

Creation of the GUIManager involves a GUIManagerDesc object:

{CODE(wrap="1", colors="c++")}  QuickGUI::GUIManagerDesc d;
{CODE}
The "desc" object outlines all of the configurable properties of a GUIManager. If you have a specific SceneManager and viewport you want to Render to, now is the time to set them:

{CODE(wrap="1", colors="c++")}  d.sceneManager = mSceneManager;
  d.viewport = mCamera->getViewport();
{CODE}
Also note that the time at which QuickGUI renders the currently active sheet can be configured:

{CODE(wrap="1", colors="c++")}  d.queueID = Ogre::RENDER_QUEUE_OVERLAY;
{CODE}
Rendering is done at the end of the desired Render Queue. Also note that these options do not have to be set prior to GUIManager creation. Safe defaults are assigned, so passing in an unmodified desc object will not cause any problems. (The GUIManager will find and use the first SceneManager and Viewport it comes across) When you have configured the desc object to your liking, use it to create a GUIManager:

{CODE(wrap="1", colors="c++")}  QuickGUI::GUIManager* mGUIManager = QuickGUI::Root::getSingletonPtr()->createGUIManager(d);
{CODE}
Please note that you can also change any of these options after the GUIManager has been created.

!!STEP 5 : Creating and Setting the Active Sheet
The UI is created via the Sheet widget. By settings a GUIManager's active sheet, the GUIManager will draw the contents of the Sheet every frame. There are 3 ways a Sheet can be created:

{CODE(wrap="1", colors="c++")} 1. Using a SheetDesc object
 2. Supplying a filename (.sheet extension)
 3. Supplying a string (containing script defining the Sheet)
{CODE}
Sheets are created via the SheetManager class. Here is an example of creating a simple Sheet of size 800 by 600 pixels:

{CODE(wrap="1", colors="c++")}  QuickGUI::SheetDesc* sd = QuickGUI::DescManager::getSingleton().getDefaultSheetDesc();
  sd->resetToDefault();
  sd->widget_dimensions.size = QuickGUI::Size(800,600);
  QuickGUI::Sheet* mySheet = QuickGUI::SheetManager::getSingleton().createSheet(sd);
{CODE}
And here is how you would create it via file:

{CODE(wrap="1", colors="c++")}  QuickGUI::Sheet* mySheet = QuickGUI::SheetManager::getSingleton().createSheet("mySheetFile.sheet",true);
{CODE}
If the second parameter to the Sheet constructor is set to false, the Sheet will treat the passed in string as the data used to create the Sheet.

After creating the sheet, we can create our UI. When we want to display the UI, pass the Sheet to a GUIManager:

{CODE(wrap="1", colors="c++")}  mGUIManager->setActiveSheet(mySheet);
{CODE}
Now that our Sheet is created, our GUI will be rendered!

!!STEP 6 : Injecting Input
Without input the GUI will not be responsive, so we'll cover that here. The following example is based off OIS callbacks, and using them to inject inputs into a QuickGUI GUIManager object.

{CODE(wrap="1", colors="c++")}  bool Window::keyPressed(const OIS::KeyEvent &arg)
  {
      mGUIManager->injectChar(static_cast<Ogre::UTFString::unicode_char>(arg.text));
      mGUIManager->injectKeyDown(static_cast<QuickGUI::KeyCode>(arg.key));
  
      return true;
  }
  
  bool Window::keyReleased(const OIS::KeyEvent &arg)
  {
      mGUIManager->injectKeyUp(static_cast<QuickGUI::KeyCode>(arg.key));
  
      return true;
  }
  
  bool Window::mouseMoved(const OIS::MouseEvent &arg)
  {
      mGUIManager->injectMousePosition(arg.state.X.abs, arg.state.Y.abs);
  
      float z = arg.state.Z.rel;
      if(z != 0)
          mGUIManager->injectMouseWheelChange(z);
  
      return true;
  }
  
  bool Window::mousePressed(const OIS::MouseEvent &arg, OIS::MouseButtonID id)
  {
      mGUIManager->injectMouseButtonDown(static_cast<QuickGUI::MouseButtonID>(id));
  
      return true;
  }
  
  bool Window::mouseReleased(const OIS::MouseEvent &arg, OIS::MouseButtonID id)
  {
      mGUIManager->injectMouseButtonUp(static_cast<QuickGUI::MouseButtonID>(id));
  
      return true;
  }
{CODE}
!!STEP 7 : Cleaning up QuickGUI


When cleaning up your application, its important that QuickGUI is deleted before Ogre. QuickGUI uses a lot of Ogre::TexturePtr, and destroying Ogre prior to QuickGUI may result in invalid pointers in QuickGUI, which will cause unexpected behavior when QuickGUI tries to clean up its Textures.

!!Conclusion
To restate, a basic code sample would look like this and must follow this sequence :

{CODE(wrap="1", colors="c++")}  new Ogre::Root();
  ...
  QuickGUI::registerScriptReader();
  ...
  Ogre::ResourceGroupManager::initialiseResourceGroups();
  ...
  new QuickGUI::Root();
  QuickGUI::SkinTypeManager::getSingletonPtr()->loadTypes();
  ...
  QuickGUI::GUIManagerDesc d;
  ...
  QuickGUI::GUIManager* gm = QuickGUI::Root::getSingletonPtr()->createGUIManager(d);
  ...
  delete QuickGUI::Root::getSingletonPtr();
  ...
  delete Ogre::Root::getSingletonPtr();
{CODE}

---
Alias: (alias(QuickGUI_Beginner_Tutorial_1))
History: QuickGUI Beginner Tutorial 1

Source of version: 4 (current)

Search by Tags

Latest Changes

Search

Online Users
