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

📦

version 2.548 · 9 versions

🌸 NAME 🌸

okay bestie, this is pods::...:Events(3pm) from the User Contributed Perl Documentation — and it's literally SDL::Events: your icon for Bindings to the Events Category in SDL API. 💅✨

🎀 CATEGORY 🎀

Core, Events — that's the category, periodt. 🫶

🦋 SYNOPSIS 🦋

Most likely you just want to know how to get events for your app. No cap, 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;
        ...
    }
}

💖 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: ':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

💅 METHODS 💅

`pump_events`

Bestie. This is the one that actually feeds the event loop — it gathers events from the input devices.

pump_events();

pump_events scoops up all the pending input info from the devices and drops it onto the event queue. No calls to pump_events = no events ever land on the queue. Ever. It's giving empty party 🎉

Most of the time you don't even think about it, because poll_event and wait_event implicitly call pump_events for you (icons, honestly). BUT — and this is the plot twist — if you're not polling or waiting for events (say you're out here filtering them instead), then you must call pump_events yourself to force an event queue update. No cap. 🫶

`peep_events (event, num_events, action, mask)`

Lowkey the nosiest function in the whole module — it checks the event queue for messages and optionally hands them back to you.

my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);

So here's the vibe check on action:

If action is SDL_ADDEVENT, up to num_events events get 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 that match mask get returned — and they are not removed from the queue. Just peeking, respectfully. 👀
If action is SDL_GETEVENT, up to num_events events at the front of the event queue matching mask get returned — and these ones are removed from the queue. Taken. Gone. Adopted.

The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all the 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. Rude, but true.

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. Main character energy, checks in, doesn't wait around.

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

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. Thread rules are thread rules, 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 — yes, you can just do that. 💅

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.

Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. Like, at all. Don't be surprised. 🙈

This function is thread safe, and can be called from other threads safely. Iconic behaviour honestly.

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 patient queen just sitting there until something happens. ⏳

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

As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that SDL::Video::set_video_mode. (Yes, the sentence is missing a verb. We don't fix, we just vibe.)

RETURN

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

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 out, return a 1 to pass the filter. Simple as. ✨

One Caveat (capital C, it's serious): if you are 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. Sneaky.

Events pushed onto the queue with SDL::Events::push_events or SDL::Events::peep_events do not get filtered. They skip the line. 💀

This callback may run in a different thread. So like... be chill about shared state.

`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. It's the updater, fr fr.

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. Blink and you missed it. 😭

This function doesn't take into account whether shift has been pressed or not. It simply does not care.

`get_mod_state`

Get the state of the modifier keys — returns the current state of the 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`

Get the state of the modifier keys. (Yes, that's what the original says. The heading is doing its own thing. We support her. 💅)

The inverse of SDL::Events::get_mod_state — allows you to impose modifier key states on your application. Forcibly. Consensually. Whatever.

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. (That's "dropped", but honestly "dropper" is a mood and we're keeping the original wording. 🫶)
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 SDL virtual keysym. (Again — "the a". Keeping it. It's canon. 📖)

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. 🎀

`enable_unicode`

Enable/Disable UNICODE translation 🌈

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. Big brain move.

Only key press events will be translated, not release events. Releases don't get the ✨translation✨.

Returns the previous translation mode as (1,0).

`enable_key_repeat`

Sets keyboard repeat rate. Hold the key down and let it go. 🔥

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 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 the the above constants. (Yes, "the the". It's part of the lore now. 💀)

`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.

Btw — the example really does call get_mouse_state, not get_relative_mouse_state. We are not touching it. Copying it exactly, because facts are facts. 🫶

`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. Poof. Be so careful. 😭

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

👀 SEE ALSO 👀

SDL::Event, SDL::Video

🫶 AUTHORS 🫶

See "AUTHORS" in SDL.

That's the whole page, bestie — you made it to the end, and honestly? Iconic. 🌟💖

This was pods::...:Events(3pm) from perl v5.42.3, dated 2026-08-19. Go forth and pump those events. 🦋✨

📦 where this page comes from

ubuntu stonking: libsdl-perl 2.548-6build1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

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

🌸 NAME 🌸

🎀 CATEGORY 🎀

🦋 SYNOPSIS 🦋

💖 CONSTANTS 💖

🌟 Export tag: ':type'

🌈 Export tag: ':mask'

💫 Export tag: ':action'

🍓 Export tag: ':state'

🧚 Export tag: ':hat'

🦋 Export tag: ':app'

💅 Export tag: ':button'

👑 Export tag: ':keysym'

🌈 Export tag ':keymod'

💅 METHODS 💅

pump_events

peep_events (event, num_events, action, mask)

RETURN

poll_event($event)

RETURN

push_event($event)

RETURN

wait_event($event)

RETURN

set_event_filter

PARAMETER

get_key_state

get_mod_state

MOD VALUES

set_mod_state

event_state

STATES

get_key_name

enable_unicode

enable_key_repeat

get_mouse_state

get_relative_mouse_state

get_app_state

joystick_event_state

👀 SEE ALSO 👀

🫶 AUTHORS 🫶

`pump_events`

`peep_events (event, num_events, action, mask)`

`poll_event($event)`

`push_event($event)`

`wait_event($event)`

`set_event_filter`

`get_key_state`

`get_mod_state`

`set_mod_state`

`event_state`

`get_key_name`

`enable_unicode`

`enable_key_repeat`

`get_mouse_state`

`get_relative_mouse_state`

`get_app_state`

`joystick_event_state`