projects / sdlgit/SDL-Site.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | history | HEAD
latest blog
[sdlgit/SDL-Site.git] / pages / SDL-Event.html-inc
CommitLineData
162a0989 1<div class="pod">
2<!-- INDEX START -->
3<h3 id="TOP">Index</h3>
4
5<ul><li><a href="#NAME">NAME</a></li>
6<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
7<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
8<li><a href="#METHODS">METHODS</a>
9<ul><li><a href="#new">new</a></li>
10<li><a href="#type">type</a></li>
11<li><a href="#active">active</a>
6e0d970b 12<ul><li><a href="#active_gain">active_gain</a></li>
162a0989 13<li><a href="#active_state">active_state</a></li>
14</ul>
15</li>
16<li><a href="#key">key</a>
6e0d970b 17<ul><li><a href="#key_state">key_state</a></li>
162a0989 18<li><a href="#key_scancode">key_scancode</a></li>
19<li><a href="#key_sym">key_sym</a></li>
20<li><a href="#key_mod">key_mod</a></li>
21<li><a href="#key_unicode">key_unicode</a></li>
22</ul>
23</li>
24<li><a href="#motion">motion</a>
6e0d970b 25<ul><li><a href="#motion_state">motion_state</a></li>
162a0989 26<li><a href="#motion_x_motion_y">motion_x, motion_y</a></li>
27<li><a href="#motion_xrel_motion_yrel">motion_xrel, motion_yrel</a></li>
28</ul>
29</li>
30<li><a href="#button">button</a>
6e0d970b 31<ul><li><a href="#button_which">button_which</a></li>
162a0989 32<li><a href="#button_button">button_button</a></li>
33<li><a href="#button_state">button_state</a></li>
34<li><a href="#button_x_button_y">button_x, button_y</a></li>
35</ul>
36</li>
37<li><a href="#jaxis">jaxis</a>
6e0d970b 38<ul><li><a href="#jaxis_which">jaxis_which</a></li>
162a0989 39<li><a href="#jaxis_axis">jaxis_axis</a></li>
40<li><a href="#jaxis_value">jaxis_value</a></li>
41</ul>
42</li>
43<li><a href="#jbutton">jbutton</a>
6e0d970b 44<ul><li><a href="#jbutton_which">jbutton_which</a></li>
162a0989 45<li><a href="#jbutton_button">jbutton_button</a></li>
46<li><a href="#jbutton_state">jbutton_state</a></li>
47</ul>
48</li>
49<li><a href="#jhat">jhat</a>
6e0d970b 50<ul><li><a href="#jhat_which">jhat_which</a></li>
162a0989 51<li><a href="#jhat_hat">jhat_hat</a></li>
52<li><a href="#jhat_value">jhat_value</a></li>
53</ul>
54</li>
55<li><a href="#jball">jball</a>
6e0d970b 56<ul><li><a href="#jball_which">jball_which</a></li>
162a0989 57<li><a href="#jball_ball">jball_ball</a></li>
58<li><a href="#jball_xrel_jball_yrel">jball_xrel, jball_yrel</a></li>
59</ul>
60</li>
61<li><a href="#resize">resize</a>
6e0d970b 62<ul><li><a href="#resize_x_resize_y">resize_x, resize_y</a></li>
162a0989 63</ul>
64</li>
6e0d970b 65<li><a href="#expose">expose</a></li>
162a0989 66<li><a href="#syswm">syswm</a>
6e0d970b 67<ul><li><a href="#syswm_msg">syswm_msg</a></li>
162a0989 68</ul>
69</li>
70<li><a href="#user">user</a>
6e0d970b 71<ul><li><a href="#user_code">user_code</a></li>
162a0989 72<li><a href="#user_data1_user_data2">user_data1, user_data2</a></li>
73</ul>
74</li>
6e0d970b 75<li><a href="#quit">quit</a></li>
162a0989 76</ul>
77</li>
78<li><a href="#AUTHOR">AUTHOR</a></li>
79<li><a href="#SEE_ALSO">SEE ALSO</a>
80</li>
81</ul><hr />
82<!-- INDEX END -->
83
84<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
85<div id="NAME_CONTENT">
86<p>SDL::Event - General event structure</p>
87
88</div>
89<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
90<div id="SYNOPSIS_CONTENT">
91<pre> use SDL::Event; # for the event object itself
92 use SDL::Events qw(pump_events poll_event); # functions for event queue handling
93
94 SDL::init(SDL_INIT_VIDEO);
95 my $event = SDL::Event-&gt;new();
96
97 while(1)
98 {
99 pump_events();
100
101 if(poll_event($event))
102 {
103 if($event-&gt;type == SDL_MOUSEBUTTONDOWN)
104 {
105 # now you can handle the details
106 $event-&gt;button_which;
107 $event-&gt;button_button;
108 $event-&gt;button_x;
109 $event-&gt;button_y;
110 }
111
112 last if $event-&gt;type == SDL_QUIT;
113 }
114
115 # your screen drawing code will be here
116 }
117
118</pre>
119
120</div>
121<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
122<div id="DESCRIPTION_CONTENT">
123<p>Event handling allows your application to receive input from the user.
124Event handling is initalised (along with video) with a call to:</p>
125<p><code>SDL::init(SDL_INIT_VIDEO);</code></p>
126<p>Internally, SDL stores all the events waiting to be handled in an event queue.
127Using functions like <code>SDL::Events::poll_event()</code>, <code>SDL::Events::peep_events</code>
128and <code>SDL::Events::wait_event()</code> you can observe and handle waiting input events.</p>
129<p>The key to event handling in SDL is the <code>SDL::Event</code> union.
130The event queue itself is composed of a series of <code>SDL::Event</code> unions, one for each waiting event.
131<code>SDL::Event</code> unions are read from the queue with the <code>SDL::Events::poll_event()</code> function
132and it is then up to the application to process the information stored with them. </p>
133
134</div>
135<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
136<div id="METHODS_CONTENT">
137
138</div>
139<h2 id="new">new</h2>
140<div id="new_CONTENT">
141<p><code>new</code> creates an empty event-object, which can be used store information.
142Either by calling <code>poll_event($event)</code> that transferes one event from the queue into our object
143or by setting all the needed data manually in order to push the event to the queue.</p>
144<pre> use SDL::Event;
145
146 my $event = SDL::Event-&gt;new();
147
148</pre>
149
150</div>
151<h2 id="type">type</h2>
152<div id="type_CONTENT">
153<p>SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing
154which union member relates to which event <code>type</code>.</p>
6e0d970b 155<pre> print 'heureka' if $event-&gt;type == SDL_MOUSEBUTTONDOWN;
162a0989 156
157</pre>
158<p>Available type constants:</p>
159<ul>
160 <li><a href="#active">SDL_ACTIVEEVENT</a> - Application visibility event structure </li>
161 <li><a href="#active">SDL_KEYDOWN</a> - Keyboard event structure </li>
162 <li><a href="#active">SDL_KEYUP</a> - Keyboard event structure </li>
163 <li><a href="#active">SDL_MOUSEMOTION</a> - Mouse motion event structure </li>
164 <li><a href="#active">SDL_MOUSEBUTTONDOWN</a> - Mouse button event structure </li>
165 <li><a href="#button">SDL_MOUSEBUTTONUP</a> - Mouse button event structure </li>
166 <li><a href="#active">SDL_JOYAXISMOTION</a> - Joystick axis motion event structure </li>
167 <li><a href="#active">SDL_JOYBALLMOTION</a> - Joystick trackball motion event structure </li>
168 <li><a href="#active">SDL_JOYHATMOTION</a> - Joystick hat position change event structure </li>
169 <li><a href="#active">SDL_JOYBUTTONDOWN</a> - Joystick button event structure </li>
170 <li><a href="#active">SDL_JOYBUTTONUP</a> - Joystick button event structure </li>
171 <li><a href="#active">SDL_VIDEORESIZE</a> - Window resize event structure </li>
172 <li><a href="#active">SDL_VIDEOEXPOSE</a> - Window expose event </li>
173 <li><a href="#active">SDL_QUIT</a> - Quit requested event </li>
174 <li><a href="#active">SDL_USEREVENT</a> - A user-defined event type </li>
175 <li><a href="#active">SDL_SYSWMEVENT</a> - Platform-dependent window manager event. </li>
176</ul>
177
6e0d970b 178<p>Event types are grouped by masks. <code>SDL_EVENTMASK($type)</code> will return the proper mask for the given <code>type</code>.</p>
179<p>Available event mask constants:</p>
180<ul>
181 <li>SDL_ACTIVEEVENTMASK </li>
182 <li>SDL_KEYDOWNMASK </li>
183 <li>SDL_KEYUPMASK </li>
184 <li>SDL_KEYEVENTMASK </li>
185 <li>SDL_MOUSEMOTIONMASK </li>
186 <li>SDL_MOUSEBUTTONDOWNMASK </li>
187 <li>SDL_MOUSEBUTTONUPMASK </li>
188 <li>SDL_MOUSEEVENTMASK </li>
189 <li>SDL_JOYAXISMOTIONMASK </li>
190 <li>SDL_JOYBALLMOTIONMASK </li>
191 <li>SDL_JOYHATMOTIONMASK </li>
192 <li>SDL_JOYBUTTONDOWNMASK </li>
193 <li>SDL_JOYBUTTONUPMASK </li>
194 <li>SDL_JOYEVENTMASK </li>
195 <li>SDL_VIDEORESIZEMASK </li>
196 <li>SDL_VIDEOEXPOSEMASK </li>
197 <li>SDL_QUITMASK </li>
198 <li>SDL_SYSWMEVENTMASK</li>
199</ul>
200
201<p>This way you can check if a given <code>type</code> matches a mask:</p>
202<pre> (SDL_JOYBUTTONDOWN &amp; SDL_MOUSEEVENTMASK) # is false
203 (SDL_MOUSEBUTTONDOWN &amp; SDL_MOUSEEVENTMASK) # is true
204 (SDL_MOUSEBUTTONUP &amp; SDL_MOUSEEVENTMASK) # is true
205 (SDL_MOUSEMOTION &amp; SDL_MOUSEEVENTMASK) # is true
206
207 # and also true is:
208
209 (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
210 | SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
211 | SDL_EVENTMASK(SDL_MOUSEMOTION))
212
213</pre>
162a0989 214
215</div>
216<h2 id="active">active</h2>
217<div id="active_CONTENT">
6e0d970b 218<p><code>active</code> is used when an event of type <code>SDL_ACTIVEEVENT</code> is reported.</p>
162a0989 219<p>When the mouse leaves or enters the window area a <code>SDL_APPMOUSEFOCUS</code> type activation event occurs,
220if the mouse entered the window then <strong>gain</strong> will be 1, otherwise <strong>gain</strong> will be 0. </p>
221<p>A <code>SDL_APPINPUTFOCUS</code> type activation event occurs when the application loses or gains keyboard focus.
222This usually occurs when another application is made active. </p>
223<p>Finally, a <code>SDL_APPACTIVE</code> type event occurs when the application is either minimised/iconified (<strong>gain</strong>=0) or restored. </p>
224<p>A single event can have multiple values set in <strong>state</strong>.</p>
225<p><strong>Note:</strong> This event does not occur when an application window is first created. </p>
226<p>A new ActiveEvent (to fake focus loss) will be created like this:</p>
227<pre> my $event = SDL::Event-&gt;new();
228 $event-&gt;type(SDL_ACTIVEEVENT);
229 $event-&gt;active_gain(0);
230 $event-&gt;active_state(SDL_APPMOUSEFOCUS);
231
232 # I think this is wrong, -&gt;active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
233
234</pre>
235
236</div>
162a0989 237<h3 id="active_gain">active_gain</h3>
238<div id="active_gain_CONTENT">
6e0d970b 239<p>See <code>active</code>. 0 if the event is a loss or 1 if it is a gain.</p>
162a0989 240
241</div>
242<h3 id="active_state">active_state</h3>
243<div id="active_state_CONTENT">
6e0d970b 244<p>A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost,
245SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).</p>
162a0989 246
247</div>
248<h2 id="key">key</h2>
249<div id="key_CONTENT">
6e0d970b 250<p><code>key</code> is used when an event of type <code>SDL_KEYDOWN</code> or <code>SDL_KEYUP</code> is reported.</p>
251<p>The type and state actually report the same information, they just use different values to do it.
252A keyboard event generally occurs when a key is released (<code>type=SDL_KEYUP</code> or <code>key_state=SDL_RELEASED</code>)
253and when a key is pressed (<code>type=SDL_KEYDOWN</code> or <code>key_state=SDL_PRESSED</code>). </p>
254<p>The <code>SDLK_CAPSLOCK</code> and <code>SDLK_NUMLOCK</code> keys are special cases and report an <code>SDL_KEYDOWN</code> when first pressed,
255then an <code>SDL_RELEASED</code> when released and pressed again. For these keys <code>KEYUP</code> and <code>KEYDOWN</code> events are therefore
256analogous to the state of the caps lock and num lock LEDs rather than the keys themselves.
257These special cases are required for compatibility with Sun workstations.</p>
258<p><strong>Note:</strong> Repeating <code>SDL_KEYDOWN</code> events will occur if key repeat is enabled (see <code>SDL_EnableKeyRepeat</code>). </p>
162a0989 259
260</div>
261<h3 id="key_state">key_state</h3>
262<div id="key_state_CONTENT">
6e0d970b 263<p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
162a0989 264
265</div>
266<h3 id="key_scancode">key_scancode</h3>
267<div id="key_scancode_CONTENT">
268
269</div>
270<h3 id="key_sym">key_sym</h3>
271<div id="key_sym_CONTENT">
272
273</div>
274<h3 id="key_mod">key_mod</h3>
275<div id="key_mod_CONTENT">
276
277</div>
278<h3 id="key_unicode">key_unicode</h3>
279<div id="key_unicode_CONTENT">
280
281</div>
282<h2 id="motion">motion</h2>
283<div id="motion_CONTENT">
284
285</div>
162a0989 286<h3 id="motion_state">motion_state</h3>
287<div id="motion_state_CONTENT">
288
289</div>
290<h3 id="motion_x_motion_y">motion_x, motion_y</h3>
291<div id="motion_x_motion_y_CONTENT">
292
293</div>
294<h3 id="motion_xrel_motion_yrel">motion_xrel, motion_yrel</h3>
295<div id="motion_xrel_motion_yrel_CONTENT">
296
297</div>
298<h2 id="button">button</h2>
299<div id="button_CONTENT">
300
301</div>
162a0989 302<h3 id="button_which">button_which</h3>
303<div id="button_which_CONTENT">
304
305</div>
306<h3 id="button_button">button_button</h3>
307<div id="button_button_CONTENT">
308
309</div>
310<h3 id="button_state">button_state</h3>
311<div id="button_state_CONTENT">
312
313</div>
314<h3 id="button_x_button_y">button_x, button_y</h3>
315<div id="button_x_button_y_CONTENT">
316
317</div>
318<h2 id="jaxis">jaxis</h2>
319<div id="jaxis_CONTENT">
320
321</div>
162a0989 322<h3 id="jaxis_which">jaxis_which</h3>
323<div id="jaxis_which_CONTENT">
324
325</div>
326<h3 id="jaxis_axis">jaxis_axis</h3>
327<div id="jaxis_axis_CONTENT">
328
329</div>
330<h3 id="jaxis_value">jaxis_value</h3>
331<div id="jaxis_value_CONTENT">
332
333</div>
334<h2 id="jbutton">jbutton</h2>
335<div id="jbutton_CONTENT">
336
337</div>
162a0989 338<h3 id="jbutton_which">jbutton_which</h3>
339<div id="jbutton_which_CONTENT">
340
341</div>
342<h3 id="jbutton_button">jbutton_button</h3>
343<div id="jbutton_button_CONTENT">
344
345</div>
346<h3 id="jbutton_state">jbutton_state</h3>
347<div id="jbutton_state_CONTENT">
348
349</div>
350<h2 id="jhat">jhat</h2>
351<div id="jhat_CONTENT">
352
353</div>
162a0989 354<h3 id="jhat_which">jhat_which</h3>
355<div id="jhat_which_CONTENT">
356
357</div>
358<h3 id="jhat_hat">jhat_hat</h3>
359<div id="jhat_hat_CONTENT">
360
361</div>
362<h3 id="jhat_value">jhat_value</h3>
363<div id="jhat_value_CONTENT">
364
365</div>
366<h2 id="jball">jball</h2>
367<div id="jball_CONTENT">
368
369</div>
162a0989 370<h3 id="jball_which">jball_which</h3>
371<div id="jball_which_CONTENT">
372
373</div>
374<h3 id="jball_ball">jball_ball</h3>
375<div id="jball_ball_CONTENT">
376
377</div>
378<h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
379<div id="jball_xrel_jball_yrel_CONTENT">
380
381</div>
382<h2 id="resize">resize</h2>
383<div id="resize_CONTENT">
384
385</div>
162a0989 386<h3 id="resize_x_resize_y">resize_x, resize_y</h3>
387<div id="resize_x_resize_y_CONTENT">
388
389</div>
390<h2 id="expose">expose</h2>
391<div id="expose_CONTENT">
392
393</div>
162a0989 394<h2 id="syswm">syswm</h2>
395<div id="syswm_CONTENT">
396
397</div>
162a0989 398<h3 id="syswm_msg">syswm_msg</h3>
399<div id="syswm_msg_CONTENT">
400
401</div>
402<h2 id="user">user</h2>
403<div id="user_CONTENT">
404
405</div>
162a0989 406<h3 id="user_code">user_code</h3>
407<div id="user_code_CONTENT">
408
409</div>
410<h3 id="user_data1_user_data2">user_data1, user_data2</h3>
411<div id="user_data1_user_data2_CONTENT">
412
413</div>
414<h2 id="quit">quit</h2>
415<div id="quit_CONTENT">
162a0989 416<p>Create a new SDL::Event object.</p>
417
418</div>
419<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
420<div id="AUTHOR_CONTENT">
421
422</div>
423<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
424<div id="SEE_ALSO_CONTENT">
425<p><cite>perl</cite></p>
426
427</div>
428</div>
Unnamed repository; edit this file to name it for gitweb.