1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Crazy Eddies GUI System: The Beginners Guide to Injecting Inputs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.4 -->
<script type="text/javascript">
function hasClass(ele,cls) {
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
}
function addClass(ele,cls) {
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
}
function removeClass(ele,cls) {
if (hasClass(ele,cls)) {
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
ele.className=ele.className.replace(reg,' ');
}
}
function toggleVisibility(linkObj) {
var base = linkObj.getAttribute('id');
var summary = document.getElementById(base + '-summary');
var content = document.getElementById(base + '-content');
var trigger = document.getElementById(base + '-trigger');
if ( hasClass(linkObj,'closed') ) {
summary.style.display = 'none';
content.style.display = 'block';
trigger.src = 'open.png';
removeClass(linkObj,'closed');
addClass(linkObj,'opened');
} else if ( hasClass(linkObj,'opened') ) {
summary.style.display = 'block';
content.style.display = 'none';
trigger.src = 'closed.png';
removeClass(linkObj,'opened');
addClass(linkObj,'closed');
}
return false;
}
</script>
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Crazy Eddies GUI System <span id="projectnumber">0.7.6</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">The Beginners Guide to Injecting Inputs </div> </div>
</div>
<div class="contents">
<div class="textblock"><dl class="author"><dt><b>Author:</b></dt><dd>Paul D Turner</dd></dl>
<p>Having read the previous tutorials in this series, you now have your GUI rendering set up, the files loaded and even have a window on screen - however you are probably wanting to have some user interaction too. This is the subject of this final tutorial in the series; here we will show the required tasks in order to end up with a complete functioning GUI in your application.</p>
<p><br/>
</p>
<h2><a class="anchor" id="input_tutorial_intro"></a>
Introduction to input for CEGUI</h2>
<h3><a class="anchor" id="input_tutorial_intro_badnews"></a>
First the bad news</h3>
<p>It shocks some people to discover that <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> does not do any automatic collection of user input; it is the responsibility of the application itself to tell <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> about any events that it needs to know about. This means that you have to tell <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> each time a key is pressed, or the mouse moves, and so on. While this may seem strange at first, the reality is that it affords you a lot more power and flexibility; we are not tying you down to any particular system for your inputs, and you may additionally filter input before it gets to <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>, although these are more advanced concepts best left for another time.</p>
<h3><a class="anchor" id="input_tutorial_intro_injectors"></a>
Get your inputs injected</h3>
<p>In order to tell <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> about the input events going on around it, we have an input injection interface. This consists of a set of functions in the <a class="el" href="classCEGUI_1_1System.html" title="The System class is the CEGUI class that provides access to all other elements in this system...">CEGUI::System</a> class - there is one member function for each type of base input:</p>
<ul>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a89ad8b8cf9fb0da01220f0999f5d769e" title="Method that injects a mouse movement event into the system.">System::injectMouseMove( float delta_x, float delta_y )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a3a5605ebc3a9a65cf8c84741d9f080c4" title="Method that injects a new position for the mouse cursor.">System::injectMousePosition( float x_pos, float y_pos )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#aede24204e0589aeef67fd163be6a0744" title="Method that injects that the mouse has left the application window.">System::injectMouseLeaves( void )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#afe49439ec231e289b1f804fd84c08c13" title="Method that injects a mouse button down event into the system.">System::injectMouseButtonDown( MouseButton button )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a6159a08b13ddcc7b4e5db78a971475a6" title="Method that injects a mouse button up event into the system.">System::injectMouseButtonUp( MouseButton button )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#aec89521017e12c2354ff0e511efd89d6" title="Method that injects a key down event into the system.">System::injectKeyDown( uint key_code )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a6d45f4dfb77aeaeafe186e3b0b7788f7" title="Method that injects a key up event into the system.">System::injectKeyUp( uint key_code )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a8161e2299453359774a77218c5a35a37" title="Method that injects a typed character event into the system.">System::injectChar( utf32 code_point )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a10ebcf52cfe3ed31ed0a4a22295123d1" title="Method that injects a mouse-wheel / scroll-wheel event into the system.">System::injectMouseWheelChange( float delta )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a8f56e87e8535cfe793f276c7238bfb22" title="Method to inject time pulses into the system.">System::injectTimePulse( float timeElapsed )</a>;</li>
</ul>
<p>And also some optional functions for click and multi-click events (which are normally automatically generated internally by the system):</p>
<ul>
<li>bool <a class="el" href="classCEGUI_1_1System.html#aee4145e733ca07d8151cf1f58553da0f" title="Function to directly inject a mouse button click event.">System::injectMouseButtonClick( MouseButton button )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#a238b6261a687c3ccd00387cbdbe46c34" title="Function to directly inject a mouse button double-click event.">System::injectMouseButtonDoubleClick( MouseButton button )</a>;</li>
<li>bool <a class="el" href="classCEGUI_1_1System.html#af6d2979a682a7739c0d8d4e6a71954f9" title="Function to directly inject a mouse button triple-click event.">System::injectMouseButtonTripleClick( MouseButton button )</a>;</li>
</ul>
<p>Yes, that's quite a collection! The first thing that you might notice is that there appears to be some repetition - things like 'mouse move' and 'mouse position', 'key down' and 'char'. For the mouse, we offer the possibility of injecting a relative movement of the mouse from it's last injected location or an absolute position - which one of these you choose will largely depend upon the type of inputs that your input library provides you with for the mouse. For keys, it is generally required that both up/down strokes and also characters are injected - there are a couple of reasons for this; first, not all keys generate a character code (like shift, alt, and so on), and second, it allows you to do your own custom (or operating system supplied) key-mapping and key auto-repeat (since <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> does not currently offer these functions).</p>
<p>The other thing to notice is the boolean return value from the injection functions. This is used to relay back to your application whether or not <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> actually consumed the input. If this returns false, it means that <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> did nothing useful with the input, and that your application may like to perform some action based on it instead. Generally for this to work as described, you should have a fullscreen DefaultWindow as your layout root with the MousePassThroughEnabled property set to true.</p>
<p><br/>
</p>
<h2><a class="anchor" id="input_tutorial_detail"></a>
A little more detail: What each injector is used for</h2>
<p>Here we will offer a brief description of what each injection function is used for, the data it expects, and what, in general, is done with the input.</p>
<h3><a class="anchor" id="input_tutorial_mousemove"></a>
bool System::injectMouseMove( float delta_x, float delta_y )</h3>
<p>This is used to inject relative mouse movements. The vales <code>delta_x</code> and <code>delta_y</code> specify the direction and number of screen pixels the mouse has moved on the x axis and y axis respectively. This causes the mouse to move by the specified amount (the actual amount moved can be changed by setting a mouse scaling factor via the <a class="el" href="classCEGUI_1_1System.html#a423af34d492a613be2d1e36a13c1d5ac" title="Set the current mouse movement scaling factor.">System::setMouseMoveScaling</a> function). If you use this, you generally do not need to use injectMousePosition.</p>
<h3><a class="anchor" id="input_tutorial_mousepos"></a>
bool System::injectMousePosition( float x_pos, float y_pos )</h3>
<p>This is used to inject the current absolute position of the mouse. The values <code>x_pos</code> and <code>y_pos</code> specify the position of the mouse in pixels, where a position of (0, 0) represents the top-left hand corner of the <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> display (so if you're in windowed mode, it's the corner of the window and not the corner of the entire screen). The <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> mouse cursor will be set to the new position. If you use this, you generally do not need to use injectMouseMove.</p>
<h3><a class="anchor" id="input_tutorial_mouseleaves"></a>
bool System::injectMouseLeaves( void )</h3>
<p>This function informs <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that the mouse cursor has left the host window that <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> considers it's rendering area. This is useful if running in windowed mode to inform widgets that the mouse has actually left the <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> display completely (otherwise it may not get to know, since under many systems no more mouse events are generated for an OS window once the mouse has left it).</p>
<h3><a class="anchor" id="input_tutorial_mbdown"></a>
bool System::injectMouseButtonDown( MouseButton button )</h3>
<p>This tells <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a mouse button has been pressed down. The value <code>button</code> is one of the <a class="el" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976" title="Enumeration of mouse buttons.">CEGUI::MouseButton</a> enumerated values, which are as follows: </p>
<div class="fragment"><pre class="fragment"><span class="keyword">enum</span> <a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976" title="Enumeration of mouse buttons.">MouseButton</a>
{
<a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976a87a089c1f7a5bc65f3fe590ed87fd22b" title="The left mouse button.">LeftButton</a>,
<a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976a208df6464827d50868802ba3cc614cf7" title="The right mouse button.">RightButton</a>,
<a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976a950f683c02eb5a3ce8509869e0aa47d9" title="The middle mouse button.">MiddleButton</a>,
<a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976a6d446c2c07b46b4ea02ada2fb44fd9ff" title="The first 'extra' mouse button.">X1Button</a>,
<a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976a7fca27705cfe21527325d529caf94f2e" title="The second 'extra' mouse button.">X2Button</a>,
<a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976a3b35b89db13e1e2d5ba9adab3f9336b5" title="Value that equals the number of mouse buttons supported by CEGUI.">MouseButtonCount</a>,
<a class="code" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976a65fb7d4cbb0783a49b61fcfe86735f3a" title="Value set for no mouse button. NB: This is not 0, do not assume!">NoButton</a>
};
</pre></div><p>If the values from your input library do not match these, you will have to perform a translation step. Also note that the value NoButton is not 0.</p>
<h3><a class="anchor" id="input_tutorial_mbup"></a>
bool System::injectMouseButtonUp( MouseButton button )</h3>
<p>This tells <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a mouse button has been released. As for the <a class="el" href="classCEGUI_1_1System.html#afe49439ec231e289b1f804fd84c08c13" title="Method that injects a mouse button down event into the system.">System::injectMouseButtonDown</a> function, the value <code>button</code> is one of the <a class="el" href="namespaceCEGUI.html#aa445483fd17f02e7d119e9be540a4976" title="Enumeration of mouse buttons.">CEGUI::MouseButton</a> enumerated values.</p>
<h3><a class="anchor" id="input_tutorial_keydown"></a>
bool System::injectKeyDown( uint key_code )</h3>
<p>This tells <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a key has been pressed. The value <code>key_code</code> is the scan code for the key - note that this is not an ASCII or other text encoding value. The available scan codes are defined in the CEGUI::Key::Scan enumeration. If you are using Microsoft DirectInput, then our scan codes are the same ones output by that library, in other cases you may be required to perform some translation. Note that for current releases, and depending upon your expected use, it may not be required to inject <em>all</em> key down/up strokes - the most common ones that you likely will need are for backspace, delete, enter, the shift keys and the arrow keys.</p>
<p>At present no automatic key mapping and generation of character codes is performed, also there is no integrated key auto-repeat functionality - though these functions may appear in future releases. If you need key auto-repeat then you will need to either use an input library that offers this function, or implement something directly. Of course you will almost certainly need character input, so for that look at the <a class="el" href="classCEGUI_1_1System.html#a8161e2299453359774a77218c5a35a37" title="Method that injects a typed character event into the system.">System::injectChar</a> function below.</p>
<h3><a class="anchor" id="input_tutorial_keyup"></a>
bool System::injectKeyUp( uint key_code )</h3>
<p>This tells <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a key has been released. As for the <a class="el" href="classCEGUI_1_1System.html#aec89521017e12c2354ff0e511efd89d6" title="Method that injects a key down event into the system.">System::injectKeyDown</a> function, the value <code>key_code</code> is a scan code for the key - and again note that this is not an ASCII or other text encoding value - see above for a more detailed description of the key scan codes.</p>
<h3><a class="anchor" id="input_tutorial_char"></a>
bool System::injectChar( utf32 code_point )</h3>
<p>This function tells <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a character key has been pressed - you will need this in order to input text into <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> widgets. The value <code>code_point'</code> is a Unicode UTF32 code point value (see the unicode website at <a href="http://unicode.org/">http://unicode.org/</a> for information about unicode). How you obtain this value is something that is dependant upon the input library that you are using. For many people, who just wish to use ASCII values, you can just pass in your ASCII codes unmodified, since Unicode values between 0 and 127 are the same as the standard ASCII codes. For other uses, you will need to consult the API documentation for your input library (it is possible, for example, to get the Microsoft Windows message pump to send you key codes in UTF32 form, though exactly how it is done is beyond the scope of this introductory tutorial).</p>
<h3><a class="anchor" id="input_tutorial_mwheel"></a>
bool System::injectMouseWheelChange( float delta )</h3>
<p>This function is used to tell <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> about the use of the mouse wheel or scroll wheel (whatever you like to call it!). Use positive values for forward movement (rolling the wheel away from the user), and negative values for backwards movement (rolling the wheel towards the user).</p>
<h3><a class="anchor" id="input_tutorial_pulse"></a>
bool System::injectTimePulse( float timeElapsed )</h3>
<p>This function is used to keep <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> informed about time (<a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> doesn't have a wristwatch, you see!). The value <code>timeElapsed</code> is a floating point number that indicates the number of seconds - or part seconds - that have passed since the last time the injector was called (or since <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> was started). The use of this function is becoming more and more important - it now controls things such as fades and timing for tool-tip widgets, menus, and also auto-repeat for mouse buttons.</p>
<h3><a class="anchor" id="input_tutorial_click"></a>
bool System::injectMouseButtonClick( MouseButton button )</h3>
<p>This is an optional injection function that informs <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a mouse button click has occurred; normally that is a down -> up sequence. Calling this function is only neccessary if the built-in automatic generation of click and multi-click events is unsuitable for your needs. If you decide you need to use this function you will normally disable the automatic event generation first by way of the <a class="el" href="classCEGUI_1_1System.html#ad947a87e0039c91b9e99a7d0126dc7e3" title="Set whether automatic mouse button click and multi-click (i.e. double-click and treble-click) event g...">System::setMouseClickEventGenerationEnabled</a> function. While it is possible to call this injection function <em>without</em> disabling the auto generated events, it will affect the behaviour as to the way events are marked as 'handled' and therefore the return code from this function.</p>
<h3><a class="anchor" id="input_tutorial_doubleclick"></a>
bool System::injectMouseButtonDoubleClick( MouseButton button )</h3>
<p>This is an optional injection function that informs <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a mouse button double-click has occurred; normally that is a down -> up -> down sequence. Calling this function is only neccessary if the built-in automatic generation of click and multi-click events is unsuitable for your needs. If you decide you need to use this function you will normally disable the automatic event generation first by way of the <a class="el" href="classCEGUI_1_1System.html#ad947a87e0039c91b9e99a7d0126dc7e3" title="Set whether automatic mouse button click and multi-click (i.e. double-click and treble-click) event g...">System::setMouseClickEventGenerationEnabled</a> function. While it is possible to call this injection function <em>without</em> disabling the auto generated events, it will affect the behaviour as to the way events are marked as 'handled' and therefore the return code from this function.</p>
<h3><a class="anchor" id="input_tutorial_tripleclick"></a>
bool System::injectMouseButtonTripleClick( MouseButton button )</h3>
<p>This is an optional injection function that informs <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> that a mouse button triple-click has occurred; normally that is a down -> up -> down -> up -> down sequence. Calling this function is only neccessary if the built-in automatic generation of click and multi-click events is unsuitable for your needs. If you decide you need to use this function you will normally disable the automatic event generation first by way of the <a class="el" href="classCEGUI_1_1System.html#ad947a87e0039c91b9e99a7d0126dc7e3" title="Set whether automatic mouse button click and multi-click (i.e. double-click and treble-click) event g...">System::setMouseClickEventGenerationEnabled</a> function. While it is possible to call this injection function <em>without</em> disabling the auto generated events, it will affect the behaviour as to the way events are marked as 'handled' and therefore the return code from this function.</p>
<p><br/>
</p>
<h2><a class="anchor" id="input_tutorial_conclusion"></a>
Conclusion</h2>
<p>Here we have seen the general idiom that <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> uses for obtaining externally generated input events. We have seen the methods for passing these inputs to <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a>, and the type and format of the information to be passed.</p>
<p>Unlike some of the other tutorials in this series, we did not provide concrete code examples. The main reason for this was to keep the tutorial reasonably short; to prevent it becoming a jumble of code for every possible combination of input system, and in the process causing more confusion. The use of any individual input library could easily fill a tutorial of it's own. </p>
</div></div>
<hr class="footer"/><address class="footer"><small>Generated on Sun Jan 22 2012 16:07:40 for Crazy Eddies GUI System by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
|
