include/SDL_events.h
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Mon, 11 Aug 2014 22:53:03 +0200
changeset 9049 411e05b86ac3
parent 9002 c1bd00f50724
child 9257 6f41196c2d6b
permissions -rw-r--r--
Updated README name in header.
     1 /*
     2   Simple DirectMedia Layer
     3   Copyright (C) 1997-2014 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  * \brief 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     /* Window events */
    89     SDL_WINDOWEVENT    = 0x200, /**< Window state change */
    90     SDL_SYSWMEVENT,             /**< System specific event */
    91 
    92     /* Keyboard events */
    93     SDL_KEYDOWN        = 0x300, /**< Key pressed */
    94     SDL_KEYUP,                  /**< Key released */
    95     SDL_TEXTEDITING,            /**< Keyboard text editing (composition) */
    96     SDL_TEXTINPUT,              /**< Keyboard text input */
    97 
    98     /* Mouse events */
    99     SDL_MOUSEMOTION    = 0x400, /**< Mouse moved */
   100     SDL_MOUSEBUTTONDOWN,        /**< Mouse button pressed */
   101     SDL_MOUSEBUTTONUP,          /**< Mouse button released */
   102     SDL_MOUSEWHEEL,             /**< Mouse wheel motion */
   103 
   104     /* Joystick events */
   105     SDL_JOYAXISMOTION  = 0x600, /**< Joystick axis motion */
   106     SDL_JOYBALLMOTION,          /**< Joystick trackball motion */
   107     SDL_JOYHATMOTION,           /**< Joystick hat position change */
   108     SDL_JOYBUTTONDOWN,          /**< Joystick button pressed */
   109     SDL_JOYBUTTONUP,            /**< Joystick button released */
   110     SDL_JOYDEVICEADDED,         /**< A new joystick has been inserted into the system */
   111     SDL_JOYDEVICEREMOVED,       /**< An opened joystick has been removed */
   112 
   113     /* Game controller events */
   114     SDL_CONTROLLERAXISMOTION  = 0x650, /**< Game controller axis motion */
   115     SDL_CONTROLLERBUTTONDOWN,          /**< Game controller button pressed */
   116     SDL_CONTROLLERBUTTONUP,            /**< Game controller button released */
   117     SDL_CONTROLLERDEVICEADDED,         /**< A new Game controller has been inserted into the system */
   118     SDL_CONTROLLERDEVICEREMOVED,       /**< An opened Game controller has been removed */
   119     SDL_CONTROLLERDEVICEREMAPPED,      /**< The controller mapping was updated */
   120 
   121     /* Touch events */
   122     SDL_FINGERDOWN      = 0x700,
   123     SDL_FINGERUP,
   124     SDL_FINGERMOTION,
   125 
   126     /* Gesture events */
   127     SDL_DOLLARGESTURE   = 0x800,
   128     SDL_DOLLARRECORD,
   129     SDL_MULTIGESTURE,
   130 
   131     /* Clipboard events */
   132     SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard changed */
   133 
   134     /* Drag and drop events */
   135     SDL_DROPFILE        = 0x1000, /**< The system requests a file open */
   136 
   137     /* Render events */
   138     SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
   139     SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
   140 
   141     /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
   142      *  and should be allocated with SDL_RegisterEvents()
   143      */
   144     SDL_USEREVENT    = 0x8000,
   145 
   146     /**
   147      *  This last event is only for bounding internal arrays
   148      */
   149     SDL_LASTEVENT    = 0xFFFF
   150 } SDL_EventType;
   151 
   152 /**
   153  *  \brief Fields shared by every event
   154  */
   155 typedef struct SDL_CommonEvent
   156 {
   157     Uint32 type;
   158     Uint32 timestamp;
   159 } SDL_CommonEvent;
   160 
   161 /**
   162  *  \brief Window state change event data (event.window.*)
   163  */
   164 typedef struct SDL_WindowEvent
   165 {
   166     Uint32 type;        /**< ::SDL_WINDOWEVENT */
   167     Uint32 timestamp;
   168     Uint32 windowID;    /**< The associated window */
   169     Uint8 event;        /**< ::SDL_WindowEventID */
   170     Uint8 padding1;
   171     Uint8 padding2;
   172     Uint8 padding3;
   173     Sint32 data1;       /**< event dependent data */
   174     Sint32 data2;       /**< event dependent data */
   175 } SDL_WindowEvent;
   176 
   177 /**
   178  *  \brief Keyboard button event structure (event.key.*)
   179  */
   180 typedef struct SDL_KeyboardEvent
   181 {
   182     Uint32 type;        /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
   183     Uint32 timestamp;
   184     Uint32 windowID;    /**< The window with keyboard focus, if any */
   185     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   186     Uint8 repeat;       /**< Non-zero if this is a key repeat */
   187     Uint8 padding2;
   188     Uint8 padding3;
   189     SDL_Keysym keysym;  /**< The key that was pressed or released */
   190 } SDL_KeyboardEvent;
   191 
   192 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
   193 /**
   194  *  \brief Keyboard text editing event structure (event.edit.*)
   195  */
   196 typedef struct SDL_TextEditingEvent
   197 {
   198     Uint32 type;                                /**< ::SDL_TEXTEDITING */
   199     Uint32 timestamp;
   200     Uint32 windowID;                            /**< The window with keyboard focus, if any */
   201     char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
   202     Sint32 start;                               /**< The start cursor of selected editing text */
   203     Sint32 length;                              /**< The length of selected editing text */
   204 } SDL_TextEditingEvent;
   205 
   206 
   207 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
   208 /**
   209  *  \brief Keyboard text input event structure (event.text.*)
   210  */
   211 typedef struct SDL_TextInputEvent
   212 {
   213     Uint32 type;                              /**< ::SDL_TEXTINPUT */
   214     Uint32 timestamp;
   215     Uint32 windowID;                          /**< The window with keyboard focus, if any */
   216     char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
   217 } SDL_TextInputEvent;
   218 
   219 /**
   220  *  \brief Mouse motion event structure (event.motion.*)
   221  */
   222 typedef struct SDL_MouseMotionEvent
   223 {
   224     Uint32 type;        /**< ::SDL_MOUSEMOTION */
   225     Uint32 timestamp;
   226     Uint32 windowID;    /**< The window with mouse focus, if any */
   227     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
   228     Uint32 state;       /**< The current button state */
   229     Sint32 x;           /**< X coordinate, relative to window */
   230     Sint32 y;           /**< Y coordinate, relative to window */
   231     Sint32 xrel;        /**< The relative motion in the X direction */
   232     Sint32 yrel;        /**< The relative motion in the Y direction */
   233 } SDL_MouseMotionEvent;
   234 
   235 /**
   236  *  \brief Mouse button event structure (event.button.*)
   237  */
   238 typedef struct SDL_MouseButtonEvent
   239 {
   240     Uint32 type;        /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
   241     Uint32 timestamp;
   242     Uint32 windowID;    /**< The window with mouse focus, if any */
   243     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
   244     Uint8 button;       /**< The mouse button index */
   245     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   246     Uint8 clicks;       /**< 1 for single-click, 2 for double-click, etc. */
   247     Uint8 padding1;
   248     Sint32 x;           /**< X coordinate, relative to window */
   249     Sint32 y;           /**< Y coordinate, relative to window */
   250 } SDL_MouseButtonEvent;
   251 
   252 /**
   253  *  \brief Mouse wheel event structure (event.wheel.*)
   254  */
   255 typedef struct SDL_MouseWheelEvent
   256 {
   257     Uint32 type;        /**< ::SDL_MOUSEWHEEL */
   258     Uint32 timestamp;
   259     Uint32 windowID;    /**< The window with mouse focus, if any */
   260     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
   261     Sint32 x;           /**< The amount scrolled horizontally, positive to the right and negative to the left */
   262     Sint32 y;           /**< The amount scrolled vertically, positive away from the user and negative toward the user */
   263 } SDL_MouseWheelEvent;
   264 
   265 /**
   266  *  \brief Joystick axis motion event structure (event.jaxis.*)
   267  */
   268 typedef struct SDL_JoyAxisEvent
   269 {
   270     Uint32 type;        /**< ::SDL_JOYAXISMOTION */
   271     Uint32 timestamp;
   272     SDL_JoystickID which; /**< The joystick instance id */
   273     Uint8 axis;         /**< The joystick axis index */
   274     Uint8 padding1;
   275     Uint8 padding2;
   276     Uint8 padding3;
   277     Sint16 value;       /**< The axis value (range: -32768 to 32767) */
   278     Uint16 padding4;
   279 } SDL_JoyAxisEvent;
   280 
   281 /**
   282  *  \brief Joystick trackball motion event structure (event.jball.*)
   283  */
   284 typedef struct SDL_JoyBallEvent
   285 {
   286     Uint32 type;        /**< ::SDL_JOYBALLMOTION */
   287     Uint32 timestamp;
   288     SDL_JoystickID which; /**< The joystick instance id */
   289     Uint8 ball;         /**< The joystick trackball index */
   290     Uint8 padding1;
   291     Uint8 padding2;
   292     Uint8 padding3;
   293     Sint16 xrel;        /**< The relative motion in the X direction */
   294     Sint16 yrel;        /**< The relative motion in the Y direction */
   295 } SDL_JoyBallEvent;
   296 
   297 /**
   298  *  \brief Joystick hat position change event structure (event.jhat.*)
   299  */
   300 typedef struct SDL_JoyHatEvent
   301 {
   302     Uint32 type;        /**< ::SDL_JOYHATMOTION */
   303     Uint32 timestamp;
   304     SDL_JoystickID which; /**< The joystick instance id */
   305     Uint8 hat;          /**< The joystick hat index */
   306     Uint8 value;        /**< The hat position value.
   307                          *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
   308                          *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
   309                          *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
   310                          *
   311                          *   Note that zero means the POV is centered.
   312                          */
   313     Uint8 padding1;
   314     Uint8 padding2;
   315 } SDL_JoyHatEvent;
   316 
   317 /**
   318  *  \brief Joystick button event structure (event.jbutton.*)
   319  */
   320 typedef struct SDL_JoyButtonEvent
   321 {
   322     Uint32 type;        /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
   323     Uint32 timestamp;
   324     SDL_JoystickID which; /**< The joystick instance id */
   325     Uint8 button;       /**< The joystick button index */
   326     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   327     Uint8 padding1;
   328     Uint8 padding2;
   329 } SDL_JoyButtonEvent;
   330 
   331 /**
   332  *  \brief Joystick device event structure (event.jdevice.*)
   333  */
   334 typedef struct SDL_JoyDeviceEvent
   335 {
   336     Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
   337     Uint32 timestamp;
   338     Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
   339 } SDL_JoyDeviceEvent;
   340 
   341 
   342 /**
   343  *  \brief Game controller axis motion event structure (event.caxis.*)
   344  */
   345 typedef struct SDL_ControllerAxisEvent
   346 {
   347     Uint32 type;        /**< ::SDL_CONTROLLERAXISMOTION */
   348     Uint32 timestamp;
   349     SDL_JoystickID which; /**< The joystick instance id */
   350     Uint8 axis;         /**< The controller axis (SDL_GameControllerAxis) */
   351     Uint8 padding1;
   352     Uint8 padding2;
   353     Uint8 padding3;
   354     Sint16 value;       /**< The axis value (range: -32768 to 32767) */
   355     Uint16 padding4;
   356 } SDL_ControllerAxisEvent;
   357 
   358 
   359 /**
   360  *  \brief Game controller button event structure (event.cbutton.*)
   361  */
   362 typedef struct SDL_ControllerButtonEvent
   363 {
   364     Uint32 type;        /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
   365     Uint32 timestamp;
   366     SDL_JoystickID which; /**< The joystick instance id */
   367     Uint8 button;       /**< The controller button (SDL_GameControllerButton) */
   368     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   369     Uint8 padding1;
   370     Uint8 padding2;
   371 } SDL_ControllerButtonEvent;
   372 
   373 
   374 /**
   375  *  \brief Controller device event structure (event.cdevice.*)
   376  */
   377 typedef struct SDL_ControllerDeviceEvent
   378 {
   379     Uint32 type;        /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */
   380     Uint32 timestamp;
   381     Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
   382 } SDL_ControllerDeviceEvent;
   383 
   384 
   385 /**
   386  *  \brief Touch finger event structure (event.tfinger.*)
   387  */
   388 typedef struct SDL_TouchFingerEvent
   389 {
   390     Uint32 type;        /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */
   391     Uint32 timestamp;
   392     SDL_TouchID touchId; /**< The touch device id */
   393     SDL_FingerID fingerId;
   394     float x;            /**< Normalized in the range 0...1 */
   395     float y;            /**< Normalized in the range 0...1 */
   396     float dx;           /**< Normalized in the range 0...1 */
   397     float dy;           /**< Normalized in the range 0...1 */
   398     float pressure;     /**< Normalized in the range 0...1 */
   399 } SDL_TouchFingerEvent;
   400 
   401 
   402 /**
   403  *  \brief Multiple Finger Gesture Event (event.mgesture.*)
   404  */
   405 typedef struct SDL_MultiGestureEvent
   406 {
   407     Uint32 type;        /**< ::SDL_MULTIGESTURE */
   408     Uint32 timestamp;
   409     SDL_TouchID touchId; /**< The touch device index */
   410     float dTheta;
   411     float dDist;
   412     float x;
   413     float y;
   414     Uint16 numFingers;
   415     Uint16 padding;
   416 } SDL_MultiGestureEvent;
   417 
   418 
   419 /**
   420  * \brief Dollar Gesture Event (event.dgesture.*)
   421  */
   422 typedef struct SDL_DollarGestureEvent
   423 {
   424     Uint32 type;        /**< ::SDL_DOLLARGESTURE */
   425     Uint32 timestamp;
   426     SDL_TouchID touchId; /**< The touch device id */
   427     SDL_GestureID gestureId;
   428     Uint32 numFingers;
   429     float error;
   430     float x;            /**< Normalized center of gesture */
   431     float y;            /**< Normalized center of gesture */
   432 } SDL_DollarGestureEvent;
   433 
   434 
   435 /**
   436  *  \brief An event used to request a file open by the system (event.drop.*)
   437  *         This event is disabled by default, you can enable it with SDL_EventState()
   438  *  \note If you enable this event, you must free the filename in the event.
   439  */
   440 typedef struct SDL_DropEvent
   441 {
   442     Uint32 type;        /**< ::SDL_DROPFILE */
   443     Uint32 timestamp;
   444     char *file;         /**< The file name, which should be freed with SDL_free() */
   445 } SDL_DropEvent;
   446 
   447 
   448 /**
   449  *  \brief The "quit requested" event
   450  */
   451 typedef struct SDL_QuitEvent
   452 {
   453     Uint32 type;        /**< ::SDL_QUIT */
   454     Uint32 timestamp;
   455 } SDL_QuitEvent;
   456 
   457 /**
   458  *  \brief OS Specific event
   459  */
   460 typedef struct SDL_OSEvent
   461 {
   462     Uint32 type;        /**< ::SDL_QUIT */
   463     Uint32 timestamp;
   464 } SDL_OSEvent;
   465 
   466 /**
   467  *  \brief A user-defined event type (event.user.*)
   468  */
   469 typedef struct SDL_UserEvent
   470 {
   471     Uint32 type;        /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */
   472     Uint32 timestamp;
   473     Uint32 windowID;    /**< The associated window if any */
   474     Sint32 code;        /**< User defined event code */
   475     void *data1;        /**< User defined data pointer */
   476     void *data2;        /**< User defined data pointer */
   477 } SDL_UserEvent;
   478 
   479 
   480 struct SDL_SysWMmsg;
   481 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
   482 
   483 /**
   484  *  \brief A video driver dependent system event (event.syswm.*)
   485  *         This event is disabled by default, you can enable it with SDL_EventState()
   486  *
   487  *  \note If you want to use this event, you should include SDL_syswm.h.
   488  */
   489 typedef struct SDL_SysWMEvent
   490 {
   491     Uint32 type;        /**< ::SDL_SYSWMEVENT */
   492     Uint32 timestamp;
   493     SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
   494 } SDL_SysWMEvent;
   495 
   496 /**
   497  *  \brief General event structure
   498  */
   499 typedef union SDL_Event
   500 {
   501     Uint32 type;                    /**< Event type, shared with all events */
   502     SDL_CommonEvent common;         /**< Common event data */
   503     SDL_WindowEvent window;         /**< Window event data */
   504     SDL_KeyboardEvent key;          /**< Keyboard event data */
   505     SDL_TextEditingEvent edit;      /**< Text editing event data */
   506     SDL_TextInputEvent text;        /**< Text input event data */
   507     SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
   508     SDL_MouseButtonEvent button;    /**< Mouse button event data */
   509     SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
   510     SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
   511     SDL_JoyBallEvent jball;         /**< Joystick ball event data */
   512     SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
   513     SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
   514     SDL_JoyDeviceEvent jdevice;     /**< Joystick device change event data */
   515     SDL_ControllerAxisEvent caxis;      /**< Game Controller axis event data */
   516     SDL_ControllerButtonEvent cbutton;  /**< Game Controller button event data */
   517     SDL_ControllerDeviceEvent cdevice;  /**< Game Controller device event data */
   518     SDL_QuitEvent quit;             /**< Quit request event data */
   519     SDL_UserEvent user;             /**< Custom event data */
   520     SDL_SysWMEvent syswm;           /**< System dependent window event data */
   521     SDL_TouchFingerEvent tfinger;   /**< Touch finger event data */
   522     SDL_MultiGestureEvent mgesture; /**< Gesture event data */
   523     SDL_DollarGestureEvent dgesture; /**< Gesture event data */
   524     SDL_DropEvent drop;             /**< Drag and drop event data */
   525 
   526     /* This is necessary for ABI compatibility between Visual C++ and GCC
   527        Visual C++ will respect the push pack pragma and use 52 bytes for
   528        this structure, and GCC will use the alignment of the largest datatype
   529        within the union, which is 8 bytes.
   530 
   531        So... we'll add padding to force the size to be 56 bytes for both.
   532     */
   533     Uint8 padding[56];
   534 } SDL_Event;
   535 
   536 
   537 /* Function prototypes */
   538 
   539 /**
   540  *  Pumps the event loop, gathering events from the input devices.
   541  *
   542  *  This function updates the event queue and internal input device state.
   543  *
   544  *  This should only be run in the thread that sets the video mode.
   545  */
   546 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   547 
   548 /* @{ */
   549 typedef enum
   550 {
   551     SDL_ADDEVENT,
   552     SDL_PEEKEVENT,
   553     SDL_GETEVENT
   554 } SDL_eventaction;
   555 
   556 /**
   557  *  Checks the event queue for messages and optionally returns them.
   558  *
   559  *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
   560  *  the back of the event queue.
   561  *
   562  *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
   563  *  of the event queue, within the specified minimum and maximum type,
   564  *  will be returned and will not be removed from the queue.
   565  *
   566  *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
   567  *  of the event queue, within the specified minimum and maximum type,
   568  *  will be returned and will be removed from the queue.
   569  *
   570  *  \return The number of events actually stored, or -1 if there was an error.
   571  *
   572  *  This function is thread-safe.
   573  */
   574 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   575                                            SDL_eventaction action,
   576                                            Uint32 minType, Uint32 maxType);
   577 /* @} */
   578 
   579 /**
   580  *  Checks to see if certain event types are in the event queue.
   581  */
   582 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
   583 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
   584 
   585 /**
   586  *  This function clears events from the event queue
   587  *  This function only affects currently queued events. If you want to make
   588  *  sure that all pending OS events are flushed, you can call SDL_PumpEvents()
   589  *  on the main thread immediately before the flush call.
   590  */
   591 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
   592 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
   593 
   594 /**
   595  *  \brief Polls for currently pending events.
   596  *
   597  *  \return 1 if there are any pending events, or 0 if there are none available.
   598  *
   599  *  \param event If not NULL, the next event is removed from the queue and
   600  *               stored in that area.
   601  */
   602 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   603 
   604 /**
   605  *  \brief Waits indefinitely for the next available event.
   606  *
   607  *  \return 1, or 0 if there was an error while waiting for events.
   608  *
   609  *  \param event If not NULL, the next event is removed from the queue and
   610  *               stored in that area.
   611  */
   612 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
   613 
   614 /**
   615  *  \brief Waits until the specified timeout (in milliseconds) for the next
   616  *         available event.
   617  *
   618  *  \return 1, or 0 if there was an error while waiting for events.
   619  *
   620  *  \param event If not NULL, the next event is removed from the queue and
   621  *               stored in that area.
   622  *  \param timeout The timeout (in milliseconds) to wait for next event.
   623  */
   624 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
   625                                                  int timeout);
   626 
   627 /**
   628  *  \brief Add an event to the event queue.
   629  *
   630  *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue
   631  *          was full or there was some other error.
   632  */
   633 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   634 
   635 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   636 
   637 /**
   638  *  Sets up a filter to process all events before they change internal state and
   639  *  are posted to the internal event queue.
   640  *
   641  *  The filter is prototyped as:
   642  *  \code
   643  *      int SDL_EventFilter(void *userdata, SDL_Event * event);
   644  *  \endcode
   645  *
   646  *  If the filter returns 1, then the event will be added to the internal queue.
   647  *  If it returns 0, then the event will be dropped from the queue, but the
   648  *  internal state will still be updated.  This allows selective filtering of
   649  *  dynamically arriving events.
   650  *
   651  *  \warning  Be very careful of what you do in the event filter function, as
   652  *            it may run in a different thread!
   653  *
   654  *  There is one caveat when dealing with the ::SDL_QuitEvent event type.  The
   655  *  event filter is only called when the window manager desires to close the
   656  *  application window.  If the event filter returns 1, then the window will
   657  *  be closed, otherwise the window will remain open if possible.
   658  *
   659  *  If the quit event is generated by an interrupt signal, it will bypass the
   660  *  internal queue and be delivered to the application at the next event poll.
   661  */
   662 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
   663                                                 void *userdata);
   664 
   665 /**
   666  *  Return the current event filter - can be used to "chain" filters.
   667  *  If there is no event filter set, this function returns SDL_FALSE.
   668  */
   669 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
   670                                                     void **userdata);
   671 
   672 /**
   673  *  Add a function which is called when an event is added to the queue.
   674  */
   675 extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
   676                                                void *userdata);
   677 
   678 /**
   679  *  Remove an event watch function added with SDL_AddEventWatch()
   680  */
   681 extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
   682                                                void *userdata);
   683 
   684 /**
   685  *  Run the filter function on the current event queue, removing any
   686  *  events for which the filter returns 0.
   687  */
   688 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
   689                                               void *userdata);
   690 
   691 /* @{ */
   692 #define SDL_QUERY   -1
   693 #define SDL_IGNORE   0
   694 #define SDL_DISABLE  0
   695 #define SDL_ENABLE   1
   696 
   697 /**
   698  *  This function allows you to set the state of processing certain events.
   699  *   - If \c state is set to ::SDL_IGNORE, that event will be automatically
   700  *     dropped from the event queue and will not event be filtered.
   701  *   - If \c state is set to ::SDL_ENABLE, that event will be processed
   702  *     normally.
   703  *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
   704  *     current processing state of the specified event.
   705  */
   706 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
   707 /* @} */
   708 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
   709 
   710 /**
   711  *  This function allocates a set of user-defined events, and returns
   712  *  the beginning event number for that set of events.
   713  *
   714  *  If there aren't enough user-defined events left, this function
   715  *  returns (Uint32)-1
   716  */
   717 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
   718 
   719 /* Ends C function definitions when using C++ */
   720 #ifdef __cplusplus
   721 }
   722 #endif
   723 #include "close_code.h"
   724 
   725 #endif /* _SDL_events_h */
   726 
   727 /* vi: set ts=4 sw=4 expandtab: */