/lib/pods/SDL/Events.pod
Unknown | 584 lines | 366 code | 218 blank | 0 comment | 0 complexity | 7e08f8541623d8f36dccfb224d51491c MD5 | raw file
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