pods::...:Events(3pm)

okay bestie, this is pods::...:Events(3pm) — the user-contributed Perl documentation for SDL::Events 💖. It's giving core docs, but make it cute.

🌸 NAME 🌸

SDL::Events — Bindings to the Events Category in SDL API. That's the name, that's the assignment. 💅

🦋 CATEGORY 🦋

Core, Events — yes, both. Iconic.

✨ SYNOPSIS ✨

Most likely you just want to know how to get events for your app. So here's the whole vibe:

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;
        ...
    }
}

Quick heads-up from the code itself: SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this and also my $event = SDL::Event->new(); # notices 'Event' ne 'Events' — singular Event, not plural Events, bestie. 😭

🎀 CONSTANTS 🎀

Okay so 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 💅

okay bestie, this is the part where we actually do stuff. buckle up 🎀

---

🫧 pump_events

pumps the event loop, gathering events from the input devices. it's giving "heartbeat of the whole system" energy, fr.

pump_events();

pump_events gathers all the pending input info from devices and drops it onto the event queue. and like — without calls to pump_events, no events would ever be placed on the queue. ever. 😭

often you don't even notice you need it, because poll_event and wait_event implicitly call pump_events for you (icons). but if you're not polling or waiting for events — say, you're filtering them — then you literally must call pump_events yourself to force an event queue update. no cap. 💅

---

🔍 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);

so depending on what action is:

• if action is SDL_ADDEVENT, up to num_events events will be added to the back of the event queue.
• if action is SDL_PEEKEVENT, up to num_events events at the front of the event queue, matching mask, will be returned — and they will not be removed from the queue.
• if action is SDL_GETEVENT, up to num_events events at the front of the event queue, matching mask, will be returned — and they will be removed from the queue.

the mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you're interested in 💖

this function is thread-safe. slay.

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

RETURN

number of Events actually stored, or -1 if there was an error.

---

🎣 poll_event($event)

polls for currently pending events.

if $event is not NULL, the next event is removed from the queue and stored in the SDL::Event structure pointed to by $event.

and because this function implicitly calls pump_events, you can only call it in the thread that set the video mode with SDL::Video::set_video_mode. main character thread only, bestie 👑

RETURN

returns 1 if there are any pending events, or 0 if there are none available.

---

📤 push_event($event)

pushes an event onto the event queue. honestly? iconic behaviour.

the event queue can actually be used as a two way communication channel 🫶 not only can events be read from the queue, but you can also push your own events onto it. event is a pointer to the event structure you wish to push onto the queue. the event gets 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 SDL.

this function is thread safe, and can be called from other threads safely ✨

RETURN

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. it's giving "i'll be here whenever you're ready" 🥺

if $event is not NULL, the next event is removed from the queue and stored in $event.

and since this function implicitly calls SDL_PumpEvents, you can only call it in the thread that SDL::Video::set_video_mode. same rules as poll_event, no exceptions.

RETURN

0 if there was an error while waiting for events, 1 otherwise.

---

🧚 set_event_filter

sets up a filter to process all events. vibe check incoming:

my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};

SDL::Events::set_event_filter($filter);

PARAMETER

set_event_filter takes a coderef that it checks all events against. the callback gets an event on the stack:

sub { my $event_to_test = shift; ...}

return a 0 to filter the event (aka yeet it 🗑️), return a 1 to pass the filter.

one Caveat: if you're filtering SDL_QUIT, the event will be filtered if it is a non-interrupt call (window closes normally). if it is an interrupt SDL_QUIT it will be processed on the next event poll. tricky lil thing, keep that in mind 💀

events pushed onto the queue with SDL::Events::push_events or SDL::Events::peep_events do not get filtered. periodt.

this callback may run in a different thread. so like. be normal about that. 😌

---

⌨️ get_key_state

grabs 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 😭 gone, never seen, rip.

also this function doesn't take into account whether shift has been pressed or not. nope. not its job. 🙅

---

🎛️ get_mod_state

gets the state of the modifier keys.

returns the current state of modifier keys.

return value is an OR'd combination of KMOD_*

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 );

MOD VALUES

• 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

gets the state of the modifier keys — well, actually it's the inverse of SDL::Events::get_mod_state 👯 it lets you impose modifier key states on your application. you're literally the main character here, deciding what's pressed.

simply pass your desired modifier states into $modstate. this value can be an OR'd combination of any KMOD* constant.

 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.

STATES

• 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 the default 🎀
• SDL_QUERY — the current processing state of the $type will be returned.

---

🔤 get_key_name

gets the name of a SDL virtual keysym.

 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. cute and useful, we love 💖

---

🌍 enable_unicode

enable/disable UNICODE translation, bestie 🌐

  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 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, and 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 SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL ✨

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 those constants above 💅

---

🐭 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 those constants above 🦋

---

📱 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 SDL's event queue. like, all of them. be so serious before you call this 😭💀

if $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.

---

🌈 SEE ALSO 🌈

SDL::Event, SDL::Video — go read those next, bestie, they're literally right there 🫶

---

👑 AUTHORS 👑

see "AUTHORS" in SDL. that's where the legends live ✨

---

okay that's the whole page!! you made it to the end, i'm so proud of you 🥹💖 this was the perl v5.42.0 edition, dated 2024-05-01, page pods::...:Events(3pm) — go forth and pump those events, queen 👑💅🌸