CEGUI In Practice - Managing input

2014-04-12T02:46:52Z

Thomas: /* On ward! */

{{VersionBadge|0.8}}
{{Series|CEGUI In Practice|3}}

== CEGUI In-Practice ==

Once again Welcome back! In this tutorial we will learn how to interact with the CEGUI System at runtime, a VERY useful feature to have for a Graphical User '''Interface'''!

CEGUI Has been designed to work on many systems, using many different renderers. As such it is tied to no particular input system. Unfortunately for us to demonstrate how to interact with CEGUI, we need to pick one and USE it don't we? So I have decided to use OIS [http://sourceforge.net/projects/wgois/]. Although I will attempt to keep OIS Specific functions and structures seperate, if they slip in, there is the reference to the system I'm using.

==== Input Injection ====

The first thing to note, is that not surprisingly CEGUI has made it easy to deal with inputing user actions into CEGUI. Whenever an action happens (User typing, hitting Escape, clicking a button) CEGUI will need to be informed about it.

<source lang="cpp">
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyDown(uint key_code); // Tells CEGUI Key has been Pressed
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyUp(uint key_code); // Tells CEGUI Key has been Released

CEGUI::System::getSingleton().getDefaultGUIContext().injectChar(utf32 code_point);
</source>

The Inject keydown/up are good for sending Shift, controls, enters, etc. While the injectChar is pretty self explanatory for what it means, it injects a 'letter'.

Handling the mouse works in a similiar method as above. The following code shows how you would inform CEGUI about a Left Mouse Button Keypress.
<source lang="cpp">CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::MouseButton::LeftButton);</source>

As you can imagine, there is a injectMouseButtonUp() as well for letting CEGUI know when the mouse is released.

And what about when the mouse itself moves? Of course thats covered

<source lang="cpp">CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseMove(float delta_x, float delta_y);</source>

The delta is in Screen pixels that the mouse moved since the last CEGUI Update.

Up until know, we haven't actually given CEGUI any processor time. If we're going to be moving a mouse, or clicking buttons, we're going to want CEGUI to display these actions. So we need to let CEGUI know how much time has passed since its last render.

<source lang="cpp">CEGUI::System::getSingleton().injectTimePulse(float timeElapsed);</source>

This allows you to inject a time pulse, based on the number of Seconds that have passed. However often you update CEGUI is up to you, but most games will want to update the GUI by injectingTime pulses during every update cycle. If you're building more of a Tool Application you might not need constant updates.

==== On ward! ====

I'm going to assume that you are using OIS and are knowledgable about its uses. Here are two functions which will allow you to interact with CEGUI

The following will input keypresses when typing. It injects the key down and up actions (By key code) and the characters that associate with those keypresses.

Note: OIS key code needs to be cast to CEGUI for this to work.

<source lang="cpp">
void InjectOISKey(bool bButtonDown, OIS::KeyEvent inKey)
{
if (bButtonDown)
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyDown((CEGUI::Key::Scan)inKey.key);
CEGUI::System::getSingleton().getDefaultGUIContext().injectChar(inKey.text);
}
else
{
CEGUI::System::getSingleton().getDefaultGUIContext().injectKeyUp((CEGUI::Key::Scan)inKey.key);
}
}
</source>

The following function will handle injection of OIS Mouse Button presses and releases
<source lang="cpp">
void InjectOISMouseButton(bool bButtonDown, OIS::MouseButtonID inButton)
{
if (bButtonDown == true)
{
switch (inButton)
{
case OIS::MB_Left:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::LeftButton);
break;
case OIS::MB_Middle:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::MiddleButton);
break;
case OIS::MB_Right:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::RightButton);
break;
case OIS::MB_Button3:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::X1Button);
break;
case OIS::MB_Button4:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonDown(CEGUI::X2Button);
break;
default:
break;

}
}
else // bButtonDown = false
{
switch (inButton)
{
case OIS::MB_Left:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::LeftButton);
break;
case OIS::MB_Middle:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::MiddleButton);
break;
case OIS::MB_Right:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::RightButton);
break;
case OIS::MB_Button3:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::X1Button);
break;
case OIS::MB_Button4:
CEGUI::System::getSingleton().getDefaultGUIContext().injectMouseButtonUp(CEGUI::X2Button);
break;
default:
break;
}
}

}
</source>

This above function will Convert a OIS Input for the mouse and change it to CEGUI. Right now the codes match, but if they ever change it will provide an example of how to use OIS with CEGUI.

==== Conclusion ====

Understandably this section is a little quicker. But it gives you information about how to start interacting with CEGUI. The next tutorial will teach us how to actually deal with keypresses and make interesting things happen. Until then!

[[Category:Tutorials]]