CEGUI In Practice - Managing input

Written for CEGUI 0.7

---

Works with versions 0.7.x (obsolete)

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 [1]. 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.

CEGUI::System::injectKeyDown(uint key_code);    // Tells CEGUI Key has been Pressed
CEGUI::System::injectKeyUp(uint key_code);      // Tells CEGUI Key has been Released
 
CEGUI::System::injectChar(utf32 code_point);

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.

CEGUI::System::injectMouseButtonDown(CEGUI::MouseButton::LeftButton);

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

CEGUI::System::injectMouseMove(float delta_x, float delta_y);

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.

CEGUI::System::injectTimePulse(float timeElapsed);

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.

void InjectOISKey(bool bButtonDown, OIS::KeyEvent inKey)
{
	if (bButtonDown)
	{
		CEGUI::System::getSingletonPtr()->injectKeyDown(inKey.key);
		CEGUI::System::getSingletonPtr()->injectChar(inKey.text);
	}
	else
	{
		CEGUI::System::getSingletonPtr()->injectKeyUp(inKey.key);
	}
}

The following function will handle injection of OIS Mouse Button presses and releases

void InjectOISMouseButton(bool bButtonDown, OIS::MouseButtonID inButton)
{
	if (bButtonDown == true)
	{
		switch (inButton)
		{
		case OIS::MB_Left:
			CEGUI::System::getSingletonPtr()->injectMouseButtonDown(CEGUI::MouseButton::LeftButton);
			break;
		case OIS::MB_Middle:
			CEGUI::System::getSingletonPtr()->injectMouseButtonDown(CEGUI::MouseButton::MiddleButton);
			break;
		case OIS::MB_Right:
			mSystem->injectMouseButtonDown(CEGUI::MouseButton::RightButton);
			break;
		case OIS::MB_Button3:
			CEGUI::System::getSingletonPtr()->injectMouseButtonDown(CEGUI::MouseButton::X1Button);
			break;
		case OIS::MB_Button4:
			CEGUI::System::getSingletonPtr()->injectMouseButtonDown(CEGUI::MouseButton::X2Button);
			break;
		case OIS::MB_NULL:	
			break;
 
		}
	}
	else // bButtonDown = false
	{
		switch (inButton)
		{
		case OIS::MB_Left:
			CEGUI::System::getSingletonPtr()->injectMouseButtonUp(CEGUI::MouseButton::LeftButton);
			break;
		case OIS::MB_Middle:
			CEGUI::System::getSingletonPtr()->injectMouseButtonUp(CEGUI::MouseButton::MiddleButton);
			break;
		case OIS::MB_Right:
			CEGUI::System::getSingletonPtr()->injectMouseButtonUp(CEGUI::MouseButton::RightButton);
			break;
		case OIS::MB_Button3:
			CEGUI::System::getSingletonPtr()->injectMouseButtonUp(CEGUI::MouseButton::X1Button);
			break;
		case OIS::MB_Button4:
			CEGUI::System::getSingletonPtr()->injectMouseButtonUp(CEGUI::MouseButton::X2Button);
			break;
		case OIS::MB_NULL:	
			break;
		}
	}
 
}

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!