1/* 2 SDL - Simple DirectMedia Layer 3 Copyright (C) 1997-2012 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 42extern "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 */ 52typedef 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)) 88typedef 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 */ 119typedef 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 */ 126typedef 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 */ 134typedef 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 */ 144typedef 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 */ 153typedef 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 */ 161typedef 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 */ 170typedef 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 */ 183typedef 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 */ 194typedef 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 */ 201typedef struct SDL_ExposeEvent { 202 Uint8 type; /**< SDL_VIDEOEXPOSE */ 203} SDL_ExposeEvent; 204 205/** The "quit requested" event */ 206typedef struct SDL_QuitEvent { 207 Uint8 type; /**< SDL_QUIT */ 208} SDL_QuitEvent; 209 210/** A user-defined event type */ 211typedef 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 */ 219struct SDL_SysWMmsg; 220typedef struct SDL_SysWMmsg SDL_SysWMmsg; 221typedef struct SDL_SysWMEvent { 222 Uint8 type; 223 SDL_SysWMmsg *msg; 224} SDL_SysWMEvent; 225 226/** General event structure */ 227typedef 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 */ 251extern DECLSPEC void SDLCALL SDL_PumpEvents(void); 252 253typedef 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 */ 277extern 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 */ 284extern 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 */ 290extern 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 */ 296extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event); 297 298/** @name Event Filtering */ 299/*@{*/ 300typedef 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 */ 323extern 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 */ 329extern 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*/ 348extern 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 */ 357