Differences between revisions 26 and 47 (spanning 21 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 26 as of 2013-07-29 16:46:32 → 
  Size: 6643
  Editor: RyanGordon
  Comment: Lots of work on SDL_EventType
+   ← 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 3:
-||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||
-Line 14:
+Line 13:
-||||<bgcolor="#EDEDED">''Android and iOS events; see [[#Android and iOS Events|Remarks]] for details''||
||SDL_APP_TERMINATING||||
||SDL_APP_LOWMEMORY||||
||SDL_APP_WILLENTERBACKGROUND||||
||SDL_APP_DIDENTERBACKGROUND||||
||SDL_APP_WILLENTERFOREGROUND||||
||SDL_APP_DIDENTERFOREGROUND||||
+||||<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 25:
+Line 24:
-||[[SDL_KeyEvent|SDL_KEYDOWN]]||key pressed||
||[[SDL_KeyEvent|SDL_KEYUP]]||key released||
+||[[SDL_KeyboardEvent|SDL_KEYDOWN]]||key pressed||
||[[SDL_KeyboardEvent|SDL_KEYUP]]||key released||
-Line 29:
+Line 28:
+||SDL_KEYMAPCHANGED||keymap changed due to a system event such as an input language or keyboard layout change (>= SDL 2.0.4)||
 Line 50:
-||[[SDL_TouchFingerEvent|SDL_FINGERDOWN]]||||
||[[SDL_TouchFingerEvent|SDL_FINGERUP]]||||
||[[SDL_TouchFingerEvent|SDL_FINGERMOTION]]||||
+||[[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 54:
-||[[SDL_MultiGestureEvent|SDL_DOLLARGESTURE]]||||
||[[SDL_MultiGestureEvent|SDL_DOLLARRECORD]]||||
+||[[SDL_DollarGestureEvent|SDL_DOLLARGESTURE]]||||
||[[SDL_DollarGestureEvent|SDL_DOLLARRECORD]]||||
 Line 61:
+||[[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 67:
+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 71:
+Line 85:
-=== Application Events ===
An SDL_QUIT event is generated when the user tries to close the last remaining SDL_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 74:
+Line 88:
-On Mac OS X, pressing Command-Q (the standard keyboard shortcut for "Quit this application") will cause SDL to generate an SDL_QUIT event. The application is still responsible for terminating itself, however.
+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.
-Line 76:
+Line 90:
-[[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.
+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.
-Line 78:
+Line 92:
-=== Android and iOS Events ===
What we currently label as "Android and iOS 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|SDL_PollEvent()]] loop, but you should set up a callback with [[SDL_SetEventFilter|SDL_SetEventFilter()] for these specific events.
+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.
-Line 83:
+Line 99:
-||SDL event||What||iOS||Android||
||SDL_APP_TERMINATING||The application is being terminated by the OS.||applicationWillTerminate()||onDestroy()||
||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()||
||SDL_APP_DIDENTERBACKGROUND||The application did enter the background and may not get CPU for some time.||applicationDidEnterBackground()||onPause()||
||SDL_APP_WILLENTERFOREGROUND||The application is about to enter the foreground.||applicationWillEnterForeground()||onResume()||
||SDL_APP_DIDENTERFOREGROUND||The application is now interactive.||applicationDidBecomeActive()||onResume()||
+||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 111:
+Line 127:
+ . [[SDL_AudioDeviceEvent]]
-Line 117:
+Line 134:
+ . [[SDL_PollEvent]]
 . [[SDL_SetEventFilter]]

Wiki Navigation

Wiki Page Content