packages/sdl2.nuget.2.0.22/build/native/include/SDL_events.h

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