3 <h3 id="TOP">Index</h3>
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>
12 <ul><li><a href="#active_gain">active_gain</a></li>
13 <li><a href="#active_state">active_state</a></li>
16 <li><a href="#key">key</a>
17 <ul><li><a href="#key_state">key_state</a></li>
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>
24 <li><a href="#motion">motion</a>
25 <ul><li><a href="#motion_state">motion_state</a></li>
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>
30 <li><a href="#button">button</a>
31 <ul><li><a href="#button_which">button_which</a></li>
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>
37 <li><a href="#jaxis">jaxis</a>
38 <ul><li><a href="#jaxis_which">jaxis_which</a></li>
39 <li><a href="#jaxis_axis">jaxis_axis</a></li>
40 <li><a href="#jaxis_value">jaxis_value</a></li>
43 <li><a href="#jbutton">jbutton</a>
44 <ul><li><a href="#jbutton_which">jbutton_which</a></li>
45 <li><a href="#jbutton_button">jbutton_button</a></li>
46 <li><a href="#jbutton_state">jbutton_state</a></li>
49 <li><a href="#jhat">jhat</a>
50 <ul><li><a href="#jhat_which">jhat_which</a></li>
51 <li><a href="#jhat_hat">jhat_hat</a></li>
52 <li><a href="#jhat_value">jhat_value</a></li>
55 <li><a href="#jball">jball</a>
56 <ul><li><a href="#jball_which">jball_which</a></li>
57 <li><a href="#jball_ball">jball_ball</a></li>
58 <li><a href="#jball_xrel_jball_yrel">jball_xrel, jball_yrel</a></li>
61 <li><a href="#resize">resize</a>
62 <ul><li><a href="#resize_x_resize_y">resize_x, resize_y</a></li>
65 <li><a href="#expose">expose</a></li>
66 <li><a href="#syswm">syswm</a>
67 <ul><li><a href="#syswm_msg">syswm_msg</a></li>
70 <li><a href="#user">user</a>
71 <ul><li><a href="#user_code">user_code</a></li>
72 <li><a href="#user_data1_user_data2">user_data1, user_data2</a></li>
75 <li><a href="#quit">quit</a></li>
78 <li><a href="#AUTHOR">AUTHOR</a></li>
79 <li><a href="#SEE_ALSO">SEE ALSO</a>
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>
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
94 SDL::init(SDL_INIT_VIDEO);
95 my $event = SDL::Event->new();
101 if(poll_event($event))
103 if($event->type == SDL_MOUSEBUTTONDOWN)
105 # now you can handle the details
106 $event->button_which;
107 $event->button_button;
112 last if $event->type == SDL_QUIT;
115 # your screen drawing code will be here
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.
124 Event 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.
127 Using functions like <code>SDL::Events::poll_event()</code>, <code>SDL::Events::peep_events</code>
128 and <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.
130 The 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
132 and it is then up to the application to process the information stored with them. </p>
135 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
136 <div id="METHODS_CONTENT">
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.
142 Either by calling <code>poll_event($event)</code> that transferes one event from the queue into our object
143 or by setting all the needed data manually in order to push the event to the queue.</p>
144 <pre> use SDL::Event;
146 my $event = SDL::Event->new();
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
154 which union member relates to which event <code>type</code>.</p>
155 <pre> print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;
158 <p>Available type constants:</p>
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>
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>
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>
201 <p>This way you can check if a given <code>type</code> matches a mask:</p>
202 <pre> (SDL_JOYBUTTONDOWN & SDL_MOUSEEVENTMASK) # is false
203 (SDL_MOUSEBUTTONDOWN & SDL_MOUSEEVENTMASK) # is true
204 (SDL_MOUSEBUTTONUP & SDL_MOUSEEVENTMASK) # is true
205 (SDL_MOUSEMOTION & SDL_MOUSEEVENTMASK) # is true
209 (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
210 | SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
211 | SDL_EVENTMASK(SDL_MOUSEMOTION))
216 <h2 id="active">active</h2>
217 <div id="active_CONTENT">
218 <p><code>active</code> is used when an event of type <code>SDL_ACTIVEEVENT</code> is reported.</p>
219 <p>When the mouse leaves or enters the window area a <code>SDL_APPMOUSEFOCUS</code> type activation event occurs,
220 if 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.
222 This 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->new();
228 $event->type(SDL_ACTIVEEVENT);
229 $event->active_gain(0);
230 $event->active_state(SDL_APPMOUSEFOCUS);
232 # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
237 <h3 id="active_gain">active_gain</h3>
238 <div id="active_gain_CONTENT">
239 <p>See <code>active</code>. 0 if the event is a loss or 1 if it is a gain.</p>
242 <h3 id="active_state">active_state</h3>
243 <div id="active_state_CONTENT">
244 <p>A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost,
245 SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).</p>
248 <h2 id="key">key</h2>
249 <div id="key_CONTENT">
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.
252 A keyboard event generally occurs when a key is released (<code>type=SDL_KEYUP</code> or <code>key_state=SDL_RELEASED</code>)
253 and 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,
255 then an <code>SDL_RELEASED</code> when released and pressed again. For these keys <code>KEYUP</code> and <code>KEYDOWN</code> events are therefore
256 analogous to the state of the caps lock and num lock LEDs rather than the keys themselves.
257 These 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>
261 <h3 id="key_state">key_state</h3>
262 <div id="key_state_CONTENT">
263 <p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
266 <h3 id="key_scancode">key_scancode</h3>
267 <div id="key_scancode_CONTENT">
270 <h3 id="key_sym">key_sym</h3>
271 <div id="key_sym_CONTENT">
274 <h3 id="key_mod">key_mod</h3>
275 <div id="key_mod_CONTENT">
278 <h3 id="key_unicode">key_unicode</h3>
279 <div id="key_unicode_CONTENT">
282 <h2 id="motion">motion</h2>
283 <div id="motion_CONTENT">
286 <h3 id="motion_state">motion_state</h3>
287 <div id="motion_state_CONTENT">
290 <h3 id="motion_x_motion_y">motion_x, motion_y</h3>
291 <div id="motion_x_motion_y_CONTENT">
294 <h3 id="motion_xrel_motion_yrel">motion_xrel, motion_yrel</h3>
295 <div id="motion_xrel_motion_yrel_CONTENT">
298 <h2 id="button">button</h2>
299 <div id="button_CONTENT">
302 <h3 id="button_which">button_which</h3>
303 <div id="button_which_CONTENT">
306 <h3 id="button_button">button_button</h3>
307 <div id="button_button_CONTENT">
310 <h3 id="button_state">button_state</h3>
311 <div id="button_state_CONTENT">
314 <h3 id="button_x_button_y">button_x, button_y</h3>
315 <div id="button_x_button_y_CONTENT">
318 <h2 id="jaxis">jaxis</h2>
319 <div id="jaxis_CONTENT">
322 <h3 id="jaxis_which">jaxis_which</h3>
323 <div id="jaxis_which_CONTENT">
326 <h3 id="jaxis_axis">jaxis_axis</h3>
327 <div id="jaxis_axis_CONTENT">
330 <h3 id="jaxis_value">jaxis_value</h3>
331 <div id="jaxis_value_CONTENT">
334 <h2 id="jbutton">jbutton</h2>
335 <div id="jbutton_CONTENT">
338 <h3 id="jbutton_which">jbutton_which</h3>
339 <div id="jbutton_which_CONTENT">
342 <h3 id="jbutton_button">jbutton_button</h3>
343 <div id="jbutton_button_CONTENT">
346 <h3 id="jbutton_state">jbutton_state</h3>
347 <div id="jbutton_state_CONTENT">
350 <h2 id="jhat">jhat</h2>
351 <div id="jhat_CONTENT">
354 <h3 id="jhat_which">jhat_which</h3>
355 <div id="jhat_which_CONTENT">
358 <h3 id="jhat_hat">jhat_hat</h3>
359 <div id="jhat_hat_CONTENT">
362 <h3 id="jhat_value">jhat_value</h3>
363 <div id="jhat_value_CONTENT">
366 <h2 id="jball">jball</h2>
367 <div id="jball_CONTENT">
370 <h3 id="jball_which">jball_which</h3>
371 <div id="jball_which_CONTENT">
374 <h3 id="jball_ball">jball_ball</h3>
375 <div id="jball_ball_CONTENT">
378 <h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
379 <div id="jball_xrel_jball_yrel_CONTENT">
382 <h2 id="resize">resize</h2>
383 <div id="resize_CONTENT">
386 <h3 id="resize_x_resize_y">resize_x, resize_y</h3>
387 <div id="resize_x_resize_y_CONTENT">
390 <h2 id="expose">expose</h2>
391 <div id="expose_CONTENT">
394 <h2 id="syswm">syswm</h2>
395 <div id="syswm_CONTENT">
398 <h3 id="syswm_msg">syswm_msg</h3>
399 <div id="syswm_msg_CONTENT">
402 <h2 id="user">user</h2>
403 <div id="user_CONTENT">
406 <h3 id="user_code">user_code</h3>
407 <div id="user_code_CONTENT">
410 <h3 id="user_data1_user_data2">user_data1, user_data2</h3>
411 <div id="user_data1_user_data2_CONTENT">
414 <h2 id="quit">quit</h2>
415 <div id="quit_CONTENT">
416 <p>Create a new SDL::Event object.</p>
419 <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
420 <div id="AUTHOR_CONTENT">
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>