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