1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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 * \file SDL_events.h
24 *
25 * Include file for SDL event handling.
26 */
27
28#ifndef SDL_events_h_
29#define SDL_events_h_
30
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"
38#include "SDL_quit.h"
39#include "SDL_gesture.h"
40#include "SDL_touch.h"
41
42#include "begin_code.h"
43/* Set up for C function definitions, even when using C++ */
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/* General keyboard/mouse state definitions */
49#define SDL_RELEASED 0
50#define SDL_PRESSED 1
51
52/**
53 * The types of events that can be delivered.
54 */
55typedef enum
56{
57 SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */
58
59 /* Application events */
60 SDL_QUIT = 0x100, /**< User-requested quit */
61
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()
66 */
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()
70 */
71 SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background
72 Called on iOS in applicationWillResignActive()
73 Called on Android in onPause()
74 */
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()
78 */
79 SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground
80 Called on iOS in applicationWillEnterForeground()
81 Called on Android in onResume()
82 */
83 SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive
84 Called on iOS in applicationDidBecomeActive()
85 Called on Android in onResume()
86 */
87
88 SDL_LOCALECHANGED, /**< The user's locale preferences have changed. */
89
90 /* Display events */
91 SDL_DISPLAYEVENT = 0x150, /**< Display state change */
92
93 /* Window events */
94 SDL_WINDOWEVENT = 0x200, /**< Window state change */
95 SDL_SYSWMEVENT, /**< System specific event */
96
97 /* Keyboard events */
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.
104 */
105 SDL_TEXTEDITING_EXT, /**< Extended keyboard text editing (composition) */
106
107 /* Mouse events */
108 SDL_MOUSEMOTION = 0x400, /**< Mouse moved */
109 SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */
110 SDL_MOUSEBUTTONUP, /**< Mouse button released */
111 SDL_MOUSEWHEEL, /**< Mouse wheel motion */
112
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 */
121 SDL_JOYBATTERYUPDATED, /**< Joystick battery level change */
122
123 /* Game controller events */
124 SDL_CONTROLLERAXISMOTION = 0x650, /**< Game controller axis motion */
125 SDL_CONTROLLERBUTTONDOWN, /**< Game controller button pressed */
126 SDL_CONTROLLERBUTTONUP, /**< Game controller button released */
127 SDL_CONTROLLERDEVICEADDED, /**< A new Game controller has been inserted into the system */
128 SDL_CONTROLLERDEVICEREMOVED, /**< An opened Game controller has been removed */
129 SDL_CONTROLLERDEVICEREMAPPED, /**< The controller mapping was updated */
130 SDL_CONTROLLERTOUCHPADDOWN, /**< Game controller touchpad was touched */
131 SDL_CONTROLLERTOUCHPADMOTION, /**< Game controller touchpad finger was moved */
132 SDL_CONTROLLERTOUCHPADUP, /**< Game controller touchpad finger was lifted */
133 SDL_CONTROLLERSENSORUPDATE, /**< Game controller sensor was updated */
134 SDL_CONTROLLERUPDATECOMPLETE_RESERVED_FOR_SDL3,
135 SDL_CONTROLLERSTEAMHANDLEUPDATED, /**< Game controller Steam handle has changed */
136
137 /* Touch events */
138 SDL_FINGERDOWN = 0x700,
139 SDL_FINGERUP,
140 SDL_FINGERMOTION,
141
142 /* Gesture events */
143 SDL_DOLLARGESTURE = 0x800,
144 SDL_DOLLARRECORD,
145 SDL_MULTIGESTURE,
146
147 /* Clipboard events */
148 SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard or primary selection changed */
149
150 /* Drag and drop events */
151 SDL_DROPFILE = 0x1000, /**< The system requests a file open */
152 SDL_DROPTEXT, /**< text/plain drag-and-drop event */
153 SDL_DROPBEGIN, /**< A new set of drops is beginning (NULL filename) */
154 SDL_DROPCOMPLETE, /**< Current set of drops is now complete (NULL filename) */
155
156 /* Audio hotplug events */
157 SDL_AUDIODEVICEADDED = 0x1100, /**< A new audio device is available */
158 SDL_AUDIODEVICEREMOVED, /**< An audio device has been removed. */
159
160 /* Sensor events */
161 SDL_SENSORUPDATE = 0x1200, /**< A sensor was updated */
162
163 /* Render events */
164 SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
165 SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
166
167 /* Internal events */
168 SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
169
170 /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
171 * and should be allocated with SDL_RegisterEvents()
172 */
173 SDL_USEREVENT = 0x8000,
174
175 /**
176 * This last event is only for bounding internal arrays
177 */
178 SDL_LASTEVENT = 0xFFFF
179} SDL_EventType;
180
181/**
182 * \brief Fields shared by every event
183 */
184typedef struct SDL_CommonEvent
185{
186 Uint32 type;
187 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
188} SDL_CommonEvent;
189
190/**
191 * \brief Display state change event data (event.display.*)
192 */
193typedef struct SDL_DisplayEvent
194{
195 Uint32 type; /**< ::SDL_DISPLAYEVENT */
196 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
197 Uint32 display; /**< The associated display index */
198 Uint8 event; /**< ::SDL_DisplayEventID */
199 Uint8 padding1;
200 Uint8 padding2;
201 Uint8 padding3;
202 Sint32 data1; /**< event dependent data */
203} SDL_DisplayEvent;
204
205/**
206 * \brief Window state change event data (event.window.*)
207 */
208typedef struct SDL_WindowEvent
209{
210 Uint32 type; /**< ::SDL_WINDOWEVENT */
211 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
212 Uint32 windowID; /**< The associated window */
213 Uint8 event; /**< ::SDL_WindowEventID */
214 Uint8 padding1;
215 Uint8 padding2;
216 Uint8 padding3;
217 Sint32 data1; /**< event dependent data */
218 Sint32 data2; /**< event dependent data */
219} SDL_WindowEvent;
220
221/**
222 * \brief Keyboard button event structure (event.key.*)
223 */
224typedef struct SDL_KeyboardEvent
225{
226 Uint32 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
227 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
228 Uint32 windowID; /**< The window with keyboard focus, if any */
229 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
230 Uint8 repeat; /**< Non-zero if this is a key repeat */
231 Uint8 padding2;
232 Uint8 padding3;
233 SDL_Keysym keysym; /**< The key that was pressed or released */
234} SDL_KeyboardEvent;
235
236#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
237/**
238 * \brief Keyboard text editing event structure (event.edit.*)
239 */
240typedef struct SDL_TextEditingEvent
241{
242 Uint32 type; /**< ::SDL_TEXTEDITING */
243 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
244 Uint32 windowID; /**< The window with keyboard focus, if any */
245 char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */
246 Sint32 start; /**< The start cursor of selected editing text */
247 Sint32 length; /**< The length of selected editing text */
248} SDL_TextEditingEvent;
249
250/**
251 * \brief Extended keyboard text editing event structure (event.editExt.*) when text would be
252 * truncated if stored in the text buffer SDL_TextEditingEvent
253 */
254typedef struct SDL_TextEditingExtEvent
255{
256 Uint32 type; /**< ::SDL_TEXTEDITING_EXT */
257 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
258 Uint32 windowID; /**< The window with keyboard focus, if any */
259 char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */
260 Sint32 start; /**< The start cursor of selected editing text */
261 Sint32 length; /**< The length of selected editing text */
262} SDL_TextEditingExtEvent;
263
264#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
265/**
266 * \brief Keyboard text input event structure (event.text.*)
267 */
268typedef struct SDL_TextInputEvent
269{
270 Uint32 type; /**< ::SDL_TEXTINPUT */
271 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
272 Uint32 windowID; /**< The window with keyboard focus, if any */
273 char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */
274} SDL_TextInputEvent;
275
276/**
277 * \brief Mouse motion event structure (event.motion.*)
278 */
279typedef struct SDL_MouseMotionEvent
280{
281 Uint32 type; /**< ::SDL_MOUSEMOTION */
282 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
283 Uint32 windowID; /**< The window with mouse focus, if any */
284 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
285 Uint32 state; /**< The current button state */
286 Sint32 x; /**< X coordinate, relative to window */
287 Sint32 y; /**< Y coordinate, relative to window */
288 Sint32 xrel; /**< The relative motion in the X direction */
289 Sint32 yrel; /**< The relative motion in the Y direction */
290} SDL_MouseMotionEvent;
291
292/**
293 * \brief Mouse button event structure (event.button.*)
294 */
295typedef struct SDL_MouseButtonEvent
296{
297 Uint32 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
298 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
299 Uint32 windowID; /**< The window with mouse focus, if any */
300 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
301 Uint8 button; /**< The mouse button index */
302 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
303 Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */
304 Uint8 padding1;
305 Sint32 x; /**< X coordinate, relative to window */
306 Sint32 y; /**< Y coordinate, relative to window */
307} SDL_MouseButtonEvent;
308
309/**
310 * \brief Mouse wheel event structure (event.wheel.*)
311 */
312typedef struct SDL_MouseWheelEvent
313{
314 Uint32 type; /**< ::SDL_MOUSEWHEEL */
315 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
316 Uint32 windowID; /**< The window with mouse focus, if any */
317 Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
318 Sint32 x; /**< The amount scrolled horizontally, positive to the right and negative to the left */
319 Sint32 y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */
320 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 */
321 float preciseX; /**< The amount scrolled horizontally, positive to the right and negative to the left, with float precision (added in 2.0.18) */
322 float preciseY; /**< The amount scrolled vertically, positive away from the user and negative toward the user, with float precision (added in 2.0.18) */
323 Sint32 mouseX; /**< X coordinate, relative to window (added in 2.26.0) */
324 Sint32 mouseY; /**< Y coordinate, relative to window (added in 2.26.0) */
325} SDL_MouseWheelEvent;
326
327/**
328 * \brief Joystick axis motion event structure (event.jaxis.*)
329 */
330typedef struct SDL_JoyAxisEvent
331{
332 Uint32 type; /**< ::SDL_JOYAXISMOTION */
333 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
334 SDL_JoystickID which; /**< The joystick instance id */
335 Uint8 axis; /**< The joystick axis index */
336 Uint8 padding1;
337 Uint8 padding2;
338 Uint8 padding3;
339 Sint16 value; /**< The axis value (range: -32768 to 32767) */
340 Uint16 padding4;
341} SDL_JoyAxisEvent;
342
343/**
344 * \brief Joystick trackball motion event structure (event.jball.*)
345 */
346typedef struct SDL_JoyBallEvent
347{
348 Uint32 type; /**< ::SDL_JOYBALLMOTION */
349 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
350 SDL_JoystickID which; /**< The joystick instance id */
351 Uint8 ball; /**< The joystick trackball index */
352 Uint8 padding1;
353 Uint8 padding2;
354 Uint8 padding3;
355 Sint16 xrel; /**< The relative motion in the X direction */
356 Sint16 yrel; /**< The relative motion in the Y direction */
357} SDL_JoyBallEvent;
358
359/**
360 * \brief Joystick hat position change event structure (event.jhat.*)
361 */
362typedef struct SDL_JoyHatEvent
363{
364 Uint32 type; /**< ::SDL_JOYHATMOTION */
365 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
366 SDL_JoystickID which; /**< The joystick instance id */
367 Uint8 hat; /**< The joystick hat index */
368 Uint8 value; /**< The hat position value.
369 * \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
370 * \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
371 * \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
372 *
373 * Note that zero means the POV is centered.
374 */
375 Uint8 padding1;
376 Uint8 padding2;
377} SDL_JoyHatEvent;
378
379/**
380 * \brief Joystick button event structure (event.jbutton.*)
381 */
382typedef struct SDL_JoyButtonEvent
383{
384 Uint32 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
385 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
386 SDL_JoystickID which; /**< The joystick instance id */
387 Uint8 button; /**< The joystick button index */
388 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
389 Uint8 padding1;
390 Uint8 padding2;
391} SDL_JoyButtonEvent;
392
393/**
394 * \brief Joystick device event structure (event.jdevice.*)
395 */
396typedef struct SDL_JoyDeviceEvent
397{
398 Uint32 type; /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
399 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
400 Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
401} SDL_JoyDeviceEvent;
402
403/**
404 * \brief Joysick battery level change event structure (event.jbattery.*)
405 */
406typedef struct SDL_JoyBatteryEvent
407{
408 Uint32 type; /**< ::SDL_JOYBATTERYUPDATED */
409 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
410 SDL_JoystickID which; /**< The joystick instance id */
411 SDL_JoystickPowerLevel level; /**< The joystick battery level */
412} SDL_JoyBatteryEvent;
413
414/**
415 * \brief Game controller axis motion event structure (event.caxis.*)
416 */
417typedef struct SDL_ControllerAxisEvent
418{
419 Uint32 type; /**< ::SDL_CONTROLLERAXISMOTION */
420 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
421 SDL_JoystickID which; /**< The joystick instance id */
422 Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */
423 Uint8 padding1;
424 Uint8 padding2;
425 Uint8 padding3;
426 Sint16 value; /**< The axis value (range: -32768 to 32767) */
427 Uint16 padding4;
428} SDL_ControllerAxisEvent;
429
430
431/**
432 * \brief Game controller button event structure (event.cbutton.*)
433 */
434typedef struct SDL_ControllerButtonEvent
435{
436 Uint32 type; /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
437 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
438 SDL_JoystickID which; /**< The joystick instance id */
439 Uint8 button; /**< The controller button (SDL_GameControllerButton) */
440 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
441 Uint8 padding1;
442 Uint8 padding2;
443} SDL_ControllerButtonEvent;
444
445
446/**
447 * \brief Controller device event structure (event.cdevice.*)
448 */
449typedef struct SDL_ControllerDeviceEvent
450{
451 Uint32 type; /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, ::SDL_CONTROLLERDEVICEREMAPPED, or ::SDL_CONTROLLERSTEAMHANDLEUPDATED */
452 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
453 Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
454} SDL_ControllerDeviceEvent;
455
456/**
457 * \brief Game controller touchpad event structure (event.ctouchpad.*)
458 */
459typedef struct SDL_ControllerTouchpadEvent
460{
461 Uint32 type; /**< ::SDL_CONTROLLERTOUCHPADDOWN or ::SDL_CONTROLLERTOUCHPADMOTION or ::SDL_CONTROLLERTOUCHPADUP */
462 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
463 SDL_JoystickID which; /**< The joystick instance id */
464 Sint32 touchpad; /**< The index of the touchpad */
465 Sint32 finger; /**< The index of the finger on the touchpad */
466 float x; /**< Normalized in the range 0...1 with 0 being on the left */
467 float y; /**< Normalized in the range 0...1 with 0 being at the top */
468 float pressure; /**< Normalized in the range 0...1 */
469} SDL_ControllerTouchpadEvent;
470
471/**
472 * \brief Game controller sensor event structure (event.csensor.*)
473 */
474typedef struct SDL_ControllerSensorEvent
475{
476 Uint32 type; /**< ::SDL_CONTROLLERSENSORUPDATE */
477 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
478 SDL_JoystickID which; /**< The joystick instance id */
479 Sint32 sensor; /**< The type of the sensor, one of the values of ::SDL_SensorType */
480 float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
481 Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
482} SDL_ControllerSensorEvent;
483
484/**
485 * \brief Audio device event structure (event.adevice.*)
486 */
487typedef struct SDL_AudioDeviceEvent
488{
489 Uint32 type; /**< ::SDL_AUDIODEVICEADDED, or ::SDL_AUDIODEVICEREMOVED */
490 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
491 Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */
492 Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */
493 Uint8 padding1;
494 Uint8 padding2;
495 Uint8 padding3;
496} SDL_AudioDeviceEvent;
497
498
499/**
500 * \brief Touch finger event structure (event.tfinger.*)
501 */
502typedef struct SDL_TouchFingerEvent
503{
504 Uint32 type; /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */
505 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
506 SDL_TouchID touchId; /**< The touch device id */
507 SDL_FingerID fingerId;
508 float x; /**< Normalized in the range 0...1 */
509 float y; /**< Normalized in the range 0...1 */
510 float dx; /**< Normalized in the range -1...1 */
511 float dy; /**< Normalized in the range -1...1 */
512 float pressure; /**< Normalized in the range 0...1 */
513 Uint32 windowID; /**< The window underneath the finger, if any */
514} SDL_TouchFingerEvent;
515
516
517/**
518 * \brief Multiple Finger Gesture Event (event.mgesture.*)
519 */
520typedef struct SDL_MultiGestureEvent
521{
522 Uint32 type; /**< ::SDL_MULTIGESTURE */
523 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
524 SDL_TouchID touchId; /**< The touch device id */
525 float dTheta;
526 float dDist;
527 float x;
528 float y;
529 Uint16 numFingers;
530 Uint16 padding;
531} SDL_MultiGestureEvent;
532
533
534/**
535 * \brief Dollar Gesture Event (event.dgesture.*)
536 */
537typedef struct SDL_DollarGestureEvent
538{
539 Uint32 type; /**< ::SDL_DOLLARGESTURE or ::SDL_DOLLARRECORD */
540 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
541 SDL_TouchID touchId; /**< The touch device id */
542 SDL_GestureID gestureId;
543 Uint32 numFingers;
544 float error;
545 float x; /**< Normalized center of gesture */
546 float y; /**< Normalized center of gesture */
547} SDL_DollarGestureEvent;
548
549
550/**
551 * \brief An event used to request a file open by the system (event.drop.*)
552 * This event is enabled by default, you can disable it with SDL_EventState().
553 * \note If this event is enabled, you must free the filename in the event.
554 */
555typedef struct SDL_DropEvent
556{
557 Uint32 type; /**< ::SDL_DROPBEGIN or ::SDL_DROPFILE or ::SDL_DROPTEXT or ::SDL_DROPCOMPLETE */
558 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
559 char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */
560 Uint32 windowID; /**< The window that was dropped on, if any */
561} SDL_DropEvent;
562
563
564/**
565 * \brief Sensor event structure (event.sensor.*)
566 */
567typedef struct SDL_SensorEvent
568{
569 Uint32 type; /**< ::SDL_SENSORUPDATE */
570 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
571 Sint32 which; /**< The instance ID of the sensor */
572 float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */
573 Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
574} SDL_SensorEvent;
575
576/**
577 * \brief The "quit requested" event
578 */
579typedef struct SDL_QuitEvent
580{
581 Uint32 type; /**< ::SDL_QUIT */
582 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
583} SDL_QuitEvent;
584
585/**
586 * \brief A user-defined event type (event.user.*)
587 */
588typedef struct SDL_UserEvent
589{
590 Uint32 type; /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */
591 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
592 Uint32 windowID; /**< The associated window if any */
593 Sint32 code; /**< User defined event code */
594 void *data1; /**< User defined data pointer */
595 void *data2; /**< User defined data pointer */
596} SDL_UserEvent;
597
598
599struct SDL_SysWMmsg;
600typedef struct SDL_SysWMmsg SDL_SysWMmsg;
601
602/**
603 * \brief A video driver dependent system event (event.syswm.*)
604 * This event is disabled by default, you can enable it with SDL_EventState()
605 *
606 * \note If you want to use this event, you should include SDL_syswm.h.
607 */
608typedef struct SDL_SysWMEvent
609{
610 Uint32 type; /**< ::SDL_SYSWMEVENT */
611 Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
612 SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
613} SDL_SysWMEvent;
614
615/**
616 * \brief General event structure
617 */
618typedef union SDL_Event
619{
620 Uint32 type; /**< Event type, shared with all events */
621 SDL_CommonEvent common; /**< Common event data */
622 SDL_DisplayEvent display; /**< Display event data */
623 SDL_WindowEvent window; /**< Window event data */
624 SDL_KeyboardEvent key; /**< Keyboard event data */
625 SDL_TextEditingEvent edit; /**< Text editing event data */
626 SDL_TextEditingExtEvent editExt; /**< Extended text editing event data */
627 SDL_TextInputEvent text; /**< Text input event data */
628 SDL_MouseMotionEvent motion; /**< Mouse motion event data */
629 SDL_MouseButtonEvent button; /**< Mouse button event data */
630 SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
631 SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */
632 SDL_JoyBallEvent jball; /**< Joystick ball event data */
633 SDL_JoyHatEvent jhat; /**< Joystick hat event data */
634 SDL_JoyButtonEvent jbutton; /**< Joystick button event data */
635 SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */
636 SDL_JoyBatteryEvent jbattery; /**< Joystick battery event data */
637 SDL_ControllerAxisEvent caxis; /**< Game Controller axis event data */
638 SDL_ControllerButtonEvent cbutton; /**< Game Controller button event data */
639 SDL_ControllerDeviceEvent cdevice; /**< Game Controller device event data */
640 SDL_ControllerTouchpadEvent ctouchpad; /**< Game Controller touchpad event data */
641 SDL_ControllerSensorEvent csensor; /**< Game Controller sensor event data */
642 SDL_AudioDeviceEvent adevice; /**< Audio device event data */
643 SDL_SensorEvent sensor; /**< Sensor event data */
644 SDL_QuitEvent quit; /**< Quit request event data */
645 SDL_UserEvent user; /**< Custom event data */
646 SDL_SysWMEvent syswm; /**< System dependent window event data */
647 SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
648 SDL_MultiGestureEvent mgesture; /**< Gesture event data */
649 SDL_DollarGestureEvent dgesture; /**< Gesture event data */
650 SDL_DropEvent drop; /**< Drag and drop event data */
651
652 /* This is necessary for ABI compatibility between Visual C++ and GCC.
653 Visual C++ will respect the push pack pragma and use 52 bytes (size of
654 SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
655 architectures) for this union, and GCC will use the alignment of the
656 largest datatype within the union, which is 8 bytes on 64-bit
657 architectures.
658
659 So... we'll add padding to force the size to be 56 bytes for both.
660
661 On architectures where pointers are 16 bytes, this needs rounding up to
662 the next multiple of 16, 64, and on architectures where pointers are
663 even larger the size of SDL_UserEvent will dominate as being 3 pointers.
664 */
665 Uint8 padding[sizeof(void *) <= 8 ? 56 : sizeof(void *) == 16 ? 64 : 3 * sizeof(void *)];
666} SDL_Event;
667
668/* Make sure we haven't broken binary compatibility */
669SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
670
671
672/* Function prototypes */
673
674/**
675 * Pump the event loop, gathering events from the input devices.
676 *
677 * This function updates the event queue and internal input device state.
678 *
679 * **WARNING**: This should only be run in the thread that initialized the
680 * video subsystem, and for extra safety, you should consider only doing those
681 * things on the main thread in any case.
682 *
683 * SDL_PumpEvents() gathers all the pending input information from devices and
684 * places it in the event queue. Without calls to SDL_PumpEvents() no events
685 * would ever be placed on the queue. Often the need for calls to
686 * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
687 * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
688 * polling or waiting for events (e.g. you are filtering them), then you must
689 * call SDL_PumpEvents() to force an event queue update.
690 *
691 * \since This function is available since SDL 2.0.0.
692 *
693 * \sa SDL_PollEvent
694 * \sa SDL_WaitEvent
695 */
696extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
697
698/* @{ */
699typedef enum
700{
701 SDL_ADDEVENT,
702 SDL_PEEKEVENT,
703 SDL_GETEVENT
704} SDL_eventaction;
705
706/**
707 * Check the event queue for messages and optionally return them.
708 *
709 * `action` may be any of the following:
710 *
711 * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
712 * event queue.
713 * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
714 * within the specified minimum and maximum type, will be returned to the
715 * caller and will _not_ be removed from the queue.
716 * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
717 * within the specified minimum and maximum type, will be returned to the
718 * caller and will be removed from the queue.
719 *
720 * You may have to call SDL_PumpEvents() before calling this function.
721 * Otherwise, the events may not be ready to be filtered when you call
722 * SDL_PeepEvents().
723 *
724 * This function is thread-safe.
725 *
726 * \param events destination buffer for the retrieved events
727 * \param numevents if action is SDL_ADDEVENT, the number of events to add
728 * back to the event queue; if action is SDL_PEEKEVENT or
729 * SDL_GETEVENT, the maximum number of events to retrieve
730 * \param action action to take; see [[#action|Remarks]] for details
731 * \param minType minimum value of the event type to be considered;
732 * SDL_FIRSTEVENT is a safe choice
733 * \param maxType maximum value of the event type to be considered;
734 * SDL_LASTEVENT is a safe choice
735 * \returns the number of events actually stored or a negative error code on
736 * failure; call SDL_GetError() for more information.
737 *
738 * \since This function is available since SDL 2.0.0.
739 *
740 * \sa SDL_PollEvent
741 * \sa SDL_PumpEvents
742 * \sa SDL_PushEvent
743 */
744extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
745 SDL_eventaction action,
746 Uint32 minType, Uint32 maxType);
747/* @} */
748
749/**
750 * Check for the existence of a certain event type in the event queue.
751 *
752 * If you need to check for a range of event types, use SDL_HasEvents()
753 * instead.
754 *
755 * \param type the type of event to be queried; see SDL_EventType for details
756 * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
757 * events matching `type` are not present.
758 *
759 * \since This function is available since SDL 2.0.0.
760 *
761 * \sa SDL_HasEvents
762 */
763extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
764
765
766/**
767 * Check for the existence of certain event types in the event queue.
768 *
769 * If you need to check for a single event type, use SDL_HasEvent() instead.
770 *
771 * \param minType the low end of event type to be queried, inclusive; see
772 * SDL_EventType for details
773 * \param maxType the high end of event type to be queried, inclusive; see
774 * SDL_EventType for details
775 * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
776 * present, or SDL_FALSE if not.
777 *
778 * \since This function is available since SDL 2.0.0.
779 *
780 * \sa SDL_HasEvents
781 */
782extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
783
784/**
785 * Clear events of a specific type from the event queue.
786 *
787 * This will unconditionally remove any events from the queue that match
788 * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
789 * instead.
790 *
791 * It's also normal to just ignore events you don't care about in your event
792 * loop without calling this function.
793 *
794 * This function only affects currently queued events. If you want to make
795 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
796 * on the main thread immediately before the flush call.
797 *
798 * \param type the type of event to be cleared; see SDL_EventType for details
799 *
800 * \since This function is available since SDL 2.0.0.
801 *
802 * \sa SDL_FlushEvents
803 */
804extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
805
806/**
807 * Clear events of a range of types from the event queue.
808 *
809 * This will unconditionally remove any events from the queue that are in the
810 * range of `minType` to `maxType`, inclusive. If you need to remove a single
811 * event type, use SDL_FlushEvent() instead.
812 *
813 * It's also normal to just ignore events you don't care about in your event
814 * loop without calling this function.
815 *
816 * This function only affects currently queued events. If you want to make
817 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
818 * on the main thread immediately before the flush call.
819 *
820 * \param minType the low end of event type to be cleared, inclusive; see
821 * SDL_EventType for details
822 * \param maxType the high end of event type to be cleared, inclusive; see
823 * SDL_EventType for details
824 *
825 * \since This function is available since SDL 2.0.0.
826 *
827 * \sa SDL_FlushEvent
828 */
829extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
830
831/**
832 * Poll for currently pending events.
833 *
834 * If `event` is not NULL, the next event is removed from the queue and stored
835 * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
836 * this event, immediately stored in the SDL Event structure -- not an event
837 * to follow.
838 *
839 * If `event` is NULL, it simply returns 1 if there is an event in the queue,
840 * but will not remove it from the queue.
841 *
842 * As this function may implicitly call SDL_PumpEvents(), you can only call
843 * this function in the thread that set the video mode.
844 *
845 * SDL_PollEvent() is the favored way of receiving system events since it can
846 * be done from the main loop and does not suspend the main loop while waiting
847 * on an event to be posted.
848 *
849 * The common practice is to fully process the event queue once every frame,
850 * usually as a first step before updating the game's state:
851 *
852 * ```c
853 * while (game_is_still_running) {
854 * SDL_Event event;
855 * while (SDL_PollEvent(&event)) { // poll until all events are handled!
856 * // decide what to do with this event.
857 * }
858 *
859 * // update game state, draw the current frame
860 * }
861 * ```
862 *
863 * \param event the SDL_Event structure to be filled with the next event from
864 * the queue, or NULL
865 * \returns 1 if there is a pending event or 0 if there are none available.
866 *
867 * \since This function is available since SDL 2.0.0.
868 *
869 * \sa SDL_GetEventFilter
870 * \sa SDL_PeepEvents
871 * \sa SDL_PushEvent
872 * \sa SDL_SetEventFilter
873 * \sa SDL_WaitEvent
874 * \sa SDL_WaitEventTimeout
875 */
876extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
877
878/**
879 * Wait indefinitely for the next available event.
880 *
881 * If `event` is not NULL, the next event is removed from the queue and stored
882 * in the SDL_Event structure pointed to by `event`.
883 *
884 * As this function may implicitly call SDL_PumpEvents(), you can only call
885 * this function in the thread that initialized the video subsystem.
886 *
887 * \param event the SDL_Event structure to be filled in with the next event
888 * from the queue, or NULL
889 * \returns 1 on success or 0 if there was an error while waiting for events;
890 * call SDL_GetError() for more information.
891 *
892 * \since This function is available since SDL 2.0.0.
893 *
894 * \sa SDL_PollEvent
895 * \sa SDL_PumpEvents
896 * \sa SDL_WaitEventTimeout
897 */
898extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
899
900/**
901 * Wait until the specified timeout (in milliseconds) for the next available
902 * event.
903 *
904 * If `event` is not NULL, the next event is removed from the queue and stored
905 * in the SDL_Event structure pointed to by `event`.
906 *
907 * As this function may implicitly call SDL_PumpEvents(), you can only call
908 * this function in the thread that initialized the video subsystem.
909 *
910 * \param event the SDL_Event structure to be filled in with the next event
911 * from the queue, or NULL
912 * \param timeout the maximum number of milliseconds to wait for the next
913 * available event
914 * \returns 1 on success or 0 if there was an error while waiting for events;
915 * call SDL_GetError() for more information. This also returns 0 if
916 * the timeout elapsed without an event arriving.
917 *
918 * \since This function is available since SDL 2.0.0.
919 *
920 * \sa SDL_PollEvent
921 * \sa SDL_PumpEvents
922 * \sa SDL_WaitEvent
923 */
924extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
925 int timeout);
926
927/**
928 * Add an event to the event queue.
929 *
930 * The event queue can actually be used as a two way communication channel.
931 * Not only can events be read from the queue, but the user can also push
932 * their own events onto it. `event` is a pointer to the event structure you
933 * wish to push onto the queue. The event is copied into the queue, and the
934 * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
935 *
936 * Note: Pushing device input events onto the queue doesn't modify the state
937 * of the device within SDL.
938 *
939 * This function is thread-safe, and can be called from other threads safely.
940 *
941 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
942 * the event filter but events added with SDL_PeepEvents() do not.
943 *
944 * For pushing application-specific events, please use SDL_RegisterEvents() to
945 * get an event type that does not conflict with other code that also wants
946 * its own custom event types.
947 *
948 * \param event the SDL_Event to be added to the queue
949 * \returns 1 on success, 0 if the event was filtered, or a negative error
950 * code on failure; call SDL_GetError() for more information. A
951 * common reason for error is the event queue being full.
952 *
953 * \since This function is available since SDL 2.0.0.
954 *
955 * \sa SDL_PeepEvents
956 * \sa SDL_PollEvent
957 * \sa SDL_RegisterEvents
958 */
959extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
960
961/**
962 * A function pointer used for callbacks that watch the event queue.
963 *
964 * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
965 * or SDL_AddEventWatch, etc
966 * \param event the event that triggered the callback
967 * \returns 1 to permit event to be added to the queue, and 0 to disallow
968 * it. When used with SDL_AddEventWatch, the return value is ignored.
969 *
970 * \sa SDL_SetEventFilter
971 * \sa SDL_AddEventWatch
972 */
973typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
974
975/**
976 * Set up a filter to process all events before they change internal state and
977 * are posted to the internal event queue.
978 *
979 * If the filter function returns 1 when called, then the event will be added
980 * to the internal queue. If it returns 0, then the event will be dropped from
981 * the queue, but the internal state will still be updated. This allows
982 * selective filtering of dynamically arriving events.
983 *
984 * **WARNING**: Be very careful of what you do in the event filter function,
985 * as it may run in a different thread!
986 *
987 * On platforms that support it, if the quit event is generated by an
988 * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
989 * application at the next event poll.
990 *
991 * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
992 * event filter is only called when the window manager desires to close the
993 * application window. If the event filter returns 1, then the window will be
994 * closed, otherwise the window will remain open if possible.
995 *
996 * Note: Disabled events never make it to the event filter function; see
997 * SDL_EventState().
998 *
999 * Note: If you just want to inspect events without filtering, you should use
1000 * SDL_AddEventWatch() instead.
1001 *
1002 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
1003 * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
1004 * not.
1005 *
1006 * \param filter An SDL_EventFilter function to call when an event happens
1007 * \param userdata a pointer that is passed to `filter`
1008 *
1009 * \since This function is available since SDL 2.0.0.
1010 *
1011 * \sa SDL_AddEventWatch
1012 * \sa SDL_EventState
1013 * \sa SDL_GetEventFilter
1014 * \sa SDL_PeepEvents
1015 * \sa SDL_PushEvent
1016 */
1017extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
1018 void *userdata);
1019
1020/**
1021 * Query the current event filter.
1022 *
1023 * This function can be used to "chain" filters, by saving the existing filter
1024 * before replacing it with a function that will call that saved filter.
1025 *
1026 * \param filter the current callback function will be stored here
1027 * \param userdata the pointer that is passed to the current event filter will
1028 * be stored here
1029 * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
1030 *
1031 * \since This function is available since SDL 2.0.0.
1032 *
1033 * \sa SDL_SetEventFilter
1034 */
1035extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
1036 void **userdata);
1037
1038/**
1039 * Add a callback to be triggered when an event is added to the event queue.
1040 *
1041 * `filter` will be called when an event happens, and its return value is
1042 * ignored.
1043 *
1044 * **WARNING**: Be very careful of what you do in the event filter function,
1045 * as it may run in a different thread!
1046 *
1047 * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
1048 * the internal queue and be delivered to the watch callback immediately, and
1049 * arrive at the next event poll.
1050 *
1051 * Note: the callback is called for events posted by the user through
1052 * SDL_PushEvent(), but not for disabled events, nor for events by a filter
1053 * callback set with SDL_SetEventFilter(), nor for events posted by the user
1054 * through SDL_PeepEvents().
1055 *
1056 * \param filter an SDL_EventFilter function to call when an event happens.
1057 * \param userdata a pointer that is passed to `filter`
1058 *
1059 * \since This function is available since SDL 2.0.0.
1060 *
1061 * \sa SDL_DelEventWatch
1062 * \sa SDL_SetEventFilter
1063 */
1064extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
1065 void *userdata);
1066
1067/**
1068 * Remove an event watch callback added with SDL_AddEventWatch().
1069 *
1070 * This function takes the same input as SDL_AddEventWatch() to identify and
1071 * delete the corresponding callback.
1072 *
1073 * \param filter the function originally passed to SDL_AddEventWatch()
1074 * \param userdata the pointer originally passed to SDL_AddEventWatch()
1075 *
1076 * \since This function is available since SDL 2.0.0.
1077 *
1078 * \sa SDL_AddEventWatch
1079 */
1080extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
1081 void *userdata);
1082
1083/**
1084 * Run a specific filter function on the current event queue, removing any
1085 * events for which the filter returns 0.
1086 *
1087 * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
1088 * this function does not change the filter permanently, it only uses the
1089 * supplied filter until this function returns.
1090 *
1091 * \param filter the SDL_EventFilter function to call when an event happens
1092 * \param userdata a pointer that is passed to `filter`
1093 *
1094 * \since This function is available since SDL 2.0.0.
1095 *
1096 * \sa SDL_GetEventFilter
1097 * \sa SDL_SetEventFilter
1098 */
1099extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
1100 void *userdata);
1101
1102/* @{ */
1103#define SDL_QUERY -1
1104#define SDL_IGNORE 0
1105#define SDL_DISABLE 0
1106#define SDL_ENABLE 1
1107
1108/**
1109 * Set the state of processing events by type.
1110 *
1111 * `state` may be any of the following:
1112 *
1113 * - `SDL_QUERY`: returns the current processing state of the specified event
1114 * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
1115 * from the event queue and will not be filtered
1116 * - `SDL_ENABLE`: the event will be processed normally
1117 *
1118 * \param type the type of event; see SDL_EventType for details
1119 * \param state how to process the event
1120 * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
1121 * of the event before this function makes any changes to it.
1122 *
1123 * \since This function is available since SDL 2.0.0.
1124 *
1125 * \sa SDL_GetEventState
1126 */
1127extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
1128/* @} */
1129#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
1130
1131/**
1132 * Allocate a set of user-defined events, and return the beginning event
1133 * number for that set of events.
1134 *
1135 * Calling this function with `numevents` <= 0 is an error and will return
1136 * (Uint32)-1.
1137 *
1138 * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
1139 * 0xFFFFFFFF), but is clearer to write.
1140 *
1141 * \param numevents the number of events to be allocated
1142 * \returns the beginning event number, or (Uint32)-1 if there are not enough
1143 * user-defined events left.
1144 *
1145 * \since This function is available since SDL 2.0.0.
1146 *
1147 * \sa SDL_PushEvent
1148 */
1149extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
1150
1151/* Ends C function definitions when using C++ */
1152#ifdef __cplusplus
1153}
1154#endif
1155#include "close_code.h"
1156
1157#endif /* SDL_events_h_ */
1158
1159/* vi: set ts=4 sw=4 expandtab: */
1160