Event queue management. More...

Modules
	Event Types
	Event types for Event.

Classes
struct	SDL::EventWatchHandle
	Handle returned by AddEventWatch(EventFilterCB) More...

Typedefs
using	SDL::EventType = SDL_EventType
	The types of events that can be delivered.

using	SDL::CommonEvent = SDL_CommonEvent
	Fields shared by every event.

using	SDL::DisplayEvent = SDL_DisplayEvent
	Display state change event data (event.display.

using	SDL::WindowEvent = SDL_WindowEvent
	Window state change event data (event.window.

using	SDL::KeyboardDeviceEvent = SDL_KeyboardDeviceEvent
	Keyboard device event structure (event.kdevice.

using	SDL::KeyboardEvent = SDL_KeyboardEvent
	Keyboard button event structure (event.key.

using	SDL::TextEditingEvent = SDL_TextEditingEvent
	Keyboard text editing event structure (event.edit.

using	SDL::TextEditingCandidatesEvent = SDL_TextEditingCandidatesEvent
	Keyboard IME candidates event structure (event.edit_candidates.

using	SDL::TextInputEvent = SDL_TextInputEvent
	Keyboard text input event structure (event.text.

using	SDL::MouseDeviceEvent = SDL_MouseDeviceEvent
	Mouse device event structure (event.mdevice.

using	SDL::MouseMotionEvent = SDL_MouseMotionEvent
	Mouse motion event structure (event.motion.

using	SDL::MouseButtonEvent = SDL_MouseButtonEvent
	Mouse button event structure (event.button.

using	SDL::MouseWheelEvent = SDL_MouseWheelEvent
	Mouse wheel event structure (event.wheel.

using	SDL::JoyAxisEvent = SDL_JoyAxisEvent
	Joystick axis motion event structure (event.jaxis.

using	SDL::JoyBallEvent = SDL_JoyBallEvent
	Joystick trackball motion event structure (event.jball.

using	SDL::JoyHatEvent = SDL_JoyHatEvent
	Joystick hat position change event structure (event.jhat.

using	SDL::JoyButtonEvent = SDL_JoyButtonEvent
	Joystick button event structure (event.jbutton.

using	SDL::JoyDeviceEvent = SDL_JoyDeviceEvent
	Joystick device event structure (event.jdevice.

using	SDL::JoyBatteryEvent = SDL_JoyBatteryEvent
	Joystick battery level change event structure (event.jbattery.

using	SDL::GamepadAxisEvent = SDL_GamepadAxisEvent
	Gamepad axis motion event structure (event.gaxis.

using	SDL::GamepadButtonEvent = SDL_GamepadButtonEvent
	Gamepad button event structure (event.gbutton.

using	SDL::GamepadDeviceEvent = SDL_GamepadDeviceEvent
	Gamepad device event structure (event.gdevice.

using	SDL::GamepadTouchpadEvent = SDL_GamepadTouchpadEvent
	Gamepad touchpad event structure (event.gtouchpad.

using	SDL::GamepadSensorEvent = SDL_GamepadSensorEvent
	Gamepad sensor event structure (event.gsensor.

using	SDL::AudioDeviceEvent = SDL_AudioDeviceEvent
	Audio device event structure (event.adevice.

using	SDL::CameraDeviceEvent = SDL_CameraDeviceEvent
	Camera device event structure (event.cdevice.

using	SDL::RenderEvent = SDL_RenderEvent
	Renderer event structure (event.render.

using	SDL::TouchFingerEvent = SDL_TouchFingerEvent
	Touch finger event structure (event.tfinger.

using	SDL::PenProximityEvent = SDL_PenProximityEvent
	Pressure-sensitive pen proximity event structure (event.pmotion.

using	SDL::PenMotionEvent = SDL_PenMotionEvent
	Pressure-sensitive pen motion event structure (event.pmotion.

using	SDL::PenTouchEvent = SDL_PenTouchEvent
	Pressure-sensitive pen touched event structure (event.ptouch.

using	SDL::PenButtonEvent = SDL_PenButtonEvent
	Pressure-sensitive pen button event structure (event.pbutton.

using	SDL::PenAxisEvent = SDL_PenAxisEvent
	Pressure-sensitive pen pressure / angle event structure (event.paxis.

using	SDL::DropEvent = SDL_DropEvent
	An event used to drop text or request a file open by the system (event.drop.

using	SDL::ClipboardEvent = SDL_ClipboardEvent
	An event triggered when the clipboard contents have changed (event.clipboard.

using	SDL::SensorEvent = SDL_SensorEvent
	Sensor event structure (event.sensor.

using	SDL::QuitEvent = SDL_QuitEvent
	The "quit requested" event.

using	SDL::UserEvent = SDL_UserEvent
	A user-defined event type (event.user.

using	SDL::Event = SDL_Event
	The structure for all events in SDL.

using	SDL::EventFilter = SDL_EventFilter
	A function pointer used for callbacks that watch the event queue.

using	SDL::EventFilterCB = std::function< bool(const Event &)>
	A std::function used for callbacks that watch the event queue.

Functions
void	SDL::PumpEvents ()
	Pump the event loop, gathering events from the input devices.

int	SDL::PeepEvents (Event *events, int numevents, EventAction action, Uint32 minType=EVENT_FIRST, Uint32 maxType=EVENT_LAST)
	Check the event queue for messages and optionally return them.

bool	SDL::HasEvent (Uint32 type)
	Check for the existence of a certain event type in the event queue.

bool	SDL::HasEvents (Uint32 minType=EVENT_FIRST, Uint32 maxType=EVENT_LAST)
	Check for the existence of certain event types in the event queue.

void	SDL::FlushEvent (Uint32 type)
	Clear events of a specific type from the event queue.

void	SDL::FlushEvents (Uint32 minType=EVENT_FIRST, Uint32 maxType=EVENT_LAST)
	Clear events of a range of types from the event queue.

bool	SDL::PollEvent (Event *event)
	Poll for currently pending events.

std::optional< Event >	SDL::PollEvent ()
	Poll for currently pending events.

void	SDL::WaitEvent (Event *event)
	Wait indefinitely for the next available event.

Event	SDL::WaitEvent ()
	Wait indefinitely for the next available event.

bool	SDL::WaitEventTimeout (Event *event, Sint32 timeoutMS)
	Wait until the specified timeout (in milliseconds) for the next available event.

std::optional< Event >	SDL::WaitEventTimeout (Sint32 timeoutMS)
	Wait until the specified timeout (in milliseconds) for the next available event.

bool	SDL::WaitEventTimeout (Event *event, std::chrono::milliseconds timeoutDuration)
	Wait until the specified timeout (with milliseconds precision) for the next available event.

std::optional< Event >	SDL::WaitEventTimeout (std::chrono::milliseconds timeoutDuration)
	Wait until the specified timeout (with milliseconds precision) for the next available event.

void	SDL::PushEvent (Event *event)
	Add an event to the event queue.

void	SDL::PushEvent (const Event &event)
	Add an event to the event queue.

void	SDL::SetEventFilter (EventFilter filter, void *userdata)
	Set up a filter to process all events before they are added to the internal event queue.

void	SDL::SetEventFilter (EventFilterCB filter={})
	Set up a filter to process all events before they are added to the internal event queue.

void	SDL::GetEventFilter (EventFilter filter, void *userdata)
	Query the current event filter.

EventFilterCB	SDL::GetEventFilter ()
	Query the current event filter.

void	SDL::AddEventWatch (EventFilter filter, void *userdata)
	Add a callback to be triggered when an event is added to the event queue.

EventWatchHandle	SDL::AddEventWatch (EventFilterCB filter)
	Add a callback to be triggered when an event is added to the event queue.

void	SDL::RemoveEventWatch (EventFilter filter, void *userdata)
	Remove an event watch callback added with SDL_AddEventWatch().

void	SDL::RemoveEventWatch (EventWatchHandle handle)
	Remove an event watch callback added with SDL_AddEventWatch(EventFilterCB).

void	SDL::FilterEvents (EventFilter filter, void *userdata)
	Run a specific filter function on the current event queue, removing any events for which the filter returns false.

void	SDL::FilterEvents (EventFilterCB filter)
	Run a specific filter function on the current event queue, removing any events for which the filter returns false.

void	SDL::SetEventEnabled (Uint32 type, bool enabled)
	Set the state of processing events by type.

bool	SDL::EventEnabled (Uint32 type)
	Query the state of processing events by type.

Uint32	SDL::RegisterEvents (int numevents)
	Allocate a set of user-defined events, and return the beginning event number for that set of events.

WindowRef	SDL::GetWindowFromEvent (const Event &event)
	Get window associated with an event.

EventActions
The type of action to request from PeepEvents().
using	SDL::EventAction = SDL_EventAction
	The type of action to request from PeepEvents().

constexpr EventAction	SDL::ADDEVENT = SDL_ADDEVENT
	Add events to the back of the queue.

constexpr EventAction	SDL::PEEKEVENT = SDL_PEEKEVENT
	Check but don't remove events from the queue front.

constexpr EventAction	SDL::GETEVENT = SDL_GETEVENT
	Retrieve/remove events from the front of the queue.

Detailed Description

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 occurred 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 PollEvent() at all).

There is other forms of control, too: PeepEvents() has more functionality at the cost of more complexity, and 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 AddEventWatch() to set a callback when new events arrive.

The app is free to generate their own events, too: PushEvent() allows the app to put events onto the queue for later retrieval; RegisterEvents() can guarantee that these events have a type that isn't in use by other parts of the system.

Typedef Documentation

◆ AudioDeviceEvent

using SDL::AudioDeviceEvent = typedef SDL_AudioDeviceEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ CameraDeviceEvent

using SDL::CameraDeviceEvent = typedef SDL_CameraDeviceEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ ClipboardEvent

using SDL::ClipboardEvent = typedef SDL_ClipboardEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ CommonEvent

using SDL::CommonEvent = typedef SDL_CommonEvent

Since: This struct is available since SDL 3.2.0.

◆ DisplayEvent

using SDL::DisplayEvent = typedef SDL_DisplayEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ DropEvent

using SDL::DropEvent = typedef SDL_DropEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ Event

using SDL::Event = typedef SDL_Event

The SDL_Event structure is the core of all event handling in SDL. SDL_Event is a union of all event structures used in SDL.

Since: This struct is available since SDL 3.2.0.

◆ EventAction

using SDL::EventAction = typedef SDL_EventAction

Since: This enum is available since SDL 3.2.0.

◆ EventFilter

using SDL::EventFilter = typedef SDL_EventFilter

Parameters

userdata	what was passed as `userdata` to SetEventFilter() or AddEventWatch(), etc.
event	the event that triggered the callback.

Returns: true to permit event to be added to the queue, and false to disallow it. When used with AddEventWatch(), the return value is ignored.

Thread safety:: 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.

Since: This datatype is available since SDL 3.2.0.

See also: SetEventFilter(); AddEventWatch()

◆ EventFilterCB

using SDL::EventFilterCB = typedef std::function<bool(const Event&)>

Parameters

event the event that triggered the callback.

Returns: true to permit event to be added to the queue, and false to disallow it. When used with AddEventWatch(), the return value is ignored.

Thread safety:: 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.

Since: This datatype is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; SetEventFilter(); AddEventWatch(); EventFilter

◆ EventType

using SDL::EventType = typedef SDL_EventType

Since: This enum is available since SDL 3.2.0.

See also: Event Types

◆ GamepadAxisEvent

using SDL::GamepadAxisEvent = typedef SDL_GamepadAxisEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ GamepadButtonEvent

using SDL::GamepadButtonEvent = typedef SDL_GamepadButtonEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ GamepadDeviceEvent

using SDL::GamepadDeviceEvent = typedef SDL_GamepadDeviceEvent

*)

Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent and an SDL_GamepadDeviceEvent.

SDL will send GAMEPAD_ADDED events for joysticks that are already plugged in during SDL_Init() and are recognized as gamepads. It will also send events for joysticks that get gamepad mappings at runtime.

Since: This struct is available since SDL 3.2.0.

See also: JoyDeviceEvent

◆ GamepadSensorEvent

using SDL::GamepadSensorEvent = typedef SDL_GamepadSensorEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ GamepadTouchpadEvent

using SDL::GamepadTouchpadEvent = typedef SDL_GamepadTouchpadEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ JoyAxisEvent

using SDL::JoyAxisEvent = typedef SDL_JoyAxisEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ JoyBallEvent

using SDL::JoyBallEvent = typedef SDL_JoyBallEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ JoyBatteryEvent

using SDL::JoyBatteryEvent = typedef SDL_JoyBatteryEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ JoyButtonEvent

using SDL::JoyButtonEvent = typedef SDL_JoyButtonEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ JoyDeviceEvent

using SDL::JoyDeviceEvent = typedef SDL_JoyDeviceEvent

*)

SDL will send JOYSTICK_ADDED events for devices that are already plugged in during SDL_Init.

Since: This struct is available since SDL 3.2.0.

See also: GamepadDeviceEvent

◆ JoyHatEvent

using SDL::JoyHatEvent = typedef SDL_JoyHatEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ KeyboardDeviceEvent

using SDL::KeyboardDeviceEvent = typedef SDL_KeyboardDeviceEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ KeyboardEvent

using SDL::KeyboardEvent = typedef SDL_KeyboardEvent

*)

The key is the base SDL_Keycode generated by pressing the scancode using the current keyboard layout, applying any options specified in SDL_HINT_KEYCODE_OPTIONS. You can get the SDL_Keycode corresponding to the event scancode and modifiers directly from the keyboard layout, bypassing SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode().

Since: This struct is available since SDL 3.2.0.

See also: GetKeyFromScancode(); HINT_KEYCODE_OPTIONS

◆ MouseButtonEvent

using SDL::MouseButtonEvent = typedef SDL_MouseButtonEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ MouseDeviceEvent

using SDL::MouseDeviceEvent = typedef SDL_MouseDeviceEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ MouseMotionEvent

using SDL::MouseMotionEvent = typedef SDL_MouseMotionEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ MouseWheelEvent

using SDL::MouseWheelEvent = typedef SDL_MouseWheelEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ PenAxisEvent

using SDL::PenAxisEvent = typedef SDL_PenAxisEvent

*)

You might get some of these events even if the pen isn't touching the tablet.

Since: This struct is available since SDL 3.2.0.

◆ PenButtonEvent

using SDL::PenButtonEvent = typedef SDL_PenButtonEvent

*)

This is for buttons on the pen itself that the user might click. The pen itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead.

Since: This struct is available since SDL 3.2.0.

◆ PenMotionEvent

using SDL::PenMotionEvent = typedef SDL_PenMotionEvent

*)

Depending on the hardware, you may get motion events when the pen is not touching a tablet, for tracking a pen even when it isn't drawing. You should listen for SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP events, or check pen_state & SDL_PEN_INPUT_DOWN to decide if a pen is "drawing" when dealing with pen motion.

Since: This struct is available since SDL 3.2.0.

◆ PenProximityEvent

using SDL::PenProximityEvent = typedef SDL_PenProximityEvent

*)

When a pen becomes visible to the system (it is close enough to a tablet, etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's ID. This ID is valid until the pen leaves proximity again (has been removed from the tablet's area, the tablet has been unplugged, etc). If the same pen reenters proximity again, it will be given a new ID.

Note that "proximity" means "close enough for the tablet to know the tool is there." The pen touching and lifting off from the tablet while not leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP.

Since: This struct is available since SDL 3.2.0.

◆ PenTouchEvent

using SDL::PenTouchEvent = typedef SDL_PenTouchEvent

*)

These events come when a pen touches a surface (a tablet, etc), or lifts off from one.

Since: This struct is available since SDL 3.2.0.

◆ QuitEvent

using SDL::QuitEvent = typedef SDL_QuitEvent

Since: This struct is available since SDL 3.2.0.

◆ RenderEvent

using SDL::RenderEvent = typedef SDL_RenderEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ SensorEvent

using SDL::SensorEvent = typedef SDL_SensorEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ TextEditingCandidatesEvent

using SDL::TextEditingCandidatesEvent = typedef SDL_TextEditingCandidatesEvent

*)

Since: This struct is available since SDL 3.2.0.

◆ TextEditingEvent

using SDL::TextEditingEvent = typedef SDL_TextEditingEvent

*)

The start cursor is the position, in UTF-8 characters, where new typing will be inserted into the editing text. The length is the number of UTF-8 characters that will be replaced by new typing.

Since: This struct is available since SDL 3.2.0.

◆ TextInputEvent

using SDL::TextInputEvent = typedef SDL_TextInputEvent

*)

This event will never be delivered unless text input is enabled by calling SDL_StartTextInput(). Text input is disabled by default!

Since: This struct is available since SDL 3.2.0.

See also: StartTextInput(); StopTextInput()

◆ TouchFingerEvent

using SDL::TouchFingerEvent = typedef SDL_TouchFingerEvent

*)

Coordinates in this event are normalized. x and y are normalized to a range between 0.0f and 1.0f, relative to the window, so (0,0) is the top left and (1,1) is the bottom right. Delta coordinates dx and dy are normalized in the ranges of -1.0f (traversed all the way from the bottom or right to all the way up or left) to 1.0f (traversed all the way from the top or left to all the way down or right).

Note that while the coordinates are normalized, they are not clamped, which means in some circumstances you can get a value outside of this range. For example, a renderer using logical presentation might give a negative value when the touch is in the letterboxing. Some platforms might report a touch outside of the window, which will also be outside of the range.

Since: This struct is available since SDL 3.2.0.

◆ UserEvent

using SDL::UserEvent = typedef SDL_UserEvent

*)

This event is unique; it is never created by SDL, but only by the application. The event can be pushed onto the event queue using SDL_PushEvent(). The contents of the structure members are completely up to the programmer; the only requirement is that '''type''' is a value obtained from SDL_RegisterEvents().

Since: This struct is available since SDL 3.2.0.

◆ WindowEvent

using SDL::WindowEvent = typedef SDL_WindowEvent

*)

Since: This struct is available since SDL 3.2.0.

Function Documentation

◆ AddEventWatch() [1/2]

void SDL::AddEventWatch	(	EventFilter	filter,
		void *	userdata
	)

inline

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 PushEvent(), but not for disabled events, nor for events by a filter callback set with SetEventFilter(), nor for events posted by the user through PeepEvents().

Parameters

filter	an EventFilter function to call when an event happens.
userdata	a pointer that is passed to `filter`.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: RemoveEventWatch; SetEventFilter

◆ AddEventWatch() [2/2]

EventWatchHandle SDL::AddEventWatch ( EventFilterCB filter )

inline

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 PushEvent(), but not for disabled events, nor for events by a filter callback set with SetEventFilter(), nor for events posted by the user through PeepEvents().

Parameters

filter an EventFilterCB to call when an event happens.

Returns: a handle that can be used on RemoveEventWatch(EventFilterHandle) on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; RemoveEventWatch(); SetEventFilter()

◆ EventEnabled()

bool SDL::EventEnabled ( Uint32 type )

inline

Parameters

type	the type of event; see SDL_EventType for details.

Returns: true if the event is being processed, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetEventEnabled()

◆ FilterEvents() [1/2]

void SDL::FilterEvents	(	EventFilter	filter,
		void *	userdata
	)

inline

See SetEventFilter() for more information. Unlike SetEventFilter(), this function does not change the filter permanently, it only uses the supplied filter until this function returns.

Parameters

filter	the EventFilter function to call when an event happens.
userdata	a pointer that is passed to `filter`.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetEventFilter(); SetEventFilter()

◆ FilterEvents() [2/2]

void SDL::FilterEvents ( EventFilterCB filter )

inline

See SetEventFilter() for more information. Unlike SetEventFilter(), this function does not change the filter permanently, it only uses the supplied filter until this function returns.

Parameters

filter the EventFilter function to call when an event happens.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Immediate callback

See also: immediate-callback; GetEventFilter(); SetEventFilter()

◆ FlushEvent()

void SDL::FlushEvent ( Uint32 type )

inline

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.

Parameters

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: FlushEvents()

◆ FlushEvents()

void SDL::FlushEvents	(	Uint32	minType = `EVENT_FIRST`,
		Uint32	maxType = `EVENT_LAST`
	)

inline

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.

Parameters

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.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: FlushEvent()

◆ GetEventFilter() [1/2]

EventFilterCB SDL::GetEventFilter ( )

inline

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: EventFilterCB on success or false if there is no event filter set.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; SetEventFilter()

◆ GetEventFilter() [2/2]

void SDL::GetEventFilter	(	EventFilter *	filter,
		void **	userdata
	)

inline

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.

Parameters

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

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetEventFilter

◆ GetWindowFromEvent()

WindowRef SDL::GetWindowFromEvent ( const Event & event )

inline

Parameters

event an event containing a windowID.

Returns: the associated window on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent; WaitEvent; WaitEventTimeout

◆ HasEvent()

bool SDL::HasEvent ( Uint32 type )

inline

If you need to check for a range of event types, use SDL_HasEvents() instead.

Parameters

type	the type of event to be queried; see Event Types for details.

Returns: true if events matching type are present, or false if events matching type are not present.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: HasEvents()

◆ HasEvents()

bool SDL::HasEvents	(	Uint32	minType = `EVENT_FIRST`,
		Uint32	maxType = `EVENT_LAST`
	)

inline

If you need to check for a single event type, use SDL_HasEvent() instead.

Parameters

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: true if events with type >= minType and <= maxType are present, or false if not.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: HasEvent()

◆ PeepEvents()

int SDL::PeepEvents	(	Event *	events,
		int	numevents,
		EventAction	action,
		Uint32	minType = `EVENT_FIRST`,
		Uint32	maxType = `EVENT_LAST`
	)

inline

action may be any of the following:

remarks

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

Parameters

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.

Returns: the number of events actually stored or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent(); PumpEvents(); PushEvent()

◆ PollEvent() [1/2]

std::optional< Event > SDL::PollEvent ( )

inline

The next event is removed from the queue and returned.

As this function may implicitly call PumpEvents(), you can only call this function in the thread that set the video mode.

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 (auto event = SDL::PollEvent()) {  // poll until all events are
handled!
        // decide what to do with this event.
    }
 
    // update game state, draw the current frame
}

Returns: Event if this got an event or std::nullopt if there are none available.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PushEvent(); WaitEvent(); WaitEventTimeout()

◆ PollEvent() [2/2]

bool SDL::PollEvent ( Event * event )

inline

If event is not nullptr, the next event is removed from the queue and stored in the Event structure pointed to by event. The true returned refers to this event, immediately stored in the SDL Event structure – not an event to follow.

If event is nullptr, it simply returns true if there is an event in the queue, but will not remove it from the queue.

As this function may implicitly call PumpEvents(), you can only call this function in the thread that set the video mode.

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) {
    SDL::Event event;
    while (SDL::PollEvent(&event)) {  // poll until all events are handled!
        // decide what to do with this event.
    }
 
    // update game state, draw the current frame
}

Parameters

event the SDL_Event structure to be filled with the next event from the queue, or nullptr.

Returns: true if this got an event or false if there are none available.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PushEvent(); WaitEvent(); WaitEventTimeout()

◆ PumpEvents()

void SDL::PumpEvents ( )

inline

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.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent(); WaitEvent()

◆ PushEvent() [1/2]

void SDL::PushEvent ( const Event & event )

inline

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 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 PushEvent() get passed through the event filter but events added with PeepEvents() do not.

For pushing application-specific events, please use RegisterEvents() to get an event type that does not conflict with other code that also wants its own custom event types.

Parameters

event the Event to be added to the queue.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PeepEvents; PollEvent; RegisterEvents

◆ PushEvent() [2/2]

void SDL::PushEvent ( Event * event )

inline

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 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 PushEvent() get passed through the event filter but events added with PeepEvents() do not.

For pushing application-specific events, please use RegisterEvents() to get an event type that does not conflict with other code that also wants its own custom event types.

Parameters

event the Event to be added to the queue.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PeepEvents; PollEvent; RegisterEvents

◆ RegisterEvents()

Uint32 SDL::RegisterEvents ( int numevents )

inline

Parameters

numevents the number of events to be allocated.

Returns: the beginning event number, or 0 if numevents is invalid or if there are not enough user-defined events left.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PushEvent()

◆ RemoveEventWatch() [1/2]

void SDL::RemoveEventWatch	(	EventFilter	filter,
		void *	userdata
	)

inline

This function takes the same input as SDL_AddEventWatch() to identify and delete the corresponding callback.

Parameters

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AddEventWatch()

◆ RemoveEventWatch() [2/2]

void SDL::RemoveEventWatch ( EventWatchHandle handle )

inline

Parameters

handle the handle returned by SDL_AddEventWatch(EventFilterCB).

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; AddEventWatch(EventFilterCB)

◆ SetEventEnabled()

void SDL::SetEventEnabled	(	Uint32	type,
		bool	enabled
	)

inline

Parameters

type	the type of event; see SDL_EventType for details.
enabled	whether to process the event or not.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: EventEnabled()

◆ SetEventFilter() [1/2]

void SDL::SetEventFilter	(	EventFilter	filter,
		void *	userdata
	)

inline

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.

Parameters

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AddEventWatch(); SetEventEnabled(); GetEventFilter(); PeepEvents(); PushEvent()

◆ SetEventFilter() [2/2]

void SDL::SetEventFilter ( EventFilterCB filter = {} )

inline

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.

Parameters

filter an EventFilterCB function to call when an event happens.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

Category:: Listener callback

See also: listener-callback; AddEventWatch(); SetEventEnabled(); GetEventFilter(); PeepEvents(); PushEvent()

◆ WaitEvent() [1/2]

Event SDL::WaitEvent ( )

inline

The next event is removed from the queue and returned.

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

Returns: Event on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent(); PushEvent(); WaitEventTimeout()

◆ WaitEvent() [2/2]

void SDL::WaitEvent ( Event * event )

inline

If event is not nullptr, the next event is removed from the queue and stored in the Event structure pointed to by event.

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

Parameters

event the Event structure to be filled in with the next event from the queue, or nullptr.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent; PushEvent; WaitEventTimeout

◆ WaitEventTimeout() [1/4]

bool SDL::WaitEventTimeout	(	Event *	event,
		Sint32	timeoutMS
	)

inline

If event is not nullptr, the next event is removed from the queue and stored in the Event structure pointed to by event.

As this function may implicitly call 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.

Parameters

event	the Event structure to be filled in with the next event from the queue, or nullptr.
timeoutMS	the maximum number of milliseconds to wait for the next available event.

Returns: true if this got an event or false if the timeout elapsed without any events available.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent(); PushEvent(); WaitEvent()

◆ WaitEventTimeout() [2/4]

bool SDL::WaitEventTimeout	(	Event *	event,
		std::chrono::milliseconds	timeoutDuration
	)

inline

If event is not nullptr, the next event is removed from the queue and stored in the Event structure pointed to by event.

As this function may implicitly call 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.

Parameters

event	the Event structure to be filled in with the next event from the queue, or nullptr.
timeoutDuration	the duration to wait for the next available event, with millisecond precision

Returns: true if this got an event or false if the timeout elapsed without any events available.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent(); PushEvent(); WaitEvent()

◆ WaitEventTimeout() [3/4]

std::optional< Event > SDL::WaitEventTimeout ( Sint32 timeoutMS )

inline

As this function may implicitly call 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.

Parameters

timeoutMS the maximum number of milliseconds to wait for the next available event.

Returns: the Event if this got an event or std::nullopt if the timeout elapsed without any events available.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent(); PushEvent(); WaitEvent()

◆ WaitEventTimeout() [4/4]

std::optional< Event > SDL::WaitEventTimeout ( std::chrono::milliseconds timeoutDuration )

inline

As this function may implicitly call 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.

Parameters

timeoutDuration the duration to wait for the next available event, with millisecond precision.

Returns: the Event if this got an event or std::nullopt if the timeout elapsed without any events available.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: PollEvent(); PushEvent(); WaitEvent()

Modules

Classes

Typedefs

Functions

EventActions

Detailed Description

Typedef Documentation

◆ AudioDeviceEvent

◆ CameraDeviceEvent

◆ ClipboardEvent

◆ CommonEvent

◆ DisplayEvent

◆ DropEvent

◆ Event

◆ EventAction

◆ EventFilter

◆ EventFilterCB

◆ EventType

◆ GamepadAxisEvent

◆ GamepadButtonEvent

◆ GamepadDeviceEvent

◆ GamepadSensorEvent

◆ GamepadTouchpadEvent

◆ JoyAxisEvent

◆ JoyBallEvent

◆ JoyBatteryEvent

◆ JoyButtonEvent

◆ JoyDeviceEvent

◆ JoyHatEvent

◆ KeyboardDeviceEvent

◆ KeyboardEvent

◆ MouseButtonEvent

◆ MouseDeviceEvent

◆ MouseMotionEvent

◆ MouseWheelEvent

◆ PenAxisEvent

◆ PenButtonEvent

◆ PenMotionEvent

◆ PenProximityEvent

◆ PenTouchEvent

◆ QuitEvent

◆ RenderEvent

◆ SensorEvent

◆ TextEditingCandidatesEvent

◆ TextEditingEvent

◆ TextInputEvent

◆ TouchFingerEvent

◆ UserEvent

◆ WindowEvent

Function Documentation

◆ AddEventWatch() [1/2]

◆ AddEventWatch() [2/2]

◆ EventEnabled()

◆ FilterEvents() [1/2]

◆ FilterEvents() [2/2]

◆ FlushEvent()

◆ FlushEvents()

◆ GetEventFilter() [1/2]

◆ GetEventFilter() [2/2]

◆ GetWindowFromEvent()

◆ HasEvent()

◆ HasEvents()

◆ PeepEvents()

remarks

◆ PollEvent() [1/2]

◆ PollEvent() [2/2]

◆ PumpEvents()

◆ PushEvent() [1/2]

◆ PushEvent() [2/2]

◆ RegisterEvents()

◆ RemoveEventWatch() [1/2]

◆ RemoveEventWatch() [2/2]

◆ SetEventEnabled()

◆ SetEventFilter() [1/2]

◆ SetEventFilter() [2/2]

◆ WaitEvent() [1/2]

◆ WaitEvent() [2/2]

◆ WaitEventTimeout() [1/4]

◆ WaitEventTimeout() [2/4]

◆ WaitEventTimeout() [3/4]