Mercurial > sdl-ios-xcode

comparison include/SDL_events.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Partial fix for bug #859 Header file update from Ken for improved doxygen output
author Sam Lantinga <slouken@libsdl.org>
date Mon, 19 Oct 2009 13:31:58 +0000
parents 00cace2d9080
children 6bb9952d5029
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
19 Sam Lantinga 19 Sam Lantinga
20 slouken@libsdl.org 20 slouken@libsdl.org
21 */ 21 */
22 22
23 /** 23 /**
24 * \file SDL_events.h 24 * \file SDL_events.h
25 * 25 *
26 * Include file for SDL event handling 26 * Include file for SDL event handling.
27 */ 27 */
28 28
29 #ifndef _SDL_events_h 29 #ifndef _SDL_events_h
30 #define _SDL_events_h 30 #define _SDL_events_h
31 31
48 /* General keyboard/mouse state definitions */ 48 /* General keyboard/mouse state definitions */
49 #define SDL_RELEASED 0 49 #define SDL_RELEASED 0
50 #define SDL_PRESSED 1 50 #define SDL_PRESSED 1
51 51
52 /** 52 /**
53 * \enum SDL_EventType 53 * \brief The types of events that can be delivered.
54 *
55 * \brief The types of events that can be delivered
56 */ 54 */
57 typedef enum 55 typedef enum
58 { 56 {
59 SDL_NOEVENT = 0, /**< Unused (do not remove) */ 57 SDL_NOEVENT = 0, /**< Unused (do not remove) */
60 SDL_WINDOWEVENT, /**< Window state change */ 58 SDL_WINDOWEVENT, /**< Window state change */
74 SDL_QUIT, /**< User-requested quit */ 72 SDL_QUIT, /**< User-requested quit */
75 SDL_SYSWMEVENT, /**< System specific event */ 73 SDL_SYSWMEVENT, /**< System specific event */
76 SDL_PROXIMITYIN, /**< Proximity In event */ 74 SDL_PROXIMITYIN, /**< Proximity In event */
77 SDL_PROXIMITYOUT, /**< Proximity Out event */ 75 SDL_PROXIMITYOUT, /**< Proximity Out event */
78 SDL_EVENT_RESERVED1, /**< Reserved for future use... */ 76 SDL_EVENT_RESERVED1, /**< Reserved for future use... */
79 SDL_EVENT_RESERVED2, 77 SDL_EVENT_RESERVED2, /**< Reserved for future use... */
80 SDL_EVENT_RESERVED3, 78 SDL_EVENT_RESERVED3, /**< Reserved for future use... */
81 /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */ 79 /** Events ::SDL_USEREVENT through ::SDL_MAXEVENTS-1 are for your use */
82 SDL_USEREVENT = 24, 80 SDL_USEREVENT = 24,
83 /* This last event is only for bounding internal arrays 81 /**
84 It is the number of bits in the event mask datatype -- Uint32 82 * This last event is only for bounding internal arrays
83 * It is the number of bits in the event mask datatype -- Uint32
85 */ 84 */
86 SDL_NUMEVENTS = 32 85 SDL_NUMEVENTS = 32
87 } SDL_EventType; 86 } SDL_EventType;
88 87
89 /** 88 /*@{*/
90 * \enum SDL_EventMask 89 #define SDL_EVENTMASK(X) (1<<(X))
91 * 90 /**
92 * \brief Predefined event masks 91 * \brief Predefined event masks
93 */ 92 */
94 #define SDL_EVENTMASK(X) (1<<(X))
95 typedef enum 93 typedef enum
96 { 94 {
97 SDL_WINDOWEVENTMASK = SDL_EVENTMASK(SDL_WINDOWEVENT), 95 SDL_WINDOWEVENTMASK = SDL_EVENTMASK(SDL_WINDOWEVENT),
98 SDL_KEYDOWNMASK = SDL_EVENTMASK(SDL_KEYDOWN), 96 SDL_KEYDOWNMASK = SDL_EVENTMASK(SDL_KEYDOWN),
99 SDL_KEYUPMASK = SDL_EVENTMASK(SDL_KEYUP), 97 SDL_KEYUPMASK = SDL_EVENTMASK(SDL_KEYUP),
119 SDL_SYSWMEVENTMASK = SDL_EVENTMASK(SDL_SYSWMEVENT), 117 SDL_SYSWMEVENTMASK = SDL_EVENTMASK(SDL_SYSWMEVENT),
120 SDL_PROXIMITYINMASK = SDL_EVENTMASK(SDL_PROXIMITYIN), 118 SDL_PROXIMITYINMASK = SDL_EVENTMASK(SDL_PROXIMITYIN),
121 SDL_PROXIMITYOUTMASK = SDL_EVENTMASK(SDL_PROXIMITYOUT) 119 SDL_PROXIMITYOUTMASK = SDL_EVENTMASK(SDL_PROXIMITYOUT)
122 } SDL_EventMask; 120 } SDL_EventMask;
123 #define SDL_ALLEVENTS 0xFFFFFFFF 121 #define SDL_ALLEVENTS 0xFFFFFFFF
124 122 /*@}*/
125 /** 123
126 * \struct SDL_WindowEvent 124 /**
127 * 125 * \brief Window state change event data (event.window.*)
128 * \brief Window state change event data (event.window.*)
129 */ 126 */
130 typedef struct SDL_WindowEvent 127 typedef struct SDL_WindowEvent
131 { 128 {
132 Uint8 type; /**< SDL_WINDOWEVENT */ 129 Uint8 type; /**< ::SDL_WINDOWEVENT */
133 SDL_WindowID windowID; /**< The associated window */ 130 SDL_WindowID windowID; /**< The associated window */
134 Uint8 event; /**< SDL_WindowEventID */ 131 Uint8 event; /**< ::SDL_WindowEventID */
135 int data1; /**< event dependent data */ 132 int data1; /**< event dependent data */
136 int data2; /**< event dependent data */ 133 int data2; /**< event dependent data */
137 } SDL_WindowEvent; 134 } SDL_WindowEvent;
138 135
139 /** 136 /**
140 * \struct SDL_KeyboardEvent 137 * \brief Keyboard button event structure (event.key.*)
141 *
142 * \brief Keyboard button event structure (event.key.*)
143 */ 138 */
144 typedef struct SDL_KeyboardEvent 139 typedef struct SDL_KeyboardEvent
145 { 140 {
146 Uint8 type; /**< SDL_KEYDOWN or SDL_KEYUP */ 141 Uint8 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
147 SDL_WindowID windowID; /**< The window with keyboard focus, if any */ 142 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
148 Uint8 which; /**< The keyboard device index */ 143 Uint8 which; /**< The keyboard device index */
149 Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ 144 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
150 SDL_keysym keysym; /**< The key that was pressed or released */ 145 SDL_keysym keysym; /**< The key that was pressed or released */
151 } SDL_KeyboardEvent; 146 } SDL_KeyboardEvent;
152 147
153 /**
154 * \struct SDL_TextEditingEvent
155 *
156 * \brief Keyboard text editing event structure (event.edit.*)
157 */
158 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32) 148 #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
149 /**
150 * \brief Keyboard text editing event structure (event.edit.*)
151 */
159 typedef struct SDL_TextEditingEvent 152 typedef struct SDL_TextEditingEvent
160 { 153 {
161 Uint8 type; /**< SDL_TEXTEDITING */ 154 Uint8 type; /**< ::SDL_TEXTEDITING */
162 char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */ 155 char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */
163 int start; /**< The start cursor of selected editing text */ 156 int start; /**< The start cursor of selected editing text */
164 int length; /**< The length of selected editing text */ 157 int length; /**< The length of selected editing text */
165 } SDL_TextEditingEvent; 158 } SDL_TextEditingEvent;
166 159
167 /** 160
168 * \struct SDL_TextInputEvent
169 *
170 * \brief Keyboard text input event structure (event.text.*)
171 */
172 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32) 161 #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
162 /**
163 * \brief Keyboard text input event structure (event.text.*)
164 */
173 typedef struct SDL_TextInputEvent 165 typedef struct SDL_TextInputEvent
174 { 166 {
175 Uint8 type; /**< SDL_TEXTINPUT */ 167 Uint8 type; /**< ::SDL_TEXTINPUT */
176 SDL_WindowID windowID; /**< The window with keyboard focus, if any */ 168 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
177 Uint8 which; /**< The keyboard device index */ 169 Uint8 which; /**< The keyboard device index */
178 char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */ 170 char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */
179 } SDL_TextInputEvent; 171 } SDL_TextInputEvent;
180 172
181 /** 173 /**
182 * \struct SDL_MouseMotionEvent 174 * \brief Mouse motion event structure (event.motion.*)
183 *
184 * \brief Mouse motion event structure (event.motion.*)
185 */ 175 */
186 typedef struct SDL_MouseMotionEvent 176 typedef struct SDL_MouseMotionEvent
187 { 177 {
188 Uint8 type; /**< SDL_MOUSEMOTION */ 178 Uint8 type; /**< ::SDL_MOUSEMOTION */
189 SDL_WindowID windowID; /**< The window with mouse focus, if any */ 179 SDL_WindowID windowID; /**< The window with mouse focus, if any */
190 Uint8 which; /**< The mouse device index */ 180 Uint8 which; /**< The mouse device index */
191 Uint8 state; /**< The current button state */ 181 Uint8 state; /**< The current button state */
192 int x; /**< X coordinate, relative to window */ 182 int x; /**< X coordinate, relative to window */
193 int y; /**< Y coordinate, relative to window */ 183 int y; /**< Y coordinate, relative to window */
201 int xrel; /**< The relative motion in the X direction */ 191 int xrel; /**< The relative motion in the X direction */
202 int yrel; /**< The relative motion in the Y direction */ 192 int yrel; /**< The relative motion in the Y direction */
203 } SDL_MouseMotionEvent; 193 } SDL_MouseMotionEvent;
204 194
205 /** 195 /**
206 * \struct SDL_MouseButtonEvent 196 * \brief Mouse button event structure (event.button.*)
207 *
208 * \brief Mouse button event structure (event.button.*)
209 */ 197 */
210 typedef struct SDL_MouseButtonEvent 198 typedef struct SDL_MouseButtonEvent
211 { 199 {
212 Uint8 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */ 200 Uint8 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
213 SDL_WindowID windowID; /**< The window with mouse focus, if any */ 201 SDL_WindowID windowID; /**< The window with mouse focus, if any */
214 Uint8 which; /**< The mouse device index */ 202 Uint8 which; /**< The mouse device index */
215 Uint8 button; /**< The mouse button index */ 203 Uint8 button; /**< The mouse button index */
216 Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ 204 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
217 int x; /**< X coordinate, relative to window */ 205 int x; /**< X coordinate, relative to window */
218 int y; /**< Y coordinate, relative to window */ 206 int y; /**< Y coordinate, relative to window */
219 } SDL_MouseButtonEvent; 207 } SDL_MouseButtonEvent;
220 208
221 /** 209 /**
222 * \struct SDL_MouseWheelEvent 210 * \brief Mouse wheel event structure (event.wheel.*)
223 *
224 * \brief Mouse wheel event structure (event.wheel.*)
225 */ 211 */
226 typedef struct SDL_MouseWheelEvent 212 typedef struct SDL_MouseWheelEvent
227 { 213 {
228 Uint8 type; /**< SDL_MOUSEWHEEL */ 214 Uint8 type; /**< ::SDL_MOUSEWHEEL */
229 SDL_WindowID windowID; /**< The window with mouse focus, if any */ 215 SDL_WindowID windowID; /**< The window with mouse focus, if any */
230 Uint8 which; /**< The mouse device index */ 216 Uint8 which; /**< The mouse device index */
231 int x; /**< The amount scrolled horizontally */ 217 int x; /**< The amount scrolled horizontally */
232 int y; /**< The amount scrolled vertically */ 218 int y; /**< The amount scrolled vertically */
233 } SDL_MouseWheelEvent; 219 } SDL_MouseWheelEvent;
234 220
235 /** 221 /**
236 * \struct SDL_JoyAxisEvent 222 * \brief Joystick axis motion event structure (event.jaxis.*)
237 *
238 * \brief Joystick axis motion event structure (event.jaxis.*)
239 */ 223 */
240 typedef struct SDL_JoyAxisEvent 224 typedef struct SDL_JoyAxisEvent
241 { 225 {
242 Uint8 type; /**< SDL_JOYAXISMOTION */ 226 Uint8 type; /**< ::SDL_JOYAXISMOTION */
243 Uint8 which; /**< The joystick device index */ 227 Uint8 which; /**< The joystick device index */
244 Uint8 axis; /**< The joystick axis index */ 228 Uint8 axis; /**< The joystick axis index */
245 int value; /**< The axis value (range: -32768 to 32767) */ 229 int value; /**< The axis value (range: -32768 to 32767) */
246 } SDL_JoyAxisEvent; 230 } SDL_JoyAxisEvent;
247 231
248 /** 232 /**
249 * \struct SDL_JoyBallEvent 233 * \brief Joystick trackball motion event structure (event.jball.*)
250 *
251 * \brief Joystick trackball motion event structure (event.jball.*)
252 */ 234 */
253 typedef struct SDL_JoyBallEvent 235 typedef struct SDL_JoyBallEvent
254 { 236 {
255 Uint8 type; /**< SDL_JOYBALLMOTION */ 237 Uint8 type; /**< ::SDL_JOYBALLMOTION */
256 Uint8 which; /**< The joystick device index */ 238 Uint8 which; /**< The joystick device index */
257 Uint8 ball; /**< The joystick trackball index */ 239 Uint8 ball; /**< The joystick trackball index */
258 int xrel; /**< The relative motion in the X direction */ 240 int xrel; /**< The relative motion in the X direction */
259 int yrel; /**< The relative motion in the Y direction */ 241 int yrel; /**< The relative motion in the Y direction */
260 } SDL_JoyBallEvent; 242 } SDL_JoyBallEvent;
261 243
262 /** 244 /**
263 * \struct SDL_JoyHatEvent 245 * \brief Joystick hat position change event structure (event.jhat.*)
264 *
265 * \brief Joystick hat position change event structure (event.jhat.*)
266 */ 246 */
267 typedef struct SDL_JoyHatEvent 247 typedef struct SDL_JoyHatEvent
268 { 248 {
269 Uint8 type; /**< SDL_JOYHATMOTION */ 249 Uint8 type; /**< ::SDL_JOYHATMOTION */
270 Uint8 which; /**< The joystick device index */ 250 Uint8 which; /**< The joystick device index */
271 Uint8 hat; /**< The joystick hat index */ 251 Uint8 hat; /**< The joystick hat index */
272 Uint8 value; /**< The hat position value: 252 Uint8 value; /**< The hat position value.
273 SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP 253 * \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
274 SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT 254 * \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
275 SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN 255 * \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
276 Note that zero means the POV is centered. 256 *
257 * Note that zero means the POV is centered.
277 */ 258 */
278 } SDL_JoyHatEvent; 259 } SDL_JoyHatEvent;
279 260
280 /** 261 /**
281 * \struct SDL_JoyButtonEvent 262 * \brief Joystick button event structure (event.jbutton.*)
282 *
283 * \brief Joystick button event structure (event.jbutton.*)
284 */ 263 */
285 typedef struct SDL_JoyButtonEvent 264 typedef struct SDL_JoyButtonEvent
286 { 265 {
287 Uint8 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */ 266 Uint8 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
288 Uint8 which; /**< The joystick device index */ 267 Uint8 which; /**< The joystick device index */
289 Uint8 button; /**< The joystick button index */ 268 Uint8 button; /**< The joystick button index */
290 Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ 269 Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
291 } SDL_JoyButtonEvent; 270 } SDL_JoyButtonEvent;
292 271
293 /** 272 /**
294 * \struct SDL_QuitEvent 273 * \brief The "quit requested" event
295 *
296 * \brief The "quit requested" event
297 */ 274 */
298 typedef struct SDL_QuitEvent 275 typedef struct SDL_QuitEvent
299 { 276 {
300 Uint8 type; /**< SDL_QUIT */ 277 Uint8 type; /**< ::SDL_QUIT */
301 } SDL_QuitEvent; 278 } SDL_QuitEvent;
302 279
303 /** 280 /**
304 * \struct SDL_UserEvent 281 * \brief A user-defined event type (event.user.*)
305 *
306 * \brief A user-defined event type (event.user.*)
307 */ 282 */
308 typedef struct SDL_UserEvent 283 typedef struct SDL_UserEvent
309 { 284 {
310 Uint8 type; /**< SDL_USEREVENT through SDL_NUMEVENTS-1 */ 285 Uint8 type; /**< ::SDL_USEREVENT through ::SDL_NUMEVENTS-1 */
311 SDL_WindowID windowID; /**< The associated window if any*/ 286 SDL_WindowID windowID; /**< The associated window if any*/
312 int code; /**< User defined event code */ 287 int code; /**< User defined event code */
313 void *data1; /**< User defined data pointer */ 288 void *data1; /**< User defined data pointer */
314 void *data2; /**< User defined data pointer */ 289 void *data2; /**< User defined data pointer */
315 } SDL_UserEvent; 290 } SDL_UserEvent;
316 291
317 /**
318 * \struct SDL_SysWMEvent
319 *
320 * \brief A video driver dependent system event (event.syswm.*)
321 *
322 * \note If you want to use this event, you should include SDL_syswm.h
323 */
324 struct SDL_SysWMmsg; 292 struct SDL_SysWMmsg;
325 typedef struct SDL_SysWMmsg SDL_SysWMmsg; 293 typedef struct SDL_SysWMmsg SDL_SysWMmsg;
294
295 /**
296 * \brief A video driver dependent system event (event.syswm.*)
297 *
298 * \note If you want to use this event, you should include SDL_syswm.h.
299 */
326 typedef struct SDL_SysWMEvent 300 typedef struct SDL_SysWMEvent
327 { 301 {
328 Uint8 type; /**< SDL_SYSWMEVENT */ 302 Uint8 type; /**< ::SDL_SYSWMEVENT */
329 SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */ 303 SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
330 } SDL_SysWMEvent; 304 } SDL_SysWMEvent;
331 305
332 typedef struct SDL_ProximityEvent 306 typedef struct SDL_ProximityEvent
333 { 307 {
337 int cursor; 311 int cursor;
338 int x; 312 int x;
339 int y; 313 int y;
340 } SDL_ProximityEvent; 314 } SDL_ProximityEvent;
341 315
342 /* Typedefs for backwards compatibility */
343 #ifndef SDL_NO_COMPAT 316 #ifndef SDL_NO_COMPAT
317 /**
318 * \addtogroup Compatibility
319 */
320 /*@{*/
321
322 /**
323 * \name Typedefs for backwards compatibility
324 */
325 /*@{*/
344 typedef struct SDL_ActiveEvent 326 typedef struct SDL_ActiveEvent
345 { 327 {
346 Uint8 type; 328 Uint8 type;
347 Uint8 gain; 329 Uint8 gain;
348 Uint8 state; 330 Uint8 state;
352 { 334 {
353 Uint8 type; 335 Uint8 type;
354 int w; 336 int w;
355 int h; 337 int h;
356 } SDL_ResizeEvent; 338 } SDL_ResizeEvent;
339 /*@}*/
340
341 /*@}*//*Compatibility*/
357 #endif 342 #endif
358 343
359 /** 344 /**
360 * \union SDL_Event 345 * \brief General event structure
361 *
362 * \brief General event structure
363 */ 346 */
364 typedef union SDL_Event 347 typedef union SDL_Event
365 { 348 {
366 Uint8 type; /**< Event type, shared with all events */ 349 Uint8 type; /**< Event type, shared with all events */
367 SDL_WindowEvent window; /**< Window event data */ 350 SDL_WindowEvent window; /**< Window event data */
378 SDL_QuitEvent quit; /**< Quit request event data */ 361 SDL_QuitEvent quit; /**< Quit request event data */
379 SDL_UserEvent user; /**< Custom event data */ 362 SDL_UserEvent user; /**< Custom event data */
380 SDL_SysWMEvent syswm; /**< System dependent window event data */ 363 SDL_SysWMEvent syswm; /**< System dependent window event data */
381 SDL_ProximityEvent proximity; /**< Proximity In or Out event */ 364 SDL_ProximityEvent proximity; /**< Proximity In or Out event */
382 365
383 /* Temporarily here for backwards compatibility */ 366 /** Temporarily here for backwards compatibility */
367 /*@{*/
384 #ifndef SDL_NO_COMPAT 368 #ifndef SDL_NO_COMPAT
385 SDL_ActiveEvent active; 369 SDL_ActiveEvent active;
386 SDL_ResizeEvent resize; 370 SDL_ResizeEvent resize;
387 #endif 371 #endif
372 /*@}*/
388 } SDL_Event; 373 } SDL_Event;
389 374
390 375
391 /* Function prototypes */ 376 /* Function prototypes */
392 377
393 /* Pumps the event loop, gathering events from the input devices. 378 /**
394 This function updates the event queue and internal input device state. 379 * Pumps the event loop, gathering events from the input devices.
395 This should only be run in the thread that sets the video mode. 380 *
396 */ 381 * This function updates the event queue and internal input device state.
382 *
383 * This should only be run in the thread that sets the video mode.
384 */
397 extern DECLSPEC void SDLCALL SDL_PumpEvents(void); 385 extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
398 386
399 /* Checks the event queue for messages and optionally returns them. 387 /*@{*/
400 If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
401 the back of the event queue.
402 If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
403 of the event queue, matching 'mask', will be returned and will not
404 be removed from the queue.
405 If 'action' is SDL_GETEVENT, up to 'numevents' events at the front
406 of the event queue, matching 'mask', will be returned and will be
407 removed from the queue.
408 This function returns the number of events actually stored, or -1
409 if there was an error. This function is thread-safe.
410 */
411 typedef enum 388 typedef enum
412 { 389 {
413 SDL_ADDEVENT, 390 SDL_ADDEVENT,
414 SDL_PEEKEVENT, 391 SDL_PEEKEVENT,
415 SDL_GETEVENT 392 SDL_GETEVENT
416 } SDL_eventaction; 393 } SDL_eventaction;
417 /* */ 394
395 /**
396 * Checks the event queue for messages and optionally returns them.
397 *
398 * If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
399 * the back of the event queue.
400 *
401 * If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
402 * of the event queue, matching \c mask, will be returned and will not
403 * be removed from the queue.
404 *
405 * If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
406 * of the event queue, matching \c mask, will be returned and will be
407 * removed from the queue.
408 *
409 * \return The number of events actually stored, or -1 if there was an error.
410 *
411 * This function is thread-safe.
412 */
418 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents, 413 extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
419 SDL_eventaction action, 414 SDL_eventaction action,
420 Uint32 mask); 415 Uint32 mask);
421 416 /*@}*/
422 /* Checks to see if certain event types are in the event queue. 417
418 /**
419 * Checks to see if certain event types are in the event queue.
423 */ 420 */
424 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 mask); 421 extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 mask);
425 422
426 /* Polls for currently pending events, and returns 1 if there are any pending 423 /**
427 events, or 0 if there are none available. If 'event' is not NULL, the next 424 * \brief Polls for currently pending events.
428 event is removed from the queue and stored in that area. 425 *
426 * \return 1 if there are any pending events, or 0 if there are none available.
427 *
428 * \param event If not NULL, the next event is removed from the queue and
429 * stored in that area.
429 */ 430 */
430 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event); 431 extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
431 432
432 /* Waits indefinitely for the next available event, returning 1, or 0 if there 433 /**
433 was an error while waiting for events. If 'event' is not NULL, the next 434 * \brief Waits indefinitely for the next available event.
434 event is removed from the queue and stored in that area. 435 *
436 * \return 1, or 0 if there was an error while waiting for events.
437 *
438 * \param event If not NULL, the next event is removed from the queue and
439 * stored in that area.
435 */ 440 */
436 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event); 441 extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
437 442
438 /* Waits until the specified timeout (in milliseconds) for the next available 443 /**
439 event, returning 1, or 0 if there was an error while waiting for events. If 444 * \brief Waits until the specified timeout (in milliseconds) for the next
440 'event' is not NULL, the next event is removed from the queue and stored in 445 * available event.
441 that area. 446 *
447 * \return 1, or 0 if there was an error while waiting for events.
448 *
449 * \param event If not NULL, the next event is removed from the queue and
450 * stored in that area.
442 */ 451 */
443 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event, 452 extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
444 int timeout); 453 int timeout);
445 454
446 /* Add an event to the event queue. 455 /**
447 This function returns 1 on success, 0 if the event was filtered, 456 * \brief Add an event to the event queue.
448 or -1 if the event queue was full or there was some other error. 457 *
458 * \return 1 on success, 0 if the event was filtered, or -1 if the event queue
459 * was full or there was some other error.
449 */ 460 */
450 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event); 461 extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
451 462
452 /*
453 This function sets up a filter to process all events before they
454 change internal state and are posted to the internal event queue.
455
456 The filter is protypted as:
457 */
458 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event); 463 typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
459 /* 464
460 If the filter returns 1, then the event will be added to the internal queue. 465 /**
461 If it returns 0, then the event will be dropped from the queue, but the 466 * Sets up a filter to process all events before they change internal state and
462 internal state will still be updated. This allows selective filtering of 467 * are posted to the internal event queue.
463 dynamically arriving events. 468 *
464 469 * The filter is protypted as:
465 WARNING: Be very careful of what you do in the event filter function, as 470 * \code
466 it may run in a different thread! 471 * int SDL_EventFilter(void *userdata, SDL_Event * event);
467 472 * \endcode
468 There is one caveat when dealing with the SDL_QUITEVENT event type. The 473 *
469 event filter is only called when the window manager desires to close the 474 * If the filter returns 1, then the event will be added to the internal queue.
470 application window. If the event filter returns 1, then the window will 475 * If it returns 0, then the event will be dropped from the queue, but the
471 be closed, otherwise the window will remain open if possible. 476 * internal state will still be updated. This allows selective filtering of
472 If the quit event is generated by an interrupt signal, it will bypass the 477 * dynamically arriving events.
473 internal queue and be delivered to the application at the next event poll. 478 *
474 */ 479 * \warning Be very careful of what you do in the event filter function, as
480 * it may run in a different thread!
481 *
482 * There is one caveat when dealing with the ::SDL_QUITEVENT event type. The
483 * event filter is only called when the window manager desires to close the
484 * application window. If the event filter returns 1, then the window will
485 * be closed, otherwise the window will remain open if possible.
486 *
487 * If the quit event is generated by an interrupt signal, it will bypass the
488 * internal queue and be delivered to the application at the next event poll.
489 */
475 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, 490 extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
476 void *userdata); 491 void *userdata);
477 492
478 /* 493 /**
479 Return the current event filter - can be used to "chain" filters. 494 * Return the current event filter - can be used to "chain" filters.
480 If there is no event filter set, this function returns SDL_FALSE. 495 * If there is no event filter set, this function returns SDL_FALSE.
481 */ 496 */
482 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter, 497 extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
483 void **userdata); 498 void **userdata);
484 499
485 /* 500 /**
486 Run the filter function on the current event queue, removing any 501 * Run the filter function on the current event queue, removing any
487 events for which the filter returns 0. 502 * events for which the filter returns 0.
488 */ 503 */
489 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, 504 extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
490 void *userdata); 505 void *userdata);
491 506
492 /* 507 /*@{*/
493 This function allows you to set the state of processing certain events.
494 If 'state' is set to SDL_IGNORE, that event will be automatically dropped
495 from the event queue and will not event be filtered.
496 If 'state' is set to SDL_ENABLE, that event will be processed normally.
497 If 'state' is set to SDL_QUERY, SDL_EventState() will return the
498 current processing state of the specified event.
499 */
500 #define SDL_QUERY -1 508 #define SDL_QUERY -1
501 #define SDL_IGNORE 0 509 #define SDL_IGNORE 0
502 #define SDL_DISABLE 0 510 #define SDL_DISABLE 0
503 #define SDL_ENABLE 1 511 #define SDL_ENABLE 1
512
513 /**
514 * This function allows you to set the state of processing certain events.
515 * - If \c state is set to ::SDL_IGNORE, that event will be automatically
516 * dropped from the event queue and will not event be filtered.
517 * - If \c state is set to ::SDL_ENABLE, that event will be processed
518 * normally.
519 * - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
520 * current processing state of the specified event.
521 */
504 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state); 522 extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
505 523 /*@}*/
506 524
507 /* Ends C function definitions when using C++ */ 525 /* Ends C function definitions when using C++ */
508 #ifdef __cplusplus 526 #ifdef __cplusplus
509 /* *INDENT-OFF* */ 527 /* *INDENT-OFF* */
510 } 528 }