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