.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "pods::SDL::Events 3pm" .TH pods::SDL::Events 3pm 2024-03-28 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME SDL::Events \- Bindings to the Events Category in SDL API .SS CATEGORY .IX Subsection "CATEGORY" Core, Events .SH SYNOPSIS .IX Header "SYNOPSIS" Most likely you just want to know how to get events for you app. .PP .Vb 3 \& use SDL \*(Aq:init\*(Aq; \& use SDL::Event; \& use SDL::Events \*(Aq:all\*(Aq; \& \& SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this \& \& ... \& \& my $event = SDL::Event\->new(); # notices \*(AqEvent\*(Aq ne \*(AqEvents\*(Aq \& \& while( 1 ) \& { \& SDL::Events::pump_events(); \& while( SDL::Events::poll_event($event) ) \& { \& #check by event type \& on_active() if $event\->type == SDL_ACTIVEEVENT; \& ... \& } \& } .Ve .SH CONSTANTS .IX Header "CONSTANTS" The constants are exported by default. You can avoid this by doing: .PP .Vb 1 \& use SDL::Events (); .Ve .PP and access them directly: .PP .Vb 1 \& SDL::Events::SDL_ACTIVEEVENT; .Ve .PP or by choosing the export tags below: .PP Export tag: ':type' .PP .Vb 10 \& SDL_ACTIVEEVENT \& SDL_KEYDOWN \& SDL_KEYUP \& SDL_MOUSEMOTION \& SDL_MOUSEBUTTONDOWN \& SDL_MOUSEBUTTONUP \& SDL_JOYAXISMOTION \& SDL_JOYBALLMOTION \& SDL_JOYHATMOTION \& SDL_JOYBUTTONDOWN \& SDL_JOYBUTTONUP \& SDL_QUIT \& SDL_SYSWMEVENT \& SDL_VIDEORESIZE \& SDL_VIDEOEXPOSE \& SDL_USEREVENT \& SDL_NUMEVENTS .Ve .PP Export tag: ':mask' .PP .Vb 10 \& SDL_EVENTMASK \& SDL_ACTIVEEVENTMASK \& SDL_KEYDOWNMASK \& SDL_KEYUPMASK \& SDL_KEYEVENTMASK \& SDL_MOUSEMOTIONMASK \& SDL_MOUSEBUTTONDOWNMASK \& SDL_MOUSEBUTTONUPMASK \& SDL_MOUSEEVENTMASK \& SDL_JOYAXISMOTIONMASK \& SDL_JOYBALLMOTIONMASK \& SDL_JOYHATMOTIONMASK \& SDL_JOYBUTTONDOWNMASK \& SDL_JOYBUTTONUPMASK \& SDL_JOYEVENTMASK \& SDL_VIDEORESIZEMASK \& SDL_VIDEOEXPOSEMASK \& SDL_QUITMASK \& SDL_SYSWMEVENTMASK \& SDL_ALLEVENTS .Ve .PP Export tag: ':action' .PP .Vb 3 \& SDL_ADDEVENT \& SDL_PEEKEVENT \& SDL_GETEVENT .Ve .PP Export tag: ':state' .PP .Vb 4 \& SDL_QUERY \& SDL_IGNORE \& SDL_DISABLE / SDL_ENABLE \& SDL_RELEASED / SDL_PRESSED .Ve .PP Export tag: ':hat' .PP .Vb 3 \& SDL_HAT_CENTERED \& SDL_HAT_UP / SDL_HAT_RIGHT / SDL_HAT_DOWN / SDL_HAT_LEFT \& SDL_HAT_RIGHTUP / SDL_HAT_RIGHTDOWN / SDL_HAT_LEFTUP / SDL_HAT_LEFTDOWN .Ve .PP Export tag: ':app' .PP .Vb 3 \& SDL_APPMOUSEFOCUS \& SDL_APPINPUTFOCUS \& SDL_APPACTIVE .Ve .PP Export tag: ':button' .PP .Vb 6 \& SDL_BUTTON \& SDL_BUTTON_LEFT / SDL_BUTTON_MIDDLE / SDL_BUTTON_RIGHT \& SDL_BUTTON_WHEELUP / SDL_BUTTON_WHEELDOWN \& SDL_BUTTON_X1 / SDL_BUTTON_X2 \& SDL_BUTTON_LMASK / SDL_BUTTON_MMASK / SDL_BUTTON_RMASK \& SDL_BUTTON_X1MASK / SDL_BUTTON_X2MASK .Ve .PP Export tag: ':keysym' .PP .Vb 10 \& SDLK_UNKNOWN \& SDLK_FIRST \& SDLK_BACKSPACE \& SDLK_TAB \& SDLK_CLEAR \& SDLK_RETURN \& SDLK_PAUSE \& SDLK_ESCAPE \& SDLK_SPACE \& SDLK_EXCLAIM \& SDLK_QUOTEDBL \& SDLK_HASH \& SDLK_DOLLAR \& SDLK_AMPERSAND \& SDLK_QUOTE \& SDLK_LEFTPAREN / SDLK_RIGHTPAREN \& SDLK_ASTERISK \& SDLK_PLUS / SDLK_MINUS \& SDLK_COMMA \& SDLK_PERIOD \& SDLK_0 .. SDLK_9 \& SDLK_COLON \& SDLK_SEMICOLON \& SDLK_LESS / SDLK_GREATER \& SDLK_EQUALS \& SDLK_QUESTION \& SDLK_AT \& SDLK_LEFTBRACKET / SDLK_RIGHTBRACKET \& SDLK_SLASH / SDLK_BACKSLASH \& SDLK_CARET \& SDLK_UNDERSCORE \& SDLK_BACKQUOTE \& SDLK_a .. SDLK_z \& SDLK_DELETE \& SDLK_WORLD_0 .. SDLK_WORLD_95 \& SDLK_KP0 .. SDLK_KP9 \& SDLK_KP_PERIOD \& SDLK_KP_DIVIDE / SDLK_KP_MULTIPLY \& SDLK_KP_MINUS / SDLK_KP_PLUS \& SDLK_KP_ENTER \& SDLK_KP_EQUALS \& SDLK_UP / SDLK_DOWN / SDLK_RIGHT / SDLK_LEFT \& SDLK_INSERT \& SDLK_HOME / SDLK_END \& SDLK_PAGEUP / SDLK_PAGEDOWN \& SDLK_F1 .. SDLK_F15 \& SDLK_NUMLOCK / SDLK_CAPSLOCK / SDLK_SCROLLOCK \& SDLK_RSHIFT / SDLK_LSHIFT \& SDLK_RCTRL / SDLK_LCTRL \& SDLK_RALT / SDLK_LALT \& SDLK_RMETA / SDLK_LMETA \& SDLK_LSUPER / SDLK_RSUPER \& SDLK_MODE \& SDLK_COMPOSE \& SDLK_HELP \& SDLK_PRINT \& SDLK_SYSREQ \& SDLK_BREAK \& SDLK_MENU \& SDLK_POWER \& SDLK_EURO \& SDLK_UNDO .Ve .PP Export tag ':keymod' .PP .Vb 9 \& KMOD_NONE \& KMOD_LSHIFT / KMOD_RSHIFT / KMOD_SHIFT \& KMOD_LCTRL / KMOD_RCTRL / KMOD_CTRL \& KMOD_LALT / KMOD_RALT / KMOD_ALT \& KMOD_LMETA / KMOD_RMETA / KMOD_META \& KMOD_NUM \& KMOD_CAPS \& KMOD_MODE \& KMOD_RESERVED .Ve .SH METHODS .IX Header "METHODS" .SS pump_events .IX Subsection "pump_events" Pumps the event loop, gathering events from the input devices. .PP .Vb 1 \& pump_events(); .Ve .PP 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. Often the need for calls to pump_events is hidden from the user since "poll_event" and "wait_event" implicitly call pump_events. 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. .SS "peep_events (event, num_events, action, mask)" .IX Subsection "peep_events (event, num_events, action, mask)" Checks the event queue for messages and optionally returns them. .PP .Vb 1 \& my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS); .Ve .PP If action is SDL_ADDEVENT, up to num_events events will be added to the back of the event queue. .PP If 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 the queue. .PP If 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 queue. .PP The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in .PP This function is thread-safe. .PP 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. .PP Examples of mask: .IP "SDL_EVENTMASK (SDL_KEYUP)" 4 .IX Item "SDL_EVENTMASK (SDL_KEYUP)" .PD 0 .IP "(SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))" 4 .IX Item "(SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))" .IP SDL_ALLEVENTS 4 .IX Item "SDL_ALLEVENTS" .IP SDL_KEYUPMASK 4 .IX Item "SDL_KEYUPMASK" .IP "SDL_ALLEVENTS ^ SDL_QUITMASK" 4 .IX Item "SDL_ALLEVENTS ^ SDL_QUITMASK" .PD .PP \fIRETURN\fR .IX Subsection "RETURN" .PP Number of Events actually stored or \-1 if there was an error .SS poll_event($event) .IX Subsection "poll_event($event)" Polls for currently pending events. .PP If \f(CW$event\fR is not NULL, the next event is removed from the queue and stored in the SDL::Event structure pointed to by \f(CW$event\fR. .PP As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with SDL::Video::set_video_mode. .PP \fIRETURN\fR .IX Subsection "RETURN" .PP Returns 1 if there are any pending events, or 0 if there are none available. .SS push_event($event) .IX Subsection "push_event($event)" Pushes an event onto the event queue .PP 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. The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns. .PP Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. .PP This function is thread safe, and can be called from other threads safely. .PP \fIRETURN\fR .IX Subsection "RETURN" .PP Returns 0 on success or \-1 if the event couldn't be pushed. .SS wait_event($event) .IX Subsection "wait_event($event)" Waits indefinitely for the next available \f(CW$event\fR, returning 0 if there was an error while waiting for events, 1 otherwise. .PP If \f(CW$event\fR is not NULL, the next event is removed from the queue and stored in \f(CW$event\fR. .PP As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that SDL::Video::set_video_mode. .PP \fIRETURN\fR .IX Subsection "RETURN" .PP 0 if there was an error while waiting for events, 1 otherwise .SS set_event_filter .IX Subsection "set_event_filter" Sets up a filter to process all events .PP .Vb 1 \& my $filter = sub { if($_[0]\->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }}; \& \& SDL::Events::set_event_filter($filter); .Ve .PP \fIPARAMETER\fR .IX Subsection "PARAMETER" .PP set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack .PP .Vb 1 \& sub { my $event_to_test = shift; ...} .Ve .PP to filter the event return a 0, to pass the filter return a 1. .PP One \fBCaveat\fR 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 interrupt SDL_QUIT it will be process on the next event poll. .PP Events pushed onto to the queue with SDL::Events::push_events or SDL::Events::peep_events do not get filtered. .PP This callback may run in a different thread. .SS get_key_state .IX Subsection "get_key_state" Get a snapshot of the current keyboard state .PP .Vb 1 \& my $keys_ref = SDL::Events::get_key_state(); \& \& print $keys_ref\->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed .Ve .PP Use SDL::Events::pump_events to update the state array. .PP 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. .PP This function doesn't take into account whether shift has been pressed or not. .SS get_mod_state .IX Subsection "get_mod_state" Get the state of the modifier keys .PP Returns the current state of modifier keys .PP Return value is an OR'd combination of KMOD_* .PP .Vb 1 \& SDL::Events::pump_events; #get latest mod_state in buffers \& \& my $mod_state = SDL::Events::get_mod_state(); \& \& # Check which ones are pressed with \& \& # no mod pressed? \& \& print \*(Aqno_mod\*(Aq if ( $mod_state & KMOD_NONE ); \& \& # CTRL or ALT \& \& print \*(Aqctrl alt\*(Aq if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT ); .Ve .PP \fIMOD VALUES\fR .IX Subsection "MOD VALUES" .IP KMOD_NONE 4 .IX Item "KMOD_NONE" .PD 0 .IP KMOD_LSHIFT 4 .IX Item "KMOD_LSHIFT" .IP KMOD_RSHIFT 4 .IX Item "KMOD_RSHIFT" .IP KMOD_LCTRL 4 .IX Item "KMOD_LCTRL" .IP KMOD_RCTRL 4 .IX Item "KMOD_RCTRL" .IP KMOD_LALT 4 .IX Item "KMOD_LALT" .IP KMOD_RALT 4 .IX Item "KMOD_RALT" .IP KMOD_LMETA 4 .IX Item "KMOD_LMETA" .IP KMOD_RMETA 4 .IX Item "KMOD_RMETA" .IP KMOD_NUM 4 .IX Item "KMOD_NUM" .IP KMOD_CAPS 4 .IX Item "KMOD_CAPS" .IP KMOD_MODE 4 .IX Item "KMOD_MODE" .IP KMOD_CTRL 4 .IX Item "KMOD_CTRL" .PD same as KMOD_LCTRL|KMOD_RCTRL .IP KMOD_SHIFT 4 .IX Item "KMOD_SHIFT" same as KMOD_LSHIFT|KMOD_RSHIFT .IP KMOD_ALT 4 .IX Item "KMOD_ALT" same as KMOD_LALT|KMOD_RALT .IP KMOD_META 4 .IX Item "KMOD_META" same as KMOD_LMETA|KMOD_RMETA .SS set_mod_state .IX Subsection "set_mod_state" Get the state of the modifier keys .PP The inverse of SDL::Events::get_mod_state allows you to impose modifier key states on your application. .PP Simply pass your desired modifier states into \f(CW$modstate\fR. This value can be a OR'd combination of any KMOD* constant. .PP .Vb 1 \& my $modstate = KMOD_LMETA | KMOD_LSHIFT; .Ve .PP Any KMOD_* constant see SDL::Events::get_mod_state for constants. SDL::Events::set_mod_state( \f(CW$modstate\fR ); .SS event_state .IX Subsection "event_state" Allows you to set the state of processing certain events .PP .Vb 1 \& SDL::Events::event_state( $type, $state ); .Ve .PP A list of \f(CW$typ\fRe(s) can be found in SDL::Event .PP \fISTATES\fR .IX Subsection "STATES" .IP SDL_IGNORE 4 .IX Item "SDL_IGNORE" The event of \f(CW$type\fR will be automatically dropper from the event queue and will not be filtered. .IP SDL_ENABLE 4 .IX Item "SDL_ENABLE" The event of \f(CW$type\fR will be processed normally. This is default. .IP SDL_QUERY 4 .IX Item "SDL_QUERY" The current processing state of the \f(CW$type\fR will be returned .SS get_key_name .IX Subsection "get_key_name" Gets the name of the a SDL virtual keysym .PP .Vb 1 \& my $event = SDL::Event\->new(); \& \& while( SDL::Events::poll_event($event) ) \& { \& my $key = $event\->key_sym; \& $key_str = SDL::Events::get_key_name($key); \& } .Ve .PP Returns a string with the name of the key sym. .SS enable_unicode .IX Subsection "enable_unicode" Enable/Disable UNICODE translation .PP .Vb 2 \& my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable \& $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables .Ve .PP 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 received key down event, the unicode member of the SDL::Event::key_sym provided structure will be then contain the corresponding character code, or otherwise zero. .PP A value of 1 for enabling, 0 for disabling and \-1 for unchanged. \-1 is useful for querying the current translation mode. .PP Only key press events will be translated not release events. .PP Returns the previous translation mode as (1,0). .SS enable_key_repeat .IX Subsection "enable_key_repeat" Sets keyboard repeat rate .PP .Vb 1 \& my $success = SDL::Events::enable_key_repeat( $delay, $interval ); .Ve .PP Enables or disables the keyboard repeat rate. \f(CW$delay\fR specifies how long the key must be pressed before it begins repeating, it then repeats at the speed specified by \f(CW$interval\fR. Both \f(CW$delay\fR and \f(CW$interval\fR are expressed in milliseconds. .PP Setting \f(CW$delay\fR to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL. .PP Return 0 on success and \-1 on fail. .SS get_mouse_state .IX Subsection "get_mouse_state" Retrieves the current state of the mouse .PP .Vb 1 \& my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) }; \& \& print \*(AqButton Left pressed\*(Aq if ($mask & SDL_BUTTON_LMASK); \& \& print \*(AqButton Right pressed\*(Aq if ($mask & SDL_BUTTON_RMASK); \& \& print \*(AqButton Middle pressed\*(Aq if ($mask & SDL_BUTTON_MMASK); \& \& print $x.\*(Aq,\*(Aq.$y; .Ve .PP The current button state is returned as a button \f(CW$bitmask\fR, which can be tested using the the above constants .SS get_relative_mouse_state .IX Subsection "get_relative_mouse_state" Retrieves the current relative state of the mouse .PP .Vb 1 \& my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) }; \& \& print \*(AqButton Left pressed\*(Aq if ($mask & SDL_BUTTON_LMASK); \& \& print \*(AqButton Right pressed\*(Aq if ($mask & SDL_BUTTON_RMASK); \& \& print \*(AqButton Middle pressed\*(Aq if ($mask & SDL_BUTTON_MMASK); \& \& print $x.\*(Aq,\*(Aq.$y; # this is relative to the last position of the mouse .Ve .PP The current button state is returned as a button \f(CW$bitmask\fR, which can be tested using the the above constants .SS get_app_state .IX Subsection "get_app_state" Gets the state of the application .PP .Vb 1 \& my $app_state = SDL::Events::get_app_state(); .Ve .PP The \f(CW$app_state\fR is a bitwise combination of: .IP SDL_APPMOUSEFOCUS 4 .IX Item "SDL_APPMOUSEFOCUS" Application has mouse focus .Sp .Vb 1 \& warn \*(Aqmouse focus\*(Aq if $app_state & SDL_APPMOUSEFOCUS .Ve .IP SDL_APPINPUTFOCUS 4 .IX Item "SDL_APPINPUTFOCUS" Application has keyboard focus .Sp .Vb 1 \& warn \*(Aqkeyboard focus\*(Aq if $app_state & SDL_APPINPUTFOCUS .Ve .IP SDL_APPACTIVE 4 .IX Item "SDL_APPACTIVE" Application is visible .Sp .Vb 1 \& warn \*(AqApplication Visible\*(Aq if $app_state & SDL_APPACTIVE .Ve .SS joystick_event_state .IX Subsection "joystick_event_state" Enable/disable joystick event polling .PP .Vb 1 \& my $status = SDL::Events::joystick_event_state( $state ); .Ve .PP 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::Joystick::update and read the joystick information manually. \f(CW$state\fR can be: .IP SDL_QUERY 4 .IX Item "SDL_QUERY" .PD 0 .IP SDL_ENABLE 4 .IX Item "SDL_ENABLE" .IP SDL_IGNORE 4 .IX Item "SDL_IGNORE" .PD Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events .PP \&\fBWarning:\fR Calling this function may delete all events currently in SDL's event queue. .PP If \f(CW$state\fR is SDL_QUERY then the current state is returned, otherwise the new processing state is returned. .SH "SEE ALSO" .IX Header "SEE ALSO" SDL::Event, SDL::Video .SH AUTHORS .IX Header "AUTHORS" See "AUTHORS" in SDL.