/lib/pods/SDL/Events.pod

  1
  2=head1 NAME
  3
  4SDL::Events - Bindings to the Events Category in SDL API
  5
  6=head2 CATEGORY
  7
  8Core, Events
  9
 10=head1 SYNOPSIS
 11
 12Most likely you just want to know how to get events for you app.
 13
 14  use SDL ':init';
 15  use SDL::Event;
 16  use SDL::Events ':all';
 17
 18  SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this 
 19
 20  ...
 21
 22  my $event = SDL::Event->new(); # notices 'Event' ne 'Events'
 23
 24  while( 1 )
 25  {
 26      SDL::Events::pump_events();
 27      while(  SDL::Events::poll_event($event) )
 28      {
 29          #check by event type
 30          on_active() if $event->type == SDL_ACTIVEEVENT; 
 31          ...
 32      }
 33  }
 34
 35=head1 CONSTANTS
 36
 37The constants are exported by default. You can avoid this by doing:
 38
 39 use SDL::Events ();
 40
 41and access them directly:
 42
 43 SDL::Events::SDL_ACTIVEEVENT;
 44
 45or by choosing the export tags below:
 46
 47Export tag: ':type'
 48
 49 SDL_ACTIVEEVENT
 50 SDL_KEYDOWN
 51 SDL_KEYUP
 52 SDL_MOUSEMOTION
 53 SDL_MOUSEBUTTONDOWN
 54 SDL_MOUSEBUTTONUP
 55 SDL_JOYAXISMOTION
 56 SDL_JOYBALLMOTION
 57 SDL_JOYHATMOTION
 58 SDL_JOYBUTTONDOWN
 59 SDL_JOYBUTTONUP
 60 SDL_QUIT
 61 SDL_SYSWMEVENT
 62 SDL_VIDEORESIZE
 63 SDL_VIDEOEXPOSE
 64 SDL_USEREVENT
 65 SDL_NUMEVENTS
 66
 67Export tag: ':mask'
 68
 69 SDL_EVENTMASK
 70 SDL_ACTIVEEVENTMASK
 71 SDL_KEYDOWNMASK
 72 SDL_KEYUPMASK
 73 SDL_KEYEVENTMASK
 74 SDL_MOUSEMOTIONMASK
 75 SDL_MOUSEBUTTONDOWNMASK
 76 SDL_MOUSEBUTTONUPMASK
 77 SDL_MOUSEEVENTMASK
 78 SDL_JOYAXISMOTIONMASK
 79 SDL_JOYBALLMOTIONMASK
 80 SDL_JOYHATMOTIONMASK
 81 SDL_JOYBUTTONDOWNMASK
 82 SDL_JOYBUTTONUPMASK
 83 SDL_JOYEVENTMASK
 84 SDL_VIDEORESIZEMASK
 85 SDL_VIDEOEXPOSEMASK
 86 SDL_QUITMASK
 87 SDL_SYSWMEVENTMASK
 88 SDL_ALLEVENTS
 89
 90Export tag: ':action'
 91
 92 SDL_ADDEVENT
 93 SDL_PEEKEVENT
 94 SDL_GETEVENT
 95
 96Export tag: ':state'
 97
 98 SDL_QUERY
 99 SDL_IGNORE
100 SDL_DISABLE / SDL_ENABLE
101 SDL_RELEASED / SDL_PRESSED
102
103Export tag: ':hat'
104
105 SDL_HAT_CENTERED
106 SDL_HAT_UP / SDL_HAT_RIGHT / SDL_HAT_DOWN / SDL_HAT_LEFT
107 SDL_HAT_RIGHTUP / SDL_HAT_RIGHTDOWN / SDL_HAT_LEFTUP / SDL_HAT_LEFTDOWN
108
109Export tag: ':app'
110
111 SDL_APPMOUSEFOCUS
112 SDL_APPINPUTFOCUS
113 SDL_APPACTIVE
114
115Export tag: ':button'
116
117 SDL_BUTTON
118 SDL_BUTTON_LEFT / SDL_BUTTON_MIDDLE / SDL_BUTTON_RIGHT
119 SDL_BUTTON_WHEELUP / SDL_BUTTON_WHEELDOWN
120 SDL_BUTTON_X1 / SDL_BUTTON_X2
121 SDL_BUTTON_LMASK / SDL_BUTTON_MMASK / SDL_BUTTON_RMASK
122 SDL_BUTTON_X1MASK / SDL_BUTTON_X2MASK
123
124Export tag: ':keysym'
125
126 SDLK_UNKNOWN
127 SDLK_FIRST
128 SDLK_BACKSPACE
129 SDLK_TAB
130 SDLK_CLEAR
131 SDLK_RETURN
132 SDLK_PAUSE
133 SDLK_ESCAPE
134 SDLK_SPACE
135 SDLK_EXCLAIM
136 SDLK_QUOTEDBL
137 SDLK_HASH
138 SDLK_DOLLAR
139 SDLK_AMPERSAND
140 SDLK_QUOTE
141 SDLK_LEFTPAREN / SDLK_RIGHTPAREN
142 SDLK_ASTERISK
143 SDLK_PLUS / SDLK_MINUS
144 SDLK_COMMA
145 SDLK_PERIOD
146 SDLK_0 .. SDLK_9
147 SDLK_COLON
148 SDLK_SEMICOLON
149 SDLK_LESS / SDLK_GREATER
150 SDLK_EQUALS
151 SDLK_QUESTION
152 SDLK_AT
153 SDLK_LEFTBRACKET / SDLK_RIGHTBRACKET
154 SDLK_SLASH / SDLK_BACKSLASH
155 SDLK_CARET
156 SDLK_UNDERSCORE
157 SDLK_BACKQUOTE
158 SDLK_a .. SDLK_z
159 SDLK_DELETE
160 SDLK_WORLD_0 .. SDLK_WORLD_95
161 SDLK_KP0 .. SDLK_KP9
162 SDLK_KP_PERIOD
163 SDLK_KP_DIVIDE / SDLK_KP_MULTIPLY
164 SDLK_KP_MINUS / SDLK_KP_PLUS
165 SDLK_KP_ENTER
166 SDLK_KP_EQUALS
167 SDLK_UP / SDLK_DOWN / SDLK_RIGHT / SDLK_LEFT
168 SDLK_INSERT
169 SDLK_HOME / SDLK_END
170 SDLK_PAGEUP / SDLK_PAGEDOWN
171 SDLK_F1 .. SDLK_F15
172 SDLK_NUMLOCK / SDLK_CAPSLOCK / SDLK_SCROLLOCK
173 SDLK_RSHIFT / SDLK_LSHIFT
174 SDLK_RCTRL  / SDLK_LCTRL
175 SDLK_RALT   / SDLK_LALT
176 SDLK_RMETA  / SDLK_LMETA
177 SDLK_LSUPER / SDLK_RSUPER
178 SDLK_MODE
179 SDLK_COMPOSE
180 SDLK_HELP
181 SDLK_PRINT
182 SDLK_SYSREQ
183 SDLK_BREAK
184 SDLK_MENU
185 SDLK_POWER
186 SDLK_EURO
187 SDLK_UNDO
188
189Export tag ':keymod'
190
191 KMOD_NONE
192 KMOD_LSHIFT / KMOD_RSHIFT / KMOD_SHIFT
193 KMOD_LCTRL  / KMOD_RCTRL  / KMOD_CTRL
194 KMOD_LALT   / KMOD_RALT   / KMOD_ALT
195 KMOD_LMETA  / KMOD_RMETA  / KMOD_META
196 KMOD_NUM
197 KMOD_CAPS
198 KMOD_MODE
199 KMOD_RESERVED
200
201=head1 METHODS
202
203=head2 pump_events
204
205Pumps the event loop, gathering events from the input devices.
206
207	pump_events();
208
209pump_events gathers all the pending input information from devices and places it on the event queue. Without calls to pump_events no events would 
210ever be placed on the queue. 
211Often the need for calls to pump_events is hidden from the user since L</poll_event> and L</wait_event> implicitly call pump_events. 
212However, 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.
213
214
215=head2 peep_events (event, num_events, action, mask) 
216
217Checks the event queue for messages and optionally returns them.  
218
219	my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);
220
221If action is SDL_ADDEVENT, up to num_events events will be added to the back of the event queue.
222
223If action is SDL_PEEKEVENT, up to num_events events at the front of the event queue, matching mask, will be returned and will not be removed from 
224the queue.
225
226If action is SDL_GETEVENT, up to num_events events at the front of the event queue, matching mask, will be returned and will be removed from the 
227queue.
228
229The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in
230
231This function is thread-safe.
232
233You 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.
234
235Examples of mask:
236
237=over
238
239=item SDL_EVENTMASK (SDL_KEYUP)
240
241=item (SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))
242    
243=item SDL_ALLEVENTS
244   
245=item SDL_KEYUPMASK
246    
247=item SDL_ALLEVENTS ^ SDL_QUITMASK
248
249=back 
250
251=head3 RETURN
252
253Number of Events actually stored or -1 if there was an error
254
255=head2 poll_event($event)
256
257Polls for currently pending events. 
258
259If $event is not NULL, the next event is removed from the queue and stored in the L<SDL::Event> structure pointed to by $event.
260
261As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with 
262L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">. 
263
264=head3 RETURN
265
266Returns 1 if there are any pending events, or 0 if there are none available. 
267
268=head2 push_event($event)
269
270Pushes an event onto the event queue 
271
272The 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 
273their own events onto it. event is a pointer to the event structure you wish to push onto the queue. 
274The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns.
275
276Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. 
277
278This function is thread safe, and can be called from other threads safely.
279
280=head3 RETURN
281
282Returns 0 on success or -1 if the event couldn't be pushed.
283
284=head2 wait_event($event)
285
286Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.
287
288If $event is not NULL, the next event is removed from the queue and stored in $event.
289
290As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that 
291L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">.  
292
293=head3 RETURN
294
2950 if there was an error while waiting for events, 1 otherwise
296
297=head2 set_event_filter
298
299Sets up a filter to process all events 
300
301	my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};
302
303	SDL::Events::set_event_filter($filter);
304
305=head3 PARAMETER
306
307set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack
308
309	sub { my $event_to_test = shift; ...}
310
311to filter the event return a 0, to pass the filter return a 1. 
312
313One B<Caveat> is if you are filtering SDL_QUIT the event will be filtered if it is non-interrupt call ( Window closes normally ). If it is a 
314interrupt SDL_QUIT it will be process on the next event poll. 
315
316Events pushed onto to the queue with L<SDL::Events::push_events|SDL::Events/"push_events"> or L<SDL::Events::peep_events|SDL::Events/"peep_events"> 
317do not get filtered.
318
319This callback may run in a different thread. 
320
321=head2 get_key_state
322
323Get a snapshot of the current keyboard state
324
325	my $keys_ref = SDL::Events::get_key_state();
326
327	print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed
328
329Use L<SDL::Events::pump_events|SDL::Events/"pump_events"> to update the state array.
330
331This 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 
332process events, then the pressed state will never show up in the get_key_state call.
333
334This function doesn't take into account whether shift has been pressed or not.
335
336=head2 get_mod_state
337
338Get the state of the modifier keys
339
340Returns the current state of modifier keys
341
342Return value is an OR'd combination of  KMOD_*
343
344 SDL::Events::pump_events; #get latest mod_state in buffers
345
346 my $mod_state = SDL::Events::get_mod_state();
347
348 # Check which ones are pressed with 
349
350 # no mod pressed?
351 
352 print 'no_mod' if  ( $mod_state & KMOD_NONE );
353
354 # CTRL or ALT 
355
356 print 'ctrl alt' if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT );
357
358=head3 MOD VALUES
359
360=over 
361
362=item KMOD_NONE
363
364=item KMOD_LSHIFT
365
366=item KMOD_RSHIFT
367
368=item KMOD_LCTRL
369
370=item KMOD_RCTRL
371
372=item KMOD_LALT
373
374=item KMOD_RALT
375
376=item KMOD_LMETA
377
378=item KMOD_RMETA
379
380=item KMOD_NUM
381
382=item KMOD_CAPS
383
384=item KMOD_MODE
385
386=item KMOD_CTRL 
387
388same as KMOD_LCTRL|KMOD_RCTRL
389
390=item KMOD_SHIFT
391
392same as KMOD_LSHIFT|KMOD_RSHIFT
393
394=item KMOD_ALT
395
396same as KMOD_LALT|KMOD_RALT
397
398=item KMOD_META
399
400same as KMOD_LMETA|KMOD_RMETA
401
402=back
403
404=head2 set_mod_state
405
406Get the state of the modifier keys
407
408The inverse of L<SDL::Events::get_mod_state|SDL::Events/"get_mod_state"> allows you to impose modifier key states on your application.
409
410Simply pass your desired modifier states into $modstate. This value can be a OR'd combination of any KMOD* constant.
411
412 my $modstate = KMOD_LMETA | KMOD_LSHIFT;
413
414Any KMOD_* constant see L<SDL::Events::get_mod_state|SDL::Events/"get_mod_state"> for constants.
415 SDL::Events::set_mod_state( $modstate );
416
417=head2 event_state 
418
419Allows you to set the state of processing certain events
420
421 SDL::Events::event_state( $type, $state );
422
423A list of $type(s) can be found in L<SDL::Event>
424
425=head3 STATES
426
427=over 4
428
429=item SDL_IGNORE
430
431The event of $type will be automatically dropper from the event queue and will not be filtered.
432
433=item SDL_ENABLE
434
435The event of $type will be processed normally. This is default.
436
437=item SDL_QUERY
438
439The current processing state of the $type will be returned
440
441=back
442
443=head2 get_key_name
444
445Gets the name of the a SDL virtual keysym
446
447 my $event = SDL::Event->new();
448
449 while( SDL::Events::poll_event($event) )
450 {
451   my $key = $event->key_sym;
452   $key_str = SDL::Events::get_key_name($key);
453 }
454
455Returns a string with the name of the key sym.
456
457=head2 enable_unicode 
458
459Enable/Disable UNICODE translation
460
461  my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
462     $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables
463
464To obtain the character codes corresponding to received keyboard events, Unicode translation must first be turned on using this function. The 
465translation incurs a slight overhead for each keyboard event and is therefore disabled by default. For each subsequently received key down event, 
466the unicode member of the L<SDL::Event::key_sym|SDL::Event/"key_sym"> provided structure will be then contain the corresponding character code, or 
467otherwise zero.
468
469A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is useful for querying the current translation mode.
470
471Only key press events will be translated not release events.
472
473Returns the previous translation mode as (1,0).
474
475=head2 enable_key_repeat 
476
477Sets keyboard repeat rate
478
479 my $success = SDL::Events::enable_key_repeat( $delay, $interval );
480
481Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repeats at the 
482speed specified by $interval. Both $delay and $interval are expressed in milliseconds.
483
484Setting $delay to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.
485
486Return 0 on success and -1 on fail.
487
488=head2 get_mouse_state 
489
490Retrieves the current state of the mouse
491
492  my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
493
494  print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);    
495
496  print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);   
497
498  print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);  
499
500  print $x.','.$y;
501
502The current button state is returned as a button $bitmask, which can be tested using the the above constants 
503
504=head2 get_relative_mouse_state 
505
506Retrieves the current relative state of the mouse
507
508  my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
509
510  print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);    
511
512  print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);   
513
514  print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);  
515
516  print $x.','.$y; # this is relative to the last position of the mouse
517
518The current button state is returned as a button $bitmask, which can be tested using the the above constants 
519
520
521=head2 get_app_state 
522
523Gets the state of the application
524
525	my $app_state = SDL::Events::get_app_state();
526
527The $app_state is a bitwise combination of:
528
529=over 
530
531=item SDL_APPMOUSEFOCUS
532
533Application has mouse focus
534
535	warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS
536
537=item SDL_APPINPUTFOCUS
538
539Application has keyboard focus
540
541	warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS
542
543
544=item SDL_APPACTIVE
545
546Application is visible
547
548	warn 'Application Visible' if $app_state & SDL_APPACTIVE
549
550=back 
551
552=head2 joystick_event_state 
553
554Enable/disable joystick event polling
555
556	my $status = SDL::Events::joystick_event_state( $state );
557
558This function is used to enable or disable joystick event processing. With joystick event processing disabled you will have to update joystick 
559states with L<SDL::Joystick::update|SDL::Joystick/"update"> and read the joystick information manually. $state can be:
560
561=over 
562
563=item SDL_QUERY
564
565=item SDL_ENABLE 
566
567=item SDL_IGNORE
568
569Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events
570
571=back
572
573B<Warning:> Calling this function may delete all events currently in SDL's event queue.
574
575If $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.
576
577=head1 SEE ALSO
578
579L<SDL::Event>, L<SDL::Video>
580
581=head1 AUTHORS
582
583See L<SDL/AUTHORS>.
584