include/SDL_events.h
author Sam Lantinga <slouken@libsdl.org>
Mon, 24 Jan 2011 16:10:13 -0800
changeset 5087 b4b0e9f1669c
parent 5014 22751715e11a
child 5146 3052772b59db
permissions -rw-r--r--
Fixed bug #1103

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