NAME

SDL2::events - SDL Event Handling

SYNOPSIS

use SDL2 qw[:events];

DESCRIPTION

SDL2::events represents the library's version as three levels: major, minor, and patch level.

Functions

These functions might be imported by name or with the :events tag.

`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_PeepEvents( ... )`

Check the event queue for messages and optionally return them.

action may be any of the following:

SDL_ADDEVENT: up to numevents events will be added to the back of the event queue
SDL_PEEKEVENT: numevents events at the front of the event queue, within the specified minimum and maximum type, will be returned to the caller and will _not_ be removed from the queue
SDL_GETEVENT: up to numevents events at the front of the event queue, within the specified minimum and maximum type, will be returned to the caller and will be removed from the queue

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( ).

This function is thread-safe.

Expected parameters include:

events - destination buffer for the retrieved events
numevents - if action is SDL_ADDEVENT, the number of events to add back to the event queue; if action is SDL_PEEKEVENT or SDL_GETEVENT, the maximum number of events to retrieve
action - action to take
minType - minimum value of the event type to be considered; SDL_FIRSTEVENT is a safe choice
maxType - maximum value of the event type to be considered; SDL_LASTEVENT is a safe choice

Returns the number of events actually stored or a negative error code on failure; call SDL_GetError( ) for more information.

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

Expected parameters include:

type - the type of event to be queried; see SDL_EventType for details

Returns SDL_TRUE if events matching type are present, or SDL_FALSE if events matching type are not present.

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

Expected parameters include:

minType - the low end of event type to be queried, inclusive; see SDL_EventType for details
maxType - the high end of event type to be queried, inclusive; see SDL_EventType for details

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.

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.

Expected parameters include:

type - the type of event to be cleared; see SDL_EventType for details

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

It's also normal to just ignore events you don't care about in your event loop without calling this function.

Expected parameters include:

minType - the low end of event type to be cleared, inclusive; see SDL_EventType for details
maxType - the high end of event type to be cleared, inclusive; see SDL_EventType for details

`SDL_PollEvent( ... )`

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.

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
}

Expected parameters include:

event - the SDL2::Event structure to be filled with the next event from the queue, or undef

Returns 1 if there is a pending event or 0 if there are none available.

`SDL_WaitEvent( ... )`

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.

Expected parameters include:

event - the SDL2::Event structure to be filled in with the next event from the queue, or undef

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.

As this function implicitly calls SDL_PumpEvents( ), you can only call this function in the thread that initialized the video subsystem.

Expected parameters include:

event - the SDL2::Event structure to be filled in with the next event from the queue, or undef
timeout - the maximum number of milliseconds to wait for the next available event

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.

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.

Expected parameters include:

event - the SDL2::Event to be added to the queue

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.

Note: Disabled events never make it to the event filter function; see SDL_EventState( ).

Note: If you just want to inspect events without filtering, you should use SDL_AddEventWatch( ) instead.

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.

Expected parameters include:

filter - An SDL_EventFilter function to call when an event happens param userdata a pointer that is passed to filter
userdata - a pointer that is passed to filter

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

Expected parameters include:

filter - the current callback function will be stored here
userdata - the pointer that is passed to the current event filter will be stored here

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.

WARNING: Be very careful of what you do in the event filter function, as it may run in a different thread!

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.

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( ).

Expected parameters include:

filter - an SDL_EventFilter function to call when an event happens.
userdata - a pointer that is passed to filter

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

Expected parameters include:

filter - the function originally passed to SDL_AddEventWatch( )
userdata - the pointer originally passed to SDL_AddEventWatch( )

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

Expected parameters include:

filter - the SDL_EventFilter function to call when an event happens
userdata - a pointer that is passed to filter

`SDL_EventState( ... )`

Set the state of processing events by type.

state may be any of the following:

- SDL_QUERY: returns the current processing state of the specified event
- SDL_IGNORE (aka SDL_DISABLE): the event will automatically be dropped from the event queue and will not be filtered
- SDL_ENABLE: the event will be processed normally

Expected parameters include:

type - the type of event; see SDL_EventType for details
state - how to process the event

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.

Expected parameters include:

type - the type of event; see SDL_EventType for details

Returns SDL_DISABLE or SDL_ENABLE, representing the processing state of the event before this function makes any changes to it.

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

Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or 0xFFFFFFFF), but is clearer to write.

Expected parameters include:

numevents - the number of events to be allocated

Returns the beginning event number, or (Uint32)-1 if there are not enough user-defined events left.

Defined Values and Enumerations

These may be imported by name or with the given tag.

Event States

General keyboard/mouse state definitions. These may be imported with the :eventstate tag.

SDL_RELEASED
SDL_PRESSED

`SDL_EventType`

The types of events that can be delivered. This enumerations may be imported with the :eventType tag.

SDL_FIRSTEVENT - Unused

Application events

SDL_QUIT - User-requested quit

These application events have special meaning on iOS, see README-ios.md for details.

SDL_APP_TERMINATING - The application is being terminated by the OS

Called on iOS in applicationWillTerminate()

Called on Android in onDestroy()

SDL_APP_LOWMEMORY - The application is low on memory, free memory if possible.

Called on iOS in applicationDidReceiveMemoryWarning()

Called on Android in onLowMemory()

SDL_APP_WILLENTERBACKGROUND - The application is about to enter the background

Called on iOS in applicationWillResignActive()

Called on Android in onPause()

SDL_APP_DIDENTERBACKGROUND - The application did enter the background and may not get CPU for some time

Called on iOS in applicationDidEnterBackground()

Called on Android in onPause()

SDL_APP_WILLENTERFOREGROUND - The application is about to enter the foreground

Called on iOS in applicationWillEnterForeground()

Called on Android in onResume()

SDL_APP_DIDENTERFOREGROUND - The application is now interactive

Called on iOS in applicationDidBecomeActive()

Called on Android in onResume()

SDL_LOCALECHANGED - The user's locale preferences have changed.

Display events

SDL_DISPLAYEVENT - Display state change

Window events

SDL_WINDOWEVENT - Window state change
SDL_SYSWMEVENT - System specific event

Keyboard events

SDL_KEYDOWN - Key pressed
SDL_KEYUP - Key released
SDL_TEXTEDITING - Keyboard text editing (composition)
SDL_TEXTINPUT - Keyboard text input
SDL_KEYMAPCHANGED - Keymap changed due to a system event such as an input language or keyboard layout change

Mouse events

SDL_MOUSEMOTION - Mouse moved
SDL_MOUSEBUTTONDOWN - Mouse button pressed
SDL_MOUSEBUTTONUP - Mouse button released
SDL_MOUSEWHEEL - Mouse wheel motion

Joystick events

SDL_JOYAXISMOTION - Joystick axis motion
SDL_JOYBALLMOTION - Joystick trackball motion
SDL_JOYHATMOTION - Joystick hat position change
SDL_JOYBUTTONDOWN - Joystick button pressed
SDL_JOYBUTTONUP - Joystick button released
SDL_JOYDEVICEADDED - A new joystick has been inserted into the system
SDL_JOYDEVICEREMOVED - An opened joystick has been removed

Game controller events

SDL_CONTROLLERAXISMOTION - Game controller axis motion
SDL_CONTROLLERBUTTONDOWN - Game controller button pressed
SDL_CONTROLLERBUTTONUP - Game controller button released
SDL_CONTROLLERDEVICEADDED - A new Game controller has been inserted into the system
SDL_CONTROLLERDEVICEREMOVED - An opened Game controller has been removed
SDL_CONTROLLERDEVICEREMAPPED - The controller mapping was updated
SDL_CONTROLLERTOUCHPADDOWN - Game controller touchpad was touched
SDL_CONTROLLERTOUCHPADMOTION - Game controller touchpad finger was moved
SDL_CONTROLLERTOUCHPADUP - Game controller touchpad finger was lifted
SDL_CONTROLLERSENSORUPDATE - Game controller sensor was updated

Touch events

SDL_FINGERDOWN
SDL_FINGERUP
SDL_FINGERMOTION

Gesture events

SDL_DOLLARGESTURE
SDL_DOLLARRECORD
SDL_MULTIGESTURE

Clipboard events

SDL_CLIPBOARDUPDATE - The clipboard changed

Drag and drop events

SDL_DROPFILE - The system requests a file open
SDL_DROPTEXT - text/plain drag-and-drop event
SDL_DROPBEGIN - A new set of drops is beginning (NULL filename)
SDL_DROPCOMPLETE - Current set of drops is now complete (NULL filename)

Audio hotplug events

SDL_AUDIODEVICEADDED - A new audio device is available
SDL_AUDIODEVICEREMOVED - An audio device has been removed

Sensor events

SDL_SENSORUPDATE - A sensor was updated

Render events

SDL_RENDER_TARGETS_RESET - The render targets have been reset and their contents need to be updated
SDL_RENDER_DEVICE_RESET - The device has been reset and all textures need to be recreated

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_LASTEVENT

`SDL_eventaction`

This enumeration may be imported with the :eventaction tag.

SDL_ADDEVENT
SDL_PEEKEVENT
SDL_GETEVENT

`SDL_EventFilter`

A function pointer used for callbacks that watch the event queue.

Parameters to expect:

userdata - what was passed as userdata to SDL_SetEventFilter( ) or SDL_AddEventWatch, etc.
event - the event that triggered the callback

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.

Event State

These values may be imported with the eventState tag.

SDL_QUERY - returns the current processing state of the specified event
SDL_IGNORE - aka SDL_DISABLE; the event will automatically be dropped from the event queue and will not be filtered
SDL_DISABLE - aka SDL_IGNORE
SDL_ENABLE - the event will be processed normally

LICENSE

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.

AUTHOR

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Functions

SDL_PumpEvents( )

SDL_PeepEvents( ... )

SDL_HasEvent( ... )

SDL_HasEvents( ... )

SDL_FlushEvent( ... )

SDL_FlushEvents( ... )

SDL_PollEvent( ... )

SDL_WaitEvent( ... )

SDL_WaitEventTimeout( ... )

SDL_PushEvent( ... )

SDL_SetEventFilter( ... )

SDL_GetEventFilter( ... )

SDL_AddEventWatch( ... )

SDL_DelEventWatch( ... )

SDL_FilterEvents( ... )

SDL_EventState( ... )

SDL_GetEventState( ... )

SDL_RegisterEvents( ... )

Defined Values and Enumerations

Event States

SDL_EventType

SDL_eventaction

SDL_EventFilter

Event State

LICENSE

AUTHOR

Module Install Instructions

`SDL_PumpEvents( )`

`SDL_PeepEvents( ... )`

`SDL_HasEvent( ... )`

`SDL_HasEvents( ... )`

`SDL_FlushEvent( ... )`

`SDL_FlushEvents( ... )`

`SDL_PollEvent( ... )`

`SDL_WaitEvent( ... )`

`SDL_WaitEventTimeout( ... )`

`SDL_PushEvent( ... )`

`SDL_SetEventFilter( ... )`

`SDL_GetEventFilter( ... )`

`SDL_AddEventWatch( ... )`

`SDL_DelEventWatch( ... )`

`SDL_FilterEvents( ... )`

`SDL_EventState( ... )`

`SDL_GetEventState( ... )`

`SDL_RegisterEvents( ... )`

`SDL_EventType`

`SDL_eventaction`

`SDL_EventFilter`