SDL2::events - SDL Event Handling
use SDL2 qw[:events];
SDL2::events represents the library's version as three levels: major, minor, and patch level.
These functions might be imported by name or with the :events tag.
:events
SDL_PumpEvents( )
Pump the event loop, gathering events from the input devices.
SDL_PumpEvents( );
This function updates the event queue and internal input device state.
WARNING: This should only be run in the thread that initialized the video subsystem, and for extra safety, you should consider only doing those things on the main thread in any case.
SDL_PumpEvents( ) gathers all the pending input information from devices and places it in the event queue. Without calls to SDL_PumpEvents( ) no events would ever be placed on the queue. Often the need for calls to SDL_PumpEvents( ) is hidden from the user since SDL_PollEvent( ... ) and SDL_WaitEvent( ... ) implicitly call SDL_PumpEvents( ). However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call SDL_PumpEvents( ) to force an event queue update.
SDL_PollEvent( ... )
SDL_WaitEvent( ... )
SDL_PeepEvents( ... )
Check the event queue for messages and optionally return them.
action may be any of the following:
action
SDL_ADDEVENT
numevents
SDL_PEEKEVENT
SDL_GETEVENT
You may have to call SDL_PumpEvents( ) before calling this function. Otherwise, the events may not be ready to be filtered when you call SDL_PeepEvents( ).
SDL_PeepEvents( )
This function is thread-safe.
Expected parameters include:
events
minType
SDL_FIRSTEVENT
maxType
SDL_LASTEVENT
Returns the number of events actually stored or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_GetError( )
SDL_HasEvent( ... )
Check for the existence of a certain event type in the event queue.
If you need to check for a range of event types, use SDL_HasEvents( ) instead.
SDL_HasEvents( )
type
Returns SDL_TRUE if events matching type are present, or SDL_FALSE if events matching type are not present.
SDL_TRUE
SDL_FALSE
SDL_HasEvents( ... )
Check for the existence of certain event types in the event queue.
If you need to check for a single event type, use SDL_HasEvent( ) instead.
SDL_HasEvent( )
SDL_EventType
Returns SDL_TRUE if events with type >= minType and <= maxType are present, or SDL_FALSE if not.
SDL_FlushEvent( ... )
Clear events of a specific type from the event queue.
This will unconditionally remove any events from the queue that match type. If you need to remove a range of event types, use SDL_FlushEvents( ) instead.
SDL_FlushEvents( )
It's also normal to just ignore events you don't care about in your event loop without calling this function.
This function only affects currently queued events. If you want to make sure that all pending OS events are flushed, you can call SDL_PumpEvents( ) on the main thread immediately before the flush call.
SDL_FlushEvents( ... )
Clear events of a range of types from the event queue.
This will unconditionally remove any events from the queue that are in the range of minType to maxType, inclusive. If you need to remove a single event type, use SDL_FlushEvent( ) instead.
SDL_FlushEvent( )
Poll for currently pending events.
If event is not undef, the next event is removed from the queue and stored in the SDL2::Event structure pointed to by event. The 1 returned refers to this event, immediately stored in the SDL Event structure -- not an event to follow.
event
undef
1
If event is undef, it simply returns 1 if there is an event in the queue, but will not remove it from the queue.
As this function implicitly calls SDL_PumpEvents( ), you can only call this function in the thread that set the video mode.
SDL_PollEvent( ... ) is the favored way of receiving system events since it can be done from the main loop and does not suspend the main loop while waiting on an event to be posted.
The common practice is to fully process the event queue once every frame, usually as a first step before updating the game's state:
while (game_is_still_running()) { while (SDL_PollEvent(\my $event)) { # poll until all events are handled! # decide what to do with this event. } # update game state, draw the current frame }
Returns 1 if there is a pending event or 0 if there are none available.
0
Wait indefinitely for the next available event.
If event is not undef, the next event is removed from the queue and stored in the SDL2::Event structure pointed to by event.
As this function implicitly calls SDL_PumpEvents( ), you can only call this function in the thread that initialized the video subsystem.
Returns 1 on success or 0 if there was an error while waiting for events; call SDL_GetError( ) for more information.
SDL_WaitEventTimeout( ... )
Wait until the specified timeout (in milliseconds) for the next available event.
If event is not , the next event is removed from the queue and stored in the DL2::Event structure pointed to by event.
timeout
Returns 1 on success or 0 if there was an error while waiting for events; call SDL_GetError( ) for more information. This also returns 0 if the timeout elapsed without an event arriving.
SDL_PushEvent( ... )
Add an event to the event queue.
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 SDL_PushEvent( ) returns.
SDL_PushEvent( )
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.
Note: Events pushed onto the queue with SDL_PushEvent( ) get passed through the event filter but events added with SDL_PeepEvents( ) do not.
For pushing application-specific events, please use SDL_RegisterEvents( ) to get an event type that does not conflict with other code that also wants its own custom event types.
SDL_RegisterEvents( )
Returns 1 on success, 0 if the event was filtered, or a negative error code on failure; call SDL_GetError( ) for more information. A common reason for error is the event queue being full.
SDL_SetEventFilter( ... )
Set up a filter to process all events before they change internal state and are posted to the internal event queue.
If the filter function returns 1 when called, then the event will be added to the internal queue. If it returns 0, then the event will be dropped from the queue, but the internal state will still be updated. This allows selective filtering of dynamically arriving events.
WARNING: Be very careful of what you do in the event filter function, as it may run in a different thread!
On platforms that support it, if the quit event is generated by an interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the application at the next event poll.
There is one caveat when dealing with the SDL_QuitEvent event type. The event filter is only called when the window manager desires to close the application window. If the event filter returns 1, then the window will be closed, otherwise the window will remain open if possible.
SDL_QuitEvent
Note: Disabled events never make it to the event filter function; see SDL_EventState( ).
SDL_EventState( )
Note: If you just want to inspect events without filtering, you should use SDL_AddEventWatch( ) instead.
SDL_AddEventWatch( )
Note: Events pushed onto the queue with SDL_PushEvent( ) get passed through the event filter, but events pushed onto the queue with SDL_PeepEvents( ) do not.
filter
SDL_EventFilter
userdata
SDL_GetEventFilter( ... )
Query the current event filter.
This function can be used to "chain" filters, by saving the existing filter before replacing it with a function that will call that saved filter.
Returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
SDL_AddEventWatch( ... )
Add a callback to be triggered when an event is added to the event queue.
filter will be called when an event happens, and its return value is ignored.
If the quit event is generated by a signal (e.g. SIGINT), it will bypass the internal queue and be delivered to the watch callback immediately, and arrive at the next event poll.
SIGINT
Note: the callback is called for events posted by the user through SDL_PushEvent( ), but not for disabled events, nor for events by a filter callback set with SDL_SetEventFilter( ), nor for events posted by the user through SDL_PeepEvents( ).
SDL_SetEventFilter( )
SDL_DelEventWatch( ... )
Remove an event watch callback added with SDL_AddEventWatch( ).
This function takes the same input as SDL_AddEventWatch( ) to identify and delete the corresponding callback.
SDL_FilterEvents( ... )
Run a specific filter function on the current event queue, removing any events for which the filter returns 0.
See SDL_SetEventFilter( ) for more information. Unlike SDL_SetEventFilter( ), this function does not change the filter permanently, it only uses the supplied filter until this function returns.
SDL_EventState( ... )
Set the state of processing events by type.
state may be any of the following:
state
SDL_QUERY
SDL_IGNORE
SDL_DISABLE
SDL_ENABLE
Returns SDL_DISABLE or SDL_ENABLE, representing the processing state of the event before this function makes any changes to it.
SDL_GetEventState( ... )
Queries for the current processing state of the specified event.
SDL_RegisterEvents( ... )
Allocate a set of user-defined events, and return the beginning event number for that set of events.
Calling this function with `numevents` <= 0 is an error and will return (Uint32)-1.
(Uint32)-1
Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or 0xFFFFFFFF), but is clearer to write.
0xFFFFFFFF
Returns the beginning event number, or (Uint32)-1 if there are not enough user-defined events left.
These may be imported by name or with the given tag.
General keyboard/mouse state definitions. These may be imported with the :eventstate tag.
:eventstate
SDL_RELEASED
SDL_PRESSED
The types of events that can be delivered. This enumerations may be imported with the :eventType tag.
:eventType
Application events
SDL_QUIT
These application events have special meaning on iOS, see README-ios.md for details.
README-ios.md
SDL_APP_TERMINATING
Called on iOS in applicationWillTerminate()
applicationWillTerminate()
Called on Android in onDestroy()
onDestroy()
SDL_APP_LOWMEMORY
Called on iOS in applicationDidReceiveMemoryWarning()
applicationDidReceiveMemoryWarning()
Called on Android in onLowMemory()
onLowMemory()
SDL_APP_WILLENTERBACKGROUND
Called on iOS in applicationWillResignActive()
applicationWillResignActive()
Called on Android in onPause()
onPause()
SDL_APP_DIDENTERBACKGROUND
Called on iOS in applicationDidEnterBackground()
applicationDidEnterBackground()
SDL_APP_WILLENTERFOREGROUND
Called on iOS in applicationWillEnterForeground()
applicationWillEnterForeground()
Called on Android in onResume()
onResume()
SDL_APP_DIDENTERFOREGROUND
Called on iOS in applicationDidBecomeActive()
applicationDidBecomeActive()
SDL_LOCALECHANGED
Display events
SDL_DISPLAYEVENT
Window events
SDL_WINDOWEVENT
SDL_SYSWMEVENT
Keyboard events
SDL_KEYDOWN
SDL_KEYUP
SDL_TEXTEDITING
SDL_TEXTINPUT
SDL_KEYMAPCHANGED
Mouse events
SDL_MOUSEMOTION
SDL_MOUSEBUTTONDOWN
SDL_MOUSEBUTTONUP
SDL_MOUSEWHEEL
Joystick events
SDL_JOYAXISMOTION
SDL_JOYBALLMOTION
SDL_JOYHATMOTION
SDL_JOYBUTTONDOWN
SDL_JOYBUTTONUP
SDL_JOYDEVICEADDED
SDL_JOYDEVICEREMOVED
Game controller events
SDL_CONTROLLERAXISMOTION
SDL_CONTROLLERBUTTONDOWN
SDL_CONTROLLERBUTTONUP
SDL_CONTROLLERDEVICEADDED
SDL_CONTROLLERDEVICEREMOVED
SDL_CONTROLLERDEVICEREMAPPED
SDL_CONTROLLERTOUCHPADDOWN
SDL_CONTROLLERTOUCHPADMOTION
SDL_CONTROLLERTOUCHPADUP
SDL_CONTROLLERSENSORUPDATE
Touch events
SDL_FINGERDOWN
SDL_FINGERUP
SDL_FINGERMOTION
Gesture events
SDL_DOLLARGESTURE
SDL_DOLLARRECORD
SDL_MULTIGESTURE
Clipboard events
SDL_CLIPBOARDUPDATE
Drag and drop events
SDL_DROPFILE
SDL_DROPTEXT
SDL_DROPBEGIN
SDL_DROPCOMPLETE
Audio hotplug events
SDL_AUDIODEVICEADDED
SDL_AUDIODEVICEREMOVED
Sensor events
SDL_SENSORUPDATE
Render events
SDL_RENDER_TARGETS_RESET
SDL_RENDER_DEVICE_RESET
Events SDL_USEREVENT through SDL_LASTEVENT are for your use, and should be allocated with SDL_RegisterEvents( ... )
SDL_USEREVENT
This last event is only for bounding internal arrays
SDL_eventaction
This enumeration may be imported with the :eventaction tag.
:eventaction
A function pointer used for callbacks that watch the event queue.
Parameters to expect:
SDL_AddEventWatch
Your callback should return 1 to permit event to be added to the queue, and 0 to disallow it. When used with SDL_AddEventWatch, the return value is ignored.
These values may be imported with the eventState tag.
eventState
Copyright (C) Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.
Sanko Robinson <sanko@cpan.org>
To install SDL2::FFI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SDL2::FFI
CPAN shell
perl -MCPAN -e shell install SDL2::FFI
For more information on module installation, please visit the detailed CPAN module installation guide.