Commit | Line | Data |
162a0989 |
1 | <div class="pod"> |
2 | <!-- INDEX START --> |
3 | <h3 id="TOP">Index</h3> |
4 | |
60f74f6f |
5 | <ul><li><a href="#NAME">NAME</a> |
6 | <ul><li><a href="#CATEGORY">CATEGORY</a></li> |
7 | </ul> |
8 | </li> |
162a0989 |
9 | <li><a href="#SYNOPSIS">SYNOPSIS</a></li> |
10 | <li><a href="#DESCRIPTION">DESCRIPTION</a></li> |
11 | <li><a href="#METHODS">METHODS</a> |
12 | <ul><li><a href="#pump_events">pump_events</a></li> |
13 | <li><a href="#peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </a> |
14 | <ul><li><a href="#RETURN">RETURN</a></li> |
15 | </ul> |
16 | </li> |
17 | <li><a href="#poll_event_event">poll_event($event)</a> |
18 | <ul><li><a href="#RETURN-2">RETURN</a></li> |
19 | </ul> |
20 | </li> |
21 | <li><a href="#push_event_event">push_event($event)</a> |
22 | <ul><li><a href="#RETURN-3">RETURN</a></li> |
23 | </ul> |
24 | </li> |
25 | <li><a href="#wait_event_event">wait_event($event)</a> |
26 | <ul><li><a href="#RETURN-4">RETURN</a></li> |
27 | </ul> |
28 | </li> |
55bbf7a2 |
29 | <li><a href="#set_event_filter">set_event_filter</a> |
30 | <ul><li><a href="#PARAMETER">PARAMETER</a></li> |
31 | </ul> |
32 | </li> |
cf23a5da |
33 | <li><a href="#get_key_state">get_key_state</a></li> |
55bbf7a2 |
34 | <li><a href="#get_mod_state">get_mod_state</a> |
35 | <ul><li><a href="#MOD_VALUES">MOD VALUES</a></li> |
36 | </ul> |
37 | </li> |
cf23a5da |
38 | <li><a href="#set_mod_state">set_mod_state</a></li> |
55bbf7a2 |
39 | <li><a href="#event_state">event_state </a> |
40 | <ul><li><a href="#STATES">STATES</a></li> |
41 | </ul> |
42 | </li> |
cf23a5da |
43 | <li><a href="#get_key_name">get_key_name</a></li> |
44 | <li><a href="#enable_unicode">enable_unicode </a></li> |
45 | <li><a href="#enable_key_repeat">enable_key_repeat </a></li> |
46 | <li><a href="#get_mouse_state">get_mouse_state </a></li> |
47 | <li><a href="#get_relative_mouse_state">get_relative_mouse_state </a></li> |
48 | <li><a href="#get_app_state">get_app_state </a></li> |
49 | <li><a href="#joystick_event_state">joystick_event_state </a></li> |
162a0989 |
50 | </ul> |
51 | </li> |
52 | <li><a href="#SEE_ALSO">SEE ALSO</a> |
53 | </li> |
54 | </ul><hr /> |
55 | <!-- INDEX END --> |
56 | |
57 | <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p> |
58 | <div id="NAME_CONTENT"> |
59 | <p>SDL::Events - Bindings to the Events Category in SDL API</p> |
60 | |
61 | </div> |
60f74f6f |
62 | <h2 id="CATEGORY">CATEGORY</h2> |
63 | <div id="CATEGORY_CONTENT"> |
64 | <p>Core, Events</p> |
65 | |
66 | </div> |
162a0989 |
67 | <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
68 | <div id="SYNOPSIS_CONTENT"> |
55bbf7a2 |
69 | <p>Most likely you just want to know how to get events for you app.</p> |
70 | <pre> use SDL; |
162a0989 |
71 | use SDL::Event; |
55bbf7a2 |
72 | use SDL::Events; |
73 | |
74 | SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this |
162a0989 |
75 | |
76 | ... |
77 | |
78 | my $event = SDL::Event->new(); # notices 'Event' ne 'Events' |
79 | |
80 | while( 1 ) |
81 | { |
82 | SDL::Events::pump_events(); |
83 | while( SDL::Events::poll_event($event) ) |
84 | { |
85 | #check by event type |
86 | on_active() if $event->type == SDL_ACTIVEEVENT; |
87 | ... |
88 | } |
89 | } |
90 | |
91 | </pre> |
92 | |
93 | </div> |
94 | <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
95 | <div id="DESCRIPTION_CONTENT"> |
96 | |
97 | |
98 | |
99 | |
100 | |
101 | </div> |
102 | <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
103 | <div id="METHODS_CONTENT"> |
104 | |
105 | </div> |
106 | <h2 id="pump_events">pump_events</h2> |
107 | <div id="pump_events_CONTENT"> |
108 | <p>Pumps the event loop, gathering events from the input devices.</p> |
109 | <pre> pump_events(); |
110 | |
111 | </pre> |
112 | <p>pump_events gathers all the pending input information from devices and places it on the event queue. Without calls to pump_events no events would ever be placed on the queue. |
46beffd8 |
113 | Often the need for calls to pump_events is hidden from the user since <a href="http://search.cpan.org/perldoc?poll_event">poll_event</a> and <a href="http://search.cpan.org/perldoc?wait_event">wait_event</a> implicitly call pump_events. |
162a0989 |
114 | However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call pump_events to force an event queue update.</p> |
115 | |
116 | |
117 | |
118 | |
119 | |
120 | </div> |
121 | <h2 id="peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </h2> |
122 | <div id="peep_events_event_num_events_action_-2"> |
123 | <p>Checks the event queue for messages and optionally returns them. </p> |
124 | <pre> my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS); |
125 | |
126 | </pre> |
127 | <p>If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue.</p> |
128 | <p>If action is SDL_PEEKEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will not be removed from the queue.</p> |
129 | <p>If action is SDL_GETEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will be removed from the queue.</p> |
130 | <p>The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in</p> |
131 | <p>This function is thread-safe.</p> |
132 | <p>You may have to call pump_events before calling this function. Otherwise, the events may not be ready to be filtered when you call peep_events.</p> |
133 | <p>Examples of mask:</p> |
134 | <dl> |
135 | <dt>SDL_EVENTMASK (SDL_KEYUP)</dt> |
136 | <dt>(SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))</dt> |
137 | <dt>SDL_ALLEVENTS</dt> |
138 | <dt>SDL_KEYUPMASK</dt> |
139 | <dt>SDL_ALLEVENTS ^ SDL_QUITMASK</dt> |
140 | </dl> |
141 | |
142 | </div> |
143 | <h3 id="RETURN">RETURN</h3> |
144 | <div id="RETURN_CONTENT"> |
145 | <p>Number of Events actually stored or -1 if there was an error</p> |
146 | |
147 | </div> |
148 | <h2 id="poll_event_event">poll_event($event)</h2> |
149 | <div id="poll_event_event_CONTENT"> |
150 | <p>Polls for currently pending events. </p> |
55bbf7a2 |
151 | <p>If $event is not NULL, the next event is removed from the queue and stored in the <a href="SDL-Event.html">SDL::Event</a> structure pointed to by $event.</p> |
92e293d6 |
152 | <p>As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>. </p> |
162a0989 |
153 | |
154 | </div> |
155 | <h3 id="RETURN-2">RETURN</h3> |
156 | <div id="RETURN_CONTENT-2"> |
157 | <p>Returns 1 if there are any pending events, or 0 if there are none available. </p> |
158 | |
159 | </div> |
160 | <h2 id="push_event_event">push_event($event)</h2> |
161 | <div id="push_event_event_CONTENT"> |
162 | <p>Pushes an event onto the event queue </p> |
163 | <p>The event queue can actually be used as a two way communication channel. Not only can events be read from the queue, but the user can also push their own events onto it. event is a pointer to the event structure you wish to push onto the queue. |
164 | The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns.</p> |
165 | <p>Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. </p> |
166 | <p>This function is thread safe, and can be called from other threads safely.</p> |
167 | |
168 | </div> |
169 | <h3 id="RETURN-3">RETURN</h3> |
170 | <div id="RETURN_CONTENT-3"> |
171 | <p>Returns 0 on success or -1 if the event couldn't be pushed.</p> |
172 | |
173 | </div> |
174 | <h2 id="wait_event_event">wait_event($event)</h2> |
175 | <div id="wait_event_event_CONTENT"> |
176 | <p>Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.</p> |
177 | <p>If $event is not NULL, the next event is removed from the queue and stored in $event.</p> |
92e293d6 |
178 | <p>As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>. </p> |
162a0989 |
179 | |
180 | </div> |
181 | <h3 id="RETURN-4">RETURN</h3> |
182 | <div id="RETURN_CONTENT-4"> |
183 | <p>0 if there was an error while waiting for events, 1 otherwise</p> |
184 | |
185 | </div> |
cf23a5da |
186 | <h2 id="set_event_filter">set_event_filter</h2> |
187 | <div id="set_event_filter_CONTENT"> |
55bbf7a2 |
188 | <p>Sets up a filter to process all events </p> |
189 | <pre> my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }}; |
190 | |
191 | SDL::Events::set_event_filter($filter); |
192 | |
193 | </pre> |
194 | |
195 | </div> |
196 | <h3 id="PARAMETER">PARAMETER</h3> |
197 | <div id="PARAMETER_CONTENT"> |
198 | <p>set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack</p> |
199 | <pre> sub { my $event_to_test = shift; ...} |
200 | |
201 | </pre> |
202 | <p>to filter the event return a 0, to pass the filter return a 1. </p> |
203 | <p>One <strong>Caveat</strong> is if you are filterign SDL_QUITEVENT the event will be filtered if it is non-intterupt call ( Window closes normally ). If it is a interrupt SDL_QUITEVENT it will be process on the next event poll. </p> |
204 | <p>Events pushed onto to the queue with <a href="/SDL-Events.html#push_events">SDL::Events::push_events</a> or <a href="/SDL-Events.html#peep_events">SDL::Events::peep_events</a> do not get filtered.</p> |
205 | <p>This callback may run in a different thread. </p> |
cf23a5da |
206 | |
207 | </div> |
208 | <h2 id="get_key_state">get_key_state</h2> |
209 | <div id="get_key_state_CONTENT"> |
55bbf7a2 |
210 | <p>Get a snapshot of the current keyboard state</p> |
211 | <pre> my $keys_ref = SDL::Events::get_key_state(); |
212 | |
213 | print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed |
214 | |
215 | </pre> |
216 | <p>Use <a href="/SDL-Events.html#pump_events">SDL::Events::pump_events</a> to update the state array.</p> |
217 | <p>This function gives you the current state after all events have been processed, so if a key or button has been pressed and released before you process events, then the pressed state will never show up in the get_key_state call.</p> |
218 | <p>This function doesn't take into account whether shift has been pressed or not.</p> |
cf23a5da |
219 | |
220 | </div> |
221 | <h2 id="get_mod_state">get_mod_state</h2> |
222 | <div id="get_mod_state_CONTENT"> |
55bbf7a2 |
223 | <p>Get the state of the modifier keys</p> |
224 | <p>Returns the current state of modifier keys</p> |
225 | <p>Return value is an OR'd combination of KMOD_*</p> |
226 | <pre> SDL::Events::pump_events; #get latest mod_state in buffers |
227 | |
228 | my $mod_state = SDL::Events::get_mod_state(); |
229 | |
230 | # Check which ones are pressed with |
231 | |
232 | # no mod pressed? |
233 | |
234 | print 'no_mod' if ( $mod_state & KMOD_NONE ); |
235 | |
236 | # CTRL or ALT |
237 | |
238 | print 'ctrl alt' if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT ); |
239 | |
240 | </pre> |
241 | |
242 | </div> |
243 | <h3 id="MOD_VALUES">MOD VALUES</h3> |
244 | <div id="MOD_VALUES_CONTENT"> |
245 | <dl> |
246 | <dt>KMOD_NONE</dt> |
247 | <dt>KMOD_LSHIFT</dt> |
248 | <dt>KMOD_RSHIFT</dt> |
249 | <dt>KMOD_LCTRL</dt> |
250 | <dt>KMOD_RCTRL</dt> |
251 | <dt>KMOD_LALT</dt> |
252 | <dt>KMOD_RALT</dt> |
253 | <dt>KMOD_LMETA</dt> |
254 | <dt>KMOD_RMETA</dt> |
255 | <dt>KMOD_NUM</dt> |
256 | <dt>KMOD_CAPS</dt> |
257 | <dt>KMOD_MODE</dt> |
258 | <dt>KMOD_CTRL </dt> |
259 | <dd> |
260 | <p>same as KMOD_LCTRL|KMOD_RCTRL</p> |
261 | </dd> |
262 | <dt>KMOD_SHIFT</dt> |
263 | <dd> |
264 | <p>same as KMOD_LSHIFT|KMOD_RSHIFT</p> |
265 | </dd> |
266 | <dt>KMOD_ALT</dt> |
267 | <dd> |
268 | <p>same as KMOD_LALT|KMOD_RALT</p> |
269 | </dd> |
270 | <dt>KMOD_META</dt> |
271 | <dd> |
272 | <p>same as KMOD_LMETA|KMOD_RMETA</p> |
273 | </dd> |
274 | </dl> |
cf23a5da |
275 | |
276 | </div> |
277 | <h2 id="set_mod_state">set_mod_state</h2> |
278 | <div id="set_mod_state_CONTENT"> |
55bbf7a2 |
279 | <p>Get the state of the modifier keys</p> |
280 | <p>The inverse of <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> allows you to impose modifier key states on your application.</p> |
281 | <p>Simply pass your desired modifier states into $modstate. This value can be a OR'd combination of any KMOD* constant.</p> |
282 | <pre> my $modstate = KMOD_LMETA | KMOD_LSHIFT; |
283 | |
284 | </pre> |
285 | <p>Any KMOD_* constant see <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> for constants. |
286 | SDL::Events::set_mod_state( $modstate );</p> |
cf23a5da |
287 | |
288 | </div> |
289 | <h2 id="event_state">event_state </h2> |
290 | <div id="event_state_CONTENT"> |
55bbf7a2 |
291 | <p>Allows you to set the state of processing certain events</p> |
292 | <pre> SDL::Events::event_state( $type, $state ); |
293 | |
294 | </pre> |
295 | <p>A list of $type(s) can be found in <a href="SDL-Event.html">SDL::Event</a></p> |
296 | |
297 | </div> |
298 | <h3 id="STATES">STATES</h3> |
299 | <div id="STATES_CONTENT"> |
300 | <dl> |
301 | <dt>SDL_IGNORE</dt> |
302 | <dd> |
303 | <p>The event of $type will be automatically dropper from the event queue and will not be filtered.</p> |
304 | </dd> |
305 | <dt>SDL_ENABLE</dt> |
306 | <dd> |
307 | <p>The event of $type will be processed normally. This is default.</p> |
308 | </dd> |
309 | <dt>SDL_QUERY</dt> |
310 | <dd> |
311 | <p>The current processing state of the $type will be returned</p> |
312 | </dd> |
313 | </dl> |
cf23a5da |
314 | |
315 | </div> |
316 | <h2 id="get_key_name">get_key_name</h2> |
317 | <div id="get_key_name_CONTENT"> |
55bbf7a2 |
318 | <p>Gets the name of the a SDL virtual keysym</p> |
319 | <pre> my $event = SDL::Event->new(); |
320 | |
321 | while( SDL::Events::poll_event($event) ) |
322 | { |
323 | my $key = $event->key_sym; |
324 | $key_str = SDL::Events::get_key_name($key); |
325 | } |
326 | |
327 | </pre> |
328 | <p>Returns a string with the name of the key sym.</p> |
cf23a5da |
329 | |
330 | </div> |
331 | <h2 id="enable_unicode">enable_unicode </h2> |
332 | <div id="enable_unicode_CONTENT"> |
55bbf7a2 |
333 | <p>Enable/Disable UNICODE translation</p> |
334 | <pre> my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable |
335 | $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables |
336 | |
337 | </pre> |
338 | <p>To obtain the character codes corresponding to received keyboard events, Unicode translation must first be turned on using this function. The translation incurs a slight overhead for each keyboard event and is therefore disabled by default. For each subsequently recieved key down event, the unicode member of the <a href="/SDL-Event.html#key_sym">SDL::Event::key_sym</a> provided structure will be then contain the corresponding character code, or otherwise zero.</p> |
339 | <p>A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is usefull for querying the current translation mode.</p> |
340 | <p>Only key press events will be translated not release events.</p> |
341 | <p>Returns the previous translation mode as (1,0).</p> |
cf23a5da |
342 | |
343 | </div> |
344 | <h2 id="enable_key_repeat">enable_key_repeat </h2> |
345 | <div id="enable_key_repeat_CONTENT"> |
55bbf7a2 |
346 | <p>Sets keyboard repeat rate</p> |
347 | <pre> my $success = SDL::Events::enable_key_repeat( $delay, $interval ); |
348 | |
349 | </pre> |
350 | <p>Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repleats at the speed specified by $interval. Both $delay and $interval are expressed in milliseconds.</p> |
351 | <p>Setting $delay to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.</p> |
352 | <p>Return 0 on success and -1 on fail.</p> |
cf23a5da |
353 | |
354 | </div> |
355 | <h2 id="get_mouse_state">get_mouse_state </h2> |
356 | <div id="get_mouse_state_CONTENT"> |
55bbf7a2 |
357 | <p>Retrives the current state of the mouse</p> |
358 | <pre> my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) }; |
359 | |
360 | print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK); |
361 | |
362 | print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK); |
363 | |
364 | print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK); |
365 | |
366 | print $x.','.$y; |
367 | |
368 | </pre> |
369 | <p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p> |
cf23a5da |
370 | |
371 | </div> |
372 | <h2 id="get_relative_mouse_state">get_relative_mouse_state </h2> |
373 | <div id="get_relative_mouse_state_CONTENT"> |
55bbf7a2 |
374 | <p>Retrives the current relative state of the mouse</p> |
375 | <pre> my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) }; |
376 | |
377 | print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK); |
378 | |
379 | print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK); |
380 | |
381 | print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK); |
382 | |
383 | print $x.','.$y; # this is relative to the last postion of the mouse |
384 | |
385 | </pre> |
386 | <p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p> |
387 | |
388 | |
389 | |
390 | |
cf23a5da |
391 | |
392 | </div> |
393 | <h2 id="get_app_state">get_app_state </h2> |
394 | <div id="get_app_state_CONTENT"> |
55bbf7a2 |
395 | <p>Gets the state of the application</p> |
396 | <pre> my $app_state = SDL::Events::get_app_state(); |
397 | |
398 | </pre> |
399 | <p>The $app_state is a bitwise combination of:</p> |
400 | <dl> |
401 | <dt>SDL_APPMOUSEFOCUS</dt> |
402 | <dd> |
403 | <p>Application has mouse focus</p> |
404 | <pre> warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS |
405 | |
406 | </pre> |
407 | </dd> |
408 | <dt>SDL_APPINPUTFOCUS</dt> |
409 | <dd> |
410 | <p>Application has keyboard focus</p> |
411 | <pre> warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS |
412 | |
413 | |
414 | |
415 | |
416 | </pre> |
417 | </dd> |
418 | <dt>SDL_APPACTIVE</dt> |
419 | <dd> |
420 | <p>Application is visible</p> |
421 | <pre> warn 'Application Visible' if $app_state & SDL_APPACTIVE |
cf23a5da |
422 | |
55bbf7a2 |
423 | </pre> |
b0e2356c |
424 | </dd> |
425 | </dl> |
55bbf7a2 |
426 | |
427 | </div> |
428 | <h2 id="joystick_event_state">joystick_event_state </h2> |
429 | <div id="joystick_event_state_CONTENT"> |
b0e2356c |
430 | <p>Enable/disable joystick event polling</p> |
55bbf7a2 |
431 | <pre> my $status = SDL::Events::joystick_event_state( $state ); |
cf23a5da |
432 | |
55bbf7a2 |
433 | </pre> |
b0e2356c |
434 | <p>This function is used to enable or disable joystick event processing. With joystick event processing disabled you will have to update joystick states with SDL_JoystickUpdate and read the joystick information manually. $state can be:</p> |
435 | <dl> |
55bbf7a2 |
436 | <dt>SDL_QUERY</dt> |
437 | <dt>SDL_ENABLE </dt> |
438 | <dt>SDL_IGNORE</dt> |
439 | <dd> |
440 | <p>Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events</p> |
441 | </dd> |
442 | </dl> |
443 | <p><strong>Warning:</strong> Calling this function may delete all events currently in SDL's event queue.</p> |
444 | <p>If $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.</p> |
cf23a5da |
445 | |
446 | </div> |
162a0989 |
447 | <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p> |
448 | <div id="SEE_ALSO_CONTENT"> |
55bbf7a2 |
449 | <p><a href="SDL-Event.html">SDL::Event</a>, <a href="SDL-Video.html">SDL::Video</a> |
60f74f6f |
450 | </p> |
162a0989 |
451 | |
452 | </div> |
453 | </div> |