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