misc/builddeps/win32/sdl/include/SDL/SDL_events.h

   1 /*
   2     SDL - Simple DirectMedia Layer
   3     Copyright (C) 1997-2009 Sam Lantinga
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Lesser General Public
   7     License as published by the Free Software Foundation; either
   8     version 2.1 of the License, or (at your option) any later version.
   9
  10     This library is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13     Lesser General Public License for more details.
  14
  15     You should have received a copy of the GNU Lesser General Public
  16     License along with this library; if not, write to the Free Software
  17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19     Sam Lantinga
  20     slouken@libsdl.org
  21 */
  22
  23 /**
  24  *  @file SDL_events.h
  25  *  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_active.h"
  34 #include "SDL_keyboard.h"
  35 #include "SDL_mouse.h"
  36 #include "SDL_joystick.h"
  37 #include "SDL_quit.h"
  38
  39 #include "begin_code.h"
  40 /* Set up for C function definitions, even when using C++ */
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /** @name General keyboard/mouse state definitions */
  46 /*@{*/
  47 #define SDL_RELEASED    0
  48 #define SDL_PRESSED     1
  49 /*@}*/
  50
  51 /** Event enumerations */
  52 typedef enum {
  53        SDL_NOEVENT = 0,                 /**< Unused (do not remove) */
  54        SDL_ACTIVEEVENT,                 /**< Application loses/gains visibility */
  55        SDL_KEYDOWN,                     /**< Keys pressed */
  56        SDL_KEYUP,                       /**< Keys released */
  57        SDL_MOUSEMOTION,                 /**< Mouse moved */
  58        SDL_MOUSEBUTTONDOWN,             /**< Mouse button pressed */
  59        SDL_MOUSEBUTTONUP,               /**< Mouse button released */
  60        SDL_JOYAXISMOTION,               /**< Joystick axis motion */
  61        SDL_JOYBALLMOTION,               /**< Joystick trackball motion */
  62        SDL_JOYHATMOTION,                /**< Joystick hat position change */
  63        SDL_JOYBUTTONDOWN,               /**< Joystick button pressed */
  64        SDL_JOYBUTTONUP,                 /**< Joystick button released */
  65        SDL_QUIT,                        /**< User-requested quit */
  66        SDL_SYSWMEVENT,                  /**< System specific event */
  67        SDL_EVENT_RESERVEDA,             /**< Reserved for future use.. */
  68        SDL_EVENT_RESERVEDB,             /**< Reserved for future use.. */
  69        SDL_VIDEORESIZE,                 /**< User resized video mode */
  70        SDL_VIDEOEXPOSE,                 /**< Screen needs to be redrawn */
  71        SDL_EVENT_RESERVED2,             /**< Reserved for future use.. */
  72        SDL_EVENT_RESERVED3,             /**< Reserved for future use.. */
  73        SDL_EVENT_RESERVED4,             /**< Reserved for future use.. */
  74        SDL_EVENT_RESERVED5,             /**< Reserved for future use.. */
  75        SDL_EVENT_RESERVED6,             /**< Reserved for future use.. */
  76        SDL_EVENT_RESERVED7,             /**< Reserved for future use.. */
  77        /** Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
  78        SDL_USEREVENT = 24,
  79        /** This last event is only for bounding internal arrays
  80         *  It is the number of bits in the event mask datatype -- Uint32
  81         */
  82        SDL_NUMEVENTS = 32
  83 } SDL_EventType;
  84
  85 /** @name Predefined event masks */
  86 /*@{*/
  87 #define SDL_EVENTMASK(X)        (1<<(X))
  88 typedef enum {
  89         SDL_ACTIVEEVENTMASK     = SDL_EVENTMASK(SDL_ACTIVEEVENT),
  90         SDL_KEYDOWNMASK         = SDL_EVENTMASK(SDL_KEYDOWN),
  91         SDL_KEYUPMASK           = SDL_EVENTMASK(SDL_KEYUP),
  92         SDL_KEYEVENTMASK        = SDL_EVENTMASK(SDL_KEYDOWN)|
  93                                   SDL_EVENTMASK(SDL_KEYUP),
  94         SDL_MOUSEMOTIONMASK     = SDL_EVENTMASK(SDL_MOUSEMOTION),
  95         SDL_MOUSEBUTTONDOWNMASK = SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN),
  96         SDL_MOUSEBUTTONUPMASK   = SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
  97         SDL_MOUSEEVENTMASK      = SDL_EVENTMASK(SDL_MOUSEMOTION)|
  98                                   SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)|
  99                                   SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
 100         SDL_JOYAXISMOTIONMASK   = SDL_EVENTMASK(SDL_JOYAXISMOTION),
 101         SDL_JOYBALLMOTIONMASK   = SDL_EVENTMASK(SDL_JOYBALLMOTION),
 102         SDL_JOYHATMOTIONMASK    = SDL_EVENTMASK(SDL_JOYHATMOTION),
 103         SDL_JOYBUTTONDOWNMASK   = SDL_EVENTMASK(SDL_JOYBUTTONDOWN),
 104         SDL_JOYBUTTONUPMASK     = SDL_EVENTMASK(SDL_JOYBUTTONUP),
 105         SDL_JOYEVENTMASK        = SDL_EVENTMASK(SDL_JOYAXISMOTION)|
 106                                   SDL_EVENTMASK(SDL_JOYBALLMOTION)|
 107                                   SDL_EVENTMASK(SDL_JOYHATMOTION)|
 108                                   SDL_EVENTMASK(SDL_JOYBUTTONDOWN)|
 109                                   SDL_EVENTMASK(SDL_JOYBUTTONUP),
 110         SDL_VIDEORESIZEMASK     = SDL_EVENTMASK(SDL_VIDEORESIZE),
 111         SDL_VIDEOEXPOSEMASK     = SDL_EVENTMASK(SDL_VIDEOEXPOSE),
 112         SDL_QUITMASK            = SDL_EVENTMASK(SDL_QUIT),
 113         SDL_SYSWMEVENTMASK      = SDL_EVENTMASK(SDL_SYSWMEVENT)
 114 } SDL_EventMask ;
 115 #define SDL_ALLEVENTS           0xFFFFFFFF
 116 /*@}*/
 117
 118 /** Application visibility event structure */
 119 typedef struct SDL_ActiveEvent {
 120         Uint8 type;     /**< SDL_ACTIVEEVENT */
 121         Uint8 gain;     /**< Whether given states were gained or lost (1/0) */
 122         Uint8 state;    /**< A mask of the focus states */
 123 } SDL_ActiveEvent;
 124
 125 /** Keyboard event structure */
 126 typedef struct SDL_KeyboardEvent {
 127         Uint8 type;     /**< SDL_KEYDOWN or SDL_KEYUP */
 128         Uint8 which;    /**< The keyboard device index */
 129         Uint8 state;    /**< SDL_PRESSED or SDL_RELEASED */
 130         SDL_keysym keysym;
 131 } SDL_KeyboardEvent;
 132
 133 /** Mouse motion event structure */
 134 typedef struct SDL_MouseMotionEvent {
 135         Uint8 type;     /**< SDL_MOUSEMOTION */
 136         Uint8 which;    /**< The mouse device index */
 137         Uint8 state;    /**< The current button state */
 138         Uint16 x, y;    /**< The X/Y coordinates of the mouse */
 139         Sint16 xrel;    /**< The relative motion in the X direction */
 140         Sint16 yrel;    /**< The relative motion in the Y direction */
 141 } SDL_MouseMotionEvent;
 142
 143 /** Mouse button event structure */
 144 typedef struct SDL_MouseButtonEvent {
 145         Uint8 type;     /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
 146         Uint8 which;    /**< The mouse device index */
 147         Uint8 button;   /**< The mouse button index */
 148         Uint8 state;    /**< SDL_PRESSED or SDL_RELEASED */
 149         Uint16 x, y;    /**< The X/Y coordinates of the mouse at press time */
 150 } SDL_MouseButtonEvent;
 151
 152 /** Joystick axis motion event structure */
 153 typedef struct SDL_JoyAxisEvent {
 154         Uint8 type;     /**< SDL_JOYAXISMOTION */
 155         Uint8 which;    /**< The joystick device index */
 156         Uint8 axis;     /**< The joystick axis index */
 157         Sint16 value;   /**< The axis value (range: -32768 to 32767) */
 158 } SDL_JoyAxisEvent;
 159
 160 /** Joystick trackball motion event structure */
 161 typedef struct SDL_JoyBallEvent {
 162         Uint8 type;     /**< SDL_JOYBALLMOTION */
 163         Uint8 which;    /**< The joystick device index */
 164         Uint8 ball;     /**< The joystick trackball index */
 165         Sint16 xrel;    /**< The relative motion in the X direction */
 166         Sint16 yrel;    /**< The relative motion in the Y direction */
 167 } SDL_JoyBallEvent;
 168
 169 /** Joystick hat position change event structure */
 170 typedef struct SDL_JoyHatEvent {
 171         Uint8 type;     /**< SDL_JOYHATMOTION */
 172         Uint8 which;    /**< The joystick device index */
 173         Uint8 hat;      /**< The joystick hat index */
 174         Uint8 value;    /**< The hat position value:
 175                          *   SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
 176                          *   SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
 177                          *   SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
 178                          *  Note that zero means the POV is centered.
 179                          */
 180 } SDL_JoyHatEvent;
 181
 182 /** Joystick button event structure */
 183 typedef struct SDL_JoyButtonEvent {
 184         Uint8 type;     /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
 185         Uint8 which;    /**< The joystick device index */
 186         Uint8 button;   /**< The joystick button index */
 187         Uint8 state;    /**< SDL_PRESSED or SDL_RELEASED */
 188 } SDL_JoyButtonEvent;
 189
 190 /** The "window resized" event
 191  *  When you get this event, you are responsible for setting a new video
 192  *  mode with the new width and height.
 193  */
 194 typedef struct SDL_ResizeEvent {
 195         Uint8 type;     /**< SDL_VIDEORESIZE */
 196         int w;          /**< New width */
 197         int h;          /**< New height */
 198 } SDL_ResizeEvent;
 199
 200 /** The "screen redraw" event */
 201 typedef struct SDL_ExposeEvent {
 202         Uint8 type;     /**< SDL_VIDEOEXPOSE */
 203 } SDL_ExposeEvent;
 204
 205 /** The "quit requested" event */
 206 typedef struct SDL_QuitEvent {
 207         Uint8 type;     /**< SDL_QUIT */
 208 } SDL_QuitEvent;
 209
 210 /** A user-defined event type */
 211 typedef struct SDL_UserEvent {
 212         Uint8 type;     /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */
 213         int code;       /**< User defined event code */
 214         void *data1;    /**< User defined data pointer */
 215         void *data2;    /**< User defined data pointer */
 216 } SDL_UserEvent;
 217
 218 /** If you want to use this event, you should include SDL_syswm.h */
 219 struct SDL_SysWMmsg;
 220 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
 221 typedef struct SDL_SysWMEvent {
 222         Uint8 type;
 223         SDL_SysWMmsg *msg;
 224 } SDL_SysWMEvent;
 225
 226 /** General event structure */
 227 typedef union SDL_Event {
 228         Uint8 type;
 229         SDL_ActiveEvent active;
 230         SDL_KeyboardEvent key;
 231         SDL_MouseMotionEvent motion;
 232         SDL_MouseButtonEvent button;
 233         SDL_JoyAxisEvent jaxis;
 234         SDL_JoyBallEvent jball;
 235         SDL_JoyHatEvent jhat;
 236         SDL_JoyButtonEvent jbutton;
 237         SDL_ResizeEvent resize;
 238         SDL_ExposeEvent expose;
 239         SDL_QuitEvent quit;
 240         SDL_UserEvent user;
 241         SDL_SysWMEvent syswm;
 242 } SDL_Event;
 243
 244
 245 /* Function prototypes */
 246
 247 /** Pumps the event loop, gathering events from the input devices.
 248  *  This function updates the event queue and internal input device state.
 249  *  This should only be run in the thread that sets the video mode.
 250  */
 251 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
 252
 253 typedef enum {
 254         SDL_ADDEVENT,
 255         SDL_PEEKEVENT,
 256         SDL_GETEVENT
 257 } SDL_eventaction;
 258
 259 /**
 260  *  Checks the event queue for messages and optionally returns them.
 261  *
 262  *  If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
 263  *  the back of the event queue.
 264  *  If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
 265  *  of the event queue, matching 'mask', will be returned and will not
 266  *  be removed from the queue.
 267  *  If 'action' is SDL_GETEVENT, up to 'numevents' events at the front
 268  *  of the event queue, matching 'mask', will be returned and will be
 269  *  removed from the queue.
 270  *
 271  *  @return
 272  *  This function returns the number of events actually stored, or -1
 273  *  if there was an error.
 274  *
 275  *  This function is thread-safe.
 276  */
 277 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
 278                                 SDL_eventaction action, Uint32 mask);
 279
 280 /** Polls for currently pending events, and returns 1 if there are any pending
 281  *  events, or 0 if there are none available.  If 'event' is not NULL, the next
 282  *  event is removed from the queue and stored in that area.
 283  */
 284 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event);
 285
 286 /** Waits indefinitely for the next available event, returning 1, or 0 if there
 287  *  was an error while waiting for events.  If 'event' is not NULL, the next
 288  *  event is removed from the queue and stored in that area.
 289  */
 290 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
 291
 292 /** Add an event to the event queue.
 293  *  This function returns 0 on success, or -1 if the event queue was full
 294  *  or there was some other error.
 295  */
 296 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
 297
 298 /** @name Event Filtering */
 299 /*@{*/
 300 typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event);
 301 /**
 302  *  This function sets up a filter to process all events before they
 303  *  change internal state and are posted to the internal event queue.
 304  *
 305  *  The filter is protypted as:
 306  *      @code typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event); @endcode
 307  *
 308  * If the filter returns 1, then the event will be added to the internal queue.
 309  * If it returns 0, then the event will be dropped from the queue, but the
 310  * internal state will still be updated.  This allows selective filtering of
 311  * dynamically arriving events.
 312  *
 313  * @warning  Be very careful of what you do in the event filter function, as
 314  *           it may run in a different thread!
 315  *
 316  * There is one caveat when dealing with the SDL_QUITEVENT event type.  The
 317  * event filter is only called when the window manager desires to close the
 318  * application window.  If the event filter returns 1, then the window will
 319  * be closed, otherwise the window will remain open if possible.
 320  * If the quit event is generated by an interrupt signal, it will bypass the
 321  * internal queue and be delivered to the application at the next event poll.
 322  */
 323 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter);
 324
 325 /**
 326  *  Return the current event filter - can be used to "chain" filters.
 327  *  If there is no event filter set, this function returns NULL.
 328  */
 329 extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void);
 330 /*@}*/
 331
 332 /** @name Event State */
 333 /*@{*/
 334 #define SDL_QUERY       -1
 335 #define SDL_IGNORE       0
 336 #define SDL_DISABLE      0
 337 #define SDL_ENABLE       1
 338 /*@}*/
 339
 340 /**
 341 * This function allows you to set the state of processing certain events.
 342 * If 'state' is set to SDL_IGNORE, that event will be automatically dropped
 343 * from the event queue and will not event be filtered.
 344 * If 'state' is set to SDL_ENABLE, that event will be processed normally.
 345 * If 'state' is set to SDL_QUERY, SDL_EventState() will return the
 346 * current processing state of the specified event.
 347 */
 348 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
 349
 350 /* Ends C function definitions when using C++ */
 351 #ifdef __cplusplus
 352 }
 353 #endif
 354 #include "close_code.h"
 355
 356 #endif /* _SDL_events_h */