An enumeration of the types of events that can be delivered.
SDL_EVENT_FIRST |
do not remove (unused) |
Application events |
|
SDL_EVENT_QUIT |
user-requested quit; see Remarks for details |
Android, iOS and WinRT events; see Remarks for details |
|
SDL_EVENT_TERMINATING |
OS is terminating the application |
SDL_EVENT_LOW_MEMORY |
OS is low on memory; free some |
SDL_EVENT_WILL_ENTER_BACKGROUND |
application is entering background |
SDL_EVENT_DID_ENTER_BACKGROUND |
application entered background |
SDL_EVENT_WILL_ENTER_FOREGROUND |
application is entering foreground |
SDL_EVENT_DID_ENTER_FOREGROUND |
application entered foreground |
Display events |
|
Display state change |
|
Window events |
|
window state change |
|
system specific event |
|
Keyboard events |
|
key pressed |
|
key released |
|
keyboard text editing (composition) |
|
keyboard text input |
|
SDL_EVENT_KEYMAP_CHANGED |
keymap changed due to a system event such as an input language or keyboard layout change (>= SDL 2.0.4) |
Mouse events |
|
mouse moved |
|
mouse button pressed |
|
mouse button released |
|
mouse wheel motion |
|
Joystick events |
|
joystick axis motion |
|
joystick hat position change |
|
joystick button pressed |
|
joystick button released |
|
joystick connected |
|
joystick disconnected |
|
Controller events |
|
controller axis motion |
|
controller button pressed |
|
controller button released |
|
controller connected |
|
controller disconnected |
|
controller mapping updated |
|
Touch events |
|
user has touched input device |
|
user stopped touching input device |
|
user is dragging finger on input device |
|
Clipboard events |
|
SDL_EVENT_CLIPBOARD_UPDATE |
the clipboard changed |
Drag and drop events |
|
the system requests a file open |
|
text/plain drag-and-drop event |
|
a new set of drops is beginning (>= SDL 2.0.5) |
|
current set of drops is now complete (>= SDL 2.0.5) |
|
Audio hotplug events |
|
a new audio device is available (>= SDL 2.0.4) |
|
an audio device has been removed (>= SDL 2.0.4) |
|
Render events |
|
SDL_EVENT_RENDER_TARGETS_RESET |
the render targets have been reset and their contents need to be updated (>= SDL 2.0.2) |
SDL_EVENT_RENDER_DEVICE_RESET |
the device has been reset and all textures need to be recreated (>= SDL 2.0.4) |
These are for your use, and should be allocated with SDL_RegisterEvents() |
|
SDL_EVENT_USER |
a user-specified event |
SDL_EVENT_LAST |
only for bounding internal arrays |
SDL_Event e;
while (SDL_PollEvent(&e)) {
if (e.type == SDL_EVENT_KEY_DOWN) {
SDL_Log("User just pressed down a key!");
}
}SDL_EVENT_QUIT events are generated for a variety of reasons. An application can choose to ignore the event, for example, if it wants to offer a prompt asking the user to save the current work.
An SDL_EVENT_QUIT event is generated when the user clicks on the close button of the last existing window. This happens in addition to the SDL_WINDOWEVENT/SDL_EVENT_WINDOW_CLOSE_REQUESTED event, so the application can check whichever is appropriate, or both, or neither. If the application ignores this event and creates another window, SDL_EVENT_QUIT will be sent again the next time the user clicks on the last remaining window's close button.
SDL_EVENT_QUIT is not limited to window closing. On Mac OS X, pressing Command-Q (the standard keyboard shortcut for "Quit this application") will cause SDL to generate an SDL_EVENT_QUIT event, regardless of what windows exist at the time. The application is still responsible for terminating itself properly, however. Applications that completely ignore Command-Q will fail Mac App Store certification.
On POSIX systems, SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) and SIGTERM (system termination request), if handlers do not already exist, that generate SDL_EVENT_QUIT events as well. There is no way to determine the cause of an SDL_EVENT_QUIT event, but setting a signal handler in your application will override the default generation of quit events for that signal.
What we currently label as "Android, iOS and WinRT events" are specific to mobile and embedded devices that have different requirements than your usual desktop application. These events must be handled in an event filter, since often the OS needs an immediate response and will terminate your process shortly after sending the event, and if it sits in the SDL event queue, it'll be too late. You can handle everything else through a normal SDL_PollEvent() loop, but you should set up a callback with SDL_SetEventFilter() for these specific events.
This is how these events currently map to the underlying OS:
SDL event |
What |
iOS |
Android |
WinRT |
SDL_EVENT_TERMINATING |
The application is being terminated by the OS. |
|
|
|
SDL_EVENT_LOW_MEMORY |
The application is low on memory, free memory if possible. |
|
|
-- |
SDL_EVENT_WILL_ENTER_BACKGROUND |
The application is about to enter the background. |
|
|
|
SDL_EVENT_DID_ENTER_BACKGROUND |
The application did enter the background and may not get CPU for some time. |
|
|
|
SDL_EVENT_WILL_ENTER_FOREGROUND |
The application is about to enter the foreground. |
|
|
|
SDL_EVENT_DID_ENTER_FOREGROUND |
The application is now interactive. |
|
|
|