1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
4
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.
8
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:
12
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.
20*/
21
22/**
23 * # CategoryEvents
24 *
25 * Event queue management.
26 *
27 * It's extremely common--often required--that an app deal with SDL's event
28 * queue. Almost all useful information about interactions with the real world
29 * flow through here: the user interacting with the computer and app, hardware
30 * coming and going, the system changing in some way, etc.
31 *
32 * An app generally takes a moment, perhaps at the start of a new frame, to
33 * examine any events that have occured since the last time and process or
34 * ignore them. This is generally done by calling SDL_PollEvent() in a loop
35 * until it returns false (or, if using the main callbacks, events are
36 * provided one at a time in calls to SDL_AppEvent() before the next call to
37 * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent()
38 * at all).
39 *
40 * There is other forms of control, too: SDL_PeepEvents() has more
41 * functionality at the cost of more complexity, and SDL_WaitEvent() can block
42 * the process until something interesting happens, which might be beneficial
43 * for certain types of programs on low-power hardware. One may also call
44 * SDL_AddEventWatch() to set a callback when new events arrive.
45 *
46 * The app is free to generate their own events, too: SDL_PushEvent allows the
47 * app to put events onto the queue for later retrieval; SDL_RegisterEvents
48 * can guarantee that these events have a type that isn't in use by other
49 * parts of the system.
50 */
51
52#ifndef SDL_events_h_
53#define SDL_events_h_
54
55#include <SDL3/SDL_stdinc.h>
56#include <SDL3/SDL_audio.h>
57#include <SDL3/SDL_camera.h>
58#include <SDL3/SDL_error.h>
59#include <SDL3/SDL_gamepad.h>
60#include <SDL3/SDL_joystick.h>
61#include <SDL3/SDL_keyboard.h>
62#include <SDL3/SDL_keycode.h>
63#include <SDL3/SDL_mouse.h>
64#include <SDL3/SDL_pen.h>
65#include <SDL3/SDL_power.h>
66#include <SDL3/SDL_sensor.h>
67#include <SDL3/SDL_scancode.h>
68#include <SDL3/SDL_touch.h>
69#include <SDL3/SDL_video.h>
70
71#include <SDL3/SDL_begin_code.h>
72/* Set up for C function definitions, even when using C++ */
73#ifdef __cplusplus
74extern "C" {
75#endif
76
77/* General keyboard/mouse/pen state definitions */
78
79/**
80 * The types of events that can be delivered.
81 *
82 * \since This enum is available since SDL 3.2.0.
83 */
84typedef enum SDL_EventType
85{
86 SDL_EVENT_FIRST = 0, /**< Unused (do not remove) */
87
88 /* Application events */
89 SDL_EVENT_QUIT = 0x100, /**< User-requested quit */
90
91 /* These application events have special meaning on iOS and Android, see README-ios.md and README-android.md for details */
92 SDL_EVENT_TERMINATING, /**< The application is being terminated by the OS. This event must be handled in a callback set with SDL_AddEventWatch().
93 Called on iOS in applicationWillTerminate()
94 Called on Android in onDestroy()
95 */
96 SDL_EVENT_LOW_MEMORY, /**< The application is low on memory, free memory if possible. This event must be handled in a callback set with SDL_AddEventWatch().
97 Called on iOS in applicationDidReceiveMemoryWarning()
98 Called on Android in onTrimMemory()
99 */
100 SDL_EVENT_WILL_ENTER_BACKGROUND, /**< The application is about to enter the background. This event must be handled in a callback set with SDL_AddEventWatch().
101 Called on iOS in applicationWillResignActive()
102 Called on Android in onPause()
103 */
104 SDL_EVENT_DID_ENTER_BACKGROUND, /**< The application did enter the background and may not get CPU for some time. This event must be handled in a callback set with SDL_AddEventWatch().
105 Called on iOS in applicationDidEnterBackground()
106 Called on Android in onPause()
107 */
108 SDL_EVENT_WILL_ENTER_FOREGROUND, /**< The application is about to enter the foreground. This event must be handled in a callback set with SDL_AddEventWatch().
109 Called on iOS in applicationWillEnterForeground()
110 Called on Android in onResume()
111 */
112 SDL_EVENT_DID_ENTER_FOREGROUND, /**< The application is now interactive. This event must be handled in a callback set with SDL_AddEventWatch().
113 Called on iOS in applicationDidBecomeActive()
114 Called on Android in onResume()
115 */
116
117 SDL_EVENT_LOCALE_CHANGED, /**< The user's locale preferences have changed. */
118
119 SDL_EVENT_SYSTEM_THEME_CHANGED, /**< The system theme changed */
120
121 /* Display events */
122 /* 0x150 was SDL_DISPLAYEVENT, reserve the number for sdl2-compat */
123 SDL_EVENT_DISPLAY_ORIENTATION = 0x151, /**< Display orientation has changed to data1 */
124 SDL_EVENT_DISPLAY_ADDED, /**< Display has been added to the system */
125 SDL_EVENT_DISPLAY_REMOVED, /**< Display has been removed from the system */
126 SDL_EVENT_DISPLAY_MOVED, /**< Display has changed position */
127 SDL_EVENT_DISPLAY_DESKTOP_MODE_CHANGED, /**< Display has changed desktop mode */
128 SDL_EVENT_DISPLAY_CURRENT_MODE_CHANGED, /**< Display has changed current mode */
129 SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED, /**< Display has changed content scale */
130 SDL_EVENT_DISPLAY_FIRST = SDL_EVENT_DISPLAY_ORIENTATION,
131 SDL_EVENT_DISPLAY_LAST = SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED,
132
133 /* Window events */
134 /* 0x200 was SDL_WINDOWEVENT, reserve the number for sdl2-compat */
135 /* 0x201 was SDL_SYSWMEVENT, reserve the number for sdl2-compat */
136 SDL_EVENT_WINDOW_SHOWN = 0x202, /**< Window has been shown */
137 SDL_EVENT_WINDOW_HIDDEN, /**< Window has been hidden */
138 SDL_EVENT_WINDOW_EXPOSED, /**< Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event */
139 SDL_EVENT_WINDOW_MOVED, /**< Window has been moved to data1, data2 */
140 SDL_EVENT_WINDOW_RESIZED, /**< Window has been resized to data1xdata2 */
141 SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED,/**< The pixel size of the window has changed to data1xdata2 */
142 SDL_EVENT_WINDOW_METAL_VIEW_RESIZED,/**< The pixel size of a Metal view associated with the window has changed */
143 SDL_EVENT_WINDOW_MINIMIZED, /**< Window has been minimized */
144 SDL_EVENT_WINDOW_MAXIMIZED, /**< Window has been maximized */
145 SDL_EVENT_WINDOW_RESTORED, /**< Window has been restored to normal size and position */
146 SDL_EVENT_WINDOW_MOUSE_ENTER, /**< Window has gained mouse focus */
147 SDL_EVENT_WINDOW_MOUSE_LEAVE, /**< Window has lost mouse focus */
148 SDL_EVENT_WINDOW_FOCUS_GAINED, /**< Window has gained keyboard focus */
149 SDL_EVENT_WINDOW_FOCUS_LOST, /**< Window has lost keyboard focus */
150 SDL_EVENT_WINDOW_CLOSE_REQUESTED, /**< The window manager requests that the window be closed */
151 SDL_EVENT_WINDOW_HIT_TEST, /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL */
152 SDL_EVENT_WINDOW_ICCPROF_CHANGED, /**< The ICC profile of the window's display has changed */
153 SDL_EVENT_WINDOW_DISPLAY_CHANGED, /**< Window has been moved to display data1 */
154 SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED, /**< Window display scale has been changed */
155 SDL_EVENT_WINDOW_SAFE_AREA_CHANGED, /**< The window safe area has been changed */
156 SDL_EVENT_WINDOW_OCCLUDED, /**< The window has been occluded */
157 SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */
158 SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */
159 SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled
160 in an event watcher, the window handle is still valid and can still be used to retrieve any properties
161 associated with the window. Otherwise, the handle has already been destroyed and all resources
162 associated with it are invalid */
163 SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */
164 SDL_EVENT_WINDOW_FIRST = SDL_EVENT_WINDOW_SHOWN,
165 SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_HDR_STATE_CHANGED,
166
167 /* Keyboard events */
168 SDL_EVENT_KEY_DOWN = 0x300, /**< Key pressed */
169 SDL_EVENT_KEY_UP, /**< Key released */
170 SDL_EVENT_TEXT_EDITING, /**< Keyboard text editing (composition) */
171 SDL_EVENT_TEXT_INPUT, /**< Keyboard text input */
172 SDL_EVENT_KEYMAP_CHANGED, /**< Keymap changed due to a system event such as an
173 input language or keyboard layout change. */
174 SDL_EVENT_KEYBOARD_ADDED, /**< A new keyboard has been inserted into the system */
175 SDL_EVENT_KEYBOARD_REMOVED, /**< A keyboard has been removed */
176 SDL_EVENT_TEXT_EDITING_CANDIDATES, /**< Keyboard text editing candidates */
177
178 /* Mouse events */
179 SDL_EVENT_MOUSE_MOTION = 0x400, /**< Mouse moved */
180 SDL_EVENT_MOUSE_BUTTON_DOWN, /**< Mouse button pressed */
181 SDL_EVENT_MOUSE_BUTTON_UP, /**< Mouse button released */
182 SDL_EVENT_MOUSE_WHEEL, /**< Mouse wheel motion */
183 SDL_EVENT_MOUSE_ADDED, /**< A new mouse has been inserted into the system */
184 SDL_EVENT_MOUSE_REMOVED, /**< A mouse has been removed */
185
186 /* Joystick events */
187 SDL_EVENT_JOYSTICK_AXIS_MOTION = 0x600, /**< Joystick axis motion */
188 SDL_EVENT_JOYSTICK_BALL_MOTION, /**< Joystick trackball motion */
189 SDL_EVENT_JOYSTICK_HAT_MOTION, /**< Joystick hat position change */
190 SDL_EVENT_JOYSTICK_BUTTON_DOWN, /**< Joystick button pressed */
191 SDL_EVENT_JOYSTICK_BUTTON_UP, /**< Joystick button released */
192 SDL_EVENT_JOYSTICK_ADDED, /**< A new joystick has been inserted into the system */
193 SDL_EVENT_JOYSTICK_REMOVED, /**< An opened joystick has been removed */
194 SDL_EVENT_JOYSTICK_BATTERY_UPDATED, /**< Joystick battery level change */
195 SDL_EVENT_JOYSTICK_UPDATE_COMPLETE, /**< Joystick update is complete */
196
197 /* Gamepad events */
198 SDL_EVENT_GAMEPAD_AXIS_MOTION = 0x650, /**< Gamepad axis motion */
199 SDL_EVENT_GAMEPAD_BUTTON_DOWN, /**< Gamepad button pressed */
200 SDL_EVENT_GAMEPAD_BUTTON_UP, /**< Gamepad button released */
201 SDL_EVENT_GAMEPAD_ADDED, /**< A new gamepad has been inserted into the system */
202 SDL_EVENT_GAMEPAD_REMOVED, /**< A gamepad has been removed */
203 SDL_EVENT_GAMEPAD_REMAPPED, /**< The gamepad mapping was updated */
204 SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN, /**< Gamepad touchpad was touched */
205 SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION, /**< Gamepad touchpad finger was moved */
206 SDL_EVENT_GAMEPAD_TOUCHPAD_UP, /**< Gamepad touchpad finger was lifted */
207 SDL_EVENT_GAMEPAD_SENSOR_UPDATE, /**< Gamepad sensor was updated */
208 SDL_EVENT_GAMEPAD_UPDATE_COMPLETE, /**< Gamepad update is complete */
209 SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED, /**< Gamepad Steam handle has changed */
210
211 /* Touch events */
212 SDL_EVENT_FINGER_DOWN = 0x700,
213 SDL_EVENT_FINGER_UP,
214 SDL_EVENT_FINGER_MOTION,
215 SDL_EVENT_FINGER_CANCELED,
216
217 /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */
218
219 /* Clipboard events */
220 SDL_EVENT_CLIPBOARD_UPDATE = 0x900, /**< The clipboard or primary selection changed */
221
222 /* Drag and drop events */
223 SDL_EVENT_DROP_FILE = 0x1000, /**< The system requests a file open */
224 SDL_EVENT_DROP_TEXT, /**< text/plain drag-and-drop event */
225 SDL_EVENT_DROP_BEGIN, /**< A new set of drops is beginning (NULL filename) */
226 SDL_EVENT_DROP_COMPLETE, /**< Current set of drops is now complete (NULL filename) */
227 SDL_EVENT_DROP_POSITION, /**< Position while moving over the window */
228
229 /* Audio hotplug events */
230 SDL_EVENT_AUDIO_DEVICE_ADDED = 0x1100, /**< A new audio device is available */
231 SDL_EVENT_AUDIO_DEVICE_REMOVED, /**< An audio device has been removed. */
232 SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED, /**< An audio device's format has been changed by the system. */
233
234 /* Sensor events */
235 SDL_EVENT_SENSOR_UPDATE = 0x1200, /**< A sensor was updated */
236
237 /* Pressure-sensitive pen events */
238 SDL_EVENT_PEN_PROXIMITY_IN = 0x1300, /**< Pressure-sensitive pen has become available */
239 SDL_EVENT_PEN_PROXIMITY_OUT, /**< Pressure-sensitive pen has become unavailable */
240 SDL_EVENT_PEN_DOWN, /**< Pressure-sensitive pen touched drawing surface */
241 SDL_EVENT_PEN_UP, /**< Pressure-sensitive pen stopped touching drawing surface */
242 SDL_EVENT_PEN_BUTTON_DOWN, /**< Pressure-sensitive pen button pressed */
243 SDL_EVENT_PEN_BUTTON_UP, /**< Pressure-sensitive pen button released */
244 SDL_EVENT_PEN_MOTION, /**< Pressure-sensitive pen is moving on the tablet */
245 SDL_EVENT_PEN_AXIS, /**< Pressure-sensitive pen angle/pressure/etc changed */
246
247 /* Camera hotplug events */
248 SDL_EVENT_CAMERA_DEVICE_ADDED = 0x1400, /**< A new camera device is available */
249 SDL_EVENT_CAMERA_DEVICE_REMOVED, /**< A camera device has been removed. */
250 SDL_EVENT_CAMERA_DEVICE_APPROVED, /**< A camera device has been approved for use by the user. */
251 SDL_EVENT_CAMERA_DEVICE_DENIED, /**< A camera device has been denied for use by the user. */
252
253 /* Render events */
254 SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
255 SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
256 SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */
257
258 /* Reserved events for private platforms */
259 SDL_EVENT_PRIVATE0 = 0x4000,
260 SDL_EVENT_PRIVATE1,
261 SDL_EVENT_PRIVATE2,
262 SDL_EVENT_PRIVATE3,
263
264 /* Internal events */
265 SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
266
267 /** Events SDL_EVENT_USER through SDL_EVENT_LAST are for your use,
268 * and should be allocated with SDL_RegisterEvents()
269 */
270 SDL_EVENT_USER = 0x8000,
271
272 /**
273 * This last event is only for bounding internal arrays
274 */
275 SDL_EVENT_LAST = 0xFFFF,
276
277 /* This just makes sure the enum is the size of Uint32 */
278 SDL_EVENT_ENUM_PADDING = 0x7FFFFFFF
279
280} SDL_EventType;
281
282/**
283 * Fields shared by every event
284 *
285 * \since This struct is available since SDL 3.2.0.
286 */
287typedef struct SDL_CommonEvent
288{
289 Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */
290 Uint32 reserved;
291 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
292} SDL_CommonEvent;
293
294/**
295 * Display state change event data (event.display.*)
296 *
297 * \since This struct is available since SDL 3.2.0.
298 */
299typedef struct SDL_DisplayEvent
300{
301 SDL_EventType type; /**< SDL_DISPLAYEVENT_* */
302 Uint32 reserved;
303 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
304 SDL_DisplayID displayID;/**< The associated display */
305 Sint32 data1; /**< event dependent data */
306 Sint32 data2; /**< event dependent data */
307} SDL_DisplayEvent;
308
309/**
310 * Window state change event data (event.window.*)
311 *
312 * \since This struct is available since SDL 3.2.0.
313 */
314typedef struct SDL_WindowEvent
315{
316 SDL_EventType type; /**< SDL_EVENT_WINDOW_* */
317 Uint32 reserved;
318 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
319 SDL_WindowID windowID; /**< The associated window */
320 Sint32 data1; /**< event dependent data */
321 Sint32 data2; /**< event dependent data */
322} SDL_WindowEvent;
323
324/**
325 * Keyboard device event structure (event.kdevice.*)
326 *
327 * \since This struct is available since SDL 3.2.0.
328 */
329typedef struct SDL_KeyboardDeviceEvent
330{
331 SDL_EventType type; /**< SDL_EVENT_KEYBOARD_ADDED or SDL_EVENT_KEYBOARD_REMOVED */
332 Uint32 reserved;
333 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
334 SDL_KeyboardID which; /**< The keyboard instance id */
335} SDL_KeyboardDeviceEvent;
336
337/**
338 * Keyboard button event structure (event.key.*)
339 *
340 * The `key` is the base SDL_Keycode generated by pressing the `scancode`
341 * using the current keyboard layout, applying any options specified in
342 * SDL_HINT_KEYCODE_OPTIONS. You can get the SDL_Keycode corresponding to the
343 * event scancode and modifiers directly from the keyboard layout, bypassing
344 * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode().
345 *
346 * \since This struct is available since SDL 3.2.0.
347 *
348 * \sa SDL_GetKeyFromScancode
349 * \sa SDL_HINT_KEYCODE_OPTIONS
350 */
351typedef struct SDL_KeyboardEvent
352{
353 SDL_EventType type; /**< SDL_EVENT_KEY_DOWN or SDL_EVENT_KEY_UP */
354 Uint32 reserved;
355 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
356 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
357 SDL_KeyboardID which; /**< The keyboard instance id, or 0 if unknown or virtual */
358 SDL_Scancode scancode; /**< SDL physical key code */
359 SDL_Keycode key; /**< SDL virtual key code */
360 SDL_Keymod mod; /**< current key modifiers */
361 Uint16 raw; /**< The platform dependent scancode for this event */
362 bool down; /**< true if the key is pressed */
363 bool repeat; /**< true if this is a key repeat */
364} SDL_KeyboardEvent;
365
366/**
367 * Keyboard text editing event structure (event.edit.*)
368 *
369 * The start cursor is the position, in UTF-8 characters, where new typing
370 * will be inserted into the editing text. The length is the number of UTF-8
371 * characters that will be replaced by new typing.
372 *
373 * \since This struct is available since SDL 3.2.0.
374 */
375typedef struct SDL_TextEditingEvent
376{
377 SDL_EventType type; /**< SDL_EVENT_TEXT_EDITING */
378 Uint32 reserved;
379 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
380 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
381 const char *text; /**< The editing text */
382 Sint32 start; /**< The start cursor of selected editing text, or -1 if not set */
383 Sint32 length; /**< The length of selected editing text, or -1 if not set */
384} SDL_TextEditingEvent;
385
386/**
387 * Keyboard IME candidates event structure (event.edit_candidates.*)
388 *
389 * \since This struct is available since SDL 3.2.0.
390 */
391typedef struct SDL_TextEditingCandidatesEvent
392{
393 SDL_EventType type; /**< SDL_EVENT_TEXT_EDITING_CANDIDATES */
394 Uint32 reserved;
395 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
396 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
397 const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */
398 Sint32 num_candidates; /**< The number of strings in `candidates` */
399 Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */
400 bool horizontal; /**< true if the list is horizontal, false if it's vertical */
401 Uint8 padding1;
402 Uint8 padding2;
403 Uint8 padding3;
404} SDL_TextEditingCandidatesEvent;
405
406/**
407 * Keyboard text input event structure (event.text.*)
408 *
409 * This event will never be delivered unless text input is enabled by calling
410 * SDL_StartTextInput(). Text input is disabled by default!
411 *
412 * \since This struct is available since SDL 3.2.0.
413 *
414 * \sa SDL_StartTextInput
415 * \sa SDL_StopTextInput
416 */
417typedef struct SDL_TextInputEvent
418{
419 SDL_EventType type; /**< SDL_EVENT_TEXT_INPUT */
420 Uint32 reserved;
421 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
422 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
423 const char *text; /**< The input text, UTF-8 encoded */
424} SDL_TextInputEvent;
425
426/**
427 * Mouse device event structure (event.mdevice.*)
428 *
429 * \since This struct is available since SDL 3.2.0.
430 */
431typedef struct SDL_MouseDeviceEvent
432{
433 SDL_EventType type; /**< SDL_EVENT_MOUSE_ADDED or SDL_EVENT_MOUSE_REMOVED */
434 Uint32 reserved;
435 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
436 SDL_MouseID which; /**< The mouse instance id */
437} SDL_MouseDeviceEvent;
438
439/**
440 * Mouse motion event structure (event.motion.*)
441 *
442 * \since This struct is available since SDL 3.2.0.
443 */
444typedef struct SDL_MouseMotionEvent
445{
446 SDL_EventType type; /**< SDL_EVENT_MOUSE_MOTION */
447 Uint32 reserved;
448 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
449 SDL_WindowID windowID; /**< The window with mouse focus, if any */
450 SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */
451 SDL_MouseButtonFlags state; /**< The current button state */
452 float x; /**< X coordinate, relative to window */
453 float y; /**< Y coordinate, relative to window */
454 float xrel; /**< The relative motion in the X direction */
455 float yrel; /**< The relative motion in the Y direction */
456} SDL_MouseMotionEvent;
457
458/**
459 * Mouse button event structure (event.button.*)
460 *
461 * \since This struct is available since SDL 3.2.0.
462 */
463typedef struct SDL_MouseButtonEvent
464{
465 SDL_EventType type; /**< SDL_EVENT_MOUSE_BUTTON_DOWN or SDL_EVENT_MOUSE_BUTTON_UP */
466 Uint32 reserved;
467 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
468 SDL_WindowID windowID; /**< The window with mouse focus, if any */
469 SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */
470 Uint8 button; /**< The mouse button index */
471 bool down; /**< true if the button is pressed */
472 Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */
473 Uint8 padding;
474 float x; /**< X coordinate, relative to window */
475 float y; /**< Y coordinate, relative to window */
476} SDL_MouseButtonEvent;
477
478/**
479 * Mouse wheel event structure (event.wheel.*)
480 *
481 * \since This struct is available since SDL 3.2.0.
482 */
483typedef struct SDL_MouseWheelEvent
484{
485 SDL_EventType type; /**< SDL_EVENT_MOUSE_WHEEL */
486 Uint32 reserved;
487 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
488 SDL_WindowID windowID; /**< The window with mouse focus, if any */
489 SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */
490 float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */
491 float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */
492 SDL_MouseWheelDirection 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 */
493 float mouse_x; /**< X coordinate, relative to window */
494 float mouse_y; /**< Y coordinate, relative to window */
495} SDL_MouseWheelEvent;
496
497/**
498 * Joystick axis motion event structure (event.jaxis.*)
499 *
500 * \since This struct is available since SDL 3.2.0.
501 */
502typedef struct SDL_JoyAxisEvent
503{
504 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_AXIS_MOTION */
505 Uint32 reserved;
506 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
507 SDL_JoystickID which; /**< The joystick instance id */
508 Uint8 axis; /**< The joystick axis index */
509 Uint8 padding1;
510 Uint8 padding2;
511 Uint8 padding3;
512 Sint16 value; /**< The axis value (range: -32768 to 32767) */
513 Uint16 padding4;
514} SDL_JoyAxisEvent;
515
516/**
517 * Joystick trackball motion event structure (event.jball.*)
518 *
519 * \since This struct is available since SDL 3.2.0.
520 */
521typedef struct SDL_JoyBallEvent
522{
523 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BALL_MOTION */
524 Uint32 reserved;
525 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
526 SDL_JoystickID which; /**< The joystick instance id */
527 Uint8 ball; /**< The joystick trackball index */
528 Uint8 padding1;
529 Uint8 padding2;
530 Uint8 padding3;
531 Sint16 xrel; /**< The relative motion in the X direction */
532 Sint16 yrel; /**< The relative motion in the Y direction */
533} SDL_JoyBallEvent;
534
535/**
536 * Joystick hat position change event structure (event.jhat.*)
537 *
538 * \since This struct is available since SDL 3.2.0.
539 */
540typedef struct SDL_JoyHatEvent
541{
542 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_HAT_MOTION */
543 Uint32 reserved;
544 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
545 SDL_JoystickID which; /**< The joystick instance id */
546 Uint8 hat; /**< The joystick hat index */
547 Uint8 value; /**< The hat position value.
548 * \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP
549 * \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT
550 * \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN
551 *
552 * Note that zero means the POV is centered.
553 */
554 Uint8 padding1;
555 Uint8 padding2;
556} SDL_JoyHatEvent;
557
558/**
559 * Joystick button event structure (event.jbutton.*)
560 *
561 * \since This struct is available since SDL 3.2.0.
562 */
563typedef struct SDL_JoyButtonEvent
564{
565 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BUTTON_DOWN or SDL_EVENT_JOYSTICK_BUTTON_UP */
566 Uint32 reserved;
567 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
568 SDL_JoystickID which; /**< The joystick instance id */
569 Uint8 button; /**< The joystick button index */
570 bool down; /**< true if the button is pressed */
571 Uint8 padding1;
572 Uint8 padding2;
573} SDL_JoyButtonEvent;
574
575/**
576 * Joystick device event structure (event.jdevice.*)
577 *
578 * SDL will send JOYSTICK_ADDED events for devices that are already plugged in
579 * during SDL_Init.
580 *
581 * \since This struct is available since SDL 3.2.0.
582 *
583 * \sa SDL_GamepadDeviceEvent
584 */
585typedef struct SDL_JoyDeviceEvent
586{
587 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_ADDED or SDL_EVENT_JOYSTICK_REMOVED or SDL_EVENT_JOYSTICK_UPDATE_COMPLETE */
588 Uint32 reserved;
589 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
590 SDL_JoystickID which; /**< The joystick instance id */
591} SDL_JoyDeviceEvent;
592
593/**
594 * Joystick battery level change event structure (event.jbattery.*)
595 *
596 * \since This struct is available since SDL 3.2.0.
597 */
598typedef struct SDL_JoyBatteryEvent
599{
600 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BATTERY_UPDATED */
601 Uint32 reserved;
602 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
603 SDL_JoystickID which; /**< The joystick instance id */
604 SDL_PowerState state; /**< The joystick battery state */
605 int percent; /**< The joystick battery percent charge remaining */
606} SDL_JoyBatteryEvent;
607
608/**
609 * Gamepad axis motion event structure (event.gaxis.*)
610 *
611 * \since This struct is available since SDL 3.2.0.
612 */
613typedef struct SDL_GamepadAxisEvent
614{
615 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_AXIS_MOTION */
616 Uint32 reserved;
617 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
618 SDL_JoystickID which; /**< The joystick instance id */
619 Uint8 axis; /**< The gamepad axis (SDL_GamepadAxis) */
620 Uint8 padding1;
621 Uint8 padding2;
622 Uint8 padding3;
623 Sint16 value; /**< The axis value (range: -32768 to 32767) */
624 Uint16 padding4;
625} SDL_GamepadAxisEvent;
626
627
628/**
629 * Gamepad button event structure (event.gbutton.*)
630 *
631 * \since This struct is available since SDL 3.2.0.
632 */
633typedef struct SDL_GamepadButtonEvent
634{
635 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_BUTTON_DOWN or SDL_EVENT_GAMEPAD_BUTTON_UP */
636 Uint32 reserved;
637 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
638 SDL_JoystickID which; /**< The joystick instance id */
639 Uint8 button; /**< The gamepad button (SDL_GamepadButton) */
640 bool down; /**< true if the button is pressed */
641 Uint8 padding1;
642 Uint8 padding2;
643} SDL_GamepadButtonEvent;
644
645
646/**
647 * Gamepad device event structure (event.gdevice.*)
648 *
649 * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent
650 * and an SDL_GamepadDeviceEvent.
651 *
652 * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged
653 * in during SDL_Init() and are recognized as gamepads. It will also send
654 * events for joysticks that get gamepad mappings at runtime.
655 *
656 * \since This struct is available since SDL 3.2.0.
657 *
658 * \sa SDL_JoyDeviceEvent
659 */
660typedef struct SDL_GamepadDeviceEvent
661{
662 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_ADDED, SDL_EVENT_GAMEPAD_REMOVED, or SDL_EVENT_GAMEPAD_REMAPPED, SDL_EVENT_GAMEPAD_UPDATE_COMPLETE or SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED */
663 Uint32 reserved;
664 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
665 SDL_JoystickID which; /**< The joystick instance id */
666} SDL_GamepadDeviceEvent;
667
668/**
669 * Gamepad touchpad event structure (event.gtouchpad.*)
670 *
671 * \since This struct is available since SDL 3.2.0.
672 */
673typedef struct SDL_GamepadTouchpadEvent
674{
675 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN or SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION or SDL_EVENT_GAMEPAD_TOUCHPAD_UP */
676 Uint32 reserved;
677 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
678 SDL_JoystickID which; /**< The joystick instance id */
679 Sint32 touchpad; /**< The index of the touchpad */
680 Sint32 finger; /**< The index of the finger on the touchpad */
681 float x; /**< Normalized in the range 0...1 with 0 being on the left */
682 float y; /**< Normalized in the range 0...1 with 0 being at the top */
683 float pressure; /**< Normalized in the range 0...1 */
684} SDL_GamepadTouchpadEvent;
685
686/**
687 * Gamepad sensor event structure (event.gsensor.*)
688 *
689 * \since This struct is available since SDL 3.2.0.
690 */
691typedef struct SDL_GamepadSensorEvent
692{
693 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_SENSOR_UPDATE */
694 Uint32 reserved;
695 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
696 SDL_JoystickID which; /**< The joystick instance id */
697 Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */
698 float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
699 Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */
700} SDL_GamepadSensorEvent;
701
702/**
703 * Audio device event structure (event.adevice.*)
704 *
705 * \since This struct is available since SDL 3.2.0.
706 */
707typedef struct SDL_AudioDeviceEvent
708{
709 SDL_EventType type; /**< SDL_EVENT_AUDIO_DEVICE_ADDED, or SDL_EVENT_AUDIO_DEVICE_REMOVED, or SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED */
710 Uint32 reserved;
711 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
712 SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */
713 bool recording; /**< false if a playback device, true if a recording device. */
714 Uint8 padding1;
715 Uint8 padding2;
716 Uint8 padding3;
717} SDL_AudioDeviceEvent;
718
719/**
720 * Camera device event structure (event.cdevice.*)
721 *
722 * \since This struct is available since SDL 3.2.0.
723 */
724typedef struct SDL_CameraDeviceEvent
725{
726 SDL_EventType type; /**< SDL_EVENT_CAMERA_DEVICE_ADDED, SDL_EVENT_CAMERA_DEVICE_REMOVED, SDL_EVENT_CAMERA_DEVICE_APPROVED, SDL_EVENT_CAMERA_DEVICE_DENIED */
727 Uint32 reserved;
728 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
729 SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */
730} SDL_CameraDeviceEvent;
731
732
733/**
734 * Renderer event structure (event.render.*)
735 *
736 * \since This struct is available since SDL 3.2.0.
737 */
738typedef struct SDL_RenderEvent
739{
740 SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */
741 Uint32 reserved;
742 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
743 SDL_WindowID windowID; /**< The window containing the renderer in question. */
744} SDL_RenderEvent;
745
746
747/**
748 * Touch finger event structure (event.tfinger.*)
749 *
750 * Coordinates in this event are normalized. `x` and `y` are normalized to a
751 * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top
752 * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are
753 * normalized in the ranges of -1.0f (traversed all the way from the bottom or
754 * right to all the way up or left) to 1.0f (traversed all the way from the
755 * top or left to all the way down or right).
756 *
757 * Note that while the coordinates are _normalized_, they are not _clamped_,
758 * which means in some circumstances you can get a value outside of this
759 * range. For example, a renderer using logical presentation might give a
760 * negative value when the touch is in the letterboxing. Some platforms might
761 * report a touch outside of the window, which will also be outside of the
762 * range.
763 *
764 * \since This struct is available since SDL 3.2.0.
765 */
766typedef struct SDL_TouchFingerEvent
767{
768 SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */
769 Uint32 reserved;
770 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
771 SDL_TouchID touchID; /**< The touch device id */
772 SDL_FingerID fingerID;
773 float x; /**< Normalized in the range 0...1 */
774 float y; /**< Normalized in the range 0...1 */
775 float dx; /**< Normalized in the range -1...1 */
776 float dy; /**< Normalized in the range -1...1 */
777 float pressure; /**< Normalized in the range 0...1 */
778 SDL_WindowID windowID; /**< The window underneath the finger, if any */
779} SDL_TouchFingerEvent;
780
781/**
782 * Pressure-sensitive pen proximity event structure (event.pmotion.*)
783 *
784 * When a pen becomes visible to the system (it is close enough to a tablet,
785 * etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's
786 * ID. This ID is valid until the pen leaves proximity again (has been removed
787 * from the tablet's area, the tablet has been unplugged, etc). If the same
788 * pen reenters proximity again, it will be given a new ID.
789 *
790 * Note that "proximity" means "close enough for the tablet to know the tool
791 * is there." The pen touching and lifting off from the tablet while not
792 * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP.
793 *
794 * \since This struct is available since SDL 3.2.0.
795 */
796typedef struct SDL_PenProximityEvent
797{
798 SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */
799 Uint32 reserved;
800 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
801 SDL_WindowID windowID; /**< The window with pen focus, if any */
802 SDL_PenID which; /**< The pen instance id */
803} SDL_PenProximityEvent;
804
805/**
806 * Pressure-sensitive pen motion event structure (event.pmotion.*)
807 *
808 * Depending on the hardware, you may get motion events when the pen is not
809 * touching a tablet, for tracking a pen even when it isn't drawing. You
810 * should listen for SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP events, or check
811 * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when
812 * dealing with pen motion.
813 *
814 * \since This struct is available since SDL 3.2.0.
815 */
816typedef struct SDL_PenMotionEvent
817{
818 SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */
819 Uint32 reserved;
820 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
821 SDL_WindowID windowID; /**< The window with pen focus, if any */
822 SDL_PenID which; /**< The pen instance id */
823 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
824 float x; /**< X coordinate, relative to window */
825 float y; /**< Y coordinate, relative to window */
826} SDL_PenMotionEvent;
827
828/**
829 * Pressure-sensitive pen touched event structure (event.ptouch.*)
830 *
831 * These events come when a pen touches a surface (a tablet, etc), or lifts
832 * off from one.
833 *
834 * \since This struct is available since SDL 3.2.0.
835 */
836typedef struct SDL_PenTouchEvent
837{
838 SDL_EventType type; /**< SDL_EVENT_PEN_DOWN or SDL_EVENT_PEN_UP */
839 Uint32 reserved;
840 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
841 SDL_WindowID windowID; /**< The window with pen focus, if any */
842 SDL_PenID which; /**< The pen instance id */
843 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
844 float x; /**< X coordinate, relative to window */
845 float y; /**< Y coordinate, relative to window */
846 bool eraser; /**< true if eraser end is used (not all pens support this). */
847 bool down; /**< true if the pen is touching or false if the pen is lifted off */
848} SDL_PenTouchEvent;
849
850/**
851 * Pressure-sensitive pen button event structure (event.pbutton.*)
852 *
853 * This is for buttons on the pen itself that the user might click. The pen
854 * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead.
855 *
856 * \since This struct is available since SDL 3.2.0.
857 */
858typedef struct SDL_PenButtonEvent
859{
860 SDL_EventType type; /**< SDL_EVENT_PEN_BUTTON_DOWN or SDL_EVENT_PEN_BUTTON_UP */
861 Uint32 reserved;
862 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
863 SDL_WindowID windowID; /**< The window with mouse focus, if any */
864 SDL_PenID which; /**< The pen instance id */
865 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
866 float x; /**< X coordinate, relative to window */
867 float y; /**< Y coordinate, relative to window */
868 Uint8 button; /**< The pen button index (first button is 1). */
869 bool down; /**< true if the button is pressed */
870} SDL_PenButtonEvent;
871
872/**
873 * Pressure-sensitive pen pressure / angle event structure (event.paxis.*)
874 *
875 * You might get some of these events even if the pen isn't touching the
876 * tablet.
877 *
878 * \since This struct is available since SDL 3.2.0.
879 */
880typedef struct SDL_PenAxisEvent
881{
882 SDL_EventType type; /**< SDL_EVENT_PEN_AXIS */
883 Uint32 reserved;
884 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
885 SDL_WindowID windowID; /**< The window with pen focus, if any */
886 SDL_PenID which; /**< The pen instance id */
887 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
888 float x; /**< X coordinate, relative to window */
889 float y; /**< Y coordinate, relative to window */
890 SDL_PenAxis axis; /**< Axis that has changed */
891 float value; /**< New value of axis */
892} SDL_PenAxisEvent;
893
894/**
895 * An event used to drop text or request a file open by the system
896 * (event.drop.*)
897 *
898 * \since This struct is available since SDL 3.2.0.
899 */
900typedef struct SDL_DropEvent
901{
902 SDL_EventType type; /**< SDL_EVENT_DROP_BEGIN or SDL_EVENT_DROP_FILE or SDL_EVENT_DROP_TEXT or SDL_EVENT_DROP_COMPLETE or SDL_EVENT_DROP_POSITION */
903 Uint32 reserved;
904 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
905 SDL_WindowID windowID; /**< The window that was dropped on, if any */
906 float x; /**< X coordinate, relative to window (not on begin) */
907 float y; /**< Y coordinate, relative to window (not on begin) */
908 const char *source; /**< The source app that sent this drop event, or NULL if that isn't available */
909 const char *data; /**< The text for SDL_EVENT_DROP_TEXT and the file name for SDL_EVENT_DROP_FILE, NULL for other events */
910} SDL_DropEvent;
911
912/**
913 * An event triggered when the clipboard contents have changed
914 * (event.clipboard.*)
915 *
916 * \since This struct is available since SDL 3.2.0.
917 */
918typedef struct SDL_ClipboardEvent
919{
920 SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */
921 Uint32 reserved;
922 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
923 bool owner; /**< are we owning the clipboard (internal update) */
924 Sint32 num_mime_types; /**< number of mime types */
925 const char **mime_types; /**< current mime types */
926} SDL_ClipboardEvent;
927
928/**
929 * Sensor event structure (event.sensor.*)
930 *
931 * \since This struct is available since SDL 3.2.0.
932 */
933typedef struct SDL_SensorEvent
934{
935 SDL_EventType type; /**< SDL_EVENT_SENSOR_UPDATE */
936 Uint32 reserved;
937 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
938 SDL_SensorID which; /**< The instance ID of the sensor */
939 float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_GetSensorData() */
940 Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */
941} SDL_SensorEvent;
942
943/**
944 * The "quit requested" event
945 *
946 * \since This struct is available since SDL 3.2.0.
947 */
948typedef struct SDL_QuitEvent
949{
950 SDL_EventType type; /**< SDL_EVENT_QUIT */
951 Uint32 reserved;
952 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
953} SDL_QuitEvent;
954
955/**
956 * A user-defined event type (event.user.*)
957 *
958 * This event is unique; it is never created by SDL, but only by the
959 * application. The event can be pushed onto the event queue using
960 * SDL_PushEvent(). The contents of the structure members are completely up to
961 * the programmer; the only requirement is that '''type''' is a value obtained
962 * from SDL_RegisterEvents().
963 *
964 * \since This struct is available since SDL 3.2.0.
965 */
966typedef struct SDL_UserEvent
967{
968 Uint32 type; /**< SDL_EVENT_USER through SDL_EVENT_LAST-1, Uint32 because these are not in the SDL_EventType enumeration */
969 Uint32 reserved;
970 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
971 SDL_WindowID windowID; /**< The associated window if any */
972 Sint32 code; /**< User defined event code */
973 void *data1; /**< User defined data pointer */
974 void *data2; /**< User defined data pointer */
975} SDL_UserEvent;
976
977
978/**
979 * The structure for all events in SDL.
980 *
981 * The SDL_Event structure is the core of all event handling in SDL. SDL_Event
982 * is a union of all event structures used in SDL.
983 *
984 * \since This struct is available since SDL 3.2.0.
985 */
986typedef union SDL_Event
987{
988 Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */
989 SDL_CommonEvent common; /**< Common event data */
990 SDL_DisplayEvent display; /**< Display event data */
991 SDL_WindowEvent window; /**< Window event data */
992 SDL_KeyboardDeviceEvent kdevice; /**< Keyboard device change event data */
993 SDL_KeyboardEvent key; /**< Keyboard event data */
994 SDL_TextEditingEvent edit; /**< Text editing event data */
995 SDL_TextEditingCandidatesEvent edit_candidates; /**< Text editing candidates event data */
996 SDL_TextInputEvent text; /**< Text input event data */
997 SDL_MouseDeviceEvent mdevice; /**< Mouse device change event data */
998 SDL_MouseMotionEvent motion; /**< Mouse motion event data */
999 SDL_MouseButtonEvent button; /**< Mouse button event data */
1000 SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
1001 SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */
1002 SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */
1003 SDL_JoyBallEvent jball; /**< Joystick ball event data */
1004 SDL_JoyHatEvent jhat; /**< Joystick hat event data */
1005 SDL_JoyButtonEvent jbutton; /**< Joystick button event data */
1006 SDL_JoyBatteryEvent jbattery; /**< Joystick battery event data */
1007 SDL_GamepadDeviceEvent gdevice; /**< Gamepad device event data */
1008 SDL_GamepadAxisEvent gaxis; /**< Gamepad axis event data */
1009 SDL_GamepadButtonEvent gbutton; /**< Gamepad button event data */
1010 SDL_GamepadTouchpadEvent gtouchpad; /**< Gamepad touchpad event data */
1011 SDL_GamepadSensorEvent gsensor; /**< Gamepad sensor event data */
1012 SDL_AudioDeviceEvent adevice; /**< Audio device event data */
1013 SDL_CameraDeviceEvent cdevice; /**< Camera device event data */
1014 SDL_SensorEvent sensor; /**< Sensor event data */
1015 SDL_QuitEvent quit; /**< Quit request event data */
1016 SDL_UserEvent user; /**< Custom event data */
1017 SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
1018 SDL_PenProximityEvent pproximity; /**< Pen proximity event data */
1019 SDL_PenTouchEvent ptouch; /**< Pen tip touching event data */
1020 SDL_PenMotionEvent pmotion; /**< Pen motion event data */
1021 SDL_PenButtonEvent pbutton; /**< Pen button event data */
1022 SDL_PenAxisEvent paxis; /**< Pen axis event data */
1023 SDL_RenderEvent render; /**< Render event data */
1024 SDL_DropEvent drop; /**< Drag and drop event data */
1025 SDL_ClipboardEvent clipboard; /**< Clipboard event data */
1026
1027 /* This is necessary for ABI compatibility between Visual C++ and GCC.
1028 Visual C++ will respect the push pack pragma and use 52 bytes (size of
1029 SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
1030 architectures) for this union, and GCC will use the alignment of the
1031 largest datatype within the union, which is 8 bytes on 64-bit
1032 architectures.
1033
1034 So... we'll add padding to force the size to be the same for both.
1035
1036 On architectures where pointers are 16 bytes, this needs rounding up to
1037 the next multiple of 16, 64, and on architectures where pointers are
1038 even larger the size of SDL_UserEvent will dominate as being 3 pointers.
1039 */
1040 Uint8 padding[128];
1041} SDL_Event;
1042
1043/* Make sure we haven't broken binary compatibility */
1044SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
1045
1046
1047/* Function prototypes */
1048
1049/**
1050 * Pump the event loop, gathering events from the input devices.
1051 *
1052 * This function updates the event queue and internal input device state.
1053 *
1054 * SDL_PumpEvents() gathers all the pending input information from devices and
1055 * places it in the event queue. Without calls to SDL_PumpEvents() no events
1056 * would ever be placed on the queue. Often the need for calls to
1057 * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
1058 * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
1059 * polling or waiting for events (e.g. you are filtering them), then you must
1060 * call SDL_PumpEvents() to force an event queue update.
1061 *
1062 * \threadsafety This function should only be called on the main thread.
1063 *
1064 * \since This function is available since SDL 3.2.0.
1065 *
1066 * \sa SDL_PollEvent
1067 * \sa SDL_WaitEvent
1068 */
1069extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void);
1070
1071/* @{ */
1072
1073/**
1074 * The type of action to request from SDL_PeepEvents().
1075 *
1076 * \since This enum is available since SDL 3.2.0.
1077 */
1078typedef enum SDL_EventAction
1079{
1080 SDL_ADDEVENT, /**< Add events to the back of the queue. */
1081 SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */
1082 SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */
1083} SDL_EventAction;
1084
1085/**
1086 * Check the event queue for messages and optionally return them.
1087 *
1088 * `action` may be any of the following:
1089 *
1090 * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
1091 * event queue.
1092 * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
1093 * within the specified minimum and maximum type, will be returned to the
1094 * caller and will _not_ be removed from the queue. If you pass NULL for
1095 * `events`, then `numevents` is ignored and the total number of matching
1096 * events will be returned.
1097 * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
1098 * within the specified minimum and maximum type, will be returned to the
1099 * caller and will be removed from the queue.
1100 *
1101 * You may have to call SDL_PumpEvents() before calling this function.
1102 * Otherwise, the events may not be ready to be filtered when you call
1103 * SDL_PeepEvents().
1104 *
1105 * \param events destination buffer for the retrieved events, may be NULL to
1106 * leave the events in the queue and return the number of events
1107 * that would have been stored.
1108 * \param numevents if action is SDL_ADDEVENT, the number of events to add
1109 * back to the event queue; if action is SDL_PEEKEVENT or
1110 * SDL_GETEVENT, the maximum number of events to retrieve.
1111 * \param action action to take; see [Remarks](#remarks) for details.
1112 * \param minType minimum value of the event type to be considered;
1113 * SDL_EVENT_FIRST is a safe choice.
1114 * \param maxType maximum value of the event type to be considered;
1115 * SDL_EVENT_LAST is a safe choice.
1116 * \returns the number of events actually stored or -1 on failure; call
1117 * SDL_GetError() for more information.
1118 *
1119 * \threadsafety It is safe to call this function from any thread.
1120 *
1121 * \since This function is available since SDL 3.2.0.
1122 *
1123 * \sa SDL_PollEvent
1124 * \sa SDL_PumpEvents
1125 * \sa SDL_PushEvent
1126 */
1127extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, SDL_EventAction action, Uint32 minType, Uint32 maxType);
1128/* @} */
1129
1130/**
1131 * Check for the existence of a certain event type in the event queue.
1132 *
1133 * If you need to check for a range of event types, use SDL_HasEvents()
1134 * instead.
1135 *
1136 * \param type the type of event to be queried; see SDL_EventType for details.
1137 * \returns true if events matching `type` are present, or false if events
1138 * matching `type` are not present.
1139 *
1140 * \threadsafety It is safe to call this function from any thread.
1141 *
1142 * \since This function is available since SDL 3.2.0.
1143 *
1144 * \sa SDL_HasEvents
1145 */
1146extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type);
1147
1148
1149/**
1150 * Check for the existence of certain event types in the event queue.
1151 *
1152 * If you need to check for a single event type, use SDL_HasEvent() instead.
1153 *
1154 * \param minType the low end of event type to be queried, inclusive; see
1155 * SDL_EventType for details.
1156 * \param maxType the high end of event type to be queried, inclusive; see
1157 * SDL_EventType for details.
1158 * \returns true if events with type >= `minType` and <= `maxType` are
1159 * present, or false if not.
1160 *
1161 * \threadsafety It is safe to call this function from any thread.
1162 *
1163 * \since This function is available since SDL 3.2.0.
1164 *
1165 * \sa SDL_HasEvents
1166 */
1167extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
1168
1169/**
1170 * Clear events of a specific type from the event queue.
1171 *
1172 * This will unconditionally remove any events from the queue that match
1173 * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
1174 * instead.
1175 *
1176 * It's also normal to just ignore events you don't care about in your event
1177 * loop without calling this function.
1178 *
1179 * This function only affects currently queued events. If you want to make
1180 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
1181 * on the main thread immediately before the flush call.
1182 *
1183 * If you have user events with custom data that needs to be freed, you should
1184 * use SDL_PeepEvents() to remove and clean up those events before calling
1185 * this function.
1186 *
1187 * \param type the type of event to be cleared; see SDL_EventType for details.
1188 *
1189 * \threadsafety It is safe to call this function from any thread.
1190 *
1191 * \since This function is available since SDL 3.2.0.
1192 *
1193 * \sa SDL_FlushEvents
1194 */
1195extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
1196
1197/**
1198 * Clear events of a range of types from the event queue.
1199 *
1200 * This will unconditionally remove any events from the queue that are in the
1201 * range of `minType` to `maxType`, inclusive. If you need to remove a single
1202 * event type, use SDL_FlushEvent() instead.
1203 *
1204 * It's also normal to just ignore events you don't care about in your event
1205 * loop without calling this function.
1206 *
1207 * This function only affects currently queued events. If you want to make
1208 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
1209 * on the main thread immediately before the flush call.
1210 *
1211 * \param minType the low end of event type to be cleared, inclusive; see
1212 * SDL_EventType for details.
1213 * \param maxType the high end of event type to be cleared, inclusive; see
1214 * SDL_EventType for details.
1215 *
1216 * \threadsafety It is safe to call this function from any thread.
1217 *
1218 * \since This function is available since SDL 3.2.0.
1219 *
1220 * \sa SDL_FlushEvent
1221 */
1222extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
1223
1224/**
1225 * Poll for currently pending events.
1226 *
1227 * If `event` is not NULL, the next event is removed from the queue and stored
1228 * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
1229 * this event, immediately stored in the SDL Event structure -- not an event
1230 * to follow.
1231 *
1232 * If `event` is NULL, it simply returns 1 if there is an event in the queue,
1233 * but will not remove it from the queue.
1234 *
1235 * As this function may implicitly call SDL_PumpEvents(), you can only call
1236 * this function in the thread that set the video mode.
1237 *
1238 * SDL_PollEvent() is the favored way of receiving system events since it can
1239 * be done from the main loop and does not suspend the main loop while waiting
1240 * on an event to be posted.
1241 *
1242 * The common practice is to fully process the event queue once every frame,
1243 * usually as a first step before updating the game's state:
1244 *
1245 * ```c
1246 * while (game_is_still_running) {
1247 * SDL_Event event;
1248 * while (SDL_PollEvent(&event)) { // poll until all events are handled!
1249 * // decide what to do with this event.
1250 * }
1251 *
1252 * // update game state, draw the current frame
1253 * }
1254 * ```
1255 *
1256 * \param event the SDL_Event structure to be filled with the next event from
1257 * the queue, or NULL.
1258 * \returns true if this got an event or false if there are none available.
1259 *
1260 * \threadsafety This function should only be called on the main thread.
1261 *
1262 * \since This function is available since SDL 3.2.0.
1263 *
1264 * \sa SDL_PushEvent
1265 * \sa SDL_WaitEvent
1266 * \sa SDL_WaitEventTimeout
1267 */
1268extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event);
1269
1270/**
1271 * Wait indefinitely for the next available event.
1272 *
1273 * If `event` is not NULL, the next event is removed from the queue and stored
1274 * in the SDL_Event structure pointed to by `event`.
1275 *
1276 * As this function may implicitly call SDL_PumpEvents(), you can only call
1277 * this function in the thread that initialized the video subsystem.
1278 *
1279 * \param event the SDL_Event structure to be filled in with the next event
1280 * from the queue, or NULL.
1281 * \returns true on success or false if there was an error while waiting for
1282 * events; call SDL_GetError() for more information.
1283 *
1284 * \threadsafety This function should only be called on the main thread.
1285 *
1286 * \since This function is available since SDL 3.2.0.
1287 *
1288 * \sa SDL_PollEvent
1289 * \sa SDL_PushEvent
1290 * \sa SDL_WaitEventTimeout
1291 */
1292extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event);
1293
1294/**
1295 * Wait until the specified timeout (in milliseconds) for the next available
1296 * event.
1297 *
1298 * If `event` is not NULL, the next event is removed from the queue and stored
1299 * in the SDL_Event structure pointed to by `event`.
1300 *
1301 * As this function may implicitly call SDL_PumpEvents(), you can only call
1302 * this function in the thread that initialized the video subsystem.
1303 *
1304 * The timeout is not guaranteed, the actual wait time could be longer due to
1305 * system scheduling.
1306 *
1307 * \param event the SDL_Event structure to be filled in with the next event
1308 * from the queue, or NULL.
1309 * \param timeoutMS the maximum number of milliseconds to wait for the next
1310 * available event.
1311 * \returns true if this got an event or false if the timeout elapsed without
1312 * any events available.
1313 *
1314 * \threadsafety This function should only be called on the main thread.
1315 *
1316 * \since This function is available since SDL 3.2.0.
1317 *
1318 * \sa SDL_PollEvent
1319 * \sa SDL_PushEvent
1320 * \sa SDL_WaitEvent
1321 */
1322extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS);
1323
1324/**
1325 * Add an event to the event queue.
1326 *
1327 * The event queue can actually be used as a two way communication channel.
1328 * Not only can events be read from the queue, but the user can also push
1329 * their own events onto it. `event` is a pointer to the event structure you
1330 * wish to push onto the queue. The event is copied into the queue, and the
1331 * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
1332 *
1333 * Note: Pushing device input events onto the queue doesn't modify the state
1334 * of the device within SDL.
1335 *
1336 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
1337 * the event filter but events added with SDL_PeepEvents() do not.
1338 *
1339 * For pushing application-specific events, please use SDL_RegisterEvents() to
1340 * get an event type that does not conflict with other code that also wants
1341 * its own custom event types.
1342 *
1343 * \param event the SDL_Event to be added to the queue.
1344 * \returns true on success, false if the event was filtered or on failure;
1345 * call SDL_GetError() for more information. A common reason for
1346 * error is the event queue being full.
1347 *
1348 * \threadsafety It is safe to call this function from any thread.
1349 *
1350 * \since This function is available since SDL 3.2.0.
1351 *
1352 * \sa SDL_PeepEvents
1353 * \sa SDL_PollEvent
1354 * \sa SDL_RegisterEvents
1355 */
1356extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event);
1357
1358/**
1359 * A function pointer used for callbacks that watch the event queue.
1360 *
1361 * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
1362 * SDL_AddEventWatch, etc.
1363 * \param event the event that triggered the callback.
1364 * \returns true to permit event to be added to the queue, and false to
1365 * disallow it. When used with SDL_AddEventWatch, the return value is
1366 * ignored.
1367 *
1368 * \threadsafety SDL may call this callback at any time from any thread; the
1369 * application is responsible for locking resources the callback
1370 * touches that need to be protected.
1371 *
1372 * \since This datatype is available since SDL 3.2.0.
1373 *
1374 * \sa SDL_SetEventFilter
1375 * \sa SDL_AddEventWatch
1376 */
1377typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
1378
1379/**
1380 * Set up a filter to process all events before they are added to the internal
1381 * event queue.
1382 *
1383 * If you just want to see events without modifying them or preventing them
1384 * from being queued, you should use SDL_AddEventWatch() instead.
1385 *
1386 * If the filter function returns true when called, then the event will be
1387 * added to the internal queue. If it returns false, then the event will be
1388 * dropped from the queue, but the internal state will still be updated. This
1389 * allows selective filtering of dynamically arriving events.
1390 *
1391 * **WARNING**: Be very careful of what you do in the event filter function,
1392 * as it may run in a different thread!
1393 *
1394 * On platforms that support it, if the quit event is generated by an
1395 * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
1396 * application at the next event poll.
1397 *
1398 * Note: Disabled events never make it to the event filter function; see
1399 * SDL_SetEventEnabled().
1400 *
1401 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
1402 * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
1403 * not.
1404 *
1405 * \param filter an SDL_EventFilter function to call when an event happens.
1406 * \param userdata a pointer that is passed to `filter`.
1407 *
1408 * \threadsafety It is safe to call this function from any thread.
1409 *
1410 * \since This function is available since SDL 3.2.0.
1411 *
1412 * \sa SDL_AddEventWatch
1413 * \sa SDL_SetEventEnabled
1414 * \sa SDL_GetEventFilter
1415 * \sa SDL_PeepEvents
1416 * \sa SDL_PushEvent
1417 */
1418extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void *userdata);
1419
1420/**
1421 * Query the current event filter.
1422 *
1423 * This function can be used to "chain" filters, by saving the existing filter
1424 * before replacing it with a function that will call that saved filter.
1425 *
1426 * \param filter the current callback function will be stored here.
1427 * \param userdata the pointer that is passed to the current event filter will
1428 * be stored here.
1429 * \returns true on success or false if there is no event filter set.
1430 *
1431 * \threadsafety It is safe to call this function from any thread.
1432 *
1433 * \since This function is available since SDL 3.2.0.
1434 *
1435 * \sa SDL_SetEventFilter
1436 */
1437extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata);
1438
1439/**
1440 * Add a callback to be triggered when an event is added to the event queue.
1441 *
1442 * `filter` will be called when an event happens, and its return value is
1443 * ignored.
1444 *
1445 * **WARNING**: Be very careful of what you do in the event filter function,
1446 * as it may run in a different thread!
1447 *
1448 * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
1449 * the internal queue and be delivered to the watch callback immediately, and
1450 * arrive at the next event poll.
1451 *
1452 * Note: the callback is called for events posted by the user through
1453 * SDL_PushEvent(), but not for disabled events, nor for events by a filter
1454 * callback set with SDL_SetEventFilter(), nor for events posted by the user
1455 * through SDL_PeepEvents().
1456 *
1457 * \param filter an SDL_EventFilter function to call when an event happens.
1458 * \param userdata a pointer that is passed to `filter`.
1459 * \returns true on success or false on failure; call SDL_GetError() for more
1460 * information.
1461 *
1462 * \threadsafety It is safe to call this function from any thread.
1463 *
1464 * \since This function is available since SDL 3.2.0.
1465 *
1466 * \sa SDL_RemoveEventWatch
1467 * \sa SDL_SetEventFilter
1468 */
1469extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata);
1470
1471/**
1472 * Remove an event watch callback added with SDL_AddEventWatch().
1473 *
1474 * This function takes the same input as SDL_AddEventWatch() to identify and
1475 * delete the corresponding callback.
1476 *
1477 * \param filter the function originally passed to SDL_AddEventWatch().
1478 * \param userdata the pointer originally passed to SDL_AddEventWatch().
1479 *
1480 * \threadsafety It is safe to call this function from any thread.
1481 *
1482 * \since This function is available since SDL 3.2.0.
1483 *
1484 * \sa SDL_AddEventWatch
1485 */
1486extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, void *userdata);
1487
1488/**
1489 * Run a specific filter function on the current event queue, removing any
1490 * events for which the filter returns false.
1491 *
1492 * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
1493 * this function does not change the filter permanently, it only uses the
1494 * supplied filter until this function returns.
1495 *
1496 * \param filter the SDL_EventFilter function to call when an event happens.
1497 * \param userdata a pointer that is passed to `filter`.
1498 *
1499 * \threadsafety It is safe to call this function from any thread.
1500 *
1501 * \since This function is available since SDL 3.2.0.
1502 *
1503 * \sa SDL_GetEventFilter
1504 * \sa SDL_SetEventFilter
1505 */
1506extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *userdata);
1507
1508/**
1509 * Set the state of processing events by type.
1510 *
1511 * \param type the type of event; see SDL_EventType for details.
1512 * \param enabled whether to process the event or not.
1513 *
1514 * \threadsafety It is safe to call this function from any thread.
1515 *
1516 * \since This function is available since SDL 3.2.0.
1517 *
1518 * \sa SDL_EventEnabled
1519 */
1520extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled);
1521
1522/**
1523 * Query the state of processing events by type.
1524 *
1525 * \param type the type of event; see SDL_EventType for details.
1526 * \returns true if the event is being processed, false otherwise.
1527 *
1528 * \threadsafety It is safe to call this function from any thread.
1529 *
1530 * \since This function is available since SDL 3.2.0.
1531 *
1532 * \sa SDL_SetEventEnabled
1533 */
1534extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type);
1535
1536/**
1537 * Allocate a set of user-defined events, and return the beginning event
1538 * number for that set of events.
1539 *
1540 * \param numevents the number of events to be allocated.
1541 * \returns the beginning event number, or 0 if numevents is invalid or if
1542 * there are not enough user-defined events left.
1543 *
1544 * \threadsafety It is safe to call this function from any thread.
1545 *
1546 * \since This function is available since SDL 3.2.0.
1547 *
1548 * \sa SDL_PushEvent
1549 */
1550extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
1551
1552/**
1553 * Get window associated with an event.
1554 *
1555 * \param event an event containing a `windowID`.
1556 * \returns the associated window on success or NULL if there is none.
1557 *
1558 * \threadsafety It is safe to call this function from any thread.
1559 *
1560 * \since This function is available since SDL 3.2.0.
1561 *
1562 * \sa SDL_PollEvent
1563 * \sa SDL_WaitEvent
1564 * \sa SDL_WaitEventTimeout
1565 */
1566extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromEvent(const SDL_Event *event);
1567
1568/* Ends C function definitions when using C++ */
1569#ifdef __cplusplus
1570}
1571#endif
1572#include <SDL3/SDL_close_code.h>
1573
1574#endif /* SDL_events_h_ */
1575