include/SDL_events.h
changeset 7191 75360622e65f
parent 7190 11612d544fcd
child 7203 c74f5dbcfd23
     1.1 --- a/include/SDL_events.h	Sat May 18 12:48:50 2013 -0700
     1.2 +++ b/include/SDL_events.h	Sat May 18 14:17:52 2013 -0700
     1.3 @@ -21,7 +21,7 @@
     1.4  
     1.5  /**
     1.6   *  \file SDL_events.h
     1.7 - *  
     1.8 + *
     1.9   *  Include file for SDL event handling.
    1.10   */
    1.11  
    1.12 @@ -42,14 +42,12 @@
    1.13  #include "begin_code.h"
    1.14  /* Set up for C function definitions, even when using C++ */
    1.15  #ifdef __cplusplus
    1.16 -/* *INDENT-OFF* */
    1.17  extern "C" {
    1.18 -/* *INDENT-ON* */
    1.19  #endif
    1.20  
    1.21  /* General keyboard/mouse state definitions */
    1.22 -#define SDL_RELEASED	0
    1.23 -#define SDL_PRESSED	1
    1.24 +#define SDL_RELEASED    0
    1.25 +#define SDL_PRESSED 1
    1.26  
    1.27  /**
    1.28   * \brief The types of events that can be delivered.
    1.29 @@ -62,27 +60,27 @@
    1.30      SDL_QUIT           = 0x100, /**< User-requested quit */
    1.31  
    1.32      /* These application events have special meaning on iOS, see README.iOS for details */
    1.33 -	SDL_APP_TERMINATING,        /**< The application is being terminated by the OS
    1.34 +    SDL_APP_TERMINATING,        /**< The application is being terminated by the OS
    1.35                                       Called on iOS in applicationWillTerminate()
    1.36                                       Called on Android in onDestroy()
    1.37                                  */
    1.38 -	SDL_APP_LOWMEMORY,          /**< The application is low on memory, free memory if possible.
    1.39 +    SDL_APP_LOWMEMORY,          /**< The application is low on memory, free memory if possible.
    1.40                                       Called on iOS in applicationDidReceiveMemoryWarning()
    1.41                                       Called on Android in onLowMemory()
    1.42                                  */
    1.43 -	SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background
    1.44 +    SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background
    1.45                                       Called on iOS in applicationWillResignActive()
    1.46                                       Called on Android in onPause()
    1.47                                  */
    1.48 -	SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time
    1.49 +    SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time
    1.50                                       Called on iOS in applicationDidEnterBackground()
    1.51                                       Called on Android in onPause()
    1.52                                  */
    1.53 -	SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground
    1.54 +    SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground
    1.55                                       Called on iOS in applicationWillEnterForeground()
    1.56                                       Called on Android in onResume()
    1.57                                  */
    1.58 -	SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive
    1.59 +    SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive
    1.60                                       Called on iOS in applicationDidBecomeActive()
    1.61                                       Called on Android in onResume()
    1.62                                  */
    1.63 @@ -112,13 +110,13 @@
    1.64      SDL_JOYDEVICEADDED,         /**< A new joystick has been inserted into the system */
    1.65      SDL_JOYDEVICEREMOVED,       /**< An opened joystick has been removed */
    1.66  
    1.67 -	/* Game controller events */
    1.68 -	SDL_CONTROLLERAXISMOTION  = 0x650, /**< Game controller axis motion */
    1.69 -	SDL_CONTROLLERBUTTONDOWN,          /**< Game controller button pressed */
    1.70 -	SDL_CONTROLLERBUTTONUP,            /**< Game controller button released */
    1.71 -	SDL_CONTROLLERDEVICEADDED,         /**< A new Game controller has been inserted into the system */
    1.72 -	SDL_CONTROLLERDEVICEREMOVED,       /**< An opened Game controller has been removed */
    1.73 -	SDL_CONTROLLERDEVICEREMAPPED,      /**< The controller mapping was updated */
    1.74 +    /* Game controller events */
    1.75 +    SDL_CONTROLLERAXISMOTION  = 0x650, /**< Game controller axis motion */
    1.76 +    SDL_CONTROLLERBUTTONDOWN,          /**< Game controller button pressed */
    1.77 +    SDL_CONTROLLERBUTTONUP,            /**< Game controller button released */
    1.78 +    SDL_CONTROLLERDEVICEADDED,         /**< A new Game controller has been inserted into the system */
    1.79 +    SDL_CONTROLLERDEVICEREMOVED,       /**< An opened Game controller has been removed */
    1.80 +    SDL_CONTROLLERDEVICEREMAPPED,      /**< The controller mapping was updated */
    1.81  
    1.82      /* Touch events */
    1.83      SDL_FINGERDOWN      = 0x700,
    1.84 @@ -135,7 +133,7 @@
    1.85  
    1.86      /* Drag and drop events */
    1.87      SDL_DROPFILE        = 0x1000, /**< The system requests a file open */
    1.88 -	
    1.89 +
    1.90      /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
    1.91       *  and should be allocated with SDL_RegisterEvents()
    1.92       */
    1.93 @@ -155,7 +153,7 @@
    1.94      Uint32 type;
    1.95      Uint32 timestamp;
    1.96  } SDL_CommonEvent;
    1.97 -    
    1.98 +
    1.99  /**
   1.100   *  \brief Window state change event data (event.window.*)
   1.101   */
   1.102 @@ -285,7 +283,7 @@
   1.103  typedef struct SDL_JoyBallEvent
   1.104  {
   1.105      Uint32 type;        /**< ::SDL_JOYBALLMOTION */
   1.106 -	Uint32 timestamp;
   1.107 +    Uint32 timestamp;
   1.108      SDL_JoystickID which; /**< The joystick instance id */
   1.109      Uint8 ball;         /**< The joystick trackball index */
   1.110      Uint8 padding1;
   1.111 @@ -301,14 +299,14 @@
   1.112  typedef struct SDL_JoyHatEvent
   1.113  {
   1.114      Uint32 type;        /**< ::SDL_JOYHATMOTION */
   1.115 -	Uint32 timestamp;
   1.116 +    Uint32 timestamp;
   1.117      SDL_JoystickID which; /**< The joystick instance id */
   1.118      Uint8 hat;          /**< The joystick hat index */
   1.119      Uint8 value;        /**< The hat position value.
   1.120                           *   \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
   1.121                           *   \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
   1.122                           *   \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
   1.123 -                         *   
   1.124 +                         *
   1.125                           *   Note that zero means the POV is centered.
   1.126                           */
   1.127      Uint8 padding1;
   1.128 @@ -321,7 +319,7 @@
   1.129  typedef struct SDL_JoyButtonEvent
   1.130  {
   1.131      Uint32 type;        /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
   1.132 -	Uint32 timestamp;
   1.133 +    Uint32 timestamp;
   1.134      SDL_JoystickID which; /**< The joystick instance id */
   1.135      Uint8 button;       /**< The joystick button index */
   1.136      Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   1.137 @@ -334,9 +332,9 @@
   1.138   */
   1.139  typedef struct SDL_JoyDeviceEvent
   1.140  {
   1.141 -	Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
   1.142 -	Uint32 timestamp;
   1.143 -	Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
   1.144 +    Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
   1.145 +    Uint32 timestamp;
   1.146 +    Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
   1.147  } SDL_JoyDeviceEvent;
   1.148  
   1.149  
   1.150 @@ -346,7 +344,7 @@
   1.151  typedef struct SDL_ControllerAxisEvent
   1.152  {
   1.153      Uint32 type;        /**< ::SDL_CONTROLLERAXISMOTION */
   1.154 -	Uint32 timestamp;
   1.155 +    Uint32 timestamp;
   1.156      SDL_JoystickID which; /**< The joystick instance id */
   1.157      Uint8 axis;         /**< The controller axis (SDL_GameControllerAxis) */
   1.158      Uint8 padding1;
   1.159 @@ -363,7 +361,7 @@
   1.160  typedef struct SDL_ControllerButtonEvent
   1.161  {
   1.162      Uint32 type;        /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
   1.163 -	Uint32 timestamp;
   1.164 +    Uint32 timestamp;
   1.165      SDL_JoystickID which; /**< The joystick instance id */
   1.166      Uint8 button;       /**< The controller button (SDL_GameControllerButton) */
   1.167      Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   1.168 @@ -377,9 +375,9 @@
   1.169   */
   1.170  typedef struct SDL_ControllerDeviceEvent
   1.171  {
   1.172 -	Uint32 type;        /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */
   1.173 -	Uint32 timestamp;
   1.174 -	Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
   1.175 +    Uint32 type;        /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */
   1.176 +    Uint32 timestamp;
   1.177 +    Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
   1.178  } SDL_ControllerDeviceEvent;
   1.179  
   1.180  
   1.181 @@ -411,7 +409,7 @@
   1.182      float dTheta;
   1.183      float dDist;
   1.184      float x;
   1.185 -    float y;  
   1.186 +    float y;
   1.187      Uint16 numFingers;
   1.188      Uint16 padding;
   1.189  } SDL_MultiGestureEvent;
   1.190 @@ -511,9 +509,9 @@
   1.191      SDL_JoyHatEvent jhat;           /**< Joystick hat event data */
   1.192      SDL_JoyButtonEvent jbutton;     /**< Joystick button event data */
   1.193      SDL_JoyDeviceEvent jdevice;     /**< Joystick device change event data */
   1.194 -	SDL_ControllerAxisEvent caxis;		/**< Game Controller axis event data */
   1.195 -	SDL_ControllerButtonEvent cbutton;  /**< Game Controller button event data */
   1.196 -	SDL_ControllerDeviceEvent cdevice;  /**< Game Controller device event data */
   1.197 +    SDL_ControllerAxisEvent caxis;      /**< Game Controller axis event data */
   1.198 +    SDL_ControllerButtonEvent cbutton;  /**< Game Controller button event data */
   1.199 +    SDL_ControllerDeviceEvent cdevice;  /**< Game Controller device event data */
   1.200      SDL_QuitEvent quit;             /**< Quit request event data */
   1.201      SDL_UserEvent user;             /**< Custom event data */
   1.202      SDL_SysWMEvent syswm;           /**< System dependent window event data */
   1.203 @@ -537,9 +535,9 @@
   1.204  
   1.205  /**
   1.206   *  Pumps the event loop, gathering events from the input devices.
   1.207 - *  
   1.208 + *
   1.209   *  This function updates the event queue and internal input device state.
   1.210 - *  
   1.211 + *
   1.212   *  This should only be run in the thread that sets the video mode.
   1.213   */
   1.214  extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
   1.215 @@ -554,20 +552,20 @@
   1.216  
   1.217  /**
   1.218   *  Checks the event queue for messages and optionally returns them.
   1.219 - *  
   1.220 + *
   1.221   *  If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
   1.222   *  the back of the event queue.
   1.223 - *  
   1.224 + *
   1.225   *  If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
   1.226   *  of the event queue, within the specified minimum and maximum type,
   1.227   *  will be returned and will not be removed from the queue.
   1.228 - *  
   1.229 - *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front 
   1.230 + *
   1.231 + *  If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
   1.232   *  of the event queue, within the specified minimum and maximum type,
   1.233   *  will be returned and will be removed from the queue.
   1.234 - *  
   1.235 + *
   1.236   *  \return The number of events actually stored, or -1 if there was an error.
   1.237 - *  
   1.238 + *
   1.239   *  This function is thread-safe.
   1.240   */
   1.241  extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
   1.242 @@ -589,31 +587,31 @@
   1.243  
   1.244  /**
   1.245   *  \brief Polls for currently pending events.
   1.246 - *  
   1.247 + *
   1.248   *  \return 1 if there are any pending events, or 0 if there are none available.
   1.249 - *  
   1.250 - *  \param event If not NULL, the next event is removed from the queue and 
   1.251 + *
   1.252 + *  \param event If not NULL, the next event is removed from the queue and
   1.253   *               stored in that area.
   1.254   */
   1.255  extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
   1.256  
   1.257  /**
   1.258   *  \brief Waits indefinitely for the next available event.
   1.259 - *  
   1.260 + *
   1.261   *  \return 1, or 0 if there was an error while waiting for events.
   1.262 - *   
   1.263 - *  \param event If not NULL, the next event is removed from the queue and 
   1.264 + *
   1.265 + *  \param event If not NULL, the next event is removed from the queue and
   1.266   *               stored in that area.
   1.267   */
   1.268  extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
   1.269  
   1.270  /**
   1.271 - *  \brief Waits until the specified timeout (in milliseconds) for the next 
   1.272 + *  \brief Waits until the specified timeout (in milliseconds) for the next
   1.273   *         available event.
   1.274 - *  
   1.275 + *
   1.276   *  \return 1, or 0 if there was an error while waiting for events.
   1.277 - *  
   1.278 - *  \param event If not NULL, the next event is removed from the queue and 
   1.279 + *
   1.280 + *  \param event If not NULL, the next event is removed from the queue and
   1.281   *               stored in that area.
   1.282   *  \param timeout The timeout (in milliseconds) to wait for next event.
   1.283   */
   1.284 @@ -622,8 +620,8 @@
   1.285  
   1.286  /**
   1.287   *  \brief Add an event to the event queue.
   1.288 - *  
   1.289 - *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue 
   1.290 + *
   1.291 + *  \return 1 on success, 0 if the event was filtered, or -1 if the event queue
   1.292   *          was full or there was some other error.
   1.293   */
   1.294  extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
   1.295 @@ -633,20 +631,20 @@
   1.296  /**
   1.297   *  Sets up a filter to process all events before they change internal state and
   1.298   *  are posted to the internal event queue.
   1.299 - *  
   1.300 + *
   1.301   *  The filter is prototyped as:
   1.302   *  \code
   1.303   *      int SDL_EventFilter(void *userdata, SDL_Event * event);
   1.304   *  \endcode
   1.305   *
   1.306   *  If the filter returns 1, then the event will be added to the internal queue.
   1.307 - *  If it returns 0, then the event will be dropped from the queue, but the 
   1.308 + *  If it returns 0, then the event will be dropped from the queue, but the
   1.309   *  internal state will still be updated.  This allows selective filtering of
   1.310   *  dynamically arriving events.
   1.311 - *  
   1.312 - *  \warning  Be very careful of what you do in the event filter function, as 
   1.313 + *
   1.314 + *  \warning  Be very careful of what you do in the event filter function, as
   1.315   *            it may run in a different thread!
   1.316 - *  
   1.317 + *
   1.318   *  There is one caveat when dealing with the ::SDL_QUITEVENT event type.  The
   1.319   *  event filter is only called when the window manager desires to close the
   1.320   *  application window.  If the event filter returns 1, then the window will
   1.321 @@ -685,18 +683,18 @@
   1.322                                                void *userdata);
   1.323  
   1.324  /*@{*/
   1.325 -#define SDL_QUERY	-1
   1.326 -#define SDL_IGNORE	 0
   1.327 -#define SDL_DISABLE	 0
   1.328 -#define SDL_ENABLE	 1
   1.329 +#define SDL_QUERY   -1
   1.330 +#define SDL_IGNORE   0
   1.331 +#define SDL_DISABLE  0
   1.332 +#define SDL_ENABLE   1
   1.333  
   1.334  /**
   1.335   *  This function allows you to set the state of processing certain events.
   1.336 - *   - If \c state is set to ::SDL_IGNORE, that event will be automatically 
   1.337 + *   - If \c state is set to ::SDL_IGNORE, that event will be automatically
   1.338   *     dropped from the event queue and will not event be filtered.
   1.339 - *   - If \c state is set to ::SDL_ENABLE, that event will be processed 
   1.340 + *   - If \c state is set to ::SDL_ENABLE, that event will be processed
   1.341   *     normally.
   1.342 - *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the 
   1.343 + *   - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
   1.344   *     current processing state of the specified event.
   1.345   */
   1.346  extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
   1.347 @@ -714,9 +712,7 @@
   1.348  
   1.349  /* Ends C function definitions when using C++ */
   1.350  #ifdef __cplusplus
   1.351 -/* *INDENT-OFF* */
   1.352  }
   1.353 -/* *INDENT-ON* */
   1.354  #endif
   1.355  #include "close_code.h"
   1.356