Differences between revisions 16 and 47 (spanning 31 versions)

SDL_EventType

An enumeration of the types of events that can be delivered.

Contents

SDL_EventType

Values

SDL_FIRSTEVENT	do not remove (unused)
Application events
SDL_QUIT	user-requested quit; see Remarks for details
Android, iOS and WinRT events; see Remarks for details
SDL_APP_TERMINATING	OS is terminating the application
SDL_APP_LOWMEMORY	OS is low on memory; free some
SDL_APP_WILLENTERBACKGROUND	application is entering background
SDL_APP_DIDENTERBACKGROUND	application entered background
SDL_APP_WILLENTERFOREGROUND	application is entering foreground
SDL_APP_DIDENTERFOREGROUND	application entered foreground
Window events
SDL_WINDOWEVENT	window state change
SDL_SYSWMEVENT	system specific event
Keyboard events
SDL_KEYDOWN	key pressed
SDL_KEYUP	key released
SDL_TEXTEDITING	keyboard text editing (composition)
SDL_TEXTINPUT	keyboard text input
SDL_KEYMAPCHANGED	keymap changed due to a system event such as an input language or keyboard layout change (>= SDL 2.0.4)
Mouse events
SDL_MOUSEMOTION	mouse moved
SDL_MOUSEBUTTONDOWN	mouse button pressed
SDL_MOUSEBUTTONUP	mouse button released
SDL_MOUSEWHEEL	mouse wheel motion
Joystick events
SDL_JOYAXISMOTION	joystick axis motion
SDL_JOYBALLMOTION	joystick trackball motion
SDL_JOYHATMOTION	joystick hat position change
SDL_JOYBUTTONDOWN	joystick button pressed
SDL_JOYBUTTONUP	joystick button released
SDL_JOYDEVICEADDED	joystick connected
SDL_JOYDEVICEREMOVED	joystick disconnected
Controller events
SDL_CONTROLLERAXISMOTION	controller axis motion
SDL_CONTROLLERBUTTONDOWN	controller button pressed
SDL_CONTROLLERBUTTONUP	controller button released
SDL_CONTROLLERDEVICEADDED	controller connected
SDL_CONTROLLERDEVICEREMOVED	controller disconnected
SDL_CONTROLLERDEVICEREMAPPED	controller mapping updated
Touch events
SDL_FINGERDOWN	user has touched input device
SDL_FINGERUP	user stopped touching input device
SDL_FINGERMOTION	user is dragging finger on input device
Gesture events
SDL_DOLLARGESTURE
SDL_DOLLARRECORD
SDL_MULTIGESTURE
Clipboard events
SDL_CLIPBOARDUPDATE	the clipboard changed
Drag and drop events
SDL_DROPFILE	the system requests a file open
SDL_DROPTEXT	text/plain drag-and-drop event
SDL_DROPBEGIN	a new set of drops is beginning (>= SDL 2.0.5)
SDL_DROPCOMPLETE	current set of drops is now complete (>= SDL 2.0.5)
Audio hotplug events
SDL_AUDIODEVICEADDED	a new audio device is available (>= SDL 2.0.4)
SDL_AUDIODEVICEREMOVED	an audio device has been removed (>= SDL 2.0.4)
Render events
SDL_RENDER_TARGETS_RESET	the render targets have been reset and their contents need to be updated (>= SDL 2.0.2)
SDL_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_USEREVENT	a user-specified event
SDL_LASTEVENT	only for bounding internal arrays

Code Examples

SDL_Event e;
while (SDL_PollEvent(&e)) {
    if (e.type == SDL_KEYDOWN) {
        SDL_Log("User just pressed down a key!");
    }
}

Remarks

SDL_QUIT

SDL_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_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_WINDOWEVENT_CLOSE event, so the application can check whichever is appropriate, or both, or neither. If the application ignores this event and creates another window, SDL_QUIT will be sent again the next time the user clicks on the last remaining window's close button.

SDL_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_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_QUIT events as well. There is no way to determine the cause of an SDL_QUIT event, but setting a signal handler in your application will override the default generation of quit events for that signal.

Android, iOS and WinRT Events

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_APP_TERMINATING	The application is being terminated by the OS.	`applicationWillTerminate()`	`onDestroy()`	`Exiting()`
SDL_APP_LOWMEMORY	The application is low on memory, free memory if possible.	`applicationDidReceiveMemoryWarning()`	`onLowMemory()`	--
SDL_APP_WILLENTERBACKGROUND	The application is about to enter the background.	`applicationWillResignActive()`	`onPause()`	`Suspending()`
SDL_APP_DIDENTERBACKGROUND	The application did enter the background and may not get CPU for some time.	`applicationDidEnterBackground()`	`onPause()`	`Suspending()`
SDL_APP_WILLENTERFOREGROUND	The application is about to enter the foreground.	`applicationWillEnterForeground()`	`onResume()`	`Resuming()`
SDL_APP_DIDENTERFOREGROUND	The application is now interactive.	`applicationDidBecomeActive()`	`onResume()`	`Resuming()`

Related Structures

Related Functions

CategoryEnum, CategoryEvents

-  ⇤ ← Revision 16 as of 2011-06-12 16:21:09 → 
  Size: 3865
  Editor: SheenaSmith
  Comment: update content - w/ Sam (add Remarks sub-heading)
+   ← Revision 47 as of 2016-10-13 20:32:06 → ⇥
  Size: 8604
  Editor: PhilippWiesemann
  Comment: Updated with content from header file.
-Deletions are marked like this.
+Additions are marked like this.
 Line 2:
-#pragma disable-camelcase
||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||
+#pragma camelcase off
-Line 11:
+Line 10:
-||<style="color: #808080;">SDL_FIRSTEVENT||<style="color: #808080;">unused (do not remove)||
+||<style="color: #808080;">SDL_FIRSTEVENT||<style="color: #808080;">do not remove (unused)||
-Line 14:
+Line 13:
+||||<bgcolor="#EDEDED">''Android, iOS and WinRT events; see [[#Android, iOS and WinRT Events|Remarks]] for details''||
||SDL_APP_TERMINATING||OS is terminating the application||
||SDL_APP_LOWMEMORY||OS is low on memory; free some||
||SDL_APP_WILLENTERBACKGROUND||application is entering background||
||SDL_APP_DIDENTERBACKGROUND||application entered background||
||SDL_APP_WILLENTERFOREGROUND||application is entering foreground||
||SDL_APP_DIDENTERFOREGROUND||application entered foreground||
-Line 15:
+Line 21:
-||SDL_WINDOWEVENT||window state change||
||SDL_SYSWMEVENT||system specific event||
+||[[SDL_WindowEvent|SDL_WINDOWEVENT]]||window state change||
||[[SDL_SysWMEvent|SDL_SYSWMEVENT]]||system specific event||
-Line 18:
+Line 24:
-||SDL_KEYDOWN||key pressed||
||SDL_KEYUP||key released||
||SDL_TEXTEDITING||keyboard text editing (composition)||
||SDL_TEXTINPUT||keyboard text input||
+||[[SDL_KeyboardEvent|SDL_KEYDOWN]]||key pressed||
||[[SDL_KeyboardEvent|SDL_KEYUP]]||key released||
||[[SDL_TextEditingEvent|SDL_TEXTEDITING]]||keyboard text editing (composition)||
||[[SDL_TextInputEvent|SDL_TEXTINPUT]]||keyboard text input||
||SDL_KEYMAPCHANGED||keymap changed due to a system event such as an input language or keyboard layout change (>= SDL 2.0.4)||
-Line 23:
+Line 30:
-||SDL_MOUSEMOTION||mouse moved||
||SDL_MOUSEBUTTONDOWN||mouse button pressed||
||SDL_MOUSEBUTTONUP||mouse button released||
||SDL_MOUSEWHEEL||mouse wheel motion||
||||<bgcolor="#EDEDED">''Tablet or multiple mice input device events''||
||SDL_INPUTMOTION||input moved||
||SDL_INPUTBUTTONDOWN||input button pressed||
||SDL_INPUTBUTTONUP||input button released||
||SDL_INPUTWHEEL||input wheel motion||
||SDL_INPUTPROXIMITYIN||input pen entered proximity||
||SDL_INPUTPROXIMITYOUT||input pen left proximity||
+||[[SDL_MouseMotionEvent|SDL_MOUSEMOTION]]||mouse moved||
||[[SDL_MouseButtonEvent|SDL_MOUSEBUTTONDOWN]]||mouse button pressed||
||[[SDL_MouseButtonEvent|SDL_MOUSEBUTTONUP]]||mouse button released||
||[[SDL_MouseWheelEvent|SDL_MOUSEWHEEL]]||mouse wheel motion||
 Line 35:
-||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_JoyAxisEvent|SDL_JOYAXISMOTION]]||joystick axis motion||
||[[SDL_JoyBallEvent|SDL_JOYBALLMOTION]]||joystick trackball motion||
||[[SDL_JoyHatEvent|SDL_JOYHATMOTION]]||joystick hat position change||
||[[SDL_JoyButtonEvent|SDL_JOYBUTTONDOWN]]||joystick button pressed||
||[[SDL_JoyButtonEvent|SDL_JOYBUTTONUP]]||joystick button released||
||[[SDL_JoyDeviceEvent|SDL_JOYDEVICEADDED]]||joystick connected||
||[[SDL_JoyDeviceEvent|SDL_JOYDEVICEREMOVED]]||joystick disconnected||
||||<bgcolor="#EDEDED">''Controller events''||
||[[SDL_ControllerAxisEvent|SDL_CONTROLLERAXISMOTION]]||controller axis motion||
||[[SDL_ControllerButtonEvent|SDL_CONTROLLERBUTTONDOWN]]||controller button pressed||
||[[SDL_ControllerButtonEvent|SDL_CONTROLLERBUTTONUP]]||controller button released||
||[[SDL_ControllerDeviceEvent|SDL_CONTROLLERDEVICEADDED]]||controller connected||
||[[SDL_ControllerDeviceEvent|SDL_CONTROLLERDEVICEREMOVED]]||controller disconnected||
||[[SDL_ControllerDeviceEvent|SDL_CONTROLLERDEVICEREMAPPED]]||controller mapping updated||
-Line 41:
+Line 50:
-||SDL_FINGERDOWN||||
||SDL_FINGERUP||||
||SDL_FINGERMOTION||||
||SDL_TOUCHBUTTONDOWN||||
||SDL_TOUCHBUTTONUP||||
+||[[SDL_TouchFingerEvent|SDL_FINGERDOWN]]||user has touched input device||
||[[SDL_TouchFingerEvent|SDL_FINGERUP]]||user stopped touching input device||
||[[SDL_TouchFingerEvent|SDL_FINGERMOTION]]||user is dragging finger on input device||
-Line 47:
+Line 54:
-||SDL_DOLLARGESTURE||||
||SDL_DOLLARRECORD||||
||SDL_MULTIGESTURE||||
+||[[SDL_DollarGestureEvent|SDL_DOLLARGESTURE]]||||
||[[SDL_DollarGestureEvent|SDL_DOLLARRECORD]]||||
||[[SDL_MultiGestureEvent|SDL_MULTIGESTURE]]||||
-Line 52:
+Line 59:
-||||<bgcolor="#EDEDED">''Obsolete events''||
||<style="color: #808080;">SDL_EVENT_COMPAT1||<style="color: #808080;">SDL 1.2 events for compatibility||
||<style="color: #808080;">SDL_EVENT_COMPAT2||<style="color: #808080;">SDL 1.2 events for compatibility||
||<style="color: #808080;">SDL_EVENT_COMPAT3||<style="color: #808080;">SDL 1.2 events for compatibility||
+||||<bgcolor="#EDEDED">''Drag and drop events''||
||[[SDL_DropEvent|SDL_DROPFILE]]||the system requests a file open||
||[[SDL_DropEvent|SDL_DROPTEXT]]||text/plain drag-and-drop event||
||[[SDL_DropEvent|SDL_DROPBEGIN]]||a new set of drops is beginning (>= SDL 2.0.5)||
||[[SDL_DropEvent|SDL_DROPCOMPLETE]]||current set of drops is now complete (>= SDL 2.0.5)||
||||<bgcolor="#EDEDED">''Audio hotplug events''||
||[[SDL_AudioDeviceEvent|SDL_AUDIODEVICEADDED]]||a new audio device is available (>= SDL 2.0.4)||
||[[SDL_AudioDeviceEvent|SDL_AUDIODEVICEREMOVED]]||an audio device has been removed (>= SDL 2.0.4)||
||||<bgcolor="#EDEDED">''Render events''||
||SDL_RENDER_TARGETS_RESET||the render targets have been reset and their contents need to be updated (>= SDL 2.0.2)||
||SDL_RENDER_DEVICE_RESET||the device has been reset and all textures need to be recreated (>= SDL 2.0.4)||
-Line 62:
+Line 76:
-You can add your code example here
+SDL_Event e;
while (SDL_PollEvent(&e)) {
    if (e.type == SDL_KEYDOWN) {
        SDL_Log("User just pressed down a key!");
    }
}
-Line 66:
+Line 85:
-=== Application Events ===
An SDL_QUIT event is generated when the user tries to close the application window.  If it is ignored or filtered out, the window will remain open.  If it is not ignored or filtered, it is queued normally and the window is allowed to close.  When the window is closed, screen updates will complete, but have no effect.
+=== SDL_QUIT ===
SDL_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.
-Line 69:
+Line 88:
-[[SDL_Init]]() installs signal handlers for `SIGINT` (keyboard interrupt) and `SIGTERM` (system termination request), if handlers do not already exist, that generate SDL_QUIT events as well.  There is no way to determine the cause of an SDL_QUIT event, but setting a signal handler in your application will override the default generation of quit events for that signal.
+An SDL_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_WINDOWEVENT_CLOSE event, so the application can check whichever is appropriate, or both, or neither. If the application ignores this event and creates another window, SDL_QUIT will be sent again the next time the user clicks on the last remaining window's close button.

SDL_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_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 [[http://en.wikipedia.org/wiki/Unix_signal|signal handlers]] for `SIGINT` (keyboard interrupt) and `SIGTERM` (system termination request), if handlers do not already exist, that generate SDL_QUIT events as well.  There is no way to determine the cause of an SDL_QUIT event, but setting a signal handler in your application will override the default generation of quit events for that signal.

=== Android, iOS and WinRT Events ===
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_APP_TERMINATING||The application is being terminated by the OS.||`applicationWillTerminate()`||`onDestroy()`|| `Exiting()`||
||SDL_APP_LOWMEMORY||The application is low on memory, free memory if possible.||`applicationDidReceiveMemoryWarning()`||`onLowMemory()`|| --||
||SDL_APP_WILLENTERBACKGROUND||The application is about to enter the background.||`applicationWillResignActive()`||`onPause()`|| `Suspending()`||
||SDL_APP_DIDENTERBACKGROUND||The application did enter the background and may not get CPU for some time.||`applicationDidEnterBackground()`||`onPause()`|| `Suspending()`||
||SDL_APP_WILLENTERFOREGROUND||The application is about to enter the foreground.||`applicationWillEnterForeground()`||`onResume()`|| `Resuming()`||
||SDL_APP_DIDENTERFOREGROUND||The application is now interactive.||`applicationDidBecomeActive()`||`onResume()`|| `Resuming()`||
-Line 76:
+Line 112:
+ . [[SDL_JoyDeviceEvent]]
 . [[SDL_ControllerAxisEvent]]
 . [[SDL_ControllerButtonEvent]]
 . [[SDL_ControllerDeviceEvent]]
-Line 80:
+Line 120:
- . [[SDL_ProximityEvent]]
-Line 86:
+Line 125:
+ . [[SDL_WindowEvent]]
 . [[SDL_DropEvent]]
 . [[SDL_AudioDeviceEvent]]
 . [[SDL_TouchFingerEvent]]
 . [[SDL_DollarGestureEvent]]
 . [[SDL_MultiGestureEvent]]
-Line 88:
+Line 134:
+ . [[SDL_PollEvent]]
 . [[SDL_SetEventFilter]]

Wiki Navigation

Wiki Page Content