include/SDL_events.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 21 Oct 2012 22:18:36 -0700
changeset 6596 b00cf2e4835c
parent 6595 c6402c811a40
child 6690 9548c8a58103
permissions -rw-r--r--
Switch C++ comment to C comment
     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 
   442     /* This is necessary for ABI compatibility between Visual C++ and GCC
   443        Visual C++ will respect the push pack pragma and use 52 bytes for
   444        this structure, and GCC will use the alignment of the largest datatype
   445        within the union, which is 8 bytes.
   446 
   447        So... we'll add padding to force the size to be 56 bytes for both.
   448     */
   449     Uint8 padding[56];
   450 } SDL_Event;
   451 
   452 
   453 /* Function prototypes */
   454 
   455 /**
   456  *  Pumps the event loop, gathering events from the input devices.
   457  *  
   458  *  This function updates the event queue and internal input device state.
   459  *  
   460  *  This should only be run in the thread that sets the video mode.
   461  */
   462 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   463 
   464 /*@{*/
   465 typedef enum
   466 {
   467     SDL_ADDEVENT,
   468     SDL_PEEKEVENT,
   469     SDL_GETEVENT
   470 } SDL_eventaction;
   471 
   472 /**
   473  *  Checks the event queue for messages and optionally returns them.
   474  *  
   475  *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
   476  *  the back of the event queue.
   477  *  
   478  *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
   479  *  of the event queue, within the specified minimum and maximum type,
   480  *  will be returned and will not be removed from the queue.
   481  *  
   482  *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front 
   483  *  of the event queue, within the specified minimum and maximum type,
   484  *  will be returned and will be removed from the queue.
   485  *  
   486  *  \return The number of events actually stored, or -1 if there was an error.
   487  *  
   488  *  This function is thread-safe.
   489  */
   490 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   491                                            SDL_eventaction action,
   492                                            Uint32 minType, Uint32 maxType);
   493 /*@}*/
   494 
   495 /**
   496  *  Checks to see if certain event types are in the event queue.
   497  */
   498 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
   499 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
   500 
   501 /**
   502  *  This function clears events from the event queue
   503  */
   504 extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
   505 extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
   506 
   507 /**
   508  *  \brief Polls for currently pending events.
   509  *  
   510  *  \return 1 if there are any pending events, or 0 if there are none available.
   511  *  
   512  *  \param event If not NULL, the next event is removed from the queue and 
   513  *               stored in that area.
   514  */
   515 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   516 
   517 /**
   518  *  \brief Waits indefinitely for the next available event.
   519  *  
   520  *  \return 1, or 0 if there was an error while waiting for events.
   521  *   
   522  *  \param event If not NULL, the next event is removed from the queue and 
   523  *               stored in that area.
   524  */
   525 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
   526 
   527 /**
   528  *  \brief Waits until the specified timeout (in milliseconds) for the next 
   529  *         available event.
   530  *  
   531  *  \return 1, or 0 if there was an error while waiting for events.
   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_WaitEventTimeout(SDL_Event * event,
   537                                                  int timeout);
   538 
   539 /**
   540  *  \brief Add an event to the event queue.
   541  *  
   542  *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue 
   543  *          was full or there was some other error.
   544  */
   545 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   546 
   547 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   548 
   549 /**
   550  *  Sets up a filter to process all events before they change internal state and
   551  *  are posted to the internal event queue.
   552  *  
   553  *  The filter is protypted as:
   554  *  \code
   555  *      int SDL_EventFilter(void *userdata, SDL_Event * event);
   556  *  \endcode
   557  *
   558  *  If the filter returns 1, then the event will be added to the internal queue.
   559  *  If it returns 0, then the event will be dropped from the queue, but the 
   560  *  internal state will still be updated.  This allows selective filtering of
   561  *  dynamically arriving events.
   562  *  
   563  *  \warning  Be very careful of what you do in the event filter function, as 
   564  *            it may run in a different thread!
   565  *  
   566  *  There is one caveat when dealing with the ::SDL_QUITEVENT event type.  The
   567  *  event filter is only called when the window manager desires to close the
   568  *  application window.  If the event filter returns 1, then the window will
   569  *  be closed, otherwise the window will remain open if possible.
   570  *
   571  *  If the quit event is generated by an interrupt signal, it will bypass the
   572  *  internal queue and be delivered to the application at the next event poll.
   573  */
   574 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
   575                                                 void *userdata);
   576 
   577 /**
   578  *  Return the current event filter - can be used to "chain" filters.
   579  *  If there is no event filter set, this function returns SDL_FALSE.
   580  */
   581 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
   582                                                     void **userdata);
   583 
   584 /**
   585  *  Add a function which is called when an event is added to the queue.
   586  */
   587 extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
   588                                                void *userdata);
   589 
   590 /**
   591  *  Remove an event watch function added with SDL_AddEventWatch()
   592  */
   593 extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
   594                                                void *userdata);
   595 
   596 /**
   597  *  Run the filter function on the current event queue, removing any
   598  *  events for which the filter returns 0.
   599  */
   600 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
   601                                               void *userdata);
   602 
   603 /*@{*/
   604 #define SDL_QUERY	-1
   605 #define SDL_IGNORE	 0
   606 #define SDL_DISABLE	 0
   607 #define SDL_ENABLE	 1
   608 
   609 /**
   610  *  This function allows you to set the state of processing certain events.
   611  *   - If \c state is set to ::SDL_IGNORE, that event will be automatically 
   612  *     dropped from the event queue and will not event be filtered.
   613  *   - If \c state is set to ::SDL_ENABLE, that event will be processed 
   614  *     normally.
   615  *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the 
   616  *     current processing state of the specified event.
   617  */
   618 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
   619 /*@}*/
   620 #define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
   621 
   622 /**
   623  *  This function allocates a set of user-defined events, and returns
   624  *  the beginning event number for that set of events.
   625  *
   626  *  If there aren't enough user-defined events left, this function
   627  *  returns (Uint32)-1
   628  */
   629 extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
   630 
   631 /* Ends C function definitions when using C++ */
   632 #ifdef __cplusplus
   633 /* *INDENT-OFF* */
   634 }
   635 /* *INDENT-ON* */
   636 #endif
   637 #include "close_code.h"
   638 
   639 #endif /* _SDL_events_h */
   640 
   641 /* vi: set ts=4 sw=4 expandtab: */