include/SDL_events.h
changeset 3407 d3baf5ac4e37
parent 3280 00cace2d9080
child 3572 6bb9952d5029
     1.1 --- a/include/SDL_events.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_events.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -21,9 +21,9 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 - * \file SDL_events.h
     1.8 - *
     1.9 - * Include file for SDL event handling
    1.10 + *  \file SDL_events.h
    1.11 + *  
    1.12 + *  Include file for SDL event handling.
    1.13   */
    1.14  
    1.15  #ifndef _SDL_events_h
    1.16 @@ -50,9 +50,7 @@
    1.17  #define SDL_PRESSED	1
    1.18  
    1.19  /**
    1.20 - * \enum SDL_EventType
    1.21 - *
    1.22 - * \brief The types of events that can be delivered
    1.23 + * \brief The types of events that can be delivered.
    1.24   */
    1.25  typedef enum
    1.26  {
    1.27 @@ -76,22 +74,22 @@
    1.28      SDL_PROXIMITYIN,            /**< Proximity In event */
    1.29      SDL_PROXIMITYOUT,           /**< Proximity Out event */
    1.30      SDL_EVENT_RESERVED1,        /**< Reserved for future use... */
    1.31 -    SDL_EVENT_RESERVED2,
    1.32 -    SDL_EVENT_RESERVED3,
    1.33 -    /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
    1.34 +    SDL_EVENT_RESERVED2,        /**< Reserved for future use... */
    1.35 +    SDL_EVENT_RESERVED3,        /**< Reserved for future use... */
    1.36 +    /** Events ::SDL_USEREVENT through ::SDL_MAXEVENTS-1 are for your use */
    1.37      SDL_USEREVENT = 24,
    1.38 -    /* This last event is only for bounding internal arrays
    1.39 -       It is the number of bits in the event mask datatype -- Uint32
    1.40 +    /**
    1.41 +     *  This last event is only for bounding internal arrays
    1.42 +     *  It is the number of bits in the event mask datatype -- Uint32
    1.43       */
    1.44      SDL_NUMEVENTS = 32
    1.45  } SDL_EventType;
    1.46  
    1.47 +/*@{*/
    1.48 +#define SDL_EVENTMASK(X)	(1<<(X))
    1.49  /**
    1.50 - * \enum SDL_EventMask
    1.51 - *
    1.52   * \brief Predefined event masks
    1.53   */
    1.54 -#define SDL_EVENTMASK(X)	(1<<(X))
    1.55  typedef enum
    1.56  {
    1.57      SDL_WINDOWEVENTMASK = SDL_EVENTMASK(SDL_WINDOWEVENT),
    1.58 @@ -121,71 +119,63 @@
    1.59      SDL_PROXIMITYOUTMASK = SDL_EVENTMASK(SDL_PROXIMITYOUT)
    1.60  } SDL_EventMask;
    1.61  #define SDL_ALLEVENTS		0xFFFFFFFF
    1.62 +/*@}*/
    1.63  
    1.64  /**
    1.65 - * \struct SDL_WindowEvent
    1.66 - *
    1.67 - * \brief Window state change event data (event.window.*)
    1.68 + *  \brief Window state change event data (event.window.*)
    1.69   */
    1.70  typedef struct SDL_WindowEvent
    1.71  {
    1.72 -    Uint8 type;             /**< SDL_WINDOWEVENT */
    1.73 +    Uint8 type;             /**< ::SDL_WINDOWEVENT */
    1.74      SDL_WindowID windowID;  /**< The associated window */
    1.75 -    Uint8 event;            /**< SDL_WindowEventID */
    1.76 +    Uint8 event;            /**< ::SDL_WindowEventID */
    1.77      int data1;              /**< event dependent data */
    1.78      int data2;              /**< event dependent data */
    1.79  } SDL_WindowEvent;
    1.80  
    1.81  /**
    1.82 - * \struct SDL_KeyboardEvent
    1.83 - *
    1.84 - * \brief Keyboard button event structure (event.key.*)
    1.85 + *  \brief Keyboard button event structure (event.key.*)
    1.86   */
    1.87  typedef struct SDL_KeyboardEvent
    1.88  {
    1.89 -    Uint8 type;             /**< SDL_KEYDOWN or SDL_KEYUP */
    1.90 +    Uint8 type;             /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
    1.91      SDL_WindowID windowID;  /**< The window with keyboard focus, if any */
    1.92      Uint8 which;            /**< The keyboard device index */
    1.93 -    Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
    1.94 +    Uint8 state;            /**< ::SDL_PRESSED or ::SDL_RELEASED */
    1.95      SDL_keysym keysym;      /**< The key that was pressed or released */
    1.96  } SDL_KeyboardEvent;
    1.97  
    1.98 +#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
    1.99  /**
   1.100 - * \struct SDL_TextEditingEvent
   1.101 - *
   1.102 - * \brief Keyboard text editing event structure (event.edit.*)
   1.103 + *  \brief Keyboard text editing event structure (event.edit.*)
   1.104   */
   1.105 -#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
   1.106  typedef struct SDL_TextEditingEvent
   1.107  {
   1.108 -    Uint8 type;                                 /**< SDL_TEXTEDITING */
   1.109 +    Uint8 type;                                 /**< ::SDL_TEXTEDITING */
   1.110      char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
   1.111      int start;                                  /**< The start cursor of selected editing text */
   1.112      int length;                                 /**< The length of selected editing text */
   1.113  } SDL_TextEditingEvent;
   1.114  
   1.115 +
   1.116 +#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
   1.117  /**
   1.118 - * \struct SDL_TextInputEvent
   1.119 - *
   1.120 - * \brief Keyboard text input event structure (event.text.*)
   1.121 + *  \brief Keyboard text input event structure (event.text.*)
   1.122   */
   1.123 -#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
   1.124  typedef struct SDL_TextInputEvent
   1.125  {
   1.126 -    Uint8 type;                               /**< SDL_TEXTINPUT */
   1.127 +    Uint8 type;                               /**< ::SDL_TEXTINPUT */
   1.128      SDL_WindowID windowID;                    /**< The window with keyboard focus, if any */
   1.129      Uint8 which;                              /**< The keyboard device index */
   1.130      char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
   1.131  } SDL_TextInputEvent;
   1.132  
   1.133  /**
   1.134 - * \struct SDL_MouseMotionEvent
   1.135 - *
   1.136 - * \brief Mouse motion event structure (event.motion.*)
   1.137 + *  \brief Mouse motion event structure (event.motion.*)
   1.138   */
   1.139  typedef struct SDL_MouseMotionEvent
   1.140  {
   1.141 -    Uint8 type;             /**< SDL_MOUSEMOTION */
   1.142 +    Uint8 type;             /**< ::SDL_MOUSEMOTION */
   1.143      SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   1.144      Uint8 which;            /**< The mouse device index */
   1.145      Uint8 state;            /**< The current button state */
   1.146 @@ -203,29 +193,25 @@
   1.147  } SDL_MouseMotionEvent;
   1.148  
   1.149  /**
   1.150 - * \struct SDL_MouseButtonEvent
   1.151 - *
   1.152 - * \brief Mouse button event structure (event.button.*)
   1.153 + *  \brief Mouse button event structure (event.button.*)
   1.154   */
   1.155  typedef struct SDL_MouseButtonEvent
   1.156  {
   1.157 -    Uint8 type;             /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
   1.158 +    Uint8 type;             /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
   1.159      SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   1.160      Uint8 which;            /**< The mouse device index */
   1.161      Uint8 button;           /**< The mouse button index */
   1.162 -    Uint8 state;            /**< SDL_PRESSED or SDL_RELEASED */
   1.163 +    Uint8 state;            /**< ::SDL_PRESSED or ::SDL_RELEASED */
   1.164      int x;                  /**< X coordinate, relative to window */
   1.165      int y;                  /**< Y coordinate, relative to window */
   1.166  } SDL_MouseButtonEvent;
   1.167  
   1.168  /**
   1.169 - * \struct SDL_MouseWheelEvent
   1.170 - *
   1.171 - * \brief Mouse wheel event structure (event.wheel.*)
   1.172 + *  \brief Mouse wheel event structure (event.wheel.*)
   1.173   */
   1.174  typedef struct SDL_MouseWheelEvent
   1.175  {
   1.176 -    Uint8 type;             /**< SDL_MOUSEWHEEL */
   1.177 +    Uint8 type;             /**< ::SDL_MOUSEWHEEL */
   1.178      SDL_WindowID windowID;  /**< The window with mouse focus, if any */
   1.179      Uint8 which;            /**< The mouse device index */
   1.180      int x;                  /**< The amount scrolled horizontally */
   1.181 @@ -233,26 +219,22 @@
   1.182  } SDL_MouseWheelEvent;
   1.183  
   1.184  /**
   1.185 - * \struct SDL_JoyAxisEvent
   1.186 - *
   1.187 - * \brief Joystick axis motion event structure (event.jaxis.*)
   1.188 + *  \brief Joystick axis motion event structure (event.jaxis.*)
   1.189   */
   1.190  typedef struct SDL_JoyAxisEvent
   1.191  {
   1.192 -    Uint8 type;         /**< SDL_JOYAXISMOTION */
   1.193 +    Uint8 type;         /**< ::SDL_JOYAXISMOTION */
   1.194      Uint8 which;        /**< The joystick device index */
   1.195      Uint8 axis;         /**< The joystick axis index */
   1.196      int value;          /**< The axis value (range: -32768 to 32767) */
   1.197  } SDL_JoyAxisEvent;
   1.198  
   1.199  /**
   1.200 - * \struct SDL_JoyBallEvent
   1.201 - *
   1.202 - * \brief Joystick trackball motion event structure (event.jball.*)
   1.203 + *  \brief Joystick trackball motion event structure (event.jball.*)
   1.204   */
   1.205  typedef struct SDL_JoyBallEvent
   1.206  {
   1.207 -    Uint8 type;         /**< SDL_JOYBALLMOTION */
   1.208 +    Uint8 type;         /**< ::SDL_JOYBALLMOTION */
   1.209      Uint8 which;        /**< The joystick device index */
   1.210      Uint8 ball;         /**< The joystick trackball index */
   1.211      int xrel;           /**< The relative motion in the X direction */
   1.212 @@ -260,72 +242,64 @@
   1.213  } SDL_JoyBallEvent;
   1.214  
   1.215  /**
   1.216 - * \struct SDL_JoyHatEvent
   1.217 - *
   1.218 - * \brief Joystick hat position change event structure (event.jhat.*)
   1.219 + *  \brief Joystick hat position change event structure (event.jhat.*)
   1.220   */
   1.221  typedef struct SDL_JoyHatEvent
   1.222  {
   1.223 -    Uint8 type;         /**< SDL_JOYHATMOTION */
   1.224 +    Uint8 type;         /**< ::SDL_JOYHATMOTION */
   1.225      Uint8 which;        /**< The joystick device index */
   1.226      Uint8 hat;          /**< The joystick hat index */
   1.227 -    Uint8 value;        /**< The hat position value:
   1.228 -                             SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
   1.229 -                             SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
   1.230 -                             SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
   1.231 -                             Note that zero means the POV is centered.
   1.232 +    Uint8 value;        /**< The hat position value.
   1.233 +                         *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
   1.234 +                         *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
   1.235 +                         *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
   1.236 +                         *   
   1.237 +                         *   Note that zero means the POV is centered.
   1.238                           */
   1.239  } SDL_JoyHatEvent;
   1.240  
   1.241  /**
   1.242 - * \struct SDL_JoyButtonEvent
   1.243 - *
   1.244 - * \brief Joystick button event structure (event.jbutton.*)
   1.245 + *  \brief Joystick button event structure (event.jbutton.*)
   1.246   */
   1.247  typedef struct SDL_JoyButtonEvent
   1.248  {
   1.249 -    Uint8 type;         /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
   1.250 +    Uint8 type;         /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
   1.251      Uint8 which;        /**< The joystick device index */
   1.252      Uint8 button;       /**< The joystick button index */
   1.253 -    Uint8 state;        /**< SDL_PRESSED or SDL_RELEASED */
   1.254 +    Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   1.255  } SDL_JoyButtonEvent;
   1.256  
   1.257  /**
   1.258 - * \struct SDL_QuitEvent
   1.259 - *
   1.260 - * \brief The "quit requested" event
   1.261 + *  \brief The "quit requested" event
   1.262   */
   1.263  typedef struct SDL_QuitEvent
   1.264  {
   1.265 -    Uint8 type;         /**< SDL_QUIT */
   1.266 +    Uint8 type;         /**< ::SDL_QUIT */
   1.267  } SDL_QuitEvent;
   1.268  
   1.269  /**
   1.270 - * \struct SDL_UserEvent
   1.271 - *
   1.272 - * \brief A user-defined event type (event.user.*)
   1.273 + *  \brief A user-defined event type (event.user.*)
   1.274   */
   1.275  typedef struct SDL_UserEvent
   1.276  {
   1.277 -    Uint8 type;             /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
   1.278 +    Uint8 type;             /**< ::SDL_USEREVENT through ::SDL_NUMEVENTS-1 */
   1.279      SDL_WindowID windowID;  /**< The associated window if any*/
   1.280      int code;               /**< User defined event code */
   1.281      void *data1;            /**< User defined data pointer */
   1.282      void *data2;            /**< User defined data pointer */
   1.283  } SDL_UserEvent;
   1.284  
   1.285 -/**
   1.286 - * \struct SDL_SysWMEvent
   1.287 - *
   1.288 - * \brief A video driver dependent system event (event.syswm.*)
   1.289 - *
   1.290 - * \note If you want to use this event, you should include SDL_syswm.h
   1.291 - */
   1.292  struct SDL_SysWMmsg;
   1.293  typedef struct SDL_SysWMmsg SDL_SysWMmsg;
   1.294 +
   1.295 +/**
   1.296 + *  \brief A video driver dependent system event (event.syswm.*)
   1.297 + *  
   1.298 + *  \note If you want to use this event, you should include SDL_syswm.h.
   1.299 + */
   1.300  typedef struct SDL_SysWMEvent
   1.301  {
   1.302 -    Uint8 type;         /**< SDL_SYSWMEVENT */
   1.303 +    Uint8 type;         /**< ::SDL_SYSWMEVENT */
   1.304      SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
   1.305  } SDL_SysWMEvent;
   1.306  
   1.307 @@ -339,8 +313,16 @@
   1.308      int y;
   1.309  } SDL_ProximityEvent;
   1.310  
   1.311 -/* Typedefs for backwards compatibility */
   1.312  #ifndef SDL_NO_COMPAT
   1.313 +/**
   1.314 + *  \addtogroup Compatibility 
   1.315 + */
   1.316 +/*@{*/
   1.317 +
   1.318 +/**
   1.319 + *  \name Typedefs for backwards compatibility
   1.320 + */
   1.321 +/*@{*/
   1.322  typedef struct SDL_ActiveEvent
   1.323  {
   1.324      Uint8 type;
   1.325 @@ -354,12 +336,13 @@
   1.326      int w;
   1.327      int h;
   1.328  } SDL_ResizeEvent;
   1.329 +/*@}*/
   1.330 +
   1.331 +/*@}*//*Compatibility*/
   1.332  #endif
   1.333  
   1.334  /**
   1.335 - * \union SDL_Event
   1.336 - *
   1.337 - * \brief General event structure
   1.338 + *  \brief General event structure
   1.339   */
   1.340  typedef union SDL_Event
   1.341  {
   1.342 @@ -380,129 +363,164 @@
   1.343      SDL_SysWMEvent syswm;           /**< System dependent window event data */
   1.344      SDL_ProximityEvent proximity;   /**< Proximity In or Out event */
   1.345  
   1.346 -    /* Temporarily here for backwards compatibility */
   1.347 +    /** Temporarily here for backwards compatibility */
   1.348 +    /*@{*/
   1.349  #ifndef SDL_NO_COMPAT
   1.350      SDL_ActiveEvent active;
   1.351      SDL_ResizeEvent resize;
   1.352  #endif
   1.353 +    /*@}*/
   1.354  } SDL_Event;
   1.355  
   1.356  
   1.357  /* Function prototypes */
   1.358  
   1.359 -/* Pumps the event loop, gathering events from the input devices.
   1.360 -   This function updates the event queue and internal input device state.
   1.361 -   This should only be run in the thread that sets the video mode.
   1.362 -*/
   1.363 +/**
   1.364 + *  Pumps the event loop, gathering events from the input devices.
   1.365 + *  
   1.366 + *  This function updates the event queue and internal input device state.
   1.367 + *  
   1.368 + *  This should only be run in the thread that sets the video mode.
   1.369 + */
   1.370  extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   1.371  
   1.372 -/* Checks the event queue for messages and optionally returns them.
   1.373 -   If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
   1.374 -   the back of the event queue.
   1.375 -   If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
   1.376 -   of the event queue, matching 'mask', will be returned and will not
   1.377 -   be removed from the queue.
   1.378 -   If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
   1.379 -   of the event queue, matching 'mask', will be returned and will be
   1.380 -   removed from the queue.
   1.381 -   This function returns the number of events actually stored, or -1
   1.382 -   if there was an error.  This function is thread-safe.
   1.383 -*/
   1.384 +/*@{*/
   1.385  typedef enum
   1.386  {
   1.387      SDL_ADDEVENT,
   1.388      SDL_PEEKEVENT,
   1.389      SDL_GETEVENT
   1.390  } SDL_eventaction;
   1.391 -/* */
   1.392 +
   1.393 +/**
   1.394 + *  Checks the event queue for messages and optionally returns them.
   1.395 + *  
   1.396 + *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
   1.397 + *  the back of the event queue.
   1.398 + *  
   1.399 + *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
   1.400 + *  of the event queue, matching \c mask, will be returned and will not
   1.401 + *  be removed from the queue.
   1.402 + *  
   1.403 + *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front 
   1.404 + *  of the event queue, matching \c mask, will be returned and will be
   1.405 + *  removed from the queue.
   1.406 + *  
   1.407 + *  \return The number of events actually stored, or -1 if there was an error.
   1.408 + *  
   1.409 + *  This function is thread-safe.
   1.410 + */
   1.411  extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   1.412                                             SDL_eventaction action,
   1.413                                             Uint32 mask);
   1.414 +/*@}*/
   1.415  
   1.416 -/* Checks to see if certain event types are in the event queue.
   1.417 +/**
   1.418 + *  Checks to see if certain event types are in the event queue.
   1.419   */
   1.420  extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 mask);
   1.421  
   1.422 -/* Polls for currently pending events, and returns 1 if there are any pending
   1.423 -   events, or 0 if there are none available.  If 'event' is not NULL, the next
   1.424 -   event is removed from the queue and stored in that area.
   1.425 +/**
   1.426 + *  \brief Polls for currently pending events.
   1.427 + *  
   1.428 + *  \return 1 if there are any pending events, or 0 if there are none available.
   1.429 + *  
   1.430 + *  \param event If not NULL, the next event is removed from the queue and 
   1.431 + *               stored in that area.
   1.432   */
   1.433  extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   1.434  
   1.435 -/* Waits indefinitely for the next available event, returning 1, or 0 if there
   1.436 -   was an error while waiting for events.  If 'event' is not NULL, the next
   1.437 -   event is removed from the queue and stored in that area.
   1.438 +/**
   1.439 + *  \brief Waits indefinitely for the next available event.
   1.440 + *  
   1.441 + *  \return 1, or 0 if there was an error while waiting for events.
   1.442 + *   
   1.443 + *  \param event If not NULL, the next event is removed from the queue and 
   1.444 + *               stored in that area.
   1.445   */
   1.446  extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
   1.447  
   1.448 -/* Waits until the specified timeout (in milliseconds) for the next available
   1.449 -   event, returning 1, or 0 if there was an error while waiting for events. If
   1.450 -   'event' is not NULL, the next event is removed from the queue and stored in
   1.451 -   that area.
   1.452 +/**
   1.453 + *  \brief Waits until the specified timeout (in milliseconds) for the next 
   1.454 + *         available event.
   1.455 + *  
   1.456 + *  \return 1, or 0 if there was an error while waiting for events.
   1.457 + *  
   1.458 + *  \param event If not NULL, the next event is removed from the queue and 
   1.459 + *               stored in that area.
   1.460   */
   1.461  extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
   1.462                                                   int timeout);
   1.463  
   1.464 -/* Add an event to the event queue.
   1.465 -   This function returns 1 on success, 0 if the event was filtered,
   1.466 -   or -1 if the event queue was full or there was some other error.
   1.467 +/**
   1.468 + *  \brief Add an event to the event queue.
   1.469 + *  
   1.470 + *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue 
   1.471 + *          was full or there was some other error.
   1.472   */
   1.473  extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   1.474  
   1.475 -/*
   1.476 -  This function sets up a filter to process all events before they
   1.477 -  change internal state and are posted to the internal event queue.
   1.478 +typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   1.479  
   1.480 -  The filter is protypted as:
   1.481 -*/
   1.482 -typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
   1.483 -/*
   1.484 -  If the filter returns 1, then the event will be added to the internal queue.
   1.485 -  If it returns 0, then the event will be dropped from the queue, but the 
   1.486 -  internal state will still be updated.  This allows selective filtering of
   1.487 -  dynamically arriving events.
   1.488 -
   1.489 -  WARNING:  Be very careful of what you do in the event filter function, as 
   1.490 -            it may run in a different thread!
   1.491 -
   1.492 -  There is one caveat when dealing with the SDL_QUITEVENT event type.  The
   1.493 -  event filter is only called when the window manager desires to close the
   1.494 -  application window.  If the event filter returns 1, then the window will
   1.495 -  be closed, otherwise the window will remain open if possible.
   1.496 -  If the quit event is generated by an interrupt signal, it will bypass the
   1.497 -  internal queue and be delivered to the application at the next event poll.
   1.498 -*/
   1.499 +/**
   1.500 + *  Sets up a filter to process all events before they change internal state and
   1.501 + *  are posted to the internal event queue.
   1.502 + *  
   1.503 + *  The filter is protypted as:
   1.504 + *  \code
   1.505 + *      int SDL_EventFilter(void *userdata, SDL_Event * event);
   1.506 + *  \endcode
   1.507 + *
   1.508 + *  If the filter returns 1, then the event will be added to the internal queue.
   1.509 + *  If it returns 0, then the event will be dropped from the queue, but the 
   1.510 + *  internal state will still be updated.  This allows selective filtering of
   1.511 + *  dynamically arriving events.
   1.512 + *  
   1.513 + *  \warning  Be very careful of what you do in the event filter function, as 
   1.514 + *            it may run in a different thread!
   1.515 + *  
   1.516 + *  There is one caveat when dealing with the ::SDL_QUITEVENT event type.  The
   1.517 + *  event filter is only called when the window manager desires to close the
   1.518 + *  application window.  If the event filter returns 1, then the window will
   1.519 + *  be closed, otherwise the window will remain open if possible.
   1.520 + *
   1.521 + *  If the quit event is generated by an interrupt signal, it will bypass the
   1.522 + *  internal queue and be delivered to the application at the next event poll.
   1.523 + */
   1.524  extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
   1.525                                                  void *userdata);
   1.526  
   1.527 -/*
   1.528 -  Return the current event filter - can be used to "chain" filters.
   1.529 -  If there is no event filter set, this function returns SDL_FALSE.
   1.530 -*/
   1.531 +/**
   1.532 + *  Return the current event filter - can be used to "chain" filters.
   1.533 + *  If there is no event filter set, this function returns SDL_FALSE.
   1.534 + */
   1.535  extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
   1.536                                                      void **userdata);
   1.537  
   1.538 -/*
   1.539 -  Run the filter function on the current event queue, removing any
   1.540 -  events for which the filter returns 0.
   1.541 -*/
   1.542 +/**
   1.543 + *  Run the filter function on the current event queue, removing any
   1.544 + *  events for which the filter returns 0.
   1.545 + */
   1.546  extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
   1.547                                                void *userdata);
   1.548  
   1.549 -/*
   1.550 -  This function allows you to set the state of processing certain events.
   1.551 -  If 'state' is set to SDL_IGNORE, that event will be automatically dropped
   1.552 -  from the event queue and will not event be filtered.
   1.553 -  If 'state' is set to SDL_ENABLE, that event will be processed normally.
   1.554 -  If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
   1.555 -  current processing state of the specified event.
   1.556 -*/
   1.557 +/*@{*/
   1.558  #define SDL_QUERY	-1
   1.559  #define SDL_IGNORE	 0
   1.560  #define SDL_DISABLE	 0
   1.561  #define SDL_ENABLE	 1
   1.562 +
   1.563 +/**
   1.564 + *  This function allows you to set the state of processing certain events.
   1.565 + *   - If \c state is set to ::SDL_IGNORE, that event will be automatically 
   1.566 + *     dropped from the event queue and will not event be filtered.
   1.567 + *   - If \c state is set to ::SDL_ENABLE, that event will be processed 
   1.568 + *     normally.
   1.569 + *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the 
   1.570 + *     current processing state of the specified event.
   1.571 + */
   1.572  extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
   1.573 -
   1.574 +/*@}*/
   1.575  
   1.576  /* Ends C function definitions when using C++ */
   1.577  #ifdef __cplusplus