2 Simple DirectMedia Layer
3 Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
25 * Include file for SDL event handling.
31 #include "SDL_stdinc.h"
32 #include "SDL_error.h"
33 #include "SDL_video.h"
34 #include "SDL_keyboard.h"
35 #include "SDL_mouse.h"
36 #include "SDL_joystick.h"
37 #include "SDL_gamecontroller.h"
39 #include "SDL_gesture.h"
40 #include "SDL_touch.h"
42 #include "begin_code.h"
43 /* Set up for C function definitions, even when using C++ */
48 /* General keyboard/mouse state definitions */
49 #define SDL_RELEASED 0
53 * The types of events that can be delivered.
57 SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */
59 /* Application events */
60 SDL_QUIT = 0x100, /**< User-requested quit */
62 /* These application events have special meaning on iOS, see README-ios.md for details */
63 SDL_APP_TERMINATING, /**< The application is being terminated by the OS
64 Called on iOS in applicationWillTerminate()
65 Called on Android in onDestroy()
67 SDL_APP_LOWMEMORY, /**< The application is low on memory, free memory if possible.
68 Called on iOS in applicationDidReceiveMemoryWarning()
69 Called on Android in onLowMemory()
71 SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background
72 Called on iOS in applicationWillResignActive()
73 Called on Android in onPause()
75 SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time
76 Called on iOS in applicationDidEnterBackground()
77 Called on Android in onPause()
79 SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground
80 Called on iOS in applicationWillEnterForeground()
81 Called on Android in onResume()
83 SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive
84 Called on iOS in applicationDidBecomeActive()
85 Called on Android in onResume()
88 SDL_LOCALECHANGED, /**< The user's locale preferences have changed. */
91 SDL_DISPLAYEVENT = 0x150, /**< Display state change */
94 SDL_WINDOWEVENT = 0x200, /**< Window state change */
95 SDL_SYSWMEVENT, /**< System specific event */
98 SDL_KEYDOWN = 0x300, /**< Key pressed */
99 SDL_KEYUP, /**< Key released */
100 SDL_TEXTEDITING, /**< Keyboard text editing (composition) */
101 SDL_TEXTINPUT, /**< Keyboard text input */
102 SDL_KEYMAPCHANGED, /**< Keymap changed due to a system event such as an
103 input language or keyboard layout change.
105 SDL_TEXTEDITING_EXT, /**< Extended keyboard text editing (composition) */
108 SDL_MOUSEMOTION = 0x400, /**< Mouse moved */
109 SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */
110 SDL_MOUSEBUTTONUP, /**< Mouse button released */
111 SDL_MOUSEWHEEL, /**< Mouse wheel motion */
113 /* Joystick events */
114 SDL_JOYAXISMOTION = 0x600, /**< Joystick axis motion */
115 SDL_JOYBALLMOTION, /**< Joystick trackball motion */
116 SDL_JOYHATMOTION, /**< Joystick hat position change */
117 SDL_JOYBUTTONDOWN, /**< Joystick button pressed */
118 SDL_JOYBUTTONUP, /**< Joystick button released */
119 SDL_JOYDEVICEADDED, /**< A new joystick has been inserted into the system */
120 SDL_JOYDEVICEREMOVED, /**< An opened joystick has been removed */
122 /* Game controller events */
123 SDL_CONTROLLERAXISMOTION = 0x650, /**< Game controller axis motion */
124 SDL_CONTROLLERBUTTONDOWN, /**< Game controller button pressed */
125 SDL_CONTROLLERBUTTONUP, /**< Game controller button released */
126 SDL_CONTROLLERDEVICEADDED, /**< A new Game controller has been inserted into the system */
127 SDL_CONTROLLERDEVICEREMOVED, /**< An opened Game controller has been removed */
128 SDL_CONTROLLERDEVICEREMAPPED, /**< The controller mapping was updated */
129 SDL_CONTROLLERTOUCHPADDOWN, /**< Game controller touchpad was touched */
130 SDL_CONTROLLERTOUCHPADMOTION, /**< Game controller touchpad finger was moved */
131 SDL_CONTROLLERTOUCHPADUP, /**< Game controller touchpad finger was lifted */
132 SDL_CONTROLLERSENSORUPDATE, /**< Game controller sensor was updated */
135 SDL_FINGERDOWN = 0x700,
140 SDL_DOLLARGESTURE = 0x800,
144 /* Clipboard events */
145 SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard changed */
147 /* Drag and drop events */
148 SDL_DROPFILE = 0x1000, /**< The system requests a file open */
149 SDL_DROPTEXT, /**< text/plain drag-and-drop event */
150 SDL_DROPBEGIN, /**< A new set of drops is beginning (NULL filename) */
151 SDL_DROPCOMPLETE, /**< Current set of drops is now complete (NULL filename) */
153 /* Audio hotplug events */
154 SDL_AUDIODEVICEADDED = 0x1100, /**< A new audio device is available */
155 SDL_AUDIODEVICEREMOVED, /**< An audio device has been removed. */
158 SDL_SENSORUPDATE = 0x1200, /**< A sensor was updated */
161 SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
162 SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
164 /* Internal events */
165 SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
167 /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
168 * and should be allocated with SDL_RegisterEvents()
170 SDL_USEREVENT = 0x8000,
173 * This last event is only for bounding internal arrays
175 SDL_LASTEVENT = 0xFFFF
179 * \brief Fields shared by every event
181 typedef struct SDL_CommonEvent
184 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
188 * \brief Display state change event data (event.display.*)
190 typedef struct SDL_DisplayEvent
192 Uint32 type; /**< ::SDL_DISPLAYEVENT */
193 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
194 Uint32 display; /**< The associated display index */
195 Uint8 event; /**< ::SDL_DisplayEventID */
199 Sint32 data1; /**< event dependent data */
203 * \brief Window state change event data (event.window.*)
205 typedef struct SDL_WindowEvent
207 Uint32 type; /**< ::SDL_WINDOWEVENT */
208 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
209 Uint32 windowID; /**< The associated window */
210 Uint8 event; /**< ::SDL_WindowEventID */
214 Sint32 data1; /**< event dependent data */
215 Sint32 data2; /**< event dependent data */
219 * \brief Keyboard button event structure (event.key.*)
221 typedef struct SDL_KeyboardEvent
223 Uint32 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
224 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
225 Uint32 windowID; /**< The window with keyboard focus, if any */
226 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
227 Uint8 repeat; /**< Non-zero if this is a key repeat */
230 SDL_Keysym keysym; /**< The key that was pressed or released */
233 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
235 * \brief Keyboard text editing event structure (event.edit.*)
237 typedef struct SDL_TextEditingEvent
239 Uint32 type; /**< ::SDL_TEXTEDITING */
240 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
241 Uint32 windowID; /**< The window with keyboard focus, if any */
242 char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */
243 Sint32 start; /**< The start cursor of selected editing text */
244 Sint32 length; /**< The length of selected editing text */
245 } SDL_TextEditingEvent;
248 * \brief Extended keyboard text editing event structure (event.editExt.*) when text would be
249 * truncated if stored in the text buffer SDL_TextEditingEvent
251 typedef struct SDL_TextEditingExtEvent
253 Uint32 type; /**< ::SDL_TEXTEDITING_EXT */
254 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
255 Uint32 windowID; /**< The window with keyboard focus, if any */
256 char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */
257 Sint32 start; /**< The start cursor of selected editing text */
258 Sint32 length; /**< The length of selected editing text */
259 } SDL_TextEditingExtEvent;
261 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
263 * \brief Keyboard text input event structure (event.text.*)
265 typedef struct SDL_TextInputEvent
267 Uint32 type; /**< ::SDL_TEXTINPUT */
268 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
269 Uint32 windowID; /**< The window with keyboard focus, if any */
270 char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */
271 } SDL_TextInputEvent;
274 * \brief Mouse motion event structure (event.motion.*)
276 typedef struct SDL_MouseMotionEvent
278 Uint32 type; /**< ::SDL_MOUSEMOTION */
279 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
280 Uint32 windowID; /**< The window with mouse focus, if any */
281 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
282 Uint32 state; /**< The current button state */
283 Sint32 x; /**< X coordinate, relative to window */
284 Sint32 y; /**< Y coordinate, relative to window */
285 Sint32 xrel; /**< The relative motion in the X direction */
286 Sint32 yrel; /**< The relative motion in the Y direction */
287 } SDL_MouseMotionEvent;
290 * \brief Mouse button event structure (event.button.*)
292 typedef struct SDL_MouseButtonEvent
294 Uint32 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
295 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
296 Uint32 windowID; /**< The window with mouse focus, if any */
297 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
298 Uint8 button; /**< The mouse button index */
299 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
300 Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */
302 Sint32 x; /**< X coordinate, relative to window */
303 Sint32 y; /**< Y coordinate, relative to window */
304 } SDL_MouseButtonEvent;
307 * \brief Mouse wheel event structure (event.wheel.*)
309 typedef struct SDL_MouseWheelEvent
311 Uint32 type; /**< ::SDL_MOUSEWHEEL */
312 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
313 Uint32 windowID; /**< The window with mouse focus, if any */
314 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
315 Sint32 x; /**< The amount scrolled horizontally, positive to the right and negative to the left */
316 Sint32 y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */
317 Uint32 direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */
318 float preciseX; /**< The amount scrolled horizontally, positive to the right and negative to the left, with float precision (added in 2.0.18) */
319 float preciseY; /**< The amount scrolled vertically, positive away from the user and negative toward the user, with float precision (added in 2.0.18) */
320 } SDL_MouseWheelEvent;
323 * \brief Joystick axis motion event structure (event.jaxis.*)
325 typedef struct SDL_JoyAxisEvent
327 Uint32 type; /**< ::SDL_JOYAXISMOTION */
328 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
329 SDL_JoystickID which; /**< The joystick instance id */
330 Uint8 axis; /**< The joystick axis index */
334 Sint16 value; /**< The axis value (range: -32768 to 32767) */
339 * \brief Joystick trackball motion event structure (event.jball.*)
341 typedef struct SDL_JoyBallEvent
343 Uint32 type; /**< ::SDL_JOYBALLMOTION */
344 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
345 SDL_JoystickID which; /**< The joystick instance id */
346 Uint8 ball; /**< The joystick trackball index */
350 Sint16 xrel; /**< The relative motion in the X direction */
351 Sint16 yrel; /**< The relative motion in the Y direction */
355 * \brief Joystick hat position change event structure (event.jhat.*)
357 typedef struct SDL_JoyHatEvent
359 Uint32 type; /**< ::SDL_JOYHATMOTION */
360 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
361 SDL_JoystickID which; /**< The joystick instance id */
362 Uint8 hat; /**< The joystick hat index */
363 Uint8 value; /**< The hat position value.
364 * \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
365 * \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
366 * \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
368 * Note that zero means the POV is centered.
375 * \brief Joystick button event structure (event.jbutton.*)
377 typedef struct SDL_JoyButtonEvent
379 Uint32 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
380 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
381 SDL_JoystickID which; /**< The joystick instance id */
382 Uint8 button; /**< The joystick button index */
383 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
386 } SDL_JoyButtonEvent;
389 * \brief Joystick device event structure (event.jdevice.*)
391 typedef struct SDL_JoyDeviceEvent
393 Uint32 type; /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
394 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
395 Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
396 } SDL_JoyDeviceEvent;
400 * \brief Game controller axis motion event structure (event.caxis.*)
402 typedef struct SDL_ControllerAxisEvent
404 Uint32 type; /**< ::SDL_CONTROLLERAXISMOTION */
405 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
406 SDL_JoystickID which; /**< The joystick instance id */
407 Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */
411 Sint16 value; /**< The axis value (range: -32768 to 32767) */
413 } SDL_ControllerAxisEvent;
417 * \brief Game controller button event structure (event.cbutton.*)
419 typedef struct SDL_ControllerButtonEvent
421 Uint32 type; /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
422 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
423 SDL_JoystickID which; /**< The joystick instance id */
424 Uint8 button; /**< The controller button (SDL_GameControllerButton) */
425 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
428 } SDL_ControllerButtonEvent;
432 * \brief Controller device event structure (event.cdevice.*)
434 typedef struct SDL_ControllerDeviceEvent
436 Uint32 type; /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */
437 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
438 Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
439 } SDL_ControllerDeviceEvent;
442 * \brief Game controller touchpad event structure (event.ctouchpad.*)
444 typedef struct SDL_ControllerTouchpadEvent
446 Uint32 type; /**< ::SDL_CONTROLLERTOUCHPADDOWN or ::SDL_CONTROLLERTOUCHPADMOTION or ::SDL_CONTROLLERTOUCHPADUP */
447 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
448 SDL_JoystickID which; /**< The joystick instance id */
449 Sint32 touchpad; /**< The index of the touchpad */
450 Sint32 finger; /**< The index of the finger on the touchpad */
451 float x; /**< Normalized in the range 0...1 with 0 being on the left */
452 float y; /**< Normalized in the range 0...1 with 0 being at the top */
453 float pressure; /**< Normalized in the range 0...1 */
454 } SDL_ControllerTouchpadEvent;
457 * \brief Game controller sensor event structure (event.csensor.*)
459 typedef struct SDL_ControllerSensorEvent
461 Uint32 type; /**< ::SDL_CONTROLLERSENSORUPDATE */
462 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
463 SDL_JoystickID which; /**< The joystick instance id */
464 Sint32 sensor; /**< The type of the sensor, one of the values of ::SDL_SensorType */
465 float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
466 } SDL_ControllerSensorEvent;
469 * \brief Audio device event structure (event.adevice.*)
471 typedef struct SDL_AudioDeviceEvent
473 Uint32 type; /**< ::SDL_AUDIODEVICEADDED, or ::SDL_AUDIODEVICEREMOVED */
474 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
475 Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */
476 Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */
480 } SDL_AudioDeviceEvent;
484 * \brief Touch finger event structure (event.tfinger.*)
486 typedef struct SDL_TouchFingerEvent
488 Uint32 type; /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */
489 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
490 SDL_TouchID touchId; /**< The touch device id */
491 SDL_FingerID fingerId;
492 float x; /**< Normalized in the range 0...1 */
493 float y; /**< Normalized in the range 0...1 */
494 float dx; /**< Normalized in the range -1...1 */
495 float dy; /**< Normalized in the range -1...1 */
496 float pressure; /**< Normalized in the range 0...1 */
497 Uint32 windowID; /**< The window underneath the finger, if any */
498 } SDL_TouchFingerEvent;
502 * \brief Multiple Finger Gesture Event (event.mgesture.*)
504 typedef struct SDL_MultiGestureEvent
506 Uint32 type; /**< ::SDL_MULTIGESTURE */
507 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
508 SDL_TouchID touchId; /**< The touch device id */
515 } SDL_MultiGestureEvent;
519 * \brief Dollar Gesture Event (event.dgesture.*)
521 typedef struct SDL_DollarGestureEvent
523 Uint32 type; /**< ::SDL_DOLLARGESTURE or ::SDL_DOLLARRECORD */
524 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
525 SDL_TouchID touchId; /**< The touch device id */
526 SDL_GestureID gestureId;
529 float x; /**< Normalized center of gesture */
530 float y; /**< Normalized center of gesture */
531 } SDL_DollarGestureEvent;
535 * \brief An event used to request a file open by the system (event.drop.*)
536 * This event is enabled by default, you can disable it with SDL_EventState().
537 * \note If this event is enabled, you must free the filename in the event.
539 typedef struct SDL_DropEvent
541 Uint32 type; /**< ::SDL_DROPBEGIN or ::SDL_DROPFILE or ::SDL_DROPTEXT or ::SDL_DROPCOMPLETE */
542 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
543 char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */
544 Uint32 windowID; /**< The window that was dropped on, if any */
549 * \brief Sensor event structure (event.sensor.*)
551 typedef struct SDL_SensorEvent
553 Uint32 type; /**< ::SDL_SENSORUPDATE */
554 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
555 Sint32 which; /**< The instance ID of the sensor */
556 float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */
560 * \brief The "quit requested" event
562 typedef struct SDL_QuitEvent
564 Uint32 type; /**< ::SDL_QUIT */
565 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
569 * \brief OS Specific event
571 typedef struct SDL_OSEvent
573 Uint32 type; /**< ::SDL_QUIT */
574 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
578 * \brief A user-defined event type (event.user.*)
580 typedef struct SDL_UserEvent
582 Uint32 type; /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */
583 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
584 Uint32 windowID; /**< The associated window if any */
585 Sint32 code; /**< User defined event code */
586 void *data1; /**< User defined data pointer */
587 void *data2; /**< User defined data pointer */
592 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
595 * \brief A video driver dependent system event (event.syswm.*)
596 * This event is disabled by default, you can enable it with SDL_EventState()
598 * \note If you want to use this event, you should include SDL_syswm.h.
600 typedef struct SDL_SysWMEvent
602 Uint32 type; /**< ::SDL_SYSWMEVENT */
603 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
604 SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
608 * \brief General event structure
610 typedef union SDL_Event
612 Uint32 type; /**< Event type, shared with all events */
613 SDL_CommonEvent common; /**< Common event data */
614 SDL_DisplayEvent display; /**< Display event data */
615 SDL_WindowEvent window; /**< Window event data */
616 SDL_KeyboardEvent key; /**< Keyboard event data */
617 SDL_TextEditingEvent edit; /**< Text editing event data */
618 SDL_TextEditingExtEvent editExt; /**< Extended text editing event data */
619 SDL_TextInputEvent text; /**< Text input event data */
620 SDL_MouseMotionEvent motion; /**< Mouse motion event data */
621 SDL_MouseButtonEvent button; /**< Mouse button event data */
622 SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
623 SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */
624 SDL_JoyBallEvent jball; /**< Joystick ball event data */
625 SDL_JoyHatEvent jhat; /**< Joystick hat event data */
626 SDL_JoyButtonEvent jbutton; /**< Joystick button event data */
627 SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */
628 SDL_ControllerAxisEvent caxis; /**< Game Controller axis event data */
629 SDL_ControllerButtonEvent cbutton; /**< Game Controller button event data */
630 SDL_ControllerDeviceEvent cdevice; /**< Game Controller device event data */
631 SDL_ControllerTouchpadEvent ctouchpad; /**< Game Controller touchpad event data */
632 SDL_ControllerSensorEvent csensor; /**< Game Controller sensor event data */
633 SDL_AudioDeviceEvent adevice; /**< Audio device event data */
634 SDL_SensorEvent sensor; /**< Sensor event data */
635 SDL_QuitEvent quit; /**< Quit request event data */
636 SDL_UserEvent user; /**< Custom event data */
637 SDL_SysWMEvent syswm; /**< System dependent window event data */
638 SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
639 SDL_MultiGestureEvent mgesture; /**< Gesture event data */
640 SDL_DollarGestureEvent dgesture; /**< Gesture event data */
641 SDL_DropEvent drop; /**< Drag and drop event data */
643 /* This is necessary for ABI compatibility between Visual C++ and GCC.
644 Visual C++ will respect the push pack pragma and use 52 bytes (size of
645 SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
646 architectures) for this union, and GCC will use the alignment of the
647 largest datatype within the union, which is 8 bytes on 64-bit
650 So... we'll add padding to force the size to be 56 bytes for both.
652 On architectures where pointers are 16 bytes, this needs rounding up to
653 the next multiple of 16, 64, and on architectures where pointers are
654 even larger the size of SDL_UserEvent will dominate as being 3 pointers.
656 Uint8 padding[sizeof(void *) <= 8 ? 56 : sizeof(void *) == 16 ? 64 : 3 * sizeof(void *)];
659 /* Make sure we haven't broken binary compatibility */
660 SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
663 /* Function prototypes */
666 * Pump the event loop, gathering events from the input devices.
668 * This function updates the event queue and internal input device state.
670 * **WARNING**: This should only be run in the thread that initialized the
671 * video subsystem, and for extra safety, you should consider only doing those
672 * things on the main thread in any case.
674 * SDL_PumpEvents() gathers all the pending input information from devices and
675 * places it in the event queue. Without calls to SDL_PumpEvents() no events
676 * would ever be placed on the queue. Often the need for calls to
677 * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
678 * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
679 * polling or waiting for events (e.g. you are filtering them), then you must
680 * call SDL_PumpEvents() to force an event queue update.
682 * \since This function is available since SDL 2.0.0.
687 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
698 * Check the event queue for messages and optionally return them.
700 * `action` may be any of the following:
702 * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
704 * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
705 * within the specified minimum and maximum type, will be returned to the
706 * caller and will _not_ be removed from the queue.
707 * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
708 * within the specified minimum and maximum type, will be returned to the
709 * caller and will be removed from the queue.
711 * You may have to call SDL_PumpEvents() before calling this function.
712 * Otherwise, the events may not be ready to be filtered when you call
715 * This function is thread-safe.
717 * \param events destination buffer for the retrieved events
718 * \param numevents if action is SDL_ADDEVENT, the number of events to add
719 * back to the event queue; if action is SDL_PEEKEVENT or
720 * SDL_GETEVENT, the maximum number of events to retrieve
721 * \param action action to take; see [[#action|Remarks]] for details
722 * \param minType minimum value of the event type to be considered;
723 * SDL_FIRSTEVENT is a safe choice
724 * \param maxType maximum value of the event type to be considered;
725 * SDL_LASTEVENT is a safe choice
726 * \returns the number of events actually stored or a negative error code on
727 * failure; call SDL_GetError() for more information.
729 * \since This function is available since SDL 2.0.0.
735 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
736 SDL_eventaction action,
737 Uint32 minType, Uint32 maxType);
741 * Check for the existence of a certain event type in the event queue.
743 * If you need to check for a range of event types, use SDL_HasEvents()
746 * \param type the type of event to be queried; see SDL_EventType for details
747 * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
748 * events matching `type` are not present.
750 * \since This function is available since SDL 2.0.0.
754 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
758 * Check for the existence of certain event types in the event queue.
760 * If you need to check for a single event type, use SDL_HasEvent() instead.
762 * \param minType the low end of event type to be queried, inclusive; see
763 * SDL_EventType for details
764 * \param maxType the high end of event type to be queried, inclusive; see
765 * SDL_EventType for details
766 * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
767 * present, or SDL_FALSE if not.
769 * \since This function is available since SDL 2.0.0.
773 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
776 * Clear events of a specific type from the event queue.
778 * This will unconditionally remove any events from the queue that match
779 * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
782 * It's also normal to just ignore events you don't care about in your event
783 * loop without calling this function.
785 * This function only affects currently queued events. If you want to make
786 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
787 * on the main thread immediately before the flush call.
789 * \param type the type of event to be cleared; see SDL_EventType for details
791 * \since This function is available since SDL 2.0.0.
793 * \sa SDL_FlushEvents
795 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
798 * Clear events of a range of types from the event queue.
800 * This will unconditionally remove any events from the queue that are in the
801 * range of `minType` to `maxType`, inclusive. If you need to remove a single
802 * event type, use SDL_FlushEvent() instead.
804 * It's also normal to just ignore events you don't care about in your event
805 * loop without calling this function.
807 * This function only affects currently queued events. If you want to make
808 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
809 * on the main thread immediately before the flush call.
811 * \param minType the low end of event type to be cleared, inclusive; see
812 * SDL_EventType for details
813 * \param maxType the high end of event type to be cleared, inclusive; see
814 * SDL_EventType for details
816 * \since This function is available since SDL 2.0.0.
820 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
823 * Poll for currently pending events.
825 * If `event` is not NULL, the next event is removed from the queue and stored
826 * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
827 * this event, immediately stored in the SDL Event structure -- not an event
830 * If `event` is NULL, it simply returns 1 if there is an event in the queue,
831 * but will not remove it from the queue.
833 * As this function may implicitly call SDL_PumpEvents(), you can only call
834 * this function in the thread that set the video mode.
836 * SDL_PollEvent() is the favored way of receiving system events since it can
837 * be done from the main loop and does not suspend the main loop while waiting
838 * on an event to be posted.
840 * The common practice is to fully process the event queue once every frame,
841 * usually as a first step before updating the game's state:
844 * while (game_is_still_running) {
846 * while (SDL_PollEvent(&event)) { // poll until all events are handled!
847 * // decide what to do with this event.
850 * // update game state, draw the current frame
854 * \param event the SDL_Event structure to be filled with the next event from
856 * \returns 1 if there is a pending event or 0 if there are none available.
858 * \since This function is available since SDL 2.0.0.
860 * \sa SDL_GetEventFilter
863 * \sa SDL_SetEventFilter
865 * \sa SDL_WaitEventTimeout
867 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
870 * Wait indefinitely for the next available event.
872 * If `event` is not NULL, the next event is removed from the queue and stored
873 * in the SDL_Event structure pointed to by `event`.
875 * As this function may implicitly call SDL_PumpEvents(), you can only call
876 * this function in the thread that initialized the video subsystem.
878 * \param event the SDL_Event structure to be filled in with the next event
879 * from the queue, or NULL
880 * \returns 1 on success or 0 if there was an error while waiting for events;
881 * call SDL_GetError() for more information.
883 * \since This function is available since SDL 2.0.0.
887 * \sa SDL_WaitEventTimeout
889 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
892 * Wait until the specified timeout (in milliseconds) for the next available
895 * If `event` is not NULL, the next event is removed from the queue and stored
896 * in the SDL_Event structure pointed to by `event`.
898 * As this function may implicitly call SDL_PumpEvents(), you can only call
899 * this function in the thread that initialized the video subsystem.
901 * \param event the SDL_Event structure to be filled in with the next event
902 * from the queue, or NULL
903 * \param timeout the maximum number of milliseconds to wait for the next
905 * \returns 1 on success or 0 if there was an error while waiting for events;
906 * call SDL_GetError() for more information. This also returns 0 if
907 * the timeout elapsed without an event arriving.
909 * \since This function is available since SDL 2.0.0.
915 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
919 * Add an event to the event queue.
921 * The event queue can actually be used as a two way communication channel.
922 * Not only can events be read from the queue, but the user can also push
923 * their own events onto it. `event` is a pointer to the event structure you
924 * wish to push onto the queue. The event is copied into the queue, and the
925 * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
927 * Note: Pushing device input events onto the queue doesn't modify the state
928 * of the device within SDL.
930 * This function is thread-safe, and can be called from other threads safely.
932 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
933 * the event filter but events added with SDL_PeepEvents() do not.
935 * For pushing application-specific events, please use SDL_RegisterEvents() to
936 * get an event type that does not conflict with other code that also wants
937 * its own custom event types.
939 * \param event the SDL_Event to be added to the queue
940 * \returns 1 on success, 0 if the event was filtered, or a negative error
941 * code on failure; call SDL_GetError() for more information. A
942 * common reason for error is the event queue being full.
944 * \since This function is available since SDL 2.0.0.
948 * \sa SDL_RegisterEvents
950 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
953 * A function pointer used for callbacks that watch the event queue.
955 * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
956 * or SDL_AddEventWatch, etc
957 * \param event the event that triggered the callback
958 * \returns 1 to permit event to be added to the queue, and 0 to disallow
959 * it. When used with SDL_AddEventWatch, the return value is ignored.
961 * \sa SDL_SetEventFilter
962 * \sa SDL_AddEventWatch
964 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
967 * Set up a filter to process all events before they change internal state and
968 * are posted to the internal event queue.
970 * If the filter function returns 1 when called, then the event will be added
971 * to the internal queue. If it returns 0, then the event will be dropped from
972 * the queue, but the internal state will still be updated. This allows
973 * selective filtering of dynamically arriving events.
975 * **WARNING**: Be very careful of what you do in the event filter function,
976 * as it may run in a different thread!
978 * On platforms that support it, if the quit event is generated by an
979 * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
980 * application at the next event poll.
982 * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
983 * event filter is only called when the window manager desires to close the
984 * application window. If the event filter returns 1, then the window will be
985 * closed, otherwise the window will remain open if possible.
987 * Note: Disabled events never make it to the event filter function; see
990 * Note: If you just want to inspect events without filtering, you should use
991 * SDL_AddEventWatch() instead.
993 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
994 * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
997 * \param filter An SDL_EventFilter function to call when an event happens
998 * \param userdata a pointer that is passed to `filter`
1000 * \since This function is available since SDL 2.0.0.
1002 * \sa SDL_AddEventWatch
1003 * \sa SDL_EventState
1004 * \sa SDL_GetEventFilter
1005 * \sa SDL_PeepEvents
1008 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
1012 * Query the current event filter.
1014 * This function can be used to "chain" filters, by saving the existing filter
1015 * before replacing it with a function that will call that saved filter.
1017 * \param filter the current callback function will be stored here
1018 * \param userdata the pointer that is passed to the current event filter will
1020 * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
1022 * \since This function is available since SDL 2.0.0.
1024 * \sa SDL_SetEventFilter
1026 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
1030 * Add a callback to be triggered when an event is added to the event queue.
1032 * `filter` will be called when an event happens, and its return value is
1035 * **WARNING**: Be very careful of what you do in the event filter function,
1036 * as it may run in a different thread!
1038 * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
1039 * the internal queue and be delivered to the watch callback immediately, and
1040 * arrive at the next event poll.
1042 * Note: the callback is called for events posted by the user through
1043 * SDL_PushEvent(), but not for disabled events, nor for events by a filter
1044 * callback set with SDL_SetEventFilter(), nor for events posted by the user
1045 * through SDL_PeepEvents().
1047 * \param filter an SDL_EventFilter function to call when an event happens.
1048 * \param userdata a pointer that is passed to `filter`
1050 * \since This function is available since SDL 2.0.0.
1052 * \sa SDL_DelEventWatch
1053 * \sa SDL_SetEventFilter
1055 extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
1059 * Remove an event watch callback added with SDL_AddEventWatch().
1061 * This function takes the same input as SDL_AddEventWatch() to identify and
1062 * delete the corresponding callback.
1064 * \param filter the function originally passed to SDL_AddEventWatch()
1065 * \param userdata the pointer originally passed to SDL_AddEventWatch()
1067 * \since This function is available since SDL 2.0.0.
1069 * \sa SDL_AddEventWatch
1071 extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
1075 * Run a specific filter function on the current event queue, removing any
1076 * events for which the filter returns 0.
1078 * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
1079 * this function does not change the filter permanently, it only uses the
1080 * supplied filter until this function returns.
1082 * \param filter the SDL_EventFilter function to call when an event happens
1083 * \param userdata a pointer that is passed to `filter`
1085 * \since This function is available since SDL 2.0.0.
1087 * \sa SDL_GetEventFilter
1088 * \sa SDL_SetEventFilter
1090 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
1094 #define SDL_QUERY -1
1095 #define SDL_IGNORE 0
1096 #define SDL_DISABLE 0
1097 #define SDL_ENABLE 1
1100 * Set the state of processing events by type.
1102 * `state` may be any of the following:
1104 * - `SDL_QUERY`: returns the current processing state of the specified event
1105 * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
1106 * from the event queue and will not be filtered
1107 * - `SDL_ENABLE`: the event will be processed normally
1109 * \param type the type of event; see SDL_EventType for details
1110 * \param state how to process the event
1111 * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
1112 * of the event before this function makes any changes to it.
1114 * \since This function is available since SDL 2.0.0.
1116 * \sa SDL_GetEventState
1118 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
1120 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
1123 * Allocate a set of user-defined events, and return the beginning event
1124 * number for that set of events.
1126 * Calling this function with `numevents` <= 0 is an error and will return
1129 * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
1130 * 0xFFFFFFFF), but is clearer to write.
1132 * \param numevents the number of events to be allocated
1133 * \returns the beginning event number, or (Uint32)-1 if there are not enough
1134 * user-defined events left.
1136 * \since This function is available since SDL 2.0.0.
1140 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
1142 /* Ends C function definitions when using C++ */
1146 #include "close_code.h"
1148 #endif /* SDL_events_h_ */
1150 /* vi: set ts=4 sw=4 expandtab: */