include/SDL_events.h
author Edward Rudd <urkle@outoforder.cc>
Tue, 05 Mar 2013 17:59:36 -0500
changeset 6964 c8aa24f05042
parent 6951 7833f01322b3
child 6972 3457cb05b7fb
permissions -rw-r--r--
add new gamecontroller APIs

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