SDL::Events (3)
Leading comments
Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) Standard preamble: ========================================================================
NAME
SDL::Events - Bindings to the Events Category in SDL APICATEGORY
Core, Events
SYNOPSIS
Most likely you just want to know how to get events for you app.
use SDL ':init';
use SDL::Event;
use SDL::Events ':all';
SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this
...
my $event = SDL::Event->new(); # notices 'Event' ne 'Events'
while( 1 )
{
SDL::Events::pump_events();
while( SDL::Events::poll_event($event) )
{
#check by event type
on_active() if $event->type == SDL_ACTIVEEVENT;
...
}
}
CONSTANTS
The constants are exported by default. You can avoid this by doing:
use SDL::Events ();
and access them directly:
SDL::Events::SDL_ACTIVEEVENT;
or by choosing the export tags below:
Export tag: ':type'
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
Export tag: ':mask'
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
Export tag: ':action'
SDL_ADDEVENT SDL_PEEKEVENT SDL_GETEVENT
Export tag: ':state'
SDL_QUERY SDL_IGNORE SDL_DISABLE / SDL_ENABLE SDL_RELEASED / SDL_PRESSED
Export tag: ':hat'
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
Export tag: ':app'
SDL_APPMOUSEFOCUS SDL_APPINPUTFOCUS SDL_APPACTIVE
Export tag: ':button'
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
Export tag: ':keysym'
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
Export tag ':keymod'
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
METHODS
pump_events
Pumps the event loop, gathering events from the input devices.
pump_events();
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.
peep_events (event, num_events, action, mask)
Checks the event queue for messages and optionally returns them.
my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);
If action is
If action is
If action is
The mask parameter is a bitwise
This function is thread-safe.
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.
Examples of mask:
- SDL_EVENTMASK(SDL_KEYUP)
- (SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) |SDL_EVENTMASK(SDL_MOUSEBUTTONUP))
- SDL_ALLEVENTS
- SDL_KEYUPMASK
- SDL_ALLEVENTS^SDL_QUITMASK
Number of Events actually stored or -1 if there was an error
poll_event($event)
Polls for currently pending events.If $event is not
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.
Returns 1 if there are any pending events, or 0 if there are none available.
push_event($event)
Pushes an event onto the event queueThe 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.
Note: Pushing device input events onto the queue doesn't modify the state of the device within
This function is thread safe, and can be called from other threads safely.
Returns 0 on success or -1 if the event couldn't be pushed.
wait_event($event)
Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.If $event is not
As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that SDL::Video::set_video_mode.
0 if there was an error while waiting for events, 1 otherwise
set_event_filter
Sets up a filter to process all events
my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};
SDL::Events::set_event_filter($filter);
set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack
sub { my $event_to_test = shift; ...}
to filter the event return a 0, to pass the filter return a 1.
One Caveat is if you are filtering
Events pushed onto to the queue with SDL::Events::push_events or SDL::Events::peep_events do not get filtered.
This callback may run in a different thread.
get_key_state
Get a snapshot of the current keyboard state
my $keys_ref = SDL::Events::get_key_state();
print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed
Use SDL::Events::pump_events to update the state array.
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.
This function doesn't take into account whether shift has been pressed or not.
get_mod_state
Get the state of the modifier keysReturns the current state of modifier keys
Return value is an
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 'no_mod' if ( $mod_state & KMOD_NONE ); # CTRL or ALT print 'ctrl alt' if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT );
- KMOD_NONE
- KMOD_LSHIFT
- KMOD_RSHIFT
- KMOD_LCTRL
- KMOD_RCTRL
- KMOD_LALT
- KMOD_RALT
- KMOD_LMETA
- KMOD_RMETA
- KMOD_NUM
- KMOD_CAPS
- KMOD_MODE
- KMOD_CTRL
- same as KMOD_LCTRL|KMOD_RCTRL
- KMOD_SHIFT
- same as KMOD_LSHIFT|KMOD_RSHIFT
- KMOD_ALT
- same as KMOD_LALT|KMOD_RALT
- KMOD_META
- same as KMOD_LMETA|KMOD_RMETA
set_mod_state
Get the state of the modifier keysThe inverse of SDL::Events::get_mod_state allows you to impose modifier key states on your application.
Simply pass your desired modifier states into $modstate. This value can be a
my $modstate = KMOD_LMETA | KMOD_LSHIFT;
Any KMOD_* constant see SDL::Events::get_mod_state for constants.
SDL::Events::set_mod_state( $modstate );
event_state
Allows you to set the state of processing certain events
SDL::Events::event_state( $type, $state );
A list of $type(s) can be found in SDL::Event
- SDL_IGNORE
- The event of $type will be automatically dropper from the event queue and will not be filtered.
- SDL_ENABLE
- The event of $type will be processed normally. This is default.
- SDL_QUERY
- The current processing state of the $type will be returned
get_key_name
Gets the name of the a
my $event = SDL::Event->new();
while( SDL::Events::poll_event($event) )
{
my $key = $event->key_sym;
$key_str = SDL::Events::get_key_name($key);
}
Returns a string with the name of the key sym.
enable_unicode
Enable/Disable
my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
$previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables
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.
A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is useful for querying the current translation mode.
Only key press events will be translated not release events.
Returns the previous translation mode as (1,0).
enable_key_repeat
Sets keyboard repeat rate
my $success = SDL::Events::enable_key_repeat( $delay, $interval );
Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repeats at the speed specified by $interval. Both $delay and $interval are expressed in milliseconds.
Setting $delay to 0 disables key repeating completely. Good default values are
Return 0 on success and -1 on fail.
get_mouse_state
Retrieves the current state of the mouse
my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
print $x.','.$y;
The current button state is returned as a button $bitmask, which can be tested using the the above constants
get_relative_mouse_state
Retrieves the current relative state of the mouse
my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
print $x.','.$y; # this is relative to the last position of the mouse
The current button state is returned as a button $bitmask, which can be tested using the the above constants
get_app_state
Gets the state of the application
my $app_state = SDL::Events::get_app_state();
The $app_state is a bitwise combination of:
- SDL_APPMOUSEFOCUS
-
Application has mouse focus
warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS - SDL_APPINPUTFOCUS
-
Application has keyboard focus
warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS - SDL_APPACTIVE
-
Application is visible
warn 'Application Visible' if $app_state & SDL_APPACTIVE
joystick_event_state
Enable/disable joystick event polling
my $status = SDL::Events::joystick_event_state( $state );
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. $state can be:
- SDL_QUERY
- SDL_ENABLE
- SDL_IGNORE
- Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events
Warning: Calling this function may delete all events currently in
If $state is