This repository has been archived by the owner on Feb 11, 2021. It is now read-only.
/
SDL_events.h
628 lines (550 loc) · 20 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
#include "SDL_keyboard.h"
#include "SDL_mouse.h"
#include "SDL_joystick.h"
#include "SDL_quit.h"
39
40
#include "SDL_gesture.h"
#include "SDL_touch.h"
41
42
43
44
#include "begin_code.h"
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
45
/* *INDENT-OFF* */
46
extern "C" {
47
/* *INDENT-ON* */
48
49
#endif
50
51
52
53
/* General keyboard/mouse state definitions */
#define SDL_RELEASED 0
#define SDL_PRESSED 1
54
/**
55
* \brief The types of events that can be delivered.
56
57
58
*/
typedef enum
{
59
60
61
62
63
64
65
66
67
68
69
SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */
/* Application events */
SDL_QUIT = 0x100, /**< User-requested quit */
/* Window events */
SDL_WINDOWEVENT = 0x200, /**< Window state change */
SDL_SYSWMEVENT, /**< System specific event */
/* Keyboard events */
SDL_KEYDOWN = 0x300, /**< Keys pressed */
70
SDL_KEYUP, /**< Keys released */
71
SDL_TEXTEDITING, /**< Keyboard text editing (composition) */
72
SDL_TEXTINPUT, /**< Keyboard text input */
73
74
75
/* Mouse events */
SDL_MOUSEMOTION = 0x400, /**< Mouse moved */
76
77
SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */
SDL_MOUSEBUTTONUP, /**< Mouse button released */
78
SDL_MOUSEWHEEL, /**< Mouse wheel motion */
79
80
81
82
83
84
85
86
/* Tablet or multiple mice input device events */
SDL_INPUTMOTION = 0x500, /**< Input moved */
SDL_INPUTBUTTONDOWN, /**< Input button pressed */
SDL_INPUTBUTTONUP, /**< Input button released */
SDL_INPUTWHEEL, /**< Input wheel motion */
SDL_INPUTPROXIMITYIN, /**< Input pen entered proximity */
SDL_INPUTPROXIMITYOUT, /**< Input pen left proximity */
87
88
89
/* Joystick events */
SDL_JOYAXISMOTION = 0x600, /**< Joystick axis motion */
90
91
92
93
SDL_JOYBALLMOTION, /**< Joystick trackball motion */
SDL_JOYHATMOTION, /**< Joystick hat position change */
SDL_JOYBUTTONDOWN, /**< Joystick button pressed */
SDL_JOYBUTTONUP, /**< Joystick button released */
94
95
96
/* Touch events */
SDL_FINGERDOWN = 0x700,
97
98
99
100
101
SDL_FINGERUP,
SDL_FINGERMOTION,
SDL_TOUCHBUTTONDOWN,
SDL_TOUCHBUTTONUP,
102
103
/* Gesture events */
SDL_DOLLARGESTURE = 0x800,
104
SDL_DOLLARRECORD,
105
106
SDL_MULTIGESTURE,
107
/* Clipboard events */
108
109
SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard changed */
110
111
112
113
114
115
/* Obsolete events */
SDL_EVENT_COMPAT1 = 0x7000, /**< SDL 1.2 events for compatibility */
SDL_EVENT_COMPAT2,
SDL_EVENT_COMPAT3,
116
117
118
119
120
121
/** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
* and should be allocated with SDL_RegisterEvents()
*/
SDL_USEREVENT = 0x8000,
122
123
/**
* This last event is only for bounding internal arrays
124
*/
125
SDL_LASTEVENT = 0xFFFF
126
} SDL_EventType;
127
128
/**
129
* \brief Window state change event data (event.window.*)
130
131
132
*/
typedef struct SDL_WindowEvent
{
133
134
135
136
137
138
139
140
Uint32 type; /**< ::SDL_WINDOWEVENT */
Uint32 windowID; /**< The associated window */
Uint8 event; /**< ::SDL_WindowEventID */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
int data1; /**< event dependent data */
int data2; /**< event dependent data */
141
142
143
} SDL_WindowEvent;
/**
144
* \brief Keyboard button event structure (event.key.*)
145
146
147
*/
typedef struct SDL_KeyboardEvent
{
148
149
150
Uint32 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
Uint32 windowID; /**< The window with keyboard focus, if any */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
151
Uint8 repeat; /**< Non-zero if this is a key repeat */
152
Uint8 padding2;
153
Uint8 padding3;
154
SDL_keysym keysym; /**< The key that was pressed or released */
155
156
} SDL_KeyboardEvent;
157
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
158
/**
159
* \brief Keyboard text editing event structure (event.edit.*)
160
161
162
*/
typedef struct SDL_TextEditingEvent
{
163
Uint32 type; /**< ::SDL_TEXTEDITING */
164
Uint32 windowID; /**< The window with keyboard focus, if any */
165
166
167
168
169
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;
170
171
#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
172
/**
173
* \brief Keyboard text input event structure (event.text.*)
174
175
176
*/
typedef struct SDL_TextInputEvent
{
177
Uint32 type; /**< ::SDL_TEXTINPUT */
178
Uint32 windowID; /**< The window with keyboard focus, if any */
179
char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */
180
181
182
} SDL_TextInputEvent;
/**
183
* \brief Mouse motion event structure (event.motion.*)
184
185
186
*/
typedef struct SDL_MouseMotionEvent
{
187
188
189
190
191
Uint32 type; /**< ::SDL_MOUSEMOTION */
Uint32 windowID; /**< The window with mouse focus, if any */
Uint8 state; /**< The current button state */
Uint8 padding1;
Uint8 padding2;
192
Uint8 padding3;
193
194
195
196
int x; /**< X coordinate, relative to window */
int y; /**< Y coordinate, relative to window */
int xrel; /**< The relative motion in the X direction */
int yrel; /**< The relative motion in the Y direction */
197
198
} SDL_MouseMotionEvent;
199
/**
200
* \brief Mouse button event structure (event.button.*)
201
202
203
*/
typedef struct SDL_MouseButtonEvent
{
204
205
206
207
208
Uint32 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
Uint32 windowID; /**< The window with mouse focus, if any */
Uint8 button; /**< The mouse button index */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
Uint8 padding1;
209
Uint8 padding2;
210
211
int x; /**< X coordinate, relative to window */
int y; /**< Y coordinate, relative to window */
212
213
} SDL_MouseButtonEvent;
214
/**
215
* \brief Mouse wheel event structure (event.wheel.*)
216
217
218
*/
typedef struct SDL_MouseWheelEvent
{
219
220
221
222
Uint32 type; /**< ::SDL_MOUSEWHEEL */
Uint32 windowID; /**< The window with mouse focus, if any */
int x; /**< The amount scrolled horizontally */
int y; /**< The amount scrolled vertically */
223
224
225
} SDL_MouseWheelEvent;
/**
226
* \brief Joystick axis motion event structure (event.jaxis.*)
227
228
229
*/
typedef struct SDL_JoyAxisEvent
{
230
Uint32 type; /**< ::SDL_JOYAXISMOTION */
231
232
Uint8 which; /**< The joystick device index */
Uint8 axis; /**< The joystick axis index */
233
234
Uint8 padding1;
Uint8 padding2;
235
int value; /**< The axis value (range: -32768 to 32767) */
236
237
} SDL_JoyAxisEvent;
238
/**
239
* \brief Joystick trackball motion event structure (event.jball.*)
240
241
242
*/
typedef struct SDL_JoyBallEvent
{
243
Uint32 type; /**< ::SDL_JOYBALLMOTION */
244
245
Uint8 which; /**< The joystick device index */
Uint8 ball; /**< The joystick trackball index */
246
247
Uint8 padding1;
Uint8 padding2;
248
249
int xrel; /**< The relative motion in the X direction */
int yrel; /**< The relative motion in the Y direction */
250
251
} SDL_JoyBallEvent;
252
/**
253
* \brief Joystick hat position change event structure (event.jhat.*)
254
255
256
*/
typedef struct SDL_JoyHatEvent
{
257
Uint32 type; /**< ::SDL_JOYHATMOTION */
258
259
Uint8 which; /**< The joystick device index */
Uint8 hat; /**< The joystick hat index */
260
261
262
263
264
265
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.
266
*/
267
Uint8 padding1;
268
269
} SDL_JoyHatEvent;
270
/**
271
* \brief Joystick button event structure (event.jbutton.*)
272
273
274
*/
typedef struct SDL_JoyButtonEvent
{
275
Uint32 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
276
277
Uint8 which; /**< The joystick device index */
Uint8 button; /**< The joystick button index */
278
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
279
Uint8 padding1;
280
281
} SDL_JoyButtonEvent;
282
283
284
285
286
287
288
289
290
/**
* \brief Touch finger motion/finger event structure (event.tmotion.*)
*/
typedef struct SDL_TouchFingerEvent
{
Uint32 type; /**< ::SDL_FINGERMOTION OR
SDL_FINGERDOWN OR SDL_FINGERUP*/
Uint32 windowID; /**< The window with mouse focus, if any */
291
292
SDL_TouchID touchId; /**< The touch device id */
SDL_FingerID fingerId;
293
294
Uint8 state; /**< The current button state */
Uint8 padding1;
295
296
Uint8 padding2;
Uint8 padding3;
297
298
Uint16 x;
Uint16 y;
299
300
Sint16 dx;
Sint16 dy;
301
Uint16 pressure;
302
303
304
305
306
307
308
309
310
311
} SDL_TouchFingerEvent;
/**
* \brief Touch finger motion/finger event structure (event.tmotion.*)
*/
typedef struct SDL_TouchButtonEvent
{
Uint32 type; /**< ::SDL_TOUCHBUTTONUP OR SDL_TOUCHBUTTONDOWN */
Uint32 windowID; /**< The window with mouse focus, if any */
312
SDL_TouchID touchId; /**< The touch device index */
313
314
315
Uint8 state; /**< The current button state */
Uint8 button; /**< The button changing state */
Uint8 padding1;
316
Uint8 padding2;
317
318
319
} SDL_TouchButtonEvent;
320
321
322
323
324
325
326
327
/**
* \brief Multiple Finger Gesture Event
*/
typedef struct SDL_MultiGestureEvent
{
Uint32 type; /**< ::SDL_MULTIGESTURE */
Uint32 windowID; /**< The window with mouse focus, if any */
328
SDL_TouchID touchId; /**< The touch device index */
329
330
331
332
float dTheta;
float dDist;
float x; //currently 0...1. Change to screen coords?
float y;
333
334
Uint16 numFingers;
Uint16 padding;
335
336
} SDL_MultiGestureEvent;
337
338
339
340
typedef struct SDL_DollarGestureEvent
{
Uint32 type; /**< ::SDL_DOLLARGESTURE */
Uint32 windowID; /**< The window with mouse focus, if any */
341
342
SDL_TouchID touchId; /**< The touch device index */
SDL_GestureID gestureId;
343
Uint32 numFingers;
344
345
346
347
348
349
350
351
float error;
/*
//TODO: Enable to give location?
float x; //currently 0...1. Change to screen coords?
float y;
*/
} SDL_DollarGestureEvent;
352
353
354
355
/**
356
* \brief The "quit requested" event
357
*/
358
359
typedef struct SDL_QuitEvent
{
360
Uint32 type; /**< ::SDL_QUIT */
361
362
} SDL_QuitEvent;
363
/**
364
* \brief A user-defined event type (event.user.*)
365
366
367
*/
typedef struct SDL_UserEvent
{
368
369
370
371
372
Uint32 type; /**< ::SDL_USEREVENT through ::SDL_NUMEVENTS-1 */
Uint32 windowID; /**< The associated window if any */
int code; /**< User defined event code */
void *data1; /**< User defined data pointer */
void *data2; /**< User defined data pointer */
373
374
375
376
} SDL_UserEvent;
struct SDL_SysWMmsg;
typedef struct SDL_SysWMmsg SDL_SysWMmsg;
377
378
379
380
381
382
/**
* \brief A video driver dependent system event (event.syswm.*)
*
* \note If you want to use this event, you should include SDL_syswm.h.
*/
383
384
typedef struct SDL_SysWMEvent
{
385
Uint32 type; /**< ::SDL_SYSWMEVENT */
386
SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
387
388
} SDL_SysWMEvent;
389
#ifndef SDL_NO_COMPAT
390
391
392
393
394
395
396
397
398
/**
* \addtogroup Compatibility
*/
/*@{*/
/**
* \name Typedefs for backwards compatibility
*/
/*@{*/
399
400
typedef struct SDL_ActiveEvent
{
401
Uint32 type;
402
403
404
Uint8 gain;
Uint8 state;
} SDL_ActiveEvent;
405
406
407
typedef struct SDL_ResizeEvent
{
408
Uint32 type;
409
410
411
int w;
int h;
} SDL_ResizeEvent;
412
413
414
/*@}*/
/*@}*//*Compatibility*/
415
#endif
416
417
/**
418
* \brief General event structure
419
420
421
*/
typedef union SDL_Event
{
422
Uint32 type; /**< Event type, shared with all events */
423
424
SDL_WindowEvent window; /**< Window event data */
SDL_KeyboardEvent key; /**< Keyboard event data */
425
SDL_TextEditingEvent edit; /**< Text editing event data */
426
SDL_TextInputEvent text; /**< Text input event data */
427
428
SDL_MouseMotionEvent motion; /**< Mouse motion event data */
SDL_MouseButtonEvent button; /**< Mouse button event data */
429
SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
430
431
432
433
434
435
436
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 */
437
438
SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
SDL_TouchButtonEvent tbutton; /**< Touch button event data */
439
SDL_MultiGestureEvent mgesture; /**< Multi Finger Gesture data*/
440
SDL_DollarGestureEvent dgesture; /**< Multi Finger Gesture data*/
441
442
443
/** Temporarily here for backwards compatibility */
/*@{*/
444
#ifndef SDL_NO_COMPAT
445
446
SDL_ActiveEvent active;
SDL_ResizeEvent resize;
447
#endif
448
/*@}*/
449
450
451
452
453
} SDL_Event;
/* Function prototypes */
454
455
456
457
458
459
460
/**
* 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.
*/
461
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
462
463
/*@{*/
464
465
466
467
468
typedef enum
{
SDL_ADDEVENT,
SDL_PEEKEVENT,
SDL_GETEVENT
469
} SDL_eventaction;
470
471
472
473
474
475
476
477
/**
* 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
478
479
* of the event queue, within the specified minimum and maximum type,
* will be returned and will not be removed from the queue.
480
481
*
* If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
482
483
* of the event queue, within the specified minimum and maximum type,
* will be returned and will be removed from the queue.
484
485
486
487
488
*
* \return The number of events actually stored, or -1 if there was an error.
*
* This function is thread-safe.
*/
489
490
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
491
Uint32 minType, Uint32 maxType);
492
/*@}*/
493
494
495
/**
* Checks to see if certain event types are in the event queue.
496
*/
497
498
499
500
501
502
503
504
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
/**
* This function clears events from the event queue
*/
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
505
506
507
508
509
510
511
512
/**
* \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.
513
*/
514
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
515
516
517
518
519
520
521
522
/**
* \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.
523
*/
524
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
525
526
527
528
529
530
531
532
533
/**
* \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.
534
535
536
537
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
int timeout);
538
539
540
541
542
/**
* \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.
543
*/
544
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
545
546
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
/**
* 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.
*/
573
574
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
void *userdata);
575
576
577
578
579
/**
* Return the current event filter - can be used to "chain" filters.
* If there is no event filter set, this function returns SDL_FALSE.
*/
580
581
582
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
void **userdata);
583
584
585
586
/**
* Run the filter function on the current event queue, removing any
* events for which the filter returns 0.
*/
587
588
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
void *userdata);
589
590
/*@{*/
591
592
593
594
595
#define SDL_QUERY -1
#define SDL_IGNORE 0
#define SDL_DISABLE 0
#define SDL_ENABLE 1
596
597
598
599
600
601
602
603
604
/**
* 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.
*/
605
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
606
/*@}*/
607
608
609
610
611
612
613
614
615
616
#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
/**
* This function allocates a set of user-defined events, and returns
* the beginning event number for that set of events.
*
* If there aren't enough user-defined events left, this function
* returns (Uint32)-1
*/
extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
617
618
619
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
620
/* *INDENT-OFF* */
621
}
622
/* *INDENT-ON* */
623
624
625
626
#endif
#include "close_code.h"
#endif /* _SDL_events_h */
627
628
/* vi: set ts=4 sw=4 expandtab: */