My Project
Loading...
Searching...
No Matches
SDL_events.h File Reference
#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "SDL_video.h"
#include "SDL_keyboard.h"
#include "SDL_mouse.h"
#include "SDL_joystick.h"
#include "SDL_gamecontroller.h"
#include "SDL_quit.h"
#include "SDL_gesture.h"
#include "SDL_touch.h"
#include "begin_code.h"
#include "close_code.h"

Go to the source code of this file.

Data Structures

struct  SDL_CommonEvent
 Fields shared by every event. More...
 
struct  SDL_DisplayEvent
 Display state change event data (event.display.*) More...
 
struct  SDL_WindowEvent
 Window state change event data (event.window.*) More...
 
struct  SDL_KeyboardEvent
 Keyboard button event structure (event.key.*) More...
 
struct  SDL_TextEditingEvent
 Keyboard text editing event structure (event.edit.*) More...
 
struct  SDL_TextEditingExtEvent
 Extended keyboard text editing event structure (event.editExt.*) when text would be truncated if stored in the text buffer SDL_TextEditingEvent. More...
 
struct  SDL_TextInputEvent
 Keyboard text input event structure (event.text.*) More...
 
struct  SDL_MouseMotionEvent
 Mouse motion event structure (event.motion.*) More...
 
struct  SDL_MouseButtonEvent
 Mouse button event structure (event.button.*) More...
 
struct  SDL_MouseWheelEvent
 Mouse wheel event structure (event.wheel.*) More...
 
struct  SDL_JoyAxisEvent
 Joystick axis motion event structure (event.jaxis.*) More...
 
struct  SDL_JoyBallEvent
 Joystick trackball motion event structure (event.jball.*) More...
 
struct  SDL_JoyHatEvent
 Joystick hat position change event structure (event.jhat.*) More...
 
struct  SDL_JoyButtonEvent
 Joystick button event structure (event.jbutton.*) More...
 
struct  SDL_JoyDeviceEvent
 Joystick device event structure (event.jdevice.*) More...
 
struct  SDL_JoyBatteryEvent
 Joysick battery level change event structure (event.jbattery.*) More...
 
struct  SDL_ControllerAxisEvent
 Game controller axis motion event structure (event.caxis.*) More...
 
struct  SDL_ControllerButtonEvent
 Game controller button event structure (event.cbutton.*) More...
 
struct  SDL_ControllerDeviceEvent
 Controller device event structure (event.cdevice.*) More...
 
struct  SDL_ControllerTouchpadEvent
 Game controller touchpad event structure (event.ctouchpad.*) More...
 
struct  SDL_ControllerSensorEvent
 Game controller sensor event structure (event.csensor.*) More...
 
struct  SDL_AudioDeviceEvent
 Audio device event structure (event.adevice.*) More...
 
struct  SDL_TouchFingerEvent
 Touch finger event structure (event.tfinger.*) More...
 
struct  SDL_MultiGestureEvent
 Multiple Finger Gesture Event (event.mgesture.*) More...
 
struct  SDL_DollarGestureEvent
 Dollar Gesture Event (event.dgesture.*) More...
 
struct  SDL_DropEvent
 An event used to request a file open by the system (event.drop.*) This event is enabled by default, you can disable it with SDL_EventState(). More...
 
struct  SDL_SensorEvent
 Sensor event structure (event.sensor.*) More...
 
struct  SDL_QuitEvent
 The "quit requested" event. More...
 
struct  SDL_OSEvent
 OS Specific event. More...
 
struct  SDL_UserEvent
 A user-defined event type (event.user.*) More...
 
struct  SDL_SysWMEvent
 A video driver dependent system event (event.syswm.*) This event is disabled by default, you can enable it with SDL_EventState() More...
 
union  SDL_Event
 General event structure. More...
 

Macros

#define SDL_RELEASED   0
 
#define SDL_PRESSED   1
 
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE   (32)
 
#define SDL_TEXTINPUTEVENT_TEXT_SIZE   (32)
 
#define SDL_QUERY   -1
 
#define SDL_IGNORE   0
 
#define SDL_DISABLE   0
 
#define SDL_ENABLE   1
 
#define SDL_GetEventState(type)   SDL_EventState(type, SDL_QUERY)
 

Typedefs

typedef struct SDL_CommonEvent SDL_CommonEvent
 Fields shared by every event.
 
typedef struct SDL_DisplayEvent SDL_DisplayEvent
 Display state change event data (event.display.*)
 
typedef struct SDL_WindowEvent SDL_WindowEvent
 Window state change event data (event.window.*)
 
typedef struct SDL_KeyboardEvent SDL_KeyboardEvent
 Keyboard button event structure (event.key.*)
 
typedef struct SDL_TextEditingEvent SDL_TextEditingEvent
 Keyboard text editing event structure (event.edit.*)
 
typedef struct SDL_TextEditingExtEvent SDL_TextEditingExtEvent
 Extended keyboard text editing event structure (event.editExt.*) when text would be truncated if stored in the text buffer SDL_TextEditingEvent.
 
typedef struct SDL_TextInputEvent SDL_TextInputEvent
 Keyboard text input event structure (event.text.*)
 
typedef struct SDL_MouseMotionEvent SDL_MouseMotionEvent
 Mouse motion event structure (event.motion.*)
 
typedef struct SDL_MouseButtonEvent SDL_MouseButtonEvent
 Mouse button event structure (event.button.*)
 
typedef struct SDL_MouseWheelEvent SDL_MouseWheelEvent
 Mouse wheel event structure (event.wheel.*)
 
typedef struct SDL_JoyAxisEvent SDL_JoyAxisEvent
 Joystick axis motion event structure (event.jaxis.*)
 
typedef struct SDL_JoyBallEvent SDL_JoyBallEvent
 Joystick trackball motion event structure (event.jball.*)
 
typedef struct SDL_JoyHatEvent SDL_JoyHatEvent
 Joystick hat position change event structure (event.jhat.*)
 
typedef struct SDL_JoyButtonEvent SDL_JoyButtonEvent
 Joystick button event structure (event.jbutton.*)
 
typedef struct SDL_JoyDeviceEvent SDL_JoyDeviceEvent
 Joystick device event structure (event.jdevice.*)
 
typedef struct SDL_JoyBatteryEvent SDL_JoyBatteryEvent
 Joysick battery level change event structure (event.jbattery.*)
 
typedef struct SDL_ControllerAxisEvent SDL_ControllerAxisEvent
 Game controller axis motion event structure (event.caxis.*)
 
typedef struct SDL_ControllerButtonEvent SDL_ControllerButtonEvent
 Game controller button event structure (event.cbutton.*)
 
typedef struct SDL_ControllerDeviceEvent SDL_ControllerDeviceEvent
 Controller device event structure (event.cdevice.*)
 
typedef struct SDL_ControllerTouchpadEvent SDL_ControllerTouchpadEvent
 Game controller touchpad event structure (event.ctouchpad.*)
 
typedef struct SDL_ControllerSensorEvent SDL_ControllerSensorEvent
 Game controller sensor event structure (event.csensor.*)
 
typedef struct SDL_AudioDeviceEvent SDL_AudioDeviceEvent
 Audio device event structure (event.adevice.*)
 
typedef struct SDL_TouchFingerEvent SDL_TouchFingerEvent
 Touch finger event structure (event.tfinger.*)
 
typedef struct SDL_MultiGestureEvent SDL_MultiGestureEvent
 Multiple Finger Gesture Event (event.mgesture.*)
 
typedef struct SDL_DollarGestureEvent SDL_DollarGestureEvent
 Dollar Gesture Event (event.dgesture.*)
 
typedef struct SDL_DropEvent SDL_DropEvent
 An event used to request a file open by the system (event.drop.*) This event is enabled by default, you can disable it with SDL_EventState().
 
typedef struct SDL_SensorEvent SDL_SensorEvent
 Sensor event structure (event.sensor.*)
 
typedef struct SDL_QuitEvent SDL_QuitEvent
 The "quit requested" event.
 
typedef struct SDL_OSEvent SDL_OSEvent
 OS Specific event.
 
typedef struct SDL_UserEvent SDL_UserEvent
 A user-defined event type (event.user.*)
 
typedef struct SDL_SysWMmsg SDL_SysWMmsg
 
typedef struct SDL_SysWMEvent SDL_SysWMEvent
 A video driver dependent system event (event.syswm.*) This event is disabled by default, you can enable it with SDL_EventState()
 
typedef union SDL_Event SDL_Event
 General event structure.
 
typedef int(SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event *event)
 

Enumerations

enum  SDL_EventType {
  SDL_FIRSTEVENT = 0 , SDL_QUIT = 0x100 , SDL_APP_TERMINATING , SDL_APP_LOWMEMORY ,
  SDL_APP_WILLENTERBACKGROUND , SDL_APP_DIDENTERBACKGROUND , SDL_APP_WILLENTERFOREGROUND , SDL_APP_DIDENTERFOREGROUND ,
  SDL_LOCALECHANGED , SDL_DISPLAYEVENT = 0x150 , SDL_WINDOWEVENT = 0x200 , SDL_SYSWMEVENT ,
  SDL_KEYDOWN = 0x300 , SDL_KEYUP , SDL_TEXTEDITING , SDL_TEXTINPUT ,
  SDL_KEYMAPCHANGED , SDL_TEXTEDITING_EXT , SDL_MOUSEMOTION = 0x400 , SDL_MOUSEBUTTONDOWN ,
  SDL_MOUSEBUTTONUP , SDL_MOUSEWHEEL , SDL_JOYAXISMOTION = 0x600 , SDL_JOYBALLMOTION ,
  SDL_JOYHATMOTION , SDL_JOYBUTTONDOWN , SDL_JOYBUTTONUP , SDL_JOYDEVICEADDED ,
  SDL_JOYDEVICEREMOVED , SDL_JOYBATTERYUPDATED , SDL_CONTROLLERAXISMOTION = 0x650 , SDL_CONTROLLERBUTTONDOWN ,
  SDL_CONTROLLERBUTTONUP , SDL_CONTROLLERDEVICEADDED , SDL_CONTROLLERDEVICEREMOVED , SDL_CONTROLLERDEVICEREMAPPED ,
  SDL_CONTROLLERTOUCHPADDOWN , SDL_CONTROLLERTOUCHPADMOTION , SDL_CONTROLLERTOUCHPADUP , SDL_CONTROLLERSENSORUPDATE ,
  SDL_FINGERDOWN = 0x700 , SDL_FINGERUP , SDL_FINGERMOTION , SDL_DOLLARGESTURE = 0x800 ,
  SDL_DOLLARRECORD , SDL_MULTIGESTURE , SDL_CLIPBOARDUPDATE = 0x900 , SDL_DROPFILE = 0x1000 ,
  SDL_DROPTEXT , SDL_DROPBEGIN , SDL_DROPCOMPLETE , SDL_AUDIODEVICEADDED = 0x1100 ,
  SDL_AUDIODEVICEREMOVED , SDL_SENSORUPDATE = 0x1200 , SDL_RENDER_TARGETS_RESET = 0x2000 , SDL_RENDER_DEVICE_RESET ,
  SDL_POLLSENTINEL = 0x7F00 , SDL_USEREVENT = 0x8000 , SDL_LASTEVENT = 0xFFFF
}
 
enum  SDL_eventaction { SDL_ADDEVENT , SDL_PEEKEVENT , SDL_GETEVENT }
 

Functions

 SDL_COMPILE_TIME_ASSERT (SDL_Event, sizeof(SDL_Event)==sizeof(((SDL_Event *) NULL) ->padding))
 
DECLSPEC void SDLCALL SDL_PumpEvents (void)
 
DECLSPEC int SDLCALL SDL_PeepEvents (SDL_Event *events, int numevents, SDL_eventaction action, Uint32 minType, Uint32 maxType)
 
DECLSPEC SDL_bool SDLCALL SDL_HasEvent (Uint32 type)
 
DECLSPEC SDL_bool SDLCALL SDL_HasEvents (Uint32 minType, Uint32 maxType)
 
DECLSPEC void SDLCALL SDL_FlushEvent (Uint32 type)
 
DECLSPEC void SDLCALL SDL_FlushEvents (Uint32 minType, Uint32 maxType)
 
DECLSPEC int SDLCALL SDL_PollEvent (SDL_Event *event)
 
DECLSPEC int SDLCALL SDL_WaitEvent (SDL_Event *event)
 
DECLSPEC int SDLCALL SDL_WaitEventTimeout (SDL_Event *event, int timeout)
 
DECLSPEC int SDLCALL SDL_PushEvent (SDL_Event *event)
 
DECLSPEC void SDLCALL SDL_SetEventFilter (SDL_EventFilter filter, void *userdata)
 
DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter (SDL_EventFilter *filter, void **userdata)
 
DECLSPEC void SDLCALL SDL_AddEventWatch (SDL_EventFilter filter, void *userdata)
 
DECLSPEC void SDLCALL SDL_DelEventWatch (SDL_EventFilter filter, void *userdata)
 
DECLSPEC void SDLCALL SDL_FilterEvents (SDL_EventFilter filter, void *userdata)
 
DECLSPEC Uint8 SDLCALL SDL_EventState (Uint32 type, int state)
 
DECLSPEC Uint32 SDLCALL SDL_RegisterEvents (int numevents)
 

Detailed Description

Include file for SDL event handling.

Typedef Documentation

◆ SDL_DropEvent

typedef struct SDL_DropEvent SDL_DropEvent

An event used to request a file open by the system (event.drop.*) This event is enabled by default, you can disable it with SDL_EventState().

Note
If this event is enabled, you must free the filename in the event.

◆ SDL_EventFilter

typedef int(SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event *event)

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

Parameters
userdatawhat was passed as userdata to SDL_SetEventFilter() or SDL_AddEventWatch, etc
eventthe event that triggered the callback
Returns
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.
See also
SDL_SetEventFilter
SDL_AddEventWatch

◆ SDL_SysWMEvent

A video driver dependent system event (event.syswm.*) This event is disabled by default, you can enable it with SDL_EventState()

Note
If you want to use this event, you should include SDL_syswm.h.

Enumeration Type Documentation

◆ SDL_EventType

The types of events that can be delivered.

Enumerator
SDL_FIRSTEVENT 

Unused (do not remove)

SDL_QUIT 

User-requested quit

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.

SDL_DISPLAYEVENT 

Display state change

SDL_WINDOWEVENT 

Window state change

SDL_SYSWMEVENT 

System specific event

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.

SDL_TEXTEDITING_EXT 

Extended keyboard text editing (composition)

SDL_MOUSEMOTION 

Mouse moved

SDL_MOUSEBUTTONDOWN 

Mouse button pressed

SDL_MOUSEBUTTONUP 

Mouse button released

SDL_MOUSEWHEEL 

Mouse wheel motion

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

SDL_JOYBATTERYUPDATED 

Joystick battery level change

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

SDL_CLIPBOARDUPDATE 

The clipboard or primary selection changed

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)

SDL_AUDIODEVICEADDED 

A new audio device is available

SDL_AUDIODEVICEREMOVED 

An audio device has been removed.

SDL_SENSORUPDATE 

A sensor was updated

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

SDL_POLLSENTINEL 

Signals the end of an event poll cycle

SDL_USEREVENT 

Events SDL_USEREVENT through SDL_LASTEVENT are for your use, and should be allocated with SDL_RegisterEvents()

SDL_LASTEVENT 

This last event is only for bounding internal arrays

Function Documentation

◆ SDL_AddEventWatch()

DECLSPEC void SDLCALL SDL_AddEventWatch ( SDL_EventFilter  filter,
void *  userdata 
)

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

Parameters
filteran SDL_EventFilter function to call when an event happens.
userdataa pointer that is passed to filter
Since
This function is available since SDL 2.0.0.
See also
SDL_DelEventWatch
SDL_SetEventFilter

◆ SDL_DelEventWatch()

DECLSPEC void SDLCALL SDL_DelEventWatch ( SDL_EventFilter  filter,
void *  userdata 
)

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.

Parameters
filterthe function originally passed to SDL_AddEventWatch()
userdatathe pointer originally passed to SDL_AddEventWatch()
Since
This function is available since SDL 2.0.0.
See also
SDL_AddEventWatch

◆ SDL_EventState()

DECLSPEC Uint8 SDLCALL SDL_EventState ( Uint32  type,
int  state 
)

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
Parameters
typethe type of event; see SDL_EventType for details
statehow 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.
Since
This function is available since SDL 2.0.0.
See also
SDL_GetEventState

◆ SDL_FilterEvents()

DECLSPEC void SDLCALL SDL_FilterEvents ( SDL_EventFilter  filter,
void *  userdata 
)

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.

Parameters
filterthe SDL_EventFilter function to call when an event happens
userdataa pointer that is passed to filter
Since
This function is available since SDL 2.0.0.
See also
SDL_GetEventFilter
SDL_SetEventFilter

◆ SDL_FlushEvent()

DECLSPEC void SDLCALL SDL_FlushEvent ( Uint32  type)

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.

Parameters
typethe type of event to be cleared; see SDL_EventType for details
Since
This function is available since SDL 2.0.0.
See also
SDL_FlushEvents

◆ SDL_FlushEvents()

DECLSPEC void SDLCALL SDL_FlushEvents ( Uint32  minType,
Uint32  maxType 
)

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.

Parameters
minTypethe low end of event type to be cleared, inclusive; see SDL_EventType for details
maxTypethe high end of event type to be cleared, inclusive; see SDL_EventType for details
Since
This function is available since SDL 2.0.0.
See also
SDL_FlushEvent

◆ SDL_GetEventFilter()

DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter ( SDL_EventFilter filter,
void **  userdata 
)

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.

Parameters
filterthe current callback function will be stored here
userdatathe 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.
Since
This function is available since SDL 2.0.0.
See also
SDL_SetEventFilter

◆ SDL_HasEvent()

DECLSPEC SDL_bool SDLCALL SDL_HasEvent ( Uint32  type)

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.

Parameters
typethe 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.
Since
This function is available since SDL 2.0.0.
See also
SDL_HasEvents

◆ SDL_HasEvents()

DECLSPEC SDL_bool SDLCALL SDL_HasEvents ( Uint32  minType,
Uint32  maxType 
)

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.

Parameters
minTypethe low end of event type to be queried, inclusive; see SDL_EventType for details
maxTypethe 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.
Since
This function is available since SDL 2.0.0.
See also
SDL_HasEvents

◆ SDL_PeepEvents()

DECLSPEC int SDLCALL SDL_PeepEvents ( SDL_Event events,
int  numevents,
SDL_eventaction  action,
Uint32  minType,
Uint32  maxType 
)

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.

Parameters
eventsdestination buffer for the retrieved events
numeventsif 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
actionaction to take; see [[#action|Remarks]] for details
minTypeminimum value of the event type to be considered; SDL_FIRSTEVENT is a safe choice
maxTypemaximum 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.
Since
This function is available since SDL 2.0.0.
See also
SDL_PollEvent
SDL_PumpEvents
SDL_PushEvent

◆ SDL_PollEvent()

DECLSPEC int SDLCALL SDL_PollEvent ( SDL_Event event)

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:

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
}
DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event)
General event structure.
Definition: SDL_events.h:626
Parameters
eventthe SDL_Event structure to be filled with the next event from the queue, or NULL
Returns
1 if there is a pending event or 0 if there are none available.
Since
This function is available since SDL 2.0.0.
See also
SDL_GetEventFilter
SDL_PeepEvents
SDL_PushEvent
SDL_SetEventFilter
SDL_WaitEvent
SDL_WaitEventTimeout

◆ SDL_PumpEvents()

DECLSPEC void SDLCALL SDL_PumpEvents ( void  )

Pump the event loop, gathering events from the input devices.

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.

Since
This function is available since SDL 2.0.0.
See also
SDL_PollEvent
SDL_WaitEvent

◆ SDL_PushEvent()

DECLSPEC int SDLCALL SDL_PushEvent ( SDL_Event event)

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.

Parameters
eventthe SDL_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.
Since
This function is available since SDL 2.0.0.
See also
SDL_PeepEvents
SDL_PollEvent
SDL_RegisterEvents

◆ SDL_RegisterEvents()

DECLSPEC Uint32 SDLCALL SDL_RegisterEvents ( int  numevents)

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.

Parameters
numeventsthe number of events to be allocated
Returns
the beginning event number, or (Uint32)-1 if there are not enough user-defined events left.
Since
This function is available since SDL 2.0.0.
See also
SDL_PushEvent

◆ SDL_SetEventFilter()

DECLSPEC void SDLCALL SDL_SetEventFilter ( SDL_EventFilter  filter,
void *  userdata 
)

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.

Parameters
filterAn SDL_EventFilter function to call when an event happens
userdataa pointer that is passed to filter
Since
This function is available since SDL 2.0.0.
See also
SDL_AddEventWatch
SDL_EventState
SDL_GetEventFilter
SDL_PeepEvents
SDL_PushEvent

◆ SDL_WaitEvent()

DECLSPEC int SDLCALL SDL_WaitEvent ( SDL_Event event)

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.

Parameters
eventthe SDL_Event structure to be filled in with the next event from the queue, or NULL
Returns
1 on success or 0 if there was an error while waiting for events; call SDL_GetError() for more information.
Since
This function is available since SDL 2.0.0.
See also
SDL_PollEvent
SDL_PumpEvents
SDL_WaitEventTimeout

◆ SDL_WaitEventTimeout()

DECLSPEC int SDLCALL SDL_WaitEventTimeout ( SDL_Event event,
int  timeout 
)

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.

Parameters
eventthe SDL_Event structure to be filled in with the next event from the queue, or NULL
timeoutthe 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.
Since
This function is available since SDL 2.0.0.
See also
SDL_PollEvent
SDL_PumpEvents
SDL_WaitEvent