Repository navigation
Expand file tree
/
Copy pathSDL_events.h
More file actions
1196 lines (1096 loc) · 47.2 KB
/
Copy pathSDL_events.h
File metadata and controls
1196 lines (1096 loc) · 47.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
42
8000
4
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
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
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
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
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
Simple DirectMedia Layer
Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
/**
* # CategoryEvents
*
* Include file for SDL event handling.
*/
#ifndef SDL_events_h_
#define SDL_events_h_
#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "SDL_video.h"
#include "SDL_keyboard.h"
#include "SDL_mouse.h"
#include "SDL_joystick.h"
#include "SDL_gamecontroller.h"
#include "SDL_quit.h"
#include "SDL_gesture.h"
#include "SDL_touch.h"
#include "begin_code.h"
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
/* General keyboard/mouse state definitions */
#define SDL_RELEASED 0
#define SDL_PRESSED 1
/**
* The types of events that can be delivered.
*/
typedef enum SDL_EventType
{
SDL_FIRSTEVENT = 0, /**< Unused (do not remove) */
/* Application events */
SDL_QUIT = 0x100, /**< User-requested quit */
/* These application events have special meaning on iOS, see README-ios.md for details */
SDL_APP_TERMINATING, /**< The application is being terminated by the OS
Called on iOS in applicationWillTerminate()
Called on Android in onDestroy()
*/
SDL_APP_LOWMEMORY, /**< The application is low on memory, free memory if possible.
Called on iOS in applicationDidReceiveMemoryWarning()
Called on Android in onLowMemory()
*/
SDL_APP_WILLENTERBACKGROUND, /**< The application is about to enter the background
Called on iOS in applicationWillResignActive()
Called on Android in onPause()
*/
SDL_APP_DIDENTERBACKGROUND, /**< The application did enter the background and may not get CPU for some time
Called on iOS in applicationDidEnterBackground()
Called on Android in onPause()
*/
SDL_APP_WILLENTERFOREGROUND, /**< The application is about to enter the foreground
Called on iOS in applicationWillEnterForeground()
Called on Android in onResume()
*/
SDL_APP_DIDENTERFOREGROUND, /**< The application is now interactive
Called on iOS in applicationDidBecomeActive()
Called on Android in onResume()
*/
SDL_LOCALECHANGED, /**< The user's locale preferences have changed. */
/* Display events */
SDL_DISPLAYEVENT = 0x150, /**< Display state change */
/* Window events */
SDL_WINDOWEVENT = 0x200, /**< Window state change */
SDL_SYSWMEVENT, /**< System specific event */
/* Keyboard events */
SDL_KEYDOWN = 0x300, /**< Key pressed */
SDL_KEYUP, /**< Key released */
SDL_TEXTEDITING, /**< Keyboard text editing (composition) */
SDL_TEXTINPUT, /**< Keyboard text input */
SDL_KEYMAPCHANGED, /**< Keymap changed due to a system event such as an
input language or keyboard layout change.
*/
SDL_TEXTEDITING_EXT, /**< Extended keyboard text editing (composition) */
/* Mouse events */
SDL_MOUSEMOTION = 0x400, /**< Mouse moved */
SDL_MOUSEBUTTONDOWN, /**< Mouse button pressed */
SDL_MOUSEBUTTONUP, /**< Mouse button released */
SDL_MOUSEWHEEL, /**< Mouse wheel motion */
/* Joystick events */
SDL_JOYAXISMOTION = 0x600, /**< 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_JOYDEVICEADDED, /**< A new joystick has been inserted into the system */
SDL_JOYDEVICEREMOVED, /**< An opened joystick has been removed */
SDL_JOYBATTERYUPDATED, /**< Joystick battery level change */
/* Game controller events */
SDL_CONTROLLERAXISMOTION = 0x650, /**< Game controller axis motion */
SDL_CONTROLLERBUTTONDOWN, /**< Game controller button pressed */
SDL_CONTROLLERBUTTONUP, /**< Game controller button released */
SDL_CONTROLLERDEVICEADDED, /**< A new Game controller has been inserted into the system */
SDL_CONTROLLERDEVICEREMOVED, /**< An opened Game controller has been removed */
SDL_CONTROLLERDEVICEREMAPPED, /**< The controller mapping was updated */
SDL_CONTROLLERTOUCHPADDOWN, /**< Game controller touchpad was touched */
SDL_CONTROLLERTOUCHPADMOTION, /**< Game controller touchpad finger was moved */
SDL_CONTROLLERTOUCHPADUP, /**< Game controller touchpad finger was lifted */
SDL_CONTROLLERSENSORUPDATE, /**< Game controller sensor was updated */
SDL_CONTROLLERUPDATECOMPLETE_RESERVED_FOR_SDL3,
SDL_CONTROLLERSTEAMHANDLEUPDATED, /**< Game controller Steam handle has changed */
/* Touch events */
SDL_FINGERDOWN = 0x700,
SDL_FINGERUP,
SDL_FINGERMOTION,
/* Gesture events */
SDL_DOLLARGESTURE = 0x800,
SDL_DOLLARRECORD,
SDL_MULTIGESTURE,
/* Clipboard events */
SDL_CLIPBOARDUPDATE = 0x900, /**< The clipboard or primary selection changed */
/* Drag and drop events */
SDL_DROPFILE = 0x1000, /**< The system requests a file open */
SDL_DROPTEXT, /**< text/plain drag-and-drop event */
SDL_DROPBEGIN, /**< A new set of drops is beginning (NULL filename) */
SDL_DROPCOMPLETE, /**< Current set of drops is now complete (NULL filename) */
/* Audio hotplug events */
SDL_AUDIODEVICEADDED = 0x1100, /**< A new audio device is available */
SDL_AUDIODEVICEREMOVED, /**< An audio device has been removed. */
/* Sensor events */
SDL_SENSORUPDATE = 0x1200, /**< A sensor was updated */
/* Render events */
SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
/* Internal events */
SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
/** Events SDL_USEREVENT through SDL_LASTEVENT are for your use,
* and should be allocated with SDL_RegisterEvents()
*/
SDL_USEREVENT = 0x8000,
/**
* This last event is only for bounding internal arrays
*/
SDL_LASTEVENT = 0xFFFF
} SDL_EventType;
/**
* Fields shared by every event
*/
typedef struct SDL_CommonEvent
{
Uint32 type;
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
} SDL_CommonEvent;
/**
* Display state change event data (event.display.*)
*/
typedef struct SDL_DisplayEvent
{
Uint32 type; /**< SDL_DISPLAYEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 display; /**< The associated display index */
Uint8 event; /**< SDL_DisplayEventID */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
Sint32 data1; /**< event dependent data */
} SDL_DisplayEvent;
/**
* Window state change event data (event.window.*)
*/
typedef struct SDL_WindowEvent
{
Uint32 type; /**< SDL_WINDOWEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The associated window */
Uint8 event; /**< SDL_WindowEventID */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
Sint32 data1; /**< event dependent data */
Sint32 data2; /**< event dependent data */
} SDL_WindowEvent;
/**
* Keyboard button event structure (event.key.*)
*/
typedef struct SDL_KeyboardEvent
{
Uint32 type; /**< SDL_KEYDOWN or SDL_KEYUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */
Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 repeat; /**< Non-zero if this is a key repeat */
Uint8 padding2;
Uint8 padding3;
SDL_Keysym keysym; /**< The key that was pressed or released */
} SDL_KeyboardEvent;
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
/**
* Keyboard text editing event structure (event.edit.*)
*/
typedef struct SDL_TextEditingEvent
{
Uint32 type; /**< SDL_TEXTEDITING */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */
Sint32 start; /**< The start cursor of selected editing text */
Sint32 length; /**< The length of selected editing text */
} SDL_TextEditingEvent;
/**
* Extended keyboard text editing event structure (event.editExt.*) when text
* would be truncated if stored in the text buffer SDL_TextEditingEvent
*/
typedef struct SDL_TextEditingExtEvent
{
Uint32 type; /**< SDL_TEXTEDITING_EXT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */
char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */
Sint32 start; /**< The start cursor of selected editing text */
Sint32 length; /**< The length of selected editing text */
} SDL_TextEditingExtEvent;
/**
* The maximum bytes of text that can be supplied in an SDL_TextInputEvent.
*/
#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
/**
* Keyboard text input event structure (event.text.*)
*
* `text` is limited to SDL_TEXTINPUTEVENT_TEXT_SIZE bytes. If the incoming
* string is larger than this, SDL will split it and send it in pieces, across
* multiple events. The string is in UTF-8 format, and if split, SDL
* guarantees that it will not split in the middle of a UTF-8 sequence, so any
* event will only contain complete codepoints. However, if there are several
* codepoints that go together into a single glyph (like an emoji "thumbs up"
* followed by a skin color), they may be split between events.
*
* This event will never be delivered unless text input is enabled by calling
* SDL_StartTextInput(). Text input is enabled by default on desktop
* platforms, and disabled by default on mobile platforms!
*
* \sa SDL_StartTextInput
* \sa SDL_StopTextInput
*/
typedef struct SDL_TextInputEvent
{
Uint32 type; /**< SDL_TEXTINPUT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text; UTF-8 encoded. */
} SDL_TextInputEvent;
/**
* Mouse motion event structure (event.motion.*)
*/
typedef struct SDL_MouseMotionEvent
{
Uint32 type; /**< SDL_MOUSEMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
Uint32 state; /**< The current button state */
Sint32 x; /**< X coordinate, relative to window */
Sint32 y; /**< Y coordinate, relative to window */
Sint32 xrel; /**< The relative motion in the X direction */
Sint32 yrel; /**< The relative motion in the Y direction */
} SDL_MouseMotionEvent;
/**
* Mouse button event structure (event.button.*)
*/
typedef struct SDL_MouseButtonEvent
{
Uint32 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
Uint8 button; /**< The mouse button index */
Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */
Uint8 padding1;
Sint32 x; /**< X coordinate, relative to window */
Sint32 y; /**< Y coordinate, relative to window */
} SDL_MouseButtonEvent;
/**
* Mouse wheel event structure (event.wheel.*)
*/
typedef struct SDL_MouseWheelEvent
{
Uint32 type; /**< SDL_MOUSEWHEEL */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
Sint32 x; /**< The amount scrolled horizontally, positive to the right and negative to the left */
Sint32 y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */
Uint32 direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */
float preciseX; /**< The amount scrolled horizontally, positive to the right and negative to the left, with float precision (added in 2.0.18) */
float preciseY; /**< The amount scrolled vertically, positive away from the user and negative toward the user, with float precision (added in 2.0.18) */
Sint32 mouseX; /**< X coordinate, relative to window (added in 2.26.0) */
Sint32 mouseY; /**< Y coordinate, relative to window (added in 2.26.0) */
} SDL_MouseWheelEvent;
/**
* Joystick axis motion event structure (event.jaxis.*)
*/
typedef struct SDL_JoyAxisEvent
{
Uint32 type; /**< SDL_JOYAXISMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 axis; /**< The joystick axis index */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
Sint16 value; /**< The axis value (range: -32768 to 32767) */
Uint16 padding4;
} SDL_JoyAxisEvent;
/**
* Joystick trackball motion event structure (event.jball.*)
*/
typedef struct SDL_JoyBallEvent
{
Uint32 type; /**< SDL_JOYBALLMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 ball; /**< The joystick trackball index */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
Sint16 xrel; /**< The relative motion in the X direction */
Sint16 yrel; /**< The relative motion in the Y direction */
} SDL_JoyBallEvent;
/**
* Joystick hat position change event structure (event.jhat.*)
*/
typedef struct SDL_JoyHatEvent
{
Uint32 type; /**< SDL_JOYHATMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 hat; /**< The joystick hat index */
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.
*/
Uint8 padding1;
Uint8 padding2;
} SDL_JoyHatEvent;
/**
* Joystick button event structure (event.jbutton.*)
*/
typedef struct SDL_JoyButtonEvent
{
Uint32 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 button; /**< The joystick button index */
Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 padding1;
Uint8 padding2;
} SDL_JoyButtonEvent;
/**
* Joystick device event structure (event.jdevice.*)
*
* SDL will send JOYSTICK_ADDED events for devices that are already plugged in
* during SDL_Init.
*
* \sa SDL_ControllerDeviceEvent
*/
typedef struct SDL_JoyDeviceEvent
{
Uint32 type; /**< SDL_JOYDEVICEADDED or SDL_JOYDEVICEREMOVED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
} SDL_JoyDeviceEvent;
/**
* Joysick battery level change event structure (event.jbattery.*)
*/
typedef struct SDL_JoyBatteryEvent
{
Uint32 type; /**< SDL_JOYBATTERYUPDATED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
SDL_JoystickPowerLevel level; /**< The joystick battery level */
} SDL_JoyBatteryEvent;
/**
* Game controller axis motion event structure (event.caxis.*)
*/
typedef struct SDL_ControllerAxisEvent
{
Uint32 type; /**< SDL_CONTROLLERAXISMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
Sint16 value; /**< The axis value (range: -32768 to 32767) */
Uint16 padding4;
} SDL_ControllerAxisEvent;
/**
* Game controller button event structure (event.cbutton.*)
*/
typedef struct SDL_ControllerButtonEvent
{
Uint32 type; /**< SDL_CONTROLLERBUTTONDOWN or SDL_CONTROLLERBUTTONUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 button; /**< The controller button (SDL_GameControllerButton) */
Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 padding1;
Uint8 padding2;
} SDL_ControllerButtonEvent;
/**
* Controller device event structure (event.cdevice.*)
*
* Joysticks that are supported game controllers receive both an
* SDL_JoyDeviceEvent and an SDL_ControllerDeviceEvent.
*
* SDL will send CONTROLLERDEVICEADDED events for joysticks that are already
* plugged in during SDL_Init() and are recognized as game controllers.
*/
typedef struct SDL_ControllerDeviceEvent
{
Uint32 type; /**< SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, SDL_CONTROLLERDEVICEREMAPPED, or SDL_CONTROLLERSTEAMHANDLEUPDATED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
} SDL_ControllerDeviceEvent;
/**
* Game controller touchpad event structure (event.ctouchpad.*)
*/
typedef struct SDL_ControllerTouchpadEvent
{
Uint32 type; /**< SDL_CONTROLLERTOUCHPADDOWN or SDL_CONTROLLERTOUCHPADMOTION or SDL_CONTROLLERTOUCHPADUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Sint32 touchpad; /**< The index of the touchpad */
Sint32 finger; /**< The index of the finger on the touchpad */
float x; /**< Normalized in the range 0...1 with 0 being on the left */
float y; /**< Normalized in the range 0...1 with 0 being at the top */
float pressure; /**< Normalized in the range 0...1 */
} SDL_ControllerTouchpadEvent;
/**
* Game controller sensor event structure (event.csensor.*)
*/
typedef struct SDL_ControllerSensorEvent
{
Uint32 type; /**< SDL_CONTROLLERSENSORUPDATE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */
float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
} SDL_ControllerSensorEvent;
/**
* Audio device event structure (event.adevice.*)
*/
typedef struct SDL_AudioDeviceEvent
{
Uint32 type; /**< SDL_AUDIODEVICEADDED, or SDL_AUDIODEVICEREMOVED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */
Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
} SDL_AudioDeviceEvent;
/**
* Touch finger event structure (event.tfinger.*)
*/
typedef struct SDL_TouchFingerEvent
{
Uint32 type; /**< SDL_FINGERMOTION or SDL_FINGERDOWN or SDL_FINGERUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */
SDL_FingerID fingerId;
float x; /**< Normalized in the range 0...1 */
float y; /**< Normalized in the range 0...1 */
float dx; /**< Normalized in the range -1...1 */
float dy; /**< Normalized in the range -1...1 */
float pressure; /**< Normalized in the range 0...1 */
Uint32 windowID; /**< The window underneath the finger, if any */
} SDL_TouchFingerEvent;
/**
* Multiple Finger Gesture Event (event.mgesture.*)
*/
typedef struct SDL_MultiGestureEvent
{
Uint32 type; /**< SDL_MULTIGESTURE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */
float dTheta;
float dDist;
float x;
float y;
Uint16 numFingers;
Uint16 padding;
} SDL_MultiGestureEvent;
/**
* Dollar Gesture Event (event.dgesture.*)
*/
typedef struct SDL_DollarGestureEvent
{
Uint32 type; /**< SDL_DOLLARGESTURE or SDL_DOLLARRECORD */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */
SDL_GestureID gestureId;
Uint32 numFingers;
float error;
float x; /**< Normalized center of gesture */
float y; /**< Normalized center of gesture */
} SDL_DollarGestureEvent;
/**
* An event used to request a file open by the system (event.drop.*)
*
* This event is enabled by default, you can disable it with SDL_EventState().
*
* If this event is enabled, you must free the filename in the event.
*/
typedef struct SDL_DropEvent
{
Uint32 type; /**< SDL_DROPBEGIN or SDL_DROPFILE or SDL_DROPTEXT or SDL_DROPCOMPLETE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */
Uint32 windowID; /**< The window that was dropped on, if any */
} SDL_DropEvent;
/**
* Sensor event structure (event.sensor.*)
*/
typedef struct SDL_SensorEvent
{
Uint32 type; /**< SDL_SENSORUPDATE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Sint32 which; /**< The instance ID of the sensor */
float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */
Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
} SDL_SensorEvent;
/**
* The "quit requested" event
*/
typedef struct SDL_QuitEvent
{
Uint32 type; /**< SDL_QUIT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
} SDL_QuitEvent;
/**
* A user-defined event type (event.user.*)
*/
typedef struct SDL_UserEvent
{
Uint32 type; /**< SDL_USEREVENT through SDL_LASTEVENT-1 */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The associated window if any */
Sint32 code; /**< User defined event code */
void *data1; /**< User defined data pointer */
void *data2; /**< User defined data pointer */
} SDL_UserEvent;
struct SDL_SysWMmsg;
typedef struct SDL_SysWMmsg SDL_SysWMmsg;
/**
* A video driver dependent system event (event.syswm.*)
*
* This event is disabled by default, you can enable it with SDL_EventState()
*
* If you want to use this event, you should include SDL_syswm.h.
*/
typedef struct SDL_SysWMEvent
{
Uint32 type; /**< SDL_SYSWMEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
} SDL_SysWMEvent;
/**
* General event structure
*
* The SDL_Event structure is the core of all event handling in SDL. SDL_Event
* is a union of all event structures used in SDL.
*/
typedef union SDL_Event
{
Uint32 type; /**< Event type, shared with all events */
SDL_CommonEvent common; /**< Common event data */
SDL_DisplayEvent display; /**< Display event data */
SDL_WindowEvent window; /**< Window event data */
SDL_KeyboardEvent key; /**< Keyboard event data */
SDL_TextEditingEvent edit; /**< Text editing event data */
SDL_TextEditingExtEvent editExt; /**< Extended text editing event data */
SDL_TextInputEvent text; /**< Text input event data */
SDL_MouseMotionEvent motion; /**< Mouse motion event data */
SDL_MouseButtonEvent button; /**< Mouse button event data */
SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
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_JoyDeviceEvent jdevice; /**< Joystick device change event data */
SDL_JoyBatteryEvent jbattery; /**< Joystick battery event data */
SDL_ControllerAxisEvent caxis; /**< Game Controller axis event data */
SDL_ControllerButtonEvent cbutton; /**< Game Controller button event data */
SDL_ControllerDeviceEvent cdevice; /**< Game Controller device event data */
SDL_ControllerTouchpadEvent ctouchpad; /**< Game Controller touchpad event data */
SDL_ControllerSensorEvent csensor; /**< Game Controller sensor event data */
SDL_AudioDeviceEvent adevice; /**< Audio device event data */
SDL_SensorEvent sensor; /**< Sensor event data */
SDL_QuitEvent quit; /**< Quit request event data */
SDL_UserEvent user; /**< Custom event data */
SDL_SysWMEvent syswm; /**< System dependent window event data */
SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
SDL_MultiGestureEvent mgesture; /**< Gesture event data */
SDL_DollarGestureEvent dgesture; /**< Gesture event data */
SDL_DropEvent drop; /**< Drag and drop event data */
/* This is necessary for ABI compatibility between Visual C++ and GCC.
Visual C++ will respect the push pack pragma and use 52 bytes (size of
SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
architectures) for this union, and GCC will use the alignment of the
largest datatype within the union, which is 8 bytes on 64-bit
architectures.
So... we'll add padding to force the size to be 56 bytes for both.
On architectures where pointers are 16 bytes, this needs rounding up to
the next multiple of 16, 64, and on architectures where pointers are
even larger the size of SDL_UserEvent will dominate as being 3 pointers.
*/
Uint8 padding[sizeof(void *) <= 8 ? 56 : sizeof(void *) == 16 ? 64 : 3 * sizeof(void *)];
} SDL_Event;
/* Make sure we haven't broken binary compatibility */
SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NULL)->padding));
/* Function prototypes */
/**
* Pump the event loop, gathering events from the input devices.
*
* This function updates the event queue and internal input device state.
*
* **WARNING**: This should only be run in the thread that initialized the
* video subsystem, and for extra safety, you should consider only doing those
* things on the main thread in any case.
*
* SDL_PumpEvents() gathers all the pending input information from devices and
* places it in the event queue. Without calls to SDL_PumpEvents() no events
* would ever be placed on the queue. Often the need for calls to
* SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
* SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
* polling or waiting for events (e.g. you are filtering them), then you must
* call SDL_PumpEvents() to force an event queue update.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_PollEvent
* \sa SDL_WaitEvent
*/
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
/* @{ */
typedef enum SDL_eventaction
{
SDL_ADDEVENT,
SDL_PEEKEVENT,
SDL_GETEVENT
} SDL_eventaction;
/**
* Check the event queue for messages and optionally return them.
*
* `action` may be any of the following:
*
* - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
* event queue.
* - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
* within the specified minimum and maximum type, will be returned to the
* caller and will _not_ be removed from the queue.
* - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
* within the specified minimum and maximum type, will be returned to the
* caller and will be removed from the queue.
*
* You may have to call SDL_PumpEvents() before calling this function.
* Otherwise, the events may not be ready to be filtered when you call
* SDL_PeepEvents().
*
* This function is thread-safe.
*
* \param events destination buffer for the retrieved events.
* \param numevents if action is SDL_ADDEVENT, the number of events to add
* back to the event queue; if action is SDL_PEEKEVENT or
* SDL_GETEVENT, the maximum number of events to retrieve.
* \param action action to take; see [[#action|Remarks]] for details.
* \param minType minimum value of the event type to be considered;
* SDL_FIRSTEVENT is a safe choice.
* \param maxType maximum value of the event type to be considered;
* SDL_LASTEVENT is a safe choice.
* \returns the number of events actually stored or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_PushEvent
*/
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
Uint32 minType, Uint32 maxType);
/* @} */
/**
* Check for the existence of a certain event type in the event queue.
*
* If you need to check for a range of event types, use SDL_HasEvents()
* instead.
*
* \param type the type of event to be queried; see SDL_EventType for details.
* \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
* events matching `type` are not present.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
/**
* Check for the existence of certain event types in the event queue.
*
* If you need to check for a single event type, use SDL_HasEvent() instead.
*
* \param minType the low end of event type to be queried, inclusive; see
* SDL_EventType for details.
* \param maxType the high end of event type to be queried, inclusive; see
* SDL_EventType for details.
* \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
* present, or SDL_FALSE if not.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
/**
* Clear events of a specific type from the event queue.
*
* This will unconditionally remove any events from the queue that match
* `type`. If you need to remove a range of event types, use SDL_FlushEvents()
* instead.
*
* It's also normal to just ignore events you don't care about in your event
* loop without calling this function.
*
* This function only affects currently queued events. If you want to make
* sure that all pending OS events are flushed, you can call SDL_PumpEvents()
* on the main thread immediately before the flush call.
*
* \param type the type of event to be cleared; see SDL_EventType for details.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_FlushEvents
*/
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
/**
* Clear events of a range of types from the event queue.
*
* This will unconditionally remove any events from the queue that are in the
* range of `minType` to `maxType`, inclusive. If you need to remove a single
* event type, use SDL_FlushEvent() instead.
*
* It's also normal to just ignore events you don't care about in your event
* loop without calling this function.
*
* This function only affects currently queued events. If you want to make
* sure that all pending OS events are flushed, you can call SDL_PumpEvents()
* on the main thread immediately before the flush call.
*
* \param minType the low end of event type to be cleared, inclusive; see
* SDL_EventType for details.
* \param maxType the high end of event type to be cleared, inclusive; see
* SDL_EventType for details.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_FlushEvent
*/
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
/**
* Poll for currently pending events.
*
* If `event` is not NULL, the next event is removed from the queue and stored
* in the SDL_Event structure pointed to by `event`. The 1 returned refers to
* this event, immediately stored in the SDL Event structure -- not an event
* to follow.
*
* If `event` is NULL, it simply returns 1 if there is an event in the queue,
* but will not remove it from the queue.
*
* As this function may implicitly call SDL_PumpEvents(), you can only call
* this function in the thread that set the video mode.
*
* SDL_PollEvent() is the favored way of receiving system events since it can
* be done from the main loop and does not suspend the main loop while waiting
* on an event to be posted.
*
* The common practice is to fully process the event queue once every frame,
* usually as a first step before updating the game's state:
*
* ```c
* while (game_is_still_running) {
* SDL_Event event;
* while (SDL_PollEvent(&event)) { // poll until all events are handled!
* // decide what to do with this event.
* }
*
* // update game state, draw the current frame
* }
* ```
*
* \param event the SDL_Event structure to be filled with the next event from
* the queue, or NULL.
* \returns 1 if there is a pending event or 0 if there are none available.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_GetEventFilter
* \sa SDL_PeepEvents
* \sa SDL_PushEvent
* \sa SDL_SetEventFilter
* \sa SDL_WaitEvent
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
/**
* Wait indefinitely for the next available event.
*
* If `event` is not NULL, the next event is removed from the queue and stored
* in the SDL_Event structure pointed to by `event`.
*
* As this function may implicitly call SDL_PumpEvents(), you can only call
* this function in the thread that initialized the video subsystem.
*
* \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL.
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
/**
* Wait until the specified timeout (in milliseconds) for the next available
* event.
*
* If `event` is not NULL, the next event is removed from the queue and stored
* in the SDL_Event structure pointed to by `event`.
*
* As this function may implicitly call SDL_PumpEvents(), you can only call
* this function in the thread that initialized the video subsystem.
*
* \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL.
* \param timeout the maximum number of milliseconds to wait for the next
* available event.
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information. This also returns 0 if
* the timeout elapsed without an event arriving.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEvent
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
int timeout);
/**
* Add an event to the event queue.
*
* The event queue can actually be used as a two way communication channel.
* Not only can events be read from the queue, but the user can also push
* their own events onto it. `event` is a pointer to the event structure you
* wish to push onto the queue. The event is copied into the queue, and the
* caller may dispose of the memory pointed to after SDL_PushEvent() returns.
*
* Note: Pushing device input events onto the queue doesn't modify the state
* of the device within SDL.
*
* This function is thread-safe, and can be called from other threads safely.
*
* Note: Events pushed onto the queue with SDL_PushEvent() get passed through
* the event filter but events added with SDL_PeepEvents() do not.
*
* For pushing application-specific events, please use SDL_RegisterEvents() to
* get an event type that does not conflict with other code that also wants
* its own custom event types.
*
* \param event the SDL_Event to be added to the queue.
* \returns 1 on success, 0 if the event was filtered, or a negative error
* code on failure; call SDL_GetError() for more information. A
* common reason for error is the event queue being full.
*
* \since This function is available since SDL 2.0.0.
*
* \sa SDL_PeepEvents
* \sa SDL_PollEvent
* \sa SDL_RegisterEvents
*/
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
/**
* A function pointer used for callbacks that watch the event queue.
*