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