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