Difference between revisions of "CEGUI In Practice - Managing input"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
m (Robot: Cosmetic changes)
Line 1: Line 1:
 
{{VersionBadge|0.7}}
 
{{VersionBadge|0.7}}
  
−
==CEGUI In-Practice==
+
== 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'''!
+
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.
+
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 ====
 
==== 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.
+
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">
 
<source lang="cpp">
−
CEGUI::System::injectKeyDown(uint key_code);   // Tells CEGUI Key has been Pressed
+
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::injectKeyUp(uint key_code); // Tells CEGUI Key has been Released
  
 
CEGUI::System::injectChar(utf32 code_point);  
 
CEGUI::System::injectChar(utf32 code_point);  
 
</source>
 
</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'.
+
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.
+
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::injectMouseButtonDown(CEGUI::MouseButton::LeftButton);</source>
 
<source lang="cpp">CEGUI::System::injectMouseButtonDown(CEGUI::MouseButton::LeftButton);</source>
  
Line 29: Line 29:
 
<source lang="cpp">CEGUI::System::injectMouseMove(float delta_x, float delta_y);</source>
 
<source lang="cpp">CEGUI::System::injectMouseMove(float delta_x, float delta_y);</source>
  
−
The delta is in Screen pixels that the mouse moved since the last CEGUI Update.
+
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.
+
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::injectTimePulse(float timeElapsed);</source>
 
<source lang="cpp">CEGUI::System::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.
+
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! ====
 
==== On ward! ====
Line 41: Line 41:
 
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
 
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.
+
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.
  
 
<source lang="cpp">
 
<source lang="cpp">
Line 113: Line 113:
 
</source>
 
</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.
+
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 ====
 
==== 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!
+
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]]
 
[[Category:Tutorials]]

Revision as of 20:43, 28 February 2011

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!

Retrieved from "http://cegui.org/wiki/index.php?title=CEGUI_In_Practice_-_Managing_input&oldid=4015"