SDL 3.0
|
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_audio.h>
#include <SDL3/SDL_camera.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_gamepad.h>
#include <SDL3/SDL_joystick.h>
#include <SDL3/SDL_keyboard.h>
#include <SDL3/SDL_keycode.h>
#include <SDL3/SDL_mouse.h>
#include <SDL3/SDL_pen.h>
#include <SDL3/SDL_power.h>
#include <SDL3/SDL_sensor.h>
#include <SDL3/SDL_scancode.h>
#include <SDL3/SDL_touch.h>
#include <SDL3/SDL_video.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>
Go to the source code of this file.
Typedefs | |
typedef bool(* | SDL_EventFilter) (void *userdata, SDL_Event *event) |
A function pointer used for callbacks that watch the event queue.
userdata | what was passed as userdata to SDL_SetEventFilter() or SDL_AddEventWatch, etc. |
event | the event that triggered the callback. |
\threadsafety SDL may call this callback at any time from any thread; the application is responsible for locking resources the callback touches that need to be protected.
Definition at line 1377 of file SDL_events.h.
enum SDL_EventAction |
The type of action to request from SDL_PeepEvents().
Enumerator | |
---|---|
SDL_ADDEVENT | Add events to the back of the queue. |
SDL_PEEKEVENT | Check but don't remove events from the queue front. |
SDL_GETEVENT | Retrieve/remove events from the front of the queue. |
Definition at line 1078 of file SDL_events.h.
enum SDL_EventType |
Event queue management.
It's extremely common–often required–that an app deal with SDL's event queue. Almost all useful information about interactions with the real world flow through here: the user interacting with the computer and app, hardware coming and going, the system changing in some way, etc.
An app generally takes a moment, perhaps at the start of a new frame, to examine any events that have occured since the last time and process or ignore them. This is generally done by calling SDL_PollEvent() in a loop until it returns false (or, if using the main callbacks, events are provided one at a time in calls to SDL_AppEvent() before the next call to SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() at all).
There is other forms of control, too: SDL_PeepEvents() has more functionality at the cost of more complexity, and SDL_WaitEvent() can block the process until something interesting happens, which might be beneficial for certain types of programs on low-power hardware. One may also call SDL_AddEventWatch() to set a callback when new events arrive.
The app is free to generate their own events, too: SDL_PushEvent allows the app to put events onto the queue for later retrieval; SDL_RegisterEvents can guarantee that these events have a type that isn't in use by other parts of the system. The types of events that can be delivered.
Enumerator | |
---|---|
SDL_EVENT_FIRST | Unused (do not remove) |
SDL_EVENT_QUIT | User-requested quit |
SDL_EVENT_TERMINATING | The application is being terminated by the OS. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationWillTerminate() Called on Android in onDestroy() |
SDL_EVENT_LOW_MEMORY | The application is low on memory, free memory if possible. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationDidReceiveMemoryWarning() Called on Android in onTrimMemory() |
SDL_EVENT_WILL_ENTER_BACKGROUND | The application is about to enter the background. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationWillResignActive() Called on Android in onPause() |
SDL_EVENT_DID_ENTER_BACKGROUND | The application did enter the background and may not get CPU for some time. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationDidEnterBackground() Called on Android in onPause() |
SDL_EVENT_WILL_ENTER_FOREGROUND | The application is about to enter the foreground. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationWillEnterForeground() Called on Android in onResume() |
SDL_EVENT_DID_ENTER_FOREGROUND | The application is now interactive. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationDidBecomeActive() Called on Android in onResume() |
SDL_EVENT_LOCALE_CHANGED | The user's locale preferences have changed. |
SDL_EVENT_SYSTEM_THEME_CHANGED | The system theme changed |
SDL_EVENT_DISPLAY_ORIENTATION | Display orientation has changed to data1 |
SDL_EVENT_DISPLAY_ADDED | Display has been added to the system |
SDL_EVENT_DISPLAY_REMOVED | Display has been removed from the system |
SDL_EVENT_DISPLAY_MOVED | Display has changed position |
SDL_EVENT_DISPLAY_DESKTOP_MODE_CHANGED | Display has changed desktop mode |
SDL_EVENT_DISPLAY_CURRENT_MODE_CHANGED | Display has changed current mode |
SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED | Display has changed content scale |
SDL_EVENT_DISPLAY_FIRST | |
SDL_EVENT_DISPLAY_LAST | |
SDL_EVENT_WINDOW_SHOWN | Window has been shown |
SDL_EVENT_WINDOW_HIDDEN | Window has been hidden |
SDL_EVENT_WINDOW_EXPOSED | Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event |
SDL_EVENT_WINDOW_MOVED | Window has been moved to data1, data2 |
SDL_EVENT_WINDOW_RESIZED | Window has been resized to data1xdata2 |
SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED | The pixel size of the window has changed to data1xdata2 |
SDL_EVENT_WINDOW_METAL_VIEW_RESIZED | The pixel size of a Metal view associated with the window has changed |
SDL_EVENT_WINDOW_MINIMIZED | Window has been minimized |
SDL_EVENT_WINDOW_MAXIMIZED | Window has been maximized |
SDL_EVENT_WINDOW_RESTORED | Window has been restored to normal size and position |
SDL_EVENT_WINDOW_MOUSE_ENTER | Window has gained mouse focus |
SDL_EVENT_WINDOW_MOUSE_LEAVE | Window has lost mouse focus |
SDL_EVENT_WINDOW_FOCUS_GAINED | Window has gained keyboard focus |
SDL_EVENT_WINDOW_FOCUS_LOST | Window has lost keyboard focus |
SDL_EVENT_WINDOW_CLOSE_REQUESTED | The window manager requests that the window be closed |
SDL_EVENT_WINDOW_HIT_TEST | Window had a hit test that wasn't SDL_HITTEST_NORMAL |
SDL_EVENT_WINDOW_ICCPROF_CHANGED | The ICC profile of the window's display has changed |
SDL_EVENT_WINDOW_DISPLAY_CHANGED | Window has been moved to display data1 |
SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED | Window display scale has been changed |
SDL_EVENT_WINDOW_SAFE_AREA_CHANGED | The window safe area has been changed |
SDL_EVENT_WINDOW_OCCLUDED | The window has been occluded |
SDL_EVENT_WINDOW_ENTER_FULLSCREEN | The window has entered fullscreen mode |
SDL_EVENT_WINDOW_LEAVE_FULLSCREEN | The window has left fullscreen mode |
SDL_EVENT_WINDOW_DESTROYED | The window with the associated ID is being or has been destroyed. If this message is being handled in an event watcher, the window handle is still valid and can still be used to retrieve any properties associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid |
SDL_EVENT_WINDOW_HDR_STATE_CHANGED | Window HDR properties have changed |
SDL_EVENT_WINDOW_FIRST | |
SDL_EVENT_WINDOW_LAST | |
SDL_EVENT_KEY_DOWN | Key pressed |
SDL_EVENT_KEY_UP | Key released |
SDL_EVENT_TEXT_EDITING | Keyboard text editing (composition) |
SDL_EVENT_TEXT_INPUT | Keyboard text input |
SDL_EVENT_KEYMAP_CHANGED | Keymap changed due to a system event such as an input language or keyboard layout change. |
SDL_EVENT_KEYBOARD_ADDED | A new keyboard has been inserted into the system |
SDL_EVENT_KEYBOARD_REMOVED | A keyboard has been removed |
SDL_EVENT_TEXT_EDITING_CANDIDATES | Keyboard text editing candidates |
SDL_EVENT_MOUSE_MOTION | Mouse moved |
SDL_EVENT_MOUSE_BUTTON_DOWN | Mouse button pressed |
SDL_EVENT_MOUSE_BUTTON_UP | Mouse button released |
SDL_EVENT_MOUSE_WHEEL | Mouse wheel motion |
SDL_EVENT_MOUSE_ADDED | A new mouse has been inserted into the system |
SDL_EVENT_MOUSE_REMOVED | A mouse has been removed |
SDL_EVENT_JOYSTICK_AXIS_MOTION | Joystick axis motion |
SDL_EVENT_JOYSTICK_BALL_MOTION | Joystick trackball motion |
SDL_EVENT_JOYSTICK_HAT_MOTION | Joystick hat position change |
SDL_EVENT_JOYSTICK_BUTTON_DOWN | Joystick button pressed |
SDL_EVENT_JOYSTICK_BUTTON_UP | Joystick button released |
SDL_EVENT_JOYSTICK_ADDED | A new joystick has been inserted into the system |
SDL_EVENT_JOYSTICK_REMOVED | An opened joystick has been removed |
SDL_EVENT_JOYSTICK_BATTERY_UPDATED | Joystick battery level change |
SDL_EVENT_JOYSTICK_UPDATE_COMPLETE | Joystick update is complete |
SDL_EVENT_GAMEPAD_AXIS_MOTION | Gamepad axis motion |
SDL_EVENT_GAMEPAD_BUTTON_DOWN | Gamepad button pressed |
SDL_EVENT_GAMEPAD_BUTTON_UP | Gamepad button released |
SDL_EVENT_GAMEPAD_ADDED | A new gamepad has been inserted into the system |
SDL_EVENT_GAMEPAD_REMOVED | A gamepad has been removed |
SDL_EVENT_GAMEPAD_REMAPPED | The gamepad mapping was updated |
SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN | Gamepad touchpad was touched |
SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION | Gamepad touchpad finger was moved |
SDL_EVENT_GAMEPAD_TOUCHPAD_UP | Gamepad touchpad finger was lifted |
SDL_EVENT_GAMEPAD_SENSOR_UPDATE | Gamepad sensor was updated |
SDL_EVENT_GAMEPAD_UPDATE_COMPLETE | Gamepad update is complete |
SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED | Gamepad Steam handle has changed |
SDL_EVENT_FINGER_DOWN | |
SDL_EVENT_FINGER_UP | |
SDL_EVENT_FINGER_MOTION | |
SDL_EVENT_FINGER_CANCELED | |
SDL_EVENT_CLIPBOARD_UPDATE | The clipboard or primary selection changed |
SDL_EVENT_DROP_FILE | The system requests a file open |
SDL_EVENT_DROP_TEXT | text/plain drag-and-drop event |
SDL_EVENT_DROP_BEGIN | A new set of drops is beginning (NULL filename) |
SDL_EVENT_DROP_COMPLETE | Current set of drops is now complete (NULL filename) |
SDL_EVENT_DROP_POSITION | Position while moving over the window |
SDL_EVENT_AUDIO_DEVICE_ADDED | A new audio device is available |
SDL_EVENT_AUDIO_DEVICE_REMOVED | An audio device has been removed. |
SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED | An audio device's format has been changed by the system. |
SDL_EVENT_SENSOR_UPDATE | A sensor was updated |
SDL_EVENT_PEN_PROXIMITY_IN | Pressure-sensitive pen has become available |
SDL_EVENT_PEN_PROXIMITY_OUT | Pressure-sensitive pen has become unavailable |
SDL_EVENT_PEN_DOWN | Pressure-sensitive pen touched drawing surface |
SDL_EVENT_PEN_UP | Pressure-sensitive pen stopped touching drawing surface |
SDL_EVENT_PEN_BUTTON_DOWN | Pressure-sensitive pen button pressed |
SDL_EVENT_PEN_BUTTON_UP | Pressure-sensitive pen button released |
SDL_EVENT_PEN_MOTION | Pressure-sensitive pen is moving on the tablet |
SDL_EVENT_PEN_AXIS | Pressure-sensitive pen angle/pressure/etc changed |
SDL_EVENT_CAMERA_DEVICE_ADDED | A new camera device is available |
SDL_EVENT_CAMERA_DEVICE_REMOVED | A camera device has been removed. |
SDL_EVENT_CAMERA_DEVICE_APPROVED | A camera device has been approved for use by the user. |
SDL_EVENT_CAMERA_DEVICE_DENIED | A camera device has been denied for use by the user. |
SDL_EVENT_RENDER_TARGETS_RESET | The render targets have been reset and their contents need to be updated |
SDL_EVENT_RENDER_DEVICE_RESET | The device has been reset and all textures need to be recreated |
SDL_EVENT_RENDER_DEVICE_LOST | The device has been lost and can't be recovered. |
SDL_EVENT_PRIVATE0 | |
SDL_EVENT_PRIVATE1 | |
SDL_EVENT_PRIVATE2 | |
SDL_EVENT_PRIVATE3 | |
SDL_EVENT_POLL_SENTINEL | Signals the end of an event poll cycle |
SDL_EVENT_USER | Events SDL_EVENT_USER through SDL_EVENT_LAST are for your use, and should be allocated with SDL_RegisterEvents() |
SDL_EVENT_LAST | This last event is only for bounding internal arrays |
SDL_EVENT_ENUM_PADDING |
Definition at line 84 of file SDL_events.h.
|
extern |
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().
filter | an SDL_EventFilter function to call when an event happens. |
userdata | a pointer that is passed to filter . |
\threadsafety It is safe to call this function from any thread.
Query the state of processing events by type.
type | the type of event; see SDL_EventType for details. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Run a specific filter function on the current event queue, removing any events for which the filter returns false.
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.
filter | the SDL_EventFilter function to call when an event happens. |
userdata | a pointer that is passed to filter . |
\threadsafety It is safe to call this function from any thread.
|
extern |
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.
If you have user events with custom data that needs to be freed, you should use SDL_PeepEvents() to remove and clean up those events before calling this function.
type | the type of event to be cleared; see SDL_EventType for details. |
\threadsafety It is safe to call this function from any thread.
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.
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.
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. |
\threadsafety It is safe to call this function from any thread.
|
extern |
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.
filter | the current callback function will be stored here. |
userdata | the pointer that is passed to the current event filter will be stored here. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Get window associated with an event.
event | an event containing a windowID . |
\threadsafety It is safe to call this function from any thread.
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.
type | the type of event to be queried; see SDL_EventType for details. |
type
are present, or false if events matching type
are not present.\threadsafety It is safe to call this function from any thread.
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.
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. |
minType
and <= maxType
are present, or false if not.\threadsafety It is safe to call this function from any thread.
|
extern |
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. If you pass NULL for events
, then numevents
is ignored and the total number of matching events will be returned.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().
events | destination buffer for the retrieved events, may be NULL to leave the events in the queue and return the number of events that would have been stored. |
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; see Remarks for details. |
minType | minimum value of the event type to be considered; SDL_EVENT_FIRST is a safe choice. |
maxType | maximum value of the event type to be considered; SDL_EVENT_LAST is a safe choice. |
\threadsafety It is safe to call this function from any thread.
Poll 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
. The 1 returned refers to this event, immediately stored in the SDL Event structure – not an event to follow.
If event
is NULL, it simply returns 1 if there is an event in the queue, but will not remove it from the queue.
As this function may implicitly call 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:
event | the SDL_Event structure to be filled with the next event from the queue, or NULL. |
\threadsafety This function should only be called on the main thread.
|
extern |
Pump the event loop, gathering events from the input devices.
This function updates the event queue and internal input device state.
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.
\threadsafety This function should only be called on the main thread.
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.
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.
event | the SDL_Event to be added to the queue. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Allocate a set of user-defined events, and return the beginning event number for that set of events.
numevents | the number of events to be allocated. |
\threadsafety It is safe to call this function from any thread.
|
extern |
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.
filter | the function originally passed to SDL_AddEventWatch(). |
userdata | the pointer originally passed to SDL_AddEventWatch(). |
\threadsafety It is safe to call this function from any thread.
Set the state of processing events by type.
type | the type of event; see SDL_EventType for details. |
enabled | whether to process the event or not. |
\threadsafety It is safe to call this function from any thread.
|
extern |
Set up a filter to process all events before they are added to the internal event queue.
If you just want to see events without modifying them or preventing them from being queued, you should use SDL_AddEventWatch() instead.
If the filter function returns true when called, then the event will be added to the internal queue. If it returns false, 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.
Note: Disabled events never make it to the event filter function; see SDL_SetEventEnabled().
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 | an SDL_EventFilter function to call when an event happens. |
userdata | a pointer that is passed to filter . |
\threadsafety It is safe to call this function from any thread.
Wait indefinitely for the next available event.
If event
is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event
.
As this function may implicitly call SDL_PumpEvents(), you can only call this function in the thread that initialized the video subsystem.
event | the SDL_Event structure to be filled in with the next event from the queue, or NULL. |
\threadsafety This function should only be called on the main thread.
Wait until the specified timeout (in milliseconds) for the next available event.
If event
is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event
.
As this function may implicitly call SDL_PumpEvents(), you can only call this function in the thread that initialized the video subsystem.
The timeout is not guaranteed, the actual wait time could be longer due to system scheduling.
event | the SDL_Event structure to be filled in with the next event from the queue, or NULL. |
timeoutMS | the maximum number of milliseconds to wait for the next available event. |
\threadsafety This function should only be called on the main thread.