SDL_events.h

00001 /*
00002   Simple DirectMedia Layer
00003   Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
00004 
00005   This software is provided 'as-is', without any express or implied
00006   warranty.  In no event will the authors be held liable for any damages
00007   arising from the use of this software.
00008 
00009   Permission is granted to anyone to use this software for any purpose,
00010   including commercial applications, and to alter it and redistribute it
00011   freely, subject to the following restrictions:
00012 
00013   1. The origin of this software must not be misrepresented; you must not
00014      claim that you wrote the original software. If you use this software
00015      in a product, an acknowledgment in the product documentation would be
00016      appreciated but is not required.
00017   2. Altered source versions must be plainly marked as such, and must not be
00018      misrepresented as being the original software.
00019   3. This notice may not be removed or altered from any source distribution.
00020 */
00021 
00022 /**
00023  *  \file SDL_events.h
00024  *
00025  *  Include file for SDL event handling.
00026  */
00027 
00028 #ifndef _SDL_events_h
00029 #define _SDL_events_h
00030 
00031 #include "SDL_stdinc.h"
00032 #include "SDL_error.h"
00033 #include "SDL_video.h"
00034 #include "SDL_keyboard.h"
00035 #include "SDL_mouse.h"
00036 #include "SDL_joystick.h"
00037 #include "SDL_gamecontroller.h"
00038 #include "SDL_quit.h"
00039 #include "SDL_gesture.h"
00040 #include "SDL_touch.h"
00041 
00042 #include "begin_code.h"
00043 /* Set up for C function definitions, even when using C++ */
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 /* General keyboard/mouse state definitions */
00049 #define SDL_RELEASED    0
00050 #define SDL_PRESSED 1
00051 
00052 /**
00053  * \brief The types of events that can be delivered.
00054  */
00055 typedef enum
00056 {
00057     SDL_FIRSTEVENT     = 0,     /**< Unused (do not remove) */
00058 
00059     /* Application events */
00060     SDL_QUIT           = 0x100, /**< User-requested quit */
00061 
00062     /* These application events have special meaning on iOS, see README-ios.txt for details */
00063     SDL_APP_TERMINATING,        /**< The application is being terminated by the OS
00064                                      Called on iOS in applicationWillTerminate()
00065                                      Called on Android in onDestroy()
00066                                 */
00067     SDL_APP_LOWMEMORY,          /**< The application is low on memory, free memory if possible.
00068                                      Called on iOS in applicationDidReceiveMemoryWarning()
00069                                      Called on Android in onLowMemory()
00070                                 */
00071     SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background
00072                                      Called on iOS in applicationWillResignActive()
00073                                      Called on Android in onPause()
00074                                 */
00075     SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time
00076                                      Called on iOS in applicationDidEnterBackground()
00077                                      Called on Android in onPause()
00078                                 */
00079     SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground
00080                                      Called on iOS in applicationWillEnterForeground()
00081                                      Called on Android in onResume()
00082                                 */
00083     SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive
00084                                      Called on iOS in applicationDidBecomeActive()
00085                                      Called on Android in onResume()
00086                                 */
00087 
00088     /* Window events */
00089     SDL_WINDOWEVENT    = 0x200, /**< Window state change */
00090     SDL_SYSWMEVENT,             /**< System specific event */
00091 
00092     /* Keyboard events */
00093     SDL_KEYDOWN        = 0x300, /**< Key pressed */
00094     SDL_KEYUP,                  /**< Key released */
00095     SDL_TEXTEDITING,            /**< Keyboard text editing (composition) */
00096     SDL_TEXTINPUT,              /**< Keyboard text input */
00097 
00098     /* Mouse events */
00099     SDL_MOUSEMOTION    = 0x400, /**< Mouse moved */
00100     SDL_MOUSEBUTTONDOWN,        /**< Mouse button pressed */
00101     SDL_MOUSEBUTTONUP,          /**< Mouse button released */
00102     SDL_MOUSEWHEEL,             /**< Mouse wheel motion */
00103 
00104     /* Joystick events */
00105     SDL_JOYAXISMOTION  = 0x600, /**< Joystick axis motion */
00106     SDL_JOYBALLMOTION,          /**< Joystick trackball motion */
00107     SDL_JOYHATMOTION,           /**< Joystick hat position change */
00108     SDL_JOYBUTTONDOWN,          /**< Joystick button pressed */
00109     SDL_JOYBUTTONUP,            /**< Joystick button released */
00110     SDL_JOYDEVICEADDED,         /**< A new joystick has been inserted into the system */
00111     SDL_JOYDEVICEREMOVED,       /**< An opened joystick has been removed */
00112 
00113     /* Game controller events */
00114     SDL_CONTROLLERAXISMOTION  = 0x650, /**< Game controller axis motion */
00115     SDL_CONTROLLERBUTTONDOWN,          /**< Game controller button pressed */
00116     SDL_CONTROLLERBUTTONUP,            /**< Game controller button released */
00117     SDL_CONTROLLERDEVICEADDED,         /**< A new Game controller has been inserted into the system */
00118     SDL_CONTROLLERDEVICEREMOVED,       /**< An opened Game controller has been removed */
00119     SDL_CONTROLLERDEVICEREMAPPED,      /**< The controller mapping was updated */
00120 
00121     /* Touch events */
00122     SDL_FINGERDOWN      = 0x700,
00123     SDL_FINGERUP,
00124     SDL_FINGERMOTION,
00125 
00126     /* Gesture events */
00127     SDL_DOLLARGESTURE   = 0x800,
00128     SDL_DOLLARRECORD,
00129     SDL_MULTIGESTURE,
00130 
00131     /* Clipboard events */
00132     SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard changed */
00133 
00134     /* Drag and drop events */
00135     SDL_DROPFILE        = 0x1000, /**< The system requests a file open */
00136 
00137     /* Render events */
00138     SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset */
00139 
00140     /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
00141      *  and should be allocated with SDL_RegisterEvents()
00142      */
00143     SDL_USEREVENT    = 0x8000,
00144 
00145     /**
00146      *  This last event is only for bounding internal arrays
00147      */
00148     SDL_LASTEVENT    = 0xFFFF
00149 } SDL_EventType;
00150 
00151 /**
00152  *  \brief Fields shared by every event
00153  */
00154 typedef struct SDL_CommonEvent
00155 {
00156     Uint32 type;
00157     Uint32 timestamp;
00158 } SDL_CommonEvent;
00159 
00160 /**
00161  *  \brief Window state change event data (event.window.*)
00162  */
00163 typedef struct SDL_WindowEvent
00164 {
00165     Uint32 type;        /**< ::SDL_WINDOWEVENT */
00166     Uint32 timestamp;
00167     Uint32 windowID;    /**< The associated window */
00168     Uint8 event;        /**< ::SDL_WindowEventID */
00169     Uint8 padding1;
00170     Uint8 padding2;
00171     Uint8 padding3;
00172     Sint32 data1;       /**< event dependent data */
00173     Sint32 data2;       /**< event dependent data */
00174 } SDL_WindowEvent;
00175 
00176 /**
00177  *  \brief Keyboard button event structure (event.key.*)
00178  */
00179 typedef struct SDL_KeyboardEvent
00180 {
00181     Uint32 type;        /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
00182     Uint32 timestamp;
00183     Uint32 windowID;    /**< The window with keyboard focus, if any */
00184     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
00185     Uint8 repeat;       /**< Non-zero if this is a key repeat */
00186     Uint8 padding2;
00187     Uint8 padding3;
00188     SDL_Keysym keysym;  /**< The key that was pressed or released */
00189 } SDL_KeyboardEvent;
00190 
00191 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
00192 /**
00193  *  \brief Keyboard text editing event structure (event.edit.*)
00194  */
00195 typedef struct SDL_TextEditingEvent
00196 {
00197     Uint32 type;                                /**< ::SDL_TEXTEDITING */
00198     Uint32 timestamp;
00199     Uint32 windowID;                            /**< The window with keyboard focus, if any */
00200     char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
00201     Sint32 start;                               /**< The start cursor of selected editing text */
00202     Sint32 length;                              /**< The length of selected editing text */
00203 } SDL_TextEditingEvent;
00204 
00205 
00206 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
00207 /**
00208  *  \brief Keyboard text input event structure (event.text.*)
00209  */
00210 typedef struct SDL_TextInputEvent
00211 {
00212     Uint32 type;                              /**< ::SDL_TEXTINPUT */
00213     Uint32 timestamp;
00214     Uint32 windowID;                          /**< The window with keyboard focus, if any */
00215     char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
00216 } SDL_TextInputEvent;
00217 
00218 /**
00219  *  \brief Mouse motion event structure (event.motion.*)
00220  */
00221 typedef struct SDL_MouseMotionEvent
00222 {
00223     Uint32 type;        /**< ::SDL_MOUSEMOTION */
00224     Uint32 timestamp;
00225     Uint32 windowID;    /**< The window with mouse focus, if any */
00226     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
00227     Uint32 state;       /**< The current button state */
00228     Sint32 x;           /**< X coordinate, relative to window */
00229     Sint32 y;           /**< Y coordinate, relative to window */
00230     Sint32 xrel;        /**< The relative motion in the X direction */
00231     Sint32 yrel;        /**< The relative motion in the Y direction */
00232 } SDL_MouseMotionEvent;
00233 
00234 /**
00235  *  \brief Mouse button event structure (event.button.*)
00236  */
00237 typedef struct SDL_MouseButtonEvent
00238 {
00239     Uint32 type;        /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
00240     Uint32 timestamp;
00241     Uint32 windowID;    /**< The window with mouse focus, if any */
00242     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
00243     Uint8 button;       /**< The mouse button index */
00244     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
00245     Uint8 clicks;       /**< 1 for single-click, 2 for double-click, etc. */
00246     Uint8 padding1;
00247     Sint32 x;           /**< X coordinate, relative to window */
00248     Sint32 y;           /**< Y coordinate, relative to window */
00249 } SDL_MouseButtonEvent;
00250 
00251 /**
00252  *  \brief Mouse wheel event structure (event.wheel.*)
00253  */
00254 typedef struct SDL_MouseWheelEvent
00255 {
00256     Uint32 type;        /**< ::SDL_MOUSEWHEEL */
00257     Uint32 timestamp;
00258     Uint32 windowID;    /**< The window with mouse focus, if any */
00259     Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
00260     Sint32 x;           /**< The amount scrolled horizontally, positive to the right and negative to the left */
00261     Sint32 y;           /**< The amount scrolled vertically, positive away from the user and negative toward the user */
00262 } SDL_MouseWheelEvent;
00263 
00264 /**
00265  *  \brief Joystick axis motion event structure (event.jaxis.*)
00266  */
00267 typedef struct SDL_JoyAxisEvent
00268 {
00269     Uint32 type;        /**< ::SDL_JOYAXISMOTION */
00270     Uint32 timestamp;
00271     SDL_JoystickID which; /**< The joystick instance id */
00272     Uint8 axis;         /**< The joystick axis index */
00273     Uint8 padding1;
00274     Uint8 padding2;
00275     Uint8 padding3;
00276     Sint16 value;       /**< The axis value (range: -32768 to 32767) */
00277     Uint16 padding4;
00278 } SDL_JoyAxisEvent;
00279 
00280 /**
00281  *  \brief Joystick trackball motion event structure (event.jball.*)
00282  */
00283 typedef struct SDL_JoyBallEvent
00284 {
00285     Uint32 type;        /**< ::SDL_JOYBALLMOTION */
00286     Uint32 timestamp;
00287     SDL_JoystickID which; /**< The joystick instance id */
00288     Uint8 ball;         /**< The joystick trackball index */
00289     Uint8 padding1;
00290     Uint8 padding2;
00291     Uint8 padding3;
00292     Sint16 xrel;        /**< The relative motion in the X direction */
00293     Sint16 yrel;        /**< The relative motion in the Y direction */
00294 } SDL_JoyBallEvent;
00295 
00296 /**
00297  *  \brief Joystick hat position change event structure (event.jhat.*)
00298  */
00299 typedef struct SDL_JoyHatEvent
00300 {
00301     Uint32 type;        /**< ::SDL_JOYHATMOTION */
00302     Uint32 timestamp;
00303     SDL_JoystickID which; /**< The joystick instance id */
00304     Uint8 hat;          /**< The joystick hat index */
00305     Uint8 value;        /**< The hat position value.
00306                          *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
00307                          *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
00308                          *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
00309                          *
00310                          *   Note that zero means the POV is centered.
00311                          */
00312     Uint8 padding1;
00313     Uint8 padding2;
00314 } SDL_JoyHatEvent;
00315 
00316 /**
00317  *  \brief Joystick button event structure (event.jbutton.*)
00318  */
00319 typedef struct SDL_JoyButtonEvent
00320 {
00321     Uint32 type;        /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
00322     Uint32 timestamp;
00323     SDL_JoystickID which; /**< The joystick instance id */
00324     Uint8 button;       /**< The joystick button index */
00325     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
00326     Uint8 padding1;
00327     Uint8 padding2;
00328 } SDL_JoyButtonEvent;
00329 
00330 /**
00331  *  \brief Joystick device event structure (event.jdevice.*)
00332  */
00333 typedef struct SDL_JoyDeviceEvent
00334 {
00335     Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
00336     Uint32 timestamp;
00337     Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
00338 } SDL_JoyDeviceEvent;
00339 
00340 
00341 /**
00342  *  \brief Game controller axis motion event structure (event.caxis.*)
00343  */
00344 typedef struct SDL_ControllerAxisEvent
00345 {
00346     Uint32 type;        /**< ::SDL_CONTROLLERAXISMOTION */
00347     Uint32 timestamp;
00348     SDL_JoystickID which; /**< The joystick instance id */
00349     Uint8 axis;         /**< The controller axis (SDL_GameControllerAxis) */
00350     Uint8 padding1;
00351     Uint8 padding2;
00352     Uint8 padding3;
00353     Sint16 value;       /**< The axis value (range: -32768 to 32767) */
00354     Uint16 padding4;
00355 } SDL_ControllerAxisEvent;
00356 
00357 
00358 /**
00359  *  \brief Game controller button event structure (event.cbutton.*)
00360  */
00361 typedef struct SDL_ControllerButtonEvent
00362 {
00363     Uint32 type;        /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
00364     Uint32 timestamp;
00365     SDL_JoystickID which; /**< The joystick instance id */
00366     Uint8 button;       /**< The controller button (SDL_GameControllerButton) */
00367     Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
00368     Uint8 padding1;
00369     Uint8 padding2;
00370 } SDL_ControllerButtonEvent;
00371 
00372 
00373 /**
00374  *  \brief Controller device event structure (event.cdevice.*)
00375  */
00376 typedef struct SDL_ControllerDeviceEvent
00377 {
00378     Uint32 type;        /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */
00379     Uint32 timestamp;
00380     Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
00381 } SDL_ControllerDeviceEvent;
00382 
00383 
00384 /**
00385  *  \brief Touch finger event structure (event.tfinger.*)
00386  */
00387 typedef struct SDL_TouchFingerEvent
00388 {
00389     Uint32 type;        /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */
00390     Uint32 timestamp;
00391     SDL_TouchID touchId; /**< The touch device id */
00392     SDL_FingerID fingerId;
00393     float x;            /**< Normalized in the range 0...1 */
00394     float y;            /**< Normalized in the range 0...1 */
00395     float dx;           /**< Normalized in the range 0...1 */
00396     float dy;           /**< Normalized in the range 0...1 */
00397     float pressure;     /**< Normalized in the range 0...1 */
00398 } SDL_TouchFingerEvent;
00399 
00400 
00401 /**
00402  *  \brief Multiple Finger Gesture Event (event.mgesture.*)
00403  */
00404 typedef struct SDL_MultiGestureEvent
00405 {
00406     Uint32 type;        /**< ::SDL_MULTIGESTURE */
00407     Uint32 timestamp;
00408     SDL_TouchID touchId; /**< The touch device index */
00409     float dTheta;
00410     float dDist;
00411     float x;
00412     float y;
00413     Uint16 numFingers;
00414     Uint16 padding;
00415 } SDL_MultiGestureEvent;
00416 
00417 
00418 /**
00419  * \brief Dollar Gesture Event (event.dgesture.*)
00420  */
00421 typedef struct SDL_DollarGestureEvent
00422 {
00423     Uint32 type;        /**< ::SDL_DOLLARGESTURE */
00424     Uint32 timestamp;
00425     SDL_TouchID touchId; /**< The touch device id */
00426     SDL_GestureID gestureId;
00427     Uint32 numFingers;
00428     float error;
00429     float x;            /**< Normalized center of gesture */
00430     float y;            /**< Normalized center of gesture */
00431 } SDL_DollarGestureEvent;
00432 
00433 
00434 /**
00435  *  \brief An event used to request a file open by the system (event.drop.*)
00436  *         This event is disabled by default, you can enable it with SDL_EventState()
00437  *  \note If you enable this event, you must free the filename in the event.
00438  */
00439 typedef struct SDL_DropEvent
00440 {
00441     Uint32 type;        /**< ::SDL_DROPFILE */
00442     Uint32 timestamp;
00443     char *file;         /**< The file name, which should be freed with SDL_free() */
00444 } SDL_DropEvent;
00445 
00446 
00447 /**
00448  *  \brief The "quit requested" event
00449  */
00450 typedef struct SDL_QuitEvent
00451 {
00452     Uint32 type;        /**< ::SDL_QUIT */
00453     Uint32 timestamp;
00454 } SDL_QuitEvent;
00455 
00456 /**
00457  *  \brief OS Specific event
00458  */
00459 typedef struct SDL_OSEvent
00460 {
00461     Uint32 type;        /**< ::SDL_QUIT */
00462     Uint32 timestamp;
00463 } SDL_OSEvent;
00464 
00465 /**
00466  *  \brief A user-defined event type (event.user.*)
00467  */
00468 typedef struct SDL_UserEvent
00469 {
00470     Uint32 type;        /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */
00471     Uint32 timestamp;
00472     Uint32 windowID;    /**< The associated window if any */
00473     Sint32 code;        /**< User defined event code */
00474     void *data1;        /**< User defined data pointer */
00475     void *data2;        /**< User defined data pointer */
00476 } SDL_UserEvent;
00477 
00478 
00479 struct SDL_SysWMmsg;
00480 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
00481 
00482 /**
00483  *  \brief A video driver dependent system event (event.syswm.*)
00484  *         This event is disabled by default, you can enable it with SDL_EventState()
00485  *
00486  *  \note If you want to use this event, you should include SDL_syswm.h.
00487  */
00488 typedef struct SDL_SysWMEvent
00489 {
00490     Uint32 type;        /**< ::SDL_SYSWMEVENT */
00491     Uint32 timestamp;
00492     SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
00493 } SDL_SysWMEvent;
00494 
00495 /**
00496  *  \brief General event structure
00497  */
00498 typedef union SDL_Event
00499 {
00500     Uint32 type;                    /**< Event type, shared with all events */
00501     SDL_CommonEvent common;         /**< Common event data */
00502     SDL_WindowEvent window;         /**< Window event data */
00503     SDL_KeyboardEvent key;          /**< Keyboard event data */
00504     SDL_TextEditingEvent edit;      /**< Text editing event data */
00505     SDL_TextInputEvent text;        /**< Text input event data */
00506     SDL_MouseMotionEvent motion;    /**< Mouse motion event data */
00507     SDL_MouseButtonEvent button;    /**< Mouse button event data */
00508     SDL_MouseWheelEvent wheel;      /**< Mouse wheel event data */
00509     SDL_JoyAxisEvent jaxis;         /**< Joystick axis event data */
00510     SDL_JoyBallEvent jball;         /**< Joystick ball event data */
00511     SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
00512     SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
00513     SDL_JoyDeviceEvent jdevice;     /**< Joystick device change event data */
00514     SDL_ControllerAxisEvent caxis;      /**< Game Controller axis event data */
00515     SDL_ControllerButtonEvent cbutton;  /**< Game Controller button event data */
00516     SDL_ControllerDeviceEvent cdevice;  /**< Game Controller device event data */
00517     SDL_QuitEvent quit;             /**< Quit request event data */
00518     SDL_UserEvent user;             /**< Custom event data */
00519     SDL_SysWMEvent syswm;           /**< System dependent window event data */
00520     SDL_TouchFingerEvent tfinger;   /**< Touch finger event data */
00521     SDL_MultiGestureEvent mgesture; /**< Gesture event data */
00522     SDL_DollarGestureEvent dgesture; /**< Gesture event data */
00523     SDL_DropEvent drop;             /**< Drag and drop event data */
00524 
00525     /* This is necessary for ABI compatibility between Visual C++ and GCC
00526        Visual C++ will respect the push pack pragma and use 52 bytes for
00527        this structure, and GCC will use the alignment of the largest datatype
00528        within the union, which is 8 bytes.
00529 
00530        So... we'll add padding to force the size to be 56 bytes for both.
00531     */
00532     Uint8 padding[56];
00533 } SDL_Event;
00534 
00535 
00536 /* Function prototypes */
00537 
00538 /**
00539  *  Pumps the event loop, gathering events from the input devices.
00540  *
00541  *  This function updates the event queue and internal input device state.
00542  *
00543  *  This should only be run in the thread that sets the video mode.
00544  */
00545 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
00546 
00547 /* @{ */
00548 typedef enum
00549 {
00550     SDL_ADDEVENT,
00551     SDL_PEEKEVENT,
00552     SDL_GETEVENT
00553 } SDL_eventaction;
00554 
00555 /**
00556  *  Checks the event queue for messages and optionally returns them.
00557  *
00558  *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
00559  *  the back of the event queue.
00560  *
00561  *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
00562  *  of the event queue, within the specified minimum and maximum type,
00563  *  will be returned and will not be removed from the queue.
00564  *
00565  *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
00566  *  of the event queue, within the specified minimum and maximum type,
00567  *  will be returned and will be removed from the queue.
00568  *
00569  *  \return The number of events actually stored, or -1 if there was an error.
00570  *
00571  *  This function is thread-safe.
00572  */
00573 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
00574                                            SDL_eventaction action,
00575                                            Uint32 minType, Uint32 maxType);
00576 /* @} */
00577 
00578 /**
00579  *  Checks to see if certain event types are in the event queue.
00580  */
00581 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
00582 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
00583 
00584 /**
00585  *  This function clears events from the event queue
00586  */
00587 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
00588 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
00589 
00590 /**
00591  *  \brief Polls for currently pending events.
00592  *
00593  *  \return 1 if there are any pending events, or 0 if there are none available.
00594  *
00595  *  \param event If not NULL, the next event is removed from the queue and
00596  *               stored in that area.
00597  */
00598 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
00599 
00600 /**
00601  *  \brief Waits indefinitely for the next available event.
00602  *
00603  *  \return 1, or 0 if there was an error while waiting for events.
00604  *
00605  *  \param event If not NULL, the next event is removed from the queue and
00606  *               stored in that area.
00607  */
00608 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
00609 
00610 /**
00611  *  \brief Waits until the specified timeout (in milliseconds) for the next
00612  *         available event.
00613  *
00614  *  \return 1, or 0 if there was an error while waiting for events.
00615  *
00616  *  \param event If not NULL, the next event is removed from the queue and
00617  *               stored in that area.
00618  *  \param timeout The timeout (in milliseconds) to wait for next event.
00619  */
00620 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
00621                                                  int timeout);
00622 
00623 /**
00624  *  \brief Add an event to the event queue.
00625  *
00626  *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue
00627  *          was full or there was some other error.
00628  */
00629 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
00630 
00631 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
00632 
00633 /**
00634  *  Sets up a filter to process all events before they change internal state and
00635  *  are posted to the internal event queue.
00636  *
00637  *  The filter is prototyped as:
00638  *  \code
00639  *      int SDL_EventFilter(void *userdata, SDL_Event * event);
00640  *  \endcode
00641  *
00642  *  If the filter returns 1, then the event will be added to the internal queue.
00643  *  If it returns 0, then the event will be dropped from the queue, but the
00644  *  internal state will still be updated.  This allows selective filtering of
00645  *  dynamically arriving events.
00646  *
00647  *  \warning  Be very careful of what you do in the event filter function, as
00648  *            it may run in a different thread!
00649  *
00650  *  There is one caveat when dealing with the ::SDL_QuitEvent event type.  The
00651  *  event filter is only called when the window manager desires to close the
00652  *  application window.  If the event filter returns 1, then the window will
00653  *  be closed, otherwise the window will remain open if possible.
00654  *
00655  *  If the quit event is generated by an interrupt signal, it will bypass the
00656  *  internal queue and be delivered to the application at the next event poll.
00657  */
00658 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
00659                                                 void *userdata);
00660 
00661 /**
00662  *  Return the current event filter - can be used to "chain" filters.
00663  *  If there is no event filter set, this function returns SDL_FALSE.
00664  */
00665 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
00666                                                     void **userdata);
00667 
00668 /**
00669  *  Add a function which is called when an event is added to the queue.
00670  */
00671 extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
00672                                                void *userdata);
00673 
00674 /**
00675  *  Remove an event watch function added with SDL_AddEventWatch()
00676  */
00677 extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
00678                                                void *userdata);
00679 
00680 /**
00681  *  Run the filter function on the current event queue, removing any
00682  *  events for which the filter returns 0.
00683  */
00684 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
00685                                               void *userdata);
00686 
00687 /* @{ */
00688 #define SDL_QUERY   -1
00689 #define SDL_IGNORE   0
00690 #define SDL_DISABLE  0
00691 #define SDL_ENABLE   1
00692 
00693 /**
00694  *  This function allows you to set the state of processing certain events.
00695  *   - If \c state is set to ::SDL_IGNORE, that event will be automatically
00696  *     dropped from the event queue and will not event be filtered.
00697  *   - If \c state is set to ::SDL_ENABLE, that event will be processed
00698  *     normally.
00699  *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
00700  *     current processing state of the specified event.
00701  */
00702 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
00703 /* @} */
00704 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
00705 
00706 /**
00707  *  This function allocates a set of user-defined events, and returns
00708  *  the beginning event number for that set of events.
00709  *
00710  *  If there aren't enough user-defined events left, this function
00711  *  returns (Uint32)-1
00712  */
00713 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
00714 
00715 /* Ends C function definitions when using C++ */
00716 #ifdef __cplusplus
00717 }
00718 #endif
00719 #include "close_code.h"
00720 
00721 #endif /* _SDL_events_h */
00722 
00723 /* vi: set ts=4 sw=4 expandtab: */