|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryEvents
|
|
|
24 *
|
|
|
25 * Event queue management.
|
|
|
26 *
|
|
|
27 * It's extremely common--often required--that an app deal with SDL's event
|
|
|
28 * queue. Almost all useful information about interactions with the real world
|
|
|
29 * flow through here: the user interacting with the computer and app, hardware
|
|
|
30 * coming and going, the system changing in some way, etc.
|
|
|
31 *
|
|
|
32 * An app generally takes a moment, perhaps at the start of a new frame, to
|
|
|
33 * examine any events that have occurred since the last time and process or
|
|
|
34 * ignore them. This is generally done by calling SDL_PollEvent() in a loop
|
|
|
35 * until it returns false (or, if using the main callbacks, events are
|
|
|
36 * provided one at a time in calls to SDL_AppEvent() before the next call to
|
|
|
37 * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent()
|
|
|
38 * at all).
|
|
|
39 *
|
|
|
40 * There is other forms of control, too: SDL_PeepEvents() has more
|
|
|
41 * functionality at the cost of more complexity, and SDL_WaitEvent() can block
|
|
|
42 * the process until something interesting happens, which might be beneficial
|
|
|
43 * for certain types of programs on low-power hardware. One may also call
|
|
|
44 * SDL_AddEventWatch() to set a callback when new events arrive.
|
|
|
45 *
|
|
|
46 * The app is free to generate their own events, too: SDL_PushEvent allows the
|
|
|
47 * app to put events onto the queue for later retrieval; SDL_RegisterEvents
|
|
|
48 * can guarantee that these events have a type that isn't in use by other
|
|
|
49 * parts of the system.
|
|
|
50 */
|
|
|
51
|
|
|
52 #ifndef SDL_events_h_
|
|
|
53 #define SDL_events_h_
|
|
|
54
|
|
|
55 #include <SDL3/SDL_stdinc.h>
|
|
|
56 #include <SDL3/SDL_audio.h>
|
|
|
57 #include <SDL3/SDL_camera.h>
|
|
|
58 #include <SDL3/SDL_error.h>
|
|
|
59 #include <SDL3/SDL_gamepad.h>
|
|
|
60 #include <SDL3/SDL_joystick.h>
|
|
|
61 #include <SDL3/SDL_keyboard.h>
|
|
|
62 #include <SDL3/SDL_keycode.h>
|
|
|
63 #include <SDL3/SDL_mouse.h>
|
|
|
64 #include <SDL3/SDL_pen.h>
|
|
|
65 #include <SDL3/SDL_power.h>
|
|
|
66 #include <SDL3/SDL_sensor.h>
|
|
|
67 #include <SDL3/SDL_scancode.h>
|
|
|
68 #include <SDL3/SDL_touch.h>
|
|
|
69 #include <SDL3/SDL_video.h>
|
|
|
70
|
|
|
71 #include <SDL3/SDL_begin_code.h>
|
|
|
72 /* Set up for C function definitions, even when using C++ */
|
|
|
73 #ifdef __cplusplus
|
|
|
74 extern "C" {
|
|
|
75 #endif
|
|
|
76
|
|
|
77 /* General keyboard/mouse/pen state definitions */
|
|
|
78
|
|
|
79 /**
|
|
|
80 * The types of events that can be delivered.
|
|
|
81 *
|
|
|
82 * \since This enum is available since SDL 3.2.0.
|
|
|
83 */
|
|
|
84 typedef enum SDL_EventType
|
|
|
85 {
|
|
|
86 SDL_EVENT_FIRST = 0, /**< Unused (do not remove) */
|
|
|
87
|
|
|
88 /* Application events */
|
|
|
89 SDL_EVENT_QUIT = 0x100, /**< User-requested quit */
|
|
|
90
|
|
|
91 /* These application events have special meaning on iOS and Android, see README-ios.md and README-android.md for details */
|
|
|
92 SDL_EVENT_TERMINATING, /**< The application is being terminated by the OS. This event must be handled in a callback set with SDL_AddEventWatch().
|
|
|
93 Called on iOS in applicationWillTerminate()
|
|
|
94 Called on Android in onDestroy()
|
|
|
95 */
|
|
|
96 SDL_EVENT_LOW_MEMORY, /**< The application is low on memory, free memory if possible. This event must be handled in a callback set with SDL_AddEventWatch().
|
|
|
97 Called on iOS in applicationDidReceiveMemoryWarning()
|
|
|
98 Called on Android in onTrimMemory()
|
|
|
99 */
|
|
|
100 SDL_EVENT_WILL_ENTER_BACKGROUND, /**< The application is about to enter the background. This event must be handled in a callback set with SDL_AddEventWatch().
|
|
|
101 Called on iOS in applicationWillResignActive()
|
|
|
102 Called on Android in onPause()
|
|
|
103 */
|
|
|
104 SDL_EVENT_DID_ENTER_BACKGROUND, /**< The application did enter the background and may not get CPU for some time. This event must be handled in a callback set with SDL_AddEventWatch().
|
|
|
105 Called on iOS in applicationDidEnterBackground()
|
|
|
106 Called on Android in onPause()
|
|
|
107 */
|
|
|
108 SDL_EVENT_WILL_ENTER_FOREGROUND, /**< The application is about to enter the foreground. This event must be handled in a callback set with SDL_AddEventWatch().
|
|
|
109 Called on iOS in applicationWillEnterForeground()
|
|
|
110 Called on Android in onResume()
|
|
|
111 */
|
|
|
112 SDL_EVENT_DID_ENTER_FOREGROUND, /**< The application is now interactive. This event must be handled in a callback set with SDL_AddEventWatch().
|
|
|
113 Called on iOS in applicationDidBecomeActive()
|
|
|
114 Called on Android in onResume()
|
|
|
115 */
|
|
|
116
|
|
|
117 SDL_EVENT_LOCALE_CHANGED, /**< The user's locale preferences have changed. */
|
|
|
118
|
|
|
119 SDL_EVENT_SYSTEM_THEME_CHANGED, /**< The system theme changed */
|
|
|
120
|
|
|
121 /* Display events */
|
|
|
122 /* 0x150 was SDL_DISPLAYEVENT, reserve the number for sdl2-compat */
|
|
|
123 SDL_EVENT_DISPLAY_ORIENTATION = 0x151, /**< Display orientation has changed to data1 */
|
|
|
124 SDL_EVENT_DISPLAY_ADDED, /**< Display has been added to the system */
|
|
|
125 SDL_EVENT_DISPLAY_REMOVED, /**< Display has been removed from the system */
|
|
|
126 SDL_EVENT_DISPLAY_MOVED, /**< Display has changed position */
|
|
|
127 SDL_EVENT_DISPLAY_DESKTOP_MODE_CHANGED, /**< Display has changed desktop mode */
|
|
|
128 SDL_EVENT_DISPLAY_CURRENT_MODE_CHANGED, /**< Display has changed current mode */
|
|
|
129 SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED, /**< Display has changed content scale */
|
|
|
130 SDL_EVENT_DISPLAY_USABLE_BOUNDS_CHANGED, /**< Display has changed usable bounds */
|
|
|
131 SDL_EVENT_DISPLAY_FIRST = SDL_EVENT_DISPLAY_ORIENTATION,
|
|
|
132 SDL_EVENT_DISPLAY_LAST = SDL_EVENT_DISPLAY_USABLE_BOUNDS_CHANGED,
|
|
|
133
|
|
|
134 /* Window events */
|
|
|
135 /* 0x200 was SDL_WINDOWEVENT, reserve the number for sdl2-compat */
|
|
|
136 /* 0x201 was SDL_SYSWMEVENT, reserve the number for sdl2-compat */
|
|
|
137 SDL_EVENT_WINDOW_SHOWN = 0x202, /**< Window has been shown */
|
|
|
138 SDL_EVENT_WINDOW_HIDDEN, /**< Window has been hidden */
|
|
|
139 SDL_EVENT_WINDOW_EXPOSED, /**< Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event.
|
|
|
140 data1 is 1 for live-resize expose events, 0 otherwise. */
|
|
|
141 SDL_EVENT_WINDOW_MOVED, /**< Window has been moved to data1, data2 */
|
|
|
142 SDL_EVENT_WINDOW_RESIZED, /**< Window has been resized to data1xdata2 */
|
|
|
143 SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED,/**< The pixel size of the window has changed to data1xdata2 */
|
|
|
144 SDL_EVENT_WINDOW_METAL_VIEW_RESIZED,/**< The pixel size of a Metal view associated with the window has changed */
|
|
|
145 SDL_EVENT_WINDOW_MINIMIZED, /**< Window has been minimized */
|
|
|
146 SDL_EVENT_WINDOW_MAXIMIZED, /**< Window has been maximized */
|
|
|
147 SDL_EVENT_WINDOW_RESTORED, /**< Window has been restored to normal size and position */
|
|
|
148 SDL_EVENT_WINDOW_MOUSE_ENTER, /**< Window has gained mouse focus */
|
|
|
149 SDL_EVENT_WINDOW_MOUSE_LEAVE, /**< Window has lost mouse focus */
|
|
|
150 SDL_EVENT_WINDOW_FOCUS_GAINED, /**< Window has gained keyboard focus */
|
|
|
151 SDL_EVENT_WINDOW_FOCUS_LOST, /**< Window has lost keyboard focus */
|
|
|
152 SDL_EVENT_WINDOW_CLOSE_REQUESTED, /**< The window manager requests that the window be closed */
|
|
|
153 SDL_EVENT_WINDOW_HIT_TEST, /**< Window had a hit test that wasn't SDL_HITTEST_NORMAL */
|
|
|
154 SDL_EVENT_WINDOW_ICCPROF_CHANGED, /**< The ICC profile of the window's display has changed */
|
|
|
155 SDL_EVENT_WINDOW_DISPLAY_CHANGED, /**< Window has been moved to display data1 */
|
|
|
156 SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED, /**< Window display scale has been changed */
|
|
|
157 SDL_EVENT_WINDOW_SAFE_AREA_CHANGED, /**< The window safe area has been changed */
|
|
|
158 SDL_EVENT_WINDOW_OCCLUDED, /**< The window has been occluded */
|
|
|
159 SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */
|
|
|
160 SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */
|
|
|
161 SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled
|
|
|
162 in an event watcher, the window handle is still valid and can still be used to retrieve any properties
|
|
|
163 associated with the window. Otherwise, the handle has already been destroyed and all resources
|
|
|
164 associated with it are invalid */
|
|
|
165 SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */
|
|
|
166 SDL_EVENT_WINDOW_FIRST = SDL_EVENT_WINDOW_SHOWN,
|
|
|
167 SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_HDR_STATE_CHANGED,
|
|
|
168
|
|
|
169 /* Keyboard events */
|
|
|
170 SDL_EVENT_KEY_DOWN = 0x300, /**< Key pressed */
|
|
|
171 SDL_EVENT_KEY_UP, /**< Key released */
|
|
|
172 SDL_EVENT_TEXT_EDITING, /**< Keyboard text editing (composition) */
|
|
|
173 SDL_EVENT_TEXT_INPUT, /**< Keyboard text input */
|
|
|
174 SDL_EVENT_KEYMAP_CHANGED, /**< Keymap changed due to a system event such as an
|
|
|
175 input language or keyboard layout change. */
|
|
|
176 SDL_EVENT_KEYBOARD_ADDED, /**< A new keyboard has been inserted into the system */
|
|
|
177 SDL_EVENT_KEYBOARD_REMOVED, /**< A keyboard has been removed */
|
|
|
178 SDL_EVENT_TEXT_EDITING_CANDIDATES, /**< Keyboard text editing candidates */
|
|
|
179 SDL_EVENT_SCREEN_KEYBOARD_SHOWN, /**< The on-screen keyboard has been shown */
|
|
|
180 SDL_EVENT_SCREEN_KEYBOARD_HIDDEN, /**< The on-screen keyboard has been hidden */
|
|
|
181
|
|
|
182 /* Mouse events */
|
|
|
183 SDL_EVENT_MOUSE_MOTION = 0x400, /**< Mouse moved */
|
|
|
184 SDL_EVENT_MOUSE_BUTTON_DOWN, /**< Mouse button pressed */
|
|
|
185 SDL_EVENT_MOUSE_BUTTON_UP, /**< Mouse button released */
|
|
|
186 SDL_EVENT_MOUSE_WHEEL, /**< Mouse wheel motion */
|
|
|
187 SDL_EVENT_MOUSE_ADDED, /**< A new mouse has been inserted into the system */
|
|
|
188 SDL_EVENT_MOUSE_REMOVED, /**< A mouse has been removed */
|
|
|
189
|
|
|
190 /* Joystick events */
|
|
|
191 SDL_EVENT_JOYSTICK_AXIS_MOTION = 0x600, /**< Joystick axis motion */
|
|
|
192 SDL_EVENT_JOYSTICK_BALL_MOTION, /**< Joystick trackball motion */
|
|
|
193 SDL_EVENT_JOYSTICK_HAT_MOTION, /**< Joystick hat position change */
|
|
|
194 SDL_EVENT_JOYSTICK_BUTTON_DOWN, /**< Joystick button pressed */
|
|
|
195 SDL_EVENT_JOYSTICK_BUTTON_UP, /**< Joystick button released */
|
|
|
196 SDL_EVENT_JOYSTICK_ADDED, /**< A new joystick has been inserted into the system */
|
|
|
197 SDL_EVENT_JOYSTICK_REMOVED, /**< An opened joystick has been removed */
|
|
|
198 SDL_EVENT_JOYSTICK_BATTERY_UPDATED, /**< Joystick battery level change */
|
|
|
199 SDL_EVENT_JOYSTICK_UPDATE_COMPLETE, /**< Joystick update is complete */
|
|
|
200
|
|
|
201 /* Gamepad events */
|
|
|
202 SDL_EVENT_GAMEPAD_AXIS_MOTION = 0x650, /**< Gamepad axis motion */
|
|
|
203 SDL_EVENT_GAMEPAD_BUTTON_DOWN, /**< Gamepad button pressed */
|
|
|
204 SDL_EVENT_GAMEPAD_BUTTON_UP, /**< Gamepad button released */
|
|
|
205 SDL_EVENT_GAMEPAD_ADDED, /**< A new gamepad has been inserted into the system */
|
|
|
206 SDL_EVENT_GAMEPAD_REMOVED, /**< A gamepad has been removed */
|
|
|
207 SDL_EVENT_GAMEPAD_REMAPPED, /**< The gamepad mapping was updated */
|
|
|
208 SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN, /**< Gamepad touchpad was touched */
|
|
|
209 SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION, /**< Gamepad touchpad finger was moved */
|
|
|
210 SDL_EVENT_GAMEPAD_TOUCHPAD_UP, /**< Gamepad touchpad finger was lifted */
|
|
|
211 SDL_EVENT_GAMEPAD_SENSOR_UPDATE, /**< Gamepad sensor was updated */
|
|
|
212 SDL_EVENT_GAMEPAD_UPDATE_COMPLETE, /**< Gamepad update is complete */
|
|
|
213 SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED, /**< Gamepad Steam handle has changed */
|
|
|
214
|
|
|
215 /* Touch events */
|
|
|
216 SDL_EVENT_FINGER_DOWN = 0x700,
|
|
|
217 SDL_EVENT_FINGER_UP,
|
|
|
218 SDL_EVENT_FINGER_MOTION,
|
|
|
219 SDL_EVENT_FINGER_CANCELED,
|
|
|
220
|
|
|
221 /* Pinch events */
|
|
|
222 SDL_EVENT_PINCH_BEGIN = 0x710, /**< Pinch gesture started */
|
|
|
223 SDL_EVENT_PINCH_UPDATE, /**< Pinch gesture updated */
|
|
|
224 SDL_EVENT_PINCH_END, /**< Pinch gesture ended */
|
|
|
225
|
|
|
226 /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */
|
|
|
227
|
|
|
228 /* Clipboard events */
|
|
|
229 SDL_EVENT_CLIPBOARD_UPDATE = 0x900, /**< The clipboard changed */
|
|
|
230
|
|
|
231 /* Drag and drop events */
|
|
|
232 SDL_EVENT_DROP_FILE = 0x1000, /**< The system requests a file open */
|
|
|
233 SDL_EVENT_DROP_TEXT, /**< text/plain drag-and-drop event */
|
|
|
234 SDL_EVENT_DROP_BEGIN, /**< A new set of drops is beginning (NULL filename) */
|
|
|
235 SDL_EVENT_DROP_COMPLETE, /**< Current set of drops is now complete (NULL filename) */
|
|
|
236 SDL_EVENT_DROP_POSITION, /**< Position while moving over the window */
|
|
|
237
|
|
|
238 /* Audio hotplug events */
|
|
|
239 SDL_EVENT_AUDIO_DEVICE_ADDED = 0x1100, /**< A new audio device is available */
|
|
|
240 SDL_EVENT_AUDIO_DEVICE_REMOVED, /**< An audio device has been removed. */
|
|
|
241 SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED, /**< An audio device's format has been changed by the system. */
|
|
|
242
|
|
|
243 /* Sensor events */
|
|
|
244 SDL_EVENT_SENSOR_UPDATE = 0x1200, /**< A sensor was updated */
|
|
|
245
|
|
|
246 /* Pressure-sensitive pen events */
|
|
|
247 SDL_EVENT_PEN_PROXIMITY_IN = 0x1300, /**< Pressure-sensitive pen has become available */
|
|
|
248 SDL_EVENT_PEN_PROXIMITY_OUT, /**< Pressure-sensitive pen has become unavailable */
|
|
|
249 SDL_EVENT_PEN_DOWN, /**< Pressure-sensitive pen touched drawing surface */
|
|
|
250 SDL_EVENT_PEN_UP, /**< Pressure-sensitive pen stopped touching drawing surface */
|
|
|
251 SDL_EVENT_PEN_BUTTON_DOWN, /**< Pressure-sensitive pen button pressed */
|
|
|
252 SDL_EVENT_PEN_BUTTON_UP, /**< Pressure-sensitive pen button released */
|
|
|
253 SDL_EVENT_PEN_MOTION, /**< Pressure-sensitive pen is moving on the tablet */
|
|
|
254 SDL_EVENT_PEN_AXIS, /**< Pressure-sensitive pen angle/pressure/etc changed */
|
|
|
255
|
|
|
256 /* Camera hotplug events */
|
|
|
257 SDL_EVENT_CAMERA_DEVICE_ADDED = 0x1400, /**< A new camera device is available */
|
|
|
258 SDL_EVENT_CAMERA_DEVICE_REMOVED, /**< A camera device has been removed. */
|
|
|
259 SDL_EVENT_CAMERA_DEVICE_APPROVED, /**< A camera device has been approved for use by the user. */
|
|
|
260 SDL_EVENT_CAMERA_DEVICE_DENIED, /**< A camera device has been denied for use by the user. */
|
|
|
261
|
|
|
262 /* Render events */
|
|
|
263 SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
|
|
|
264 SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
|
|
|
265 SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */
|
|
|
266
|
|
|
267 /* Reserved events for private platforms */
|
|
|
268 SDL_EVENT_PRIVATE0 = 0x4000,
|
|
|
269 SDL_EVENT_PRIVATE1,
|
|
|
270 SDL_EVENT_PRIVATE2,
|
|
|
271 SDL_EVENT_PRIVATE3,
|
|
|
272
|
|
|
273 /* Internal events */
|
|
|
274 SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
|
|
|
275
|
|
|
276 /** Events SDL_EVENT_USER through SDL_EVENT_LAST are for your use,
|
|
|
277 * and should be allocated with SDL_RegisterEvents()
|
|
|
278 */
|
|
|
279 SDL_EVENT_USER = 0x8000,
|
|
|
280
|
|
|
281 /**
|
|
|
282 * This last event is only for bounding internal arrays
|
|
|
283 */
|
|
|
284 SDL_EVENT_LAST = 0xFFFF,
|
|
|
285
|
|
|
286 /* This just makes sure the enum is the size of Uint32 */
|
|
|
287 SDL_EVENT_ENUM_PADDING = 0x7FFFFFFF
|
|
|
288
|
|
|
289 } SDL_EventType;
|
|
|
290
|
|
|
291 /**
|
|
|
292 * Fields shared by every event
|
|
|
293 *
|
|
|
294 * \since This struct is available since SDL 3.2.0.
|
|
|
295 */
|
|
|
296 typedef struct SDL_CommonEvent
|
|
|
297 {
|
|
|
298 Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */
|
|
|
299 Uint32 reserved;
|
|
|
300 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
301 } SDL_CommonEvent;
|
|
|
302
|
|
|
303 /**
|
|
|
304 * Display state change event data (event.display.*)
|
|
|
305 *
|
|
|
306 * \since This struct is available since SDL 3.2.0.
|
|
|
307 */
|
|
|
308 typedef struct SDL_DisplayEvent
|
|
|
309 {
|
|
|
310 SDL_EventType type; /**< SDL_EVENT_DISPLAY_* */
|
|
|
311 Uint32 reserved;
|
|
|
312 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
313 SDL_DisplayID displayID;/**< The associated display */
|
|
|
314 Sint32 data1; /**< event dependent data */
|
|
|
315 Sint32 data2; /**< event dependent data */
|
|
|
316 } SDL_DisplayEvent;
|
|
|
317
|
|
|
318 /**
|
|
|
319 * Window state change event data (event.window.*)
|
|
|
320 *
|
|
|
321 * \since This struct is available since SDL 3.2.0.
|
|
|
322 */
|
|
|
323 typedef struct SDL_WindowEvent
|
|
|
324 {
|
|
|
325 SDL_EventType type; /**< SDL_EVENT_WINDOW_* */
|
|
|
326 Uint32 reserved;
|
|
|
327 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
328 SDL_WindowID windowID; /**< The associated window */
|
|
|
329 Sint32 data1; /**< event dependent data */
|
|
|
330 Sint32 data2; /**< event dependent data */
|
|
|
331 } SDL_WindowEvent;
|
|
|
332
|
|
|
333 /**
|
|
|
334 * Keyboard device event structure (event.kdevice.*)
|
|
|
335 *
|
|
|
336 * \since This struct is available since SDL 3.2.0.
|
|
|
337 */
|
|
|
338 typedef struct SDL_KeyboardDeviceEvent
|
|
|
339 {
|
|
|
340 SDL_EventType type; /**< SDL_EVENT_KEYBOARD_ADDED or SDL_EVENT_KEYBOARD_REMOVED */
|
|
|
341 Uint32 reserved;
|
|
|
342 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
343 SDL_KeyboardID which; /**< The keyboard instance id */
|
|
|
344 } SDL_KeyboardDeviceEvent;
|
|
|
345
|
|
|
346 /**
|
|
|
347 * Keyboard button event structure (event.key.*)
|
|
|
348 *
|
|
|
349 * The `key` is the base SDL_Keycode generated by pressing the `scancode`
|
|
|
350 * using the current keyboard layout, applying any options specified in
|
|
|
351 * SDL_HINT_KEYCODE_OPTIONS. You can get the SDL_Keycode corresponding to the
|
|
|
352 * event scancode and modifiers directly from the keyboard layout, bypassing
|
|
|
353 * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode().
|
|
|
354 *
|
|
|
355 * \since This struct is available since SDL 3.2.0.
|
|
|
356 *
|
|
|
357 * \sa SDL_GetKeyFromScancode
|
|
|
358 * \sa SDL_HINT_KEYCODE_OPTIONS
|
|
|
359 */
|
|
|
360 typedef struct SDL_KeyboardEvent
|
|
|
361 {
|
|
|
362 SDL_EventType type; /**< SDL_EVENT_KEY_DOWN or SDL_EVENT_KEY_UP */
|
|
|
363 Uint32 reserved;
|
|
|
364 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
365 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
|
|
|
366 SDL_KeyboardID which; /**< The keyboard instance id, or 0 if unknown or virtual */
|
|
|
367 SDL_Scancode scancode; /**< SDL physical key code */
|
|
|
368 SDL_Keycode key; /**< SDL virtual key code */
|
|
|
369 SDL_Keymod mod; /**< current key modifiers */
|
|
|
370 Uint16 raw; /**< The platform dependent scancode for this event */
|
|
|
371 bool down; /**< true if the key is pressed */
|
|
|
372 bool repeat; /**< true if this is a key repeat */
|
|
|
373 } SDL_KeyboardEvent;
|
|
|
374
|
|
|
375 /**
|
|
|
376 * Keyboard text editing event structure (event.edit.*)
|
|
|
377 *
|
|
|
378 * The start cursor is the position, in UTF-8 characters, where new typing
|
|
|
379 * will be inserted into the editing text. The length is the number of UTF-8
|
|
|
380 * characters that will be replaced by new typing.
|
|
|
381 *
|
|
|
382 * \since This struct is available since SDL 3.2.0.
|
|
|
383 */
|
|
|
384 typedef struct SDL_TextEditingEvent
|
|
|
385 {
|
|
|
386 SDL_EventType type; /**< SDL_EVENT_TEXT_EDITING */
|
|
|
387 Uint32 reserved;
|
|
|
388 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
389 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
|
|
|
390 const char *text; /**< The editing text */
|
|
|
391 Sint32 start; /**< The start cursor of selected editing text, or -1 if not set */
|
|
|
392 Sint32 length; /**< The length of selected editing text, or -1 if not set */
|
|
|
393 } SDL_TextEditingEvent;
|
|
|
394
|
|
|
395 /**
|
|
|
396 * Keyboard IME candidates event structure (event.edit_candidates.*)
|
|
|
397 *
|
|
|
398 * \since This struct is available since SDL 3.2.0.
|
|
|
399 */
|
|
|
400 typedef struct SDL_TextEditingCandidatesEvent
|
|
|
401 {
|
|
|
402 SDL_EventType type; /**< SDL_EVENT_TEXT_EDITING_CANDIDATES */
|
|
|
403 Uint32 reserved;
|
|
|
404 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
405 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
|
|
|
406 const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */
|
|
|
407 Sint32 num_candidates; /**< The number of strings in `candidates` */
|
|
|
408 Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */
|
|
|
409 bool horizontal; /**< true if the list is horizontal, false if it's vertical */
|
|
|
410 Uint8 padding1;
|
|
|
411 Uint8 padding2;
|
|
|
412 Uint8 padding3;
|
|
|
413 } SDL_TextEditingCandidatesEvent;
|
|
|
414
|
|
|
415 /**
|
|
|
416 * Keyboard text input event structure (event.text.*)
|
|
|
417 *
|
|
|
418 * This event will never be delivered unless text input is enabled by calling
|
|
|
419 * SDL_StartTextInput(). Text input is disabled by default!
|
|
|
420 *
|
|
|
421 * \since This struct is available since SDL 3.2.0.
|
|
|
422 *
|
|
|
423 * \sa SDL_StartTextInput
|
|
|
424 * \sa SDL_StopTextInput
|
|
|
425 */
|
|
|
426 typedef struct SDL_TextInputEvent
|
|
|
427 {
|
|
|
428 SDL_EventType type; /**< SDL_EVENT_TEXT_INPUT */
|
|
|
429 Uint32 reserved;
|
|
|
430 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
431 SDL_WindowID windowID; /**< The window with keyboard focus, if any */
|
|
|
432 const char *text; /**< The input text, UTF-8 encoded */
|
|
|
433 } SDL_TextInputEvent;
|
|
|
434
|
|
|
435 /**
|
|
|
436 * Mouse device event structure (event.mdevice.*)
|
|
|
437 *
|
|
|
438 * \since This struct is available since SDL 3.2.0.
|
|
|
439 */
|
|
|
440 typedef struct SDL_MouseDeviceEvent
|
|
|
441 {
|
|
|
442 SDL_EventType type; /**< SDL_EVENT_MOUSE_ADDED or SDL_EVENT_MOUSE_REMOVED */
|
|
|
443 Uint32 reserved;
|
|
|
444 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
445 SDL_MouseID which; /**< The mouse instance id */
|
|
|
446 } SDL_MouseDeviceEvent;
|
|
|
447
|
|
|
448 /**
|
|
|
449 * Mouse motion event structure (event.motion.*)
|
|
|
450 *
|
|
|
451 * \since This struct is available since SDL 3.2.0.
|
|
|
452 */
|
|
|
453 typedef struct SDL_MouseMotionEvent
|
|
|
454 {
|
|
|
455 SDL_EventType type; /**< SDL_EVENT_MOUSE_MOTION */
|
|
|
456 Uint32 reserved;
|
|
|
457 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
458 SDL_WindowID windowID; /**< The window with mouse focus, if any */
|
|
|
459 SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */
|
|
|
460 SDL_MouseButtonFlags state; /**< The current button state */
|
|
|
461 float x; /**< X coordinate, relative to window */
|
|
|
462 float y; /**< Y coordinate, relative to window */
|
|
|
463 float xrel; /**< The relative motion in the X direction */
|
|
|
464 float yrel; /**< The relative motion in the Y direction */
|
|
|
465 } SDL_MouseMotionEvent;
|
|
|
466
|
|
|
467 /**
|
|
|
468 * Mouse button event structure (event.button.*)
|
|
|
469 *
|
|
|
470 * \since This struct is available since SDL 3.2.0.
|
|
|
471 */
|
|
|
472 typedef struct SDL_MouseButtonEvent
|
|
|
473 {
|
|
|
474 SDL_EventType type; /**< SDL_EVENT_MOUSE_BUTTON_DOWN or SDL_EVENT_MOUSE_BUTTON_UP */
|
|
|
475 Uint32 reserved;
|
|
|
476 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
477 SDL_WindowID windowID; /**< The window with mouse focus, if any */
|
|
|
478 SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */
|
|
|
479 Uint8 button; /**< The mouse button index */
|
|
|
480 bool down; /**< true if the button is pressed */
|
|
|
481 Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */
|
|
|
482 Uint8 padding;
|
|
|
483 float x; /**< X coordinate, relative to window */
|
|
|
484 float y; /**< Y coordinate, relative to window */
|
|
|
485 } SDL_MouseButtonEvent;
|
|
|
486
|
|
|
487 /**
|
|
|
488 * Mouse wheel event structure (event.wheel.*)
|
|
|
489 *
|
|
|
490 * \since This struct is available since SDL 3.2.0.
|
|
|
491 */
|
|
|
492 typedef struct SDL_MouseWheelEvent
|
|
|
493 {
|
|
|
494 SDL_EventType type; /**< SDL_EVENT_MOUSE_WHEEL */
|
|
|
495 Uint32 reserved;
|
|
|
496 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
497 SDL_WindowID windowID; /**< The window with mouse focus, if any */
|
|
|
498 SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */
|
|
|
499 float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */
|
|
|
500 float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */
|
|
|
501 SDL_MouseWheelDirection 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 */
|
|
|
502 float mouse_x; /**< X coordinate, relative to window */
|
|
|
503 float mouse_y; /**< Y coordinate, relative to window */
|
|
|
504 Sint32 integer_x; /**< The amount scrolled horizontally, accumulated to whole scroll "ticks" (added in 3.2.12) */
|
|
|
505 Sint32 integer_y; /**< The amount scrolled vertically, accumulated to whole scroll "ticks" (added in 3.2.12) */
|
|
|
506 } SDL_MouseWheelEvent;
|
|
|
507
|
|
|
508 /**
|
|
|
509 * Joystick axis motion event structure (event.jaxis.*)
|
|
|
510 *
|
|
|
511 * \since This struct is available since SDL 3.2.0.
|
|
|
512 */
|
|
|
513 typedef struct SDL_JoyAxisEvent
|
|
|
514 {
|
|
|
515 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_AXIS_MOTION */
|
|
|
516 Uint32 reserved;
|
|
|
517 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
518 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
519 Uint8 axis; /**< The joystick axis index */
|
|
|
520 Uint8 padding1;
|
|
|
521 Uint8 padding2;
|
|
|
522 Uint8 padding3;
|
|
|
523 Sint16 value; /**< The axis value (range: -32768 to 32767) */
|
|
|
524 Uint16 padding4;
|
|
|
525 } SDL_JoyAxisEvent;
|
|
|
526
|
|
|
527 /**
|
|
|
528 * Joystick trackball motion event structure (event.jball.*)
|
|
|
529 *
|
|
|
530 * \since This struct is available since SDL 3.2.0.
|
|
|
531 */
|
|
|
532 typedef struct SDL_JoyBallEvent
|
|
|
533 {
|
|
|
534 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BALL_MOTION */
|
|
|
535 Uint32 reserved;
|
|
|
536 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
537 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
538 Uint8 ball; /**< The joystick trackball index */
|
|
|
539 Uint8 padding1;
|
|
|
540 Uint8 padding2;
|
|
|
541 Uint8 padding3;
|
|
|
542 Sint16 xrel; /**< The relative motion in the X direction */
|
|
|
543 Sint16 yrel; /**< The relative motion in the Y direction */
|
|
|
544 } SDL_JoyBallEvent;
|
|
|
545
|
|
|
546 /**
|
|
|
547 * Joystick hat position change event structure (event.jhat.*)
|
|
|
548 *
|
|
|
549 * \since This struct is available since SDL 3.2.0.
|
|
|
550 */
|
|
|
551 typedef struct SDL_JoyHatEvent
|
|
|
552 {
|
|
|
553 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_HAT_MOTION */
|
|
|
554 Uint32 reserved;
|
|
|
555 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
556 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
557 Uint8 hat; /**< The joystick hat index */
|
|
|
558 Uint8 value; /**< The hat position value.
|
|
|
559 * \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP
|
|
|
560 * \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT
|
|
|
561 * \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN
|
|
|
562 *
|
|
|
563 * Note that zero means the POV is centered.
|
|
|
564 */
|
|
|
565 Uint8 padding1;
|
|
|
566 Uint8 padding2;
|
|
|
567 } SDL_JoyHatEvent;
|
|
|
568
|
|
|
569 /**
|
|
|
570 * Joystick button event structure (event.jbutton.*)
|
|
|
571 *
|
|
|
572 * \since This struct is available since SDL 3.2.0.
|
|
|
573 */
|
|
|
574 typedef struct SDL_JoyButtonEvent
|
|
|
575 {
|
|
|
576 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BUTTON_DOWN or SDL_EVENT_JOYSTICK_BUTTON_UP */
|
|
|
577 Uint32 reserved;
|
|
|
578 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
579 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
580 Uint8 button; /**< The joystick button index */
|
|
|
581 bool down; /**< true if the button is pressed */
|
|
|
582 Uint8 padding1;
|
|
|
583 Uint8 padding2;
|
|
|
584 } SDL_JoyButtonEvent;
|
|
|
585
|
|
|
586 /**
|
|
|
587 * Joystick device event structure (event.jdevice.*)
|
|
|
588 *
|
|
|
589 * SDL will send JOYSTICK_ADDED events for devices that are already plugged in
|
|
|
590 * during SDL_Init.
|
|
|
591 *
|
|
|
592 * \since This struct is available since SDL 3.2.0.
|
|
|
593 *
|
|
|
594 * \sa SDL_GamepadDeviceEvent
|
|
|
595 */
|
|
|
596 typedef struct SDL_JoyDeviceEvent
|
|
|
597 {
|
|
|
598 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_ADDED or SDL_EVENT_JOYSTICK_REMOVED or SDL_EVENT_JOYSTICK_UPDATE_COMPLETE */
|
|
|
599 Uint32 reserved;
|
|
|
600 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
601 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
602 } SDL_JoyDeviceEvent;
|
|
|
603
|
|
|
604 /**
|
|
|
605 * Joystick battery level change event structure (event.jbattery.*)
|
|
|
606 *
|
|
|
607 * \since This struct is available since SDL 3.2.0.
|
|
|
608 */
|
|
|
609 typedef struct SDL_JoyBatteryEvent
|
|
|
610 {
|
|
|
611 SDL_EventType type; /**< SDL_EVENT_JOYSTICK_BATTERY_UPDATED */
|
|
|
612 Uint32 reserved;
|
|
|
613 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
614 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
615 SDL_PowerState state; /**< The joystick battery state */
|
|
|
616 int percent; /**< The joystick battery percent charge remaining */
|
|
|
617 } SDL_JoyBatteryEvent;
|
|
|
618
|
|
|
619 /**
|
|
|
620 * Gamepad axis motion event structure (event.gaxis.*)
|
|
|
621 *
|
|
|
622 * \since This struct is available since SDL 3.2.0.
|
|
|
623 */
|
|
|
624 typedef struct SDL_GamepadAxisEvent
|
|
|
625 {
|
|
|
626 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_AXIS_MOTION */
|
|
|
627 Uint32 reserved;
|
|
|
628 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
629 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
630 Uint8 axis; /**< The gamepad axis (SDL_GamepadAxis) */
|
|
|
631 Uint8 padding1;
|
|
|
632 Uint8 padding2;
|
|
|
633 Uint8 padding3;
|
|
|
634 Sint16 value; /**< The axis value (range: -32768 to 32767) */
|
|
|
635 Uint16 padding4;
|
|
|
636 } SDL_GamepadAxisEvent;
|
|
|
637
|
|
|
638
|
|
|
639 /**
|
|
|
640 * Gamepad button event structure (event.gbutton.*)
|
|
|
641 *
|
|
|
642 * \since This struct is available since SDL 3.2.0.
|
|
|
643 */
|
|
|
644 typedef struct SDL_GamepadButtonEvent
|
|
|
645 {
|
|
|
646 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_BUTTON_DOWN or SDL_EVENT_GAMEPAD_BUTTON_UP */
|
|
|
647 Uint32 reserved;
|
|
|
648 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
649 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
650 Uint8 button; /**< The gamepad button (SDL_GamepadButton) */
|
|
|
651 bool down; /**< true if the button is pressed */
|
|
|
652 Uint8 padding1;
|
|
|
653 Uint8 padding2;
|
|
|
654 } SDL_GamepadButtonEvent;
|
|
|
655
|
|
|
656
|
|
|
657 /**
|
|
|
658 * Gamepad device event structure (event.gdevice.*)
|
|
|
659 *
|
|
|
660 * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent
|
|
|
661 * and an SDL_GamepadDeviceEvent.
|
|
|
662 *
|
|
|
663 * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged
|
|
|
664 * in during SDL_Init() and are recognized as gamepads. It will also send
|
|
|
665 * events for joysticks that get gamepad mappings at runtime.
|
|
|
666 *
|
|
|
667 * \since This struct is available since SDL 3.2.0.
|
|
|
668 *
|
|
|
669 * \sa SDL_JoyDeviceEvent
|
|
|
670 */
|
|
|
671 typedef struct SDL_GamepadDeviceEvent
|
|
|
672 {
|
|
|
673 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_ADDED, SDL_EVENT_GAMEPAD_REMOVED, or SDL_EVENT_GAMEPAD_REMAPPED, SDL_EVENT_GAMEPAD_UPDATE_COMPLETE or SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED */
|
|
|
674 Uint32 reserved;
|
|
|
675 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
676 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
677 } SDL_GamepadDeviceEvent;
|
|
|
678
|
|
|
679 /**
|
|
|
680 * Gamepad touchpad event structure (event.gtouchpad.*)
|
|
|
681 *
|
|
|
682 * \since This struct is available since SDL 3.2.0.
|
|
|
683 */
|
|
|
684 typedef struct SDL_GamepadTouchpadEvent
|
|
|
685 {
|
|
|
686 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN or SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION or SDL_EVENT_GAMEPAD_TOUCHPAD_UP */
|
|
|
687 Uint32 reserved;
|
|
|
688 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
689 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
690 Sint32 touchpad; /**< The index of the touchpad */
|
|
|
691 Sint32 finger; /**< The index of the finger on the touchpad */
|
|
|
692 float x; /**< Normalized in the range 0...1 with 0 being on the left */
|
|
|
693 float y; /**< Normalized in the range 0...1 with 0 being at the top */
|
|
|
694 float pressure; /**< Normalized in the range 0...1 */
|
|
|
695 } SDL_GamepadTouchpadEvent;
|
|
|
696
|
|
|
697 /**
|
|
|
698 * Gamepad sensor event structure (event.gsensor.*)
|
|
|
699 *
|
|
|
700 * \since This struct is available since SDL 3.2.0.
|
|
|
701 */
|
|
|
702 typedef struct SDL_GamepadSensorEvent
|
|
|
703 {
|
|
|
704 SDL_EventType type; /**< SDL_EVENT_GAMEPAD_SENSOR_UPDATE */
|
|
|
705 Uint32 reserved;
|
|
|
706 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
707 SDL_JoystickID which; /**< The joystick instance id */
|
|
|
708 Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */
|
|
|
709 float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
|
|
|
710 Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */
|
|
|
711 } SDL_GamepadSensorEvent;
|
|
|
712
|
|
|
713 /**
|
|
|
714 * Audio device event structure (event.adevice.*)
|
|
|
715 *
|
|
|
716 * Note that SDL will send a SDL_EVENT_AUDIO_DEVICE_ADDED event for every
|
|
|
717 * device it discovers during initialization. After that, this event will only
|
|
|
718 * arrive when a device is hotplugged during the program's run.
|
|
|
719 *
|
|
|
720 * \since This struct is available since SDL 3.2.0.
|
|
|
721 */
|
|
|
722 typedef struct SDL_AudioDeviceEvent
|
|
|
723 {
|
|
|
724 SDL_EventType type; /**< SDL_EVENT_AUDIO_DEVICE_ADDED, or SDL_EVENT_AUDIO_DEVICE_REMOVED, or SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED */
|
|
|
725 Uint32 reserved;
|
|
|
726 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
727 SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */
|
|
|
728 bool recording; /**< false if a playback device, true if a recording device. */
|
|
|
729 Uint8 padding1;
|
|
|
730 Uint8 padding2;
|
|
|
731 Uint8 padding3;
|
|
|
732 } SDL_AudioDeviceEvent;
|
|
|
733
|
|
|
734 /**
|
|
|
735 * Camera device event structure (event.cdevice.*)
|
|
|
736 *
|
|
|
737 * \since This struct is available since SDL 3.2.0.
|
|
|
738 */
|
|
|
739 typedef struct SDL_CameraDeviceEvent
|
|
|
740 {
|
|
|
741 SDL_EventType type; /**< SDL_EVENT_CAMERA_DEVICE_ADDED, SDL_EVENT_CAMERA_DEVICE_REMOVED, SDL_EVENT_CAMERA_DEVICE_APPROVED, SDL_EVENT_CAMERA_DEVICE_DENIED */
|
|
|
742 Uint32 reserved;
|
|
|
743 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
744 SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */
|
|
|
745 } SDL_CameraDeviceEvent;
|
|
|
746
|
|
|
747
|
|
|
748 /**
|
|
|
749 * Renderer event structure (event.render.*)
|
|
|
750 *
|
|
|
751 * \since This struct is available since SDL 3.2.0.
|
|
|
752 */
|
|
|
753 typedef struct SDL_RenderEvent
|
|
|
754 {
|
|
|
755 SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */
|
|
|
756 Uint32 reserved;
|
|
|
757 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
758 SDL_WindowID windowID; /**< The window containing the renderer in question. */
|
|
|
759 } SDL_RenderEvent;
|
|
|
760
|
|
|
761
|
|
|
762 /**
|
|
|
763 * Touch finger event structure (event.tfinger.*)
|
|
|
764 *
|
|
|
765 * Coordinates in this event are normalized. `x` and `y` are normalized to a
|
|
|
766 * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top
|
|
|
767 * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are
|
|
|
768 * normalized in the ranges of -1.0f (traversed all the way from the bottom or
|
|
|
769 * right to all the way up or left) to 1.0f (traversed all the way from the
|
|
|
770 * top or left to all the way down or right).
|
|
|
771 *
|
|
|
772 * Note that while the coordinates are _normalized_, they are not _clamped_,
|
|
|
773 * which means in some circumstances you can get a value outside of this
|
|
|
774 * range. For example, a renderer using logical presentation might give a
|
|
|
775 * negative value when the touch is in the letterboxing. Some platforms might
|
|
|
776 * report a touch outside of the window, which will also be outside of the
|
|
|
777 * range.
|
|
|
778 *
|
|
|
779 * \since This struct is available since SDL 3.2.0.
|
|
|
780 */
|
|
|
781 typedef struct SDL_TouchFingerEvent
|
|
|
782 {
|
|
|
783 SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */
|
|
|
784 Uint32 reserved;
|
|
|
785 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
786 SDL_TouchID touchID; /**< The touch device id */
|
|
|
787 SDL_FingerID fingerID;
|
|
|
788 float x; /**< Normalized in the range 0...1 */
|
|
|
789 float y; /**< Normalized in the range 0...1 */
|
|
|
790 float dx; /**< Normalized in the range -1...1 */
|
|
|
791 float dy; /**< Normalized in the range -1...1 */
|
|
|
792 float pressure; /**< Normalized in the range 0...1 */
|
|
|
793 SDL_WindowID windowID; /**< The window underneath the finger, if any */
|
|
|
794 } SDL_TouchFingerEvent;
|
|
|
795
|
|
|
796 /**
|
|
|
797 * Pinch event structure (event.pinch.*)
|
|
|
798 */
|
|
|
799 typedef struct SDL_PinchFingerEvent
|
|
|
800 {
|
|
|
801 SDL_EventType type; /**< ::SDL_EVENT_PINCH_BEGIN or ::SDL_EVENT_PINCH_UPDATE or ::SDL_EVENT_PINCH_END */
|
|
|
802 Uint32 reserved;
|
|
|
803 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
804 float scale; /**< The scale change since the last SDL_EVENT_PINCH_UPDATE. Scale < 1 is "zoom out". Scale > 1 is "zoom in". */
|
|
|
805 SDL_WindowID windowID; /**< The window underneath the finger, if any */
|
|
|
806 } SDL_PinchFingerEvent;
|
|
|
807
|
|
|
808 /**
|
|
|
809 * Pressure-sensitive pen proximity event structure (event.pproximity.*)
|
|
|
810 *
|
|
|
811 * When a pen becomes visible to the system (it is close enough to a tablet,
|
|
|
812 * etc), SDL will send an SDL_EVENT_PEN_PROXIMITY_IN event with the new pen's
|
|
|
813 * ID. This ID is valid until the pen leaves proximity again (has been removed
|
|
|
814 * from the tablet's area, the tablet has been unplugged, etc). If the same
|
|
|
815 * pen reenters proximity again, it will be given a new ID.
|
|
|
816 *
|
|
|
817 * Note that "proximity" means "close enough for the tablet to know the tool
|
|
|
818 * is there." The pen touching and lifting off from the tablet while not
|
|
|
819 * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP.
|
|
|
820 *
|
|
|
821 * Not all platforms have a window associated with the pen during proximity
|
|
|
822 * events. Some wait until motion/button/etc events to offer this info.
|
|
|
823 *
|
|
|
824 * \since This struct is available since SDL 3.2.0.
|
|
|
825 */
|
|
|
826 typedef struct SDL_PenProximityEvent
|
|
|
827 {
|
|
|
828 SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */
|
|
|
829 Uint32 reserved;
|
|
|
830 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
831 SDL_WindowID windowID; /**< The window with pen focus, if any */
|
|
|
832 SDL_PenID which; /**< The pen instance id */
|
|
|
833 } SDL_PenProximityEvent;
|
|
|
834
|
|
|
835 /**
|
|
|
836 * Pressure-sensitive pen motion event structure (event.pmotion.*)
|
|
|
837 *
|
|
|
838 * Depending on the hardware, you may get motion events when the pen is not
|
|
|
839 * touching a tablet, for tracking a pen even when it isn't drawing. You
|
|
|
840 * should listen for SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP events, or check
|
|
|
841 * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when
|
|
|
842 * dealing with pen motion.
|
|
|
843 *
|
|
|
844 * \since This struct is available since SDL 3.2.0.
|
|
|
845 */
|
|
|
846 typedef struct SDL_PenMotionEvent
|
|
|
847 {
|
|
|
848 SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */
|
|
|
849 Uint32 reserved;
|
|
|
850 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
851 SDL_WindowID windowID; /**< The window with pen focus, if any */
|
|
|
852 SDL_PenID which; /**< The pen instance id */
|
|
|
853 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
|
|
|
854 float x; /**< X coordinate, relative to window */
|
|
|
855 float y; /**< Y coordinate, relative to window */
|
|
|
856 } SDL_PenMotionEvent;
|
|
|
857
|
|
|
858 /**
|
|
|
859 * Pressure-sensitive pen touched event structure (event.ptouch.*)
|
|
|
860 *
|
|
|
861 * These events come when a pen touches a surface (a tablet, etc), or lifts
|
|
|
862 * off from one.
|
|
|
863 *
|
|
|
864 * \since This struct is available since SDL 3.2.0.
|
|
|
865 */
|
|
|
866 typedef struct SDL_PenTouchEvent
|
|
|
867 {
|
|
|
868 SDL_EventType type; /**< SDL_EVENT_PEN_DOWN or SDL_EVENT_PEN_UP */
|
|
|
869 Uint32 reserved;
|
|
|
870 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
871 SDL_WindowID windowID; /**< The window with pen focus, if any */
|
|
|
872 SDL_PenID which; /**< The pen instance id */
|
|
|
873 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
|
|
|
874 float x; /**< X coordinate, relative to window */
|
|
|
875 float y; /**< Y coordinate, relative to window */
|
|
|
876 bool eraser; /**< true if eraser end is used (not all pens support this). */
|
|
|
877 bool down; /**< true if the pen is touching or false if the pen is lifted off */
|
|
|
878 } SDL_PenTouchEvent;
|
|
|
879
|
|
|
880 /**
|
|
|
881 * Pressure-sensitive pen button event structure (event.pbutton.*)
|
|
|
882 *
|
|
|
883 * This is for buttons on the pen itself that the user might click. The pen
|
|
|
884 * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead.
|
|
|
885 *
|
|
|
886 * \since This struct is available since SDL 3.2.0.
|
|
|
887 */
|
|
|
888 typedef struct SDL_PenButtonEvent
|
|
|
889 {
|
|
|
890 SDL_EventType type; /**< SDL_EVENT_PEN_BUTTON_DOWN or SDL_EVENT_PEN_BUTTON_UP */
|
|
|
891 Uint32 reserved;
|
|
|
892 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
893 SDL_WindowID windowID; /**< The window with mouse focus, if any */
|
|
|
894 SDL_PenID which; /**< The pen instance id */
|
|
|
895 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
|
|
|
896 float x; /**< X coordinate, relative to window */
|
|
|
897 float y; /**< Y coordinate, relative to window */
|
|
|
898 Uint8 button; /**< The pen button index (first button is 1). */
|
|
|
899 bool down; /**< true if the button is pressed */
|
|
|
900 } SDL_PenButtonEvent;
|
|
|
901
|
|
|
902 /**
|
|
|
903 * Pressure-sensitive pen pressure / angle event structure (event.paxis.*)
|
|
|
904 *
|
|
|
905 * You might get some of these events even if the pen isn't touching the
|
|
|
906 * tablet.
|
|
|
907 *
|
|
|
908 * \since This struct is available since SDL 3.2.0.
|
|
|
909 */
|
|
|
910 typedef struct SDL_PenAxisEvent
|
|
|
911 {
|
|
|
912 SDL_EventType type; /**< SDL_EVENT_PEN_AXIS */
|
|
|
913 Uint32 reserved;
|
|
|
914 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
915 SDL_WindowID windowID; /**< The window with pen focus, if any */
|
|
|
916 SDL_PenID which; /**< The pen instance id */
|
|
|
917 SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */
|
|
|
918 float x; /**< X coordinate, relative to window */
|
|
|
919 float y; /**< Y coordinate, relative to window */
|
|
|
920 SDL_PenAxis axis; /**< Axis that has changed */
|
|
|
921 float value; /**< New value of axis */
|
|
|
922 } SDL_PenAxisEvent;
|
|
|
923
|
|
|
924 /**
|
|
|
925 * An event used to drop text or request a file open by the system
|
|
|
926 * (event.drop.*)
|
|
|
927 *
|
|
|
928 * \since This struct is available since SDL 3.2.0.
|
|
|
929 */
|
|
|
930 typedef struct SDL_DropEvent
|
|
|
931 {
|
|
|
932 SDL_EventType type; /**< SDL_EVENT_DROP_BEGIN or SDL_EVENT_DROP_FILE or SDL_EVENT_DROP_TEXT or SDL_EVENT_DROP_COMPLETE or SDL_EVENT_DROP_POSITION */
|
|
|
933 Uint32 reserved;
|
|
|
934 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
935 SDL_WindowID windowID; /**< The window that was dropped on, if any */
|
|
|
936 float x; /**< X coordinate, relative to window (not on begin) */
|
|
|
937 float y; /**< Y coordinate, relative to window (not on begin) */
|
|
|
938 const char *source; /**< The source app that sent this drop event, or NULL if that isn't available */
|
|
|
939 const char *data; /**< The text for SDL_EVENT_DROP_TEXT and the file name for SDL_EVENT_DROP_FILE, NULL for other events */
|
|
|
940 } SDL_DropEvent;
|
|
|
941
|
|
|
942 /**
|
|
|
943 * An event triggered when the clipboard contents have changed
|
|
|
944 * (event.clipboard.*)
|
|
|
945 *
|
|
|
946 * \since This struct is available since SDL 3.2.0.
|
|
|
947 */
|
|
|
948 typedef struct SDL_ClipboardEvent
|
|
|
949 {
|
|
|
950 SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */
|
|
|
951 Uint32 reserved;
|
|
|
952 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
953 bool owner; /**< are we owning the clipboard (internal update) */
|
|
|
954 Sint32 num_mime_types; /**< number of mime types */
|
|
|
955 const char **mime_types; /**< current mime types */
|
|
|
956 } SDL_ClipboardEvent;
|
|
|
957
|
|
|
958 /**
|
|
|
959 * Sensor event structure (event.sensor.*)
|
|
|
960 *
|
|
|
961 * \since This struct is available since SDL 3.2.0.
|
|
|
962 */
|
|
|
963 typedef struct SDL_SensorEvent
|
|
|
964 {
|
|
|
965 SDL_EventType type; /**< SDL_EVENT_SENSOR_UPDATE */
|
|
|
966 Uint32 reserved;
|
|
|
967 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
968 SDL_SensorID which; /**< The instance ID of the sensor */
|
|
|
969 float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_GetSensorData() */
|
|
|
970 Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */
|
|
|
971 } SDL_SensorEvent;
|
|
|
972
|
|
|
973 /**
|
|
|
974 * The "quit requested" event
|
|
|
975 *
|
|
|
976 * \since This struct is available since SDL 3.2.0.
|
|
|
977 */
|
|
|
978 typedef struct SDL_QuitEvent
|
|
|
979 {
|
|
|
980 SDL_EventType type; /**< SDL_EVENT_QUIT */
|
|
|
981 Uint32 reserved;
|
|
|
982 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
983 } SDL_QuitEvent;
|
|
|
984
|
|
|
985 /**
|
|
|
986 * A user-defined event type (event.user.*)
|
|
|
987 *
|
|
|
988 * This event is unique; it is never created by SDL, but only by the
|
|
|
989 * application. The event can be pushed onto the event queue using
|
|
|
990 * SDL_PushEvent(). The contents of the structure members are completely up to
|
|
|
991 * the programmer; the only requirement is that '''type''' is a value obtained
|
|
|
992 * from SDL_RegisterEvents().
|
|
|
993 *
|
|
|
994 * \since This struct is available since SDL 3.2.0.
|
|
|
995 */
|
|
|
996 typedef struct SDL_UserEvent
|
|
|
997 {
|
|
|
998 Uint32 type; /**< SDL_EVENT_USER through SDL_EVENT_LAST, Uint32 because these are not in the SDL_EventType enumeration */
|
|
|
999 Uint32 reserved;
|
|
|
1000 Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
|
|
|
1001 SDL_WindowID windowID; /**< The associated window if any */
|
|
|
1002 Sint32 code; /**< User defined event code */
|
|
|
1003 void *data1; /**< User defined data pointer */
|
|
|
1004 void *data2; /**< User defined data pointer */
|
|
|
1005 } SDL_UserEvent;
|
|
|
1006
|
|
|
1007
|
|
|
1008 /**
|
|
|
1009 * The structure for all events in SDL.
|
|
|
1010 *
|
|
|
1011 * The SDL_Event structure is the core of all event handling in SDL. SDL_Event
|
|
|
1012 * is a union of all event structures used in SDL.
|
|
|
1013 *
|
|
|
1014 * \since This struct is available since SDL 3.2.0.
|
|
|
1015 */
|
|
|
1016 typedef union SDL_Event
|
|
|
1017 {
|
|
|
1018 Uint32 type; /**< Event type, shared with all events, Uint32 to cover user events which are not in the SDL_EventType enumeration */
|
|
|
1019 SDL_CommonEvent common; /**< Common event data */
|
|
|
1020 SDL_DisplayEvent display; /**< Display event data */
|
|
|
1021 SDL_WindowEvent window; /**< Window event data */
|
|
|
1022 SDL_KeyboardDeviceEvent kdevice; /**< Keyboard device change event data */
|
|
|
1023 SDL_KeyboardEvent key; /**< Keyboard event data */
|
|
|
1024 SDL_TextEditingEvent edit; /**< Text editing event data */
|
|
|
1025 SDL_TextEditingCandidatesEvent edit_candidates; /**< Text editing candidates event data */
|
|
|
1026 SDL_TextInputEvent text; /**< Text input event data */
|
|
|
1027 SDL_MouseDeviceEvent mdevice; /**< Mouse device change event data */
|
|
|
1028 SDL_MouseMotionEvent motion; /**< Mouse motion event data */
|
|
|
1029 SDL_MouseButtonEvent button; /**< Mouse button event data */
|
|
|
1030 SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
|
|
|
1031 SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */
|
|
|
1032 SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */
|
|
|
1033 SDL_JoyBallEvent jball; /**< Joystick ball event data */
|
|
|
1034 SDL_JoyHatEvent jhat; /**< Joystick hat event data */
|
|
|
1035 SDL_JoyButtonEvent jbutton; /**< Joystick button event data */
|
|
|
1036 SDL_JoyBatteryEvent jbattery; /**< Joystick battery event data */
|
|
|
1037 SDL_GamepadDeviceEvent gdevice; /**< Gamepad device event data */
|
|
|
1038 SDL_GamepadAxisEvent gaxis; /**< Gamepad axis event data */
|
|
|
1039 SDL_GamepadButtonEvent gbutton; /**< Gamepad button event data */
|
|
|
1040 SDL_GamepadTouchpadEvent gtouchpad; /**< Gamepad touchpad event data */
|
|
|
1041 SDL_GamepadSensorEvent gsensor; /**< Gamepad sensor event data */
|
|
|
1042 SDL_AudioDeviceEvent adevice; /**< Audio device event data */
|
|
|
1043 SDL_CameraDeviceEvent cdevice; /**< Camera device event data */
|
|
|
1044 SDL_SensorEvent sensor; /**< Sensor event data */
|
|
|
1045 SDL_QuitEvent quit; /**< Quit request event data */
|
|
|
1046 SDL_UserEvent user; /**< Custom event data */
|
|
|
1047 SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
|
|
|
1048 SDL_PinchFingerEvent pinch; /**< Pinch event data */
|
|
|
1049 SDL_PenProximityEvent pproximity; /**< Pen proximity event data */
|
|
|
1050 SDL_PenTouchEvent ptouch; /**< Pen tip touching event data */
|
|
|
1051 SDL_PenMotionEvent pmotion; /**< Pen motion event data */
|
|
|
1052 SDL_PenButtonEvent pbutton; /**< Pen button event data */
|
|
|
1053 SDL_PenAxisEvent paxis; /**< Pen axis event data */
|
|
|
1054 SDL_RenderEvent render; /**< Render event data */
|
|
|
1055 SDL_DropEvent drop; /**< Drag and drop event data */
|
|
|
1056 SDL_ClipboardEvent clipboard; /**< Clipboard event data */
|
|
|
1057
|
|
|
1058 /* This is necessary for ABI compatibility between Visual C++ and GCC.
|
|
|
1059 Visual C++ will respect the push pack pragma and use 52 bytes (size of
|
|
|
1060 SDL_TextEditingEvent, the largest structure for 32-bit and 64-bit
|
|
|
1061 architectures) for this union, and GCC will use the alignment of the
|
|
|
1062 largest datatype within the union, which is 8 bytes on 64-bit
|
|
|
1063 architectures.
|
|
|
1064
|
|
|
1065 So... we'll add padding to force the size to be the same for both.
|
|
|
1066
|
|
|
1067 On architectures where pointers are 16 bytes, this needs rounding up to
|
|
|
1068 the next multiple of 16, 64, and on architectures where pointers are
|
|
|
1069 even larger the size of SDL_UserEvent will dominate as being 3 pointers.
|
|
|
1070 */
|
|
|
1071 Uint8 padding[128];
|
|
|
1072 } SDL_Event;
|
|
|
1073
|
|
|
1074 /* Make sure we haven't broken binary compatibility */
|
|
|
1075 SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof((SDL_static_cast(SDL_Event *, NULL))->padding));
|
|
|
1076
|
|
|
1077
|
|
|
1078 /* Function prototypes */
|
|
|
1079
|
|
|
1080 /**
|
|
|
1081 * Pump the event loop, gathering events from the input devices.
|
|
|
1082 *
|
|
|
1083 * This function updates the event queue and internal input device state.
|
|
|
1084 *
|
|
|
1085 * SDL_PumpEvents() gathers all the pending input information from devices and
|
|
|
1086 * places it in the event queue. Without calls to SDL_PumpEvents() no events
|
|
|
1087 * would ever be placed on the queue. Often the need for calls to
|
|
|
1088 * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
|
|
|
1089 * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
|
|
|
1090 * polling or waiting for events (e.g. you are filtering them), then you must
|
|
|
1091 * call SDL_PumpEvents() to force an event queue update.
|
|
|
1092 *
|
|
|
1093 * \threadsafety This function should only be called on the main thread.
|
|
|
1094 *
|
|
|
1095 * \since This function is available since SDL 3.2.0.
|
|
|
1096 *
|
|
|
1097 * \sa SDL_PollEvent
|
|
|
1098 * \sa SDL_WaitEvent
|
|
|
1099 */
|
|
|
1100 extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void);
|
|
|
1101
|
|
|
1102 /* @{ */
|
|
|
1103
|
|
|
1104 /**
|
|
|
1105 * The type of action to request from SDL_PeepEvents().
|
|
|
1106 *
|
|
|
1107 * \since This enum is available since SDL 3.2.0.
|
|
|
1108 */
|
|
|
1109 typedef enum SDL_EventAction
|
|
|
1110 {
|
|
|
1111 SDL_ADDEVENT, /**< Add events to the back of the queue. */
|
|
|
1112 SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */
|
|
|
1113 SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */
|
|
|
1114 } SDL_EventAction;
|
|
|
1115
|
|
|
1116 /**
|
|
|
1117 * Check the event queue for messages and optionally return them.
|
|
|
1118 *
|
|
|
1119 * `action` may be any of the following:
|
|
|
1120 *
|
|
|
1121 * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
|
|
|
1122 * event queue.
|
|
|
1123 * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
|
|
|
1124 * within the specified minimum and maximum type, will be returned to the
|
|
|
1125 * caller and will _not_ be removed from the queue. If you pass NULL for
|
|
|
1126 * `events`, then `numevents` is ignored and the total number of matching
|
|
|
1127 * events will be returned.
|
|
|
1128 * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
|
|
|
1129 * within the specified minimum and maximum type, will be returned to the
|
|
|
1130 * caller and will be removed from the queue.
|
|
|
1131 *
|
|
|
1132 * You may have to call SDL_PumpEvents() before calling this function.
|
|
|
1133 * Otherwise, the events may not be ready to be filtered when you call
|
|
|
1134 * SDL_PeepEvents().
|
|
|
1135 *
|
|
|
1136 * \param events destination buffer for the retrieved events, may be NULL to
|
|
|
1137 * leave the events in the queue and return the number of events
|
|
|
1138 * that would have been stored.
|
|
|
1139 * \param numevents if action is SDL_ADDEVENT, the number of events to add
|
|
|
1140 * back to the event queue; if action is SDL_PEEKEVENT or
|
|
|
1141 * SDL_GETEVENT, the maximum number of events to retrieve.
|
|
|
1142 * \param action action to take; see [Remarks](#remarks) for details.
|
|
|
1143 * \param minType minimum value of the event type to be considered;
|
|
|
1144 * SDL_EVENT_FIRST is a safe choice.
|
|
|
1145 * \param maxType maximum value of the event type to be considered;
|
|
|
1146 * SDL_EVENT_LAST is a safe choice.
|
|
|
1147 * \returns the number of events actually stored or -1 on failure; call
|
|
|
1148 * SDL_GetError() for more information.
|
|
|
1149 *
|
|
|
1150 * \threadsafety It is safe to call this function from any thread.
|
|
|
1151 *
|
|
|
1152 * \since This function is available since SDL 3.2.0.
|
|
|
1153 *
|
|
|
1154 * \sa SDL_PollEvent
|
|
|
1155 * \sa SDL_PumpEvents
|
|
|
1156 * \sa SDL_PushEvent
|
|
|
1157 */
|
|
|
1158 extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, SDL_EventAction action, Uint32 minType, Uint32 maxType);
|
|
|
1159 /* @} */
|
|
|
1160
|
|
|
1161 /**
|
|
|
1162 * Check for the existence of a certain event type in the event queue.
|
|
|
1163 *
|
|
|
1164 * If you need to check for a range of event types, use SDL_HasEvents()
|
|
|
1165 * instead.
|
|
|
1166 *
|
|
|
1167 * \param type the type of event to be queried; see SDL_EventType for details.
|
|
|
1168 * \returns true if events matching `type` are present, or false if events
|
|
|
1169 * matching `type` are not present.
|
|
|
1170 *
|
|
|
1171 * \threadsafety It is safe to call this function from any thread.
|
|
|
1172 *
|
|
|
1173 * \since This function is available since SDL 3.2.0.
|
|
|
1174 *
|
|
|
1175 * \sa SDL_HasEvents
|
|
|
1176 */
|
|
|
1177 extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type);
|
|
|
1178
|
|
|
1179
|
|
|
1180 /**
|
|
|
1181 * Check for the existence of certain event types in the event queue.
|
|
|
1182 *
|
|
|
1183 * If you need to check for a single event type, use SDL_HasEvent() instead.
|
|
|
1184 *
|
|
|
1185 * \param minType the low end of event type to be queried, inclusive; see
|
|
|
1186 * SDL_EventType for details.
|
|
|
1187 * \param maxType the high end of event type to be queried, inclusive; see
|
|
|
1188 * SDL_EventType for details.
|
|
|
1189 * \returns true if events with type >= `minType` and <= `maxType` are
|
|
|
1190 * present, or false if not.
|
|
|
1191 *
|
|
|
1192 * \threadsafety It is safe to call this function from any thread.
|
|
|
1193 *
|
|
|
1194 * \since This function is available since SDL 3.2.0.
|
|
|
1195 *
|
|
|
1196 * \sa SDL_HasEvents
|
|
|
1197 */
|
|
|
1198 extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
|
|
|
1199
|
|
|
1200 /**
|
|
|
1201 * Clear events of a specific type from the event queue.
|
|
|
1202 *
|
|
|
1203 * This will unconditionally remove any events from the queue that match
|
|
|
1204 * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
|
|
|
1205 * instead.
|
|
|
1206 *
|
|
|
1207 * It's also normal to just ignore events you don't care about in your event
|
|
|
1208 * loop without calling this function.
|
|
|
1209 *
|
|
|
1210 * This function only affects currently queued events. If you want to make
|
|
|
1211 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
|
|
|
1212 * on the main thread immediately before the flush call.
|
|
|
1213 *
|
|
|
1214 * If you have user events with custom data that needs to be freed, you should
|
|
|
1215 * use SDL_PeepEvents() to remove and clean up those events before calling
|
|
|
1216 * this function.
|
|
|
1217 *
|
|
|
1218 * \param type the type of event to be cleared; see SDL_EventType for details.
|
|
|
1219 *
|
|
|
1220 * \threadsafety It is safe to call this function from any thread.
|
|
|
1221 *
|
|
|
1222 * \since This function is available since SDL 3.2.0.
|
|
|
1223 *
|
|
|
1224 * \sa SDL_FlushEvents
|
|
|
1225 */
|
|
|
1226 extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
|
|
|
1227
|
|
|
1228 /**
|
|
|
1229 * Clear events of a range of types from the event queue.
|
|
|
1230 *
|
|
|
1231 * This will unconditionally remove any events from the queue that are in the
|
|
|
1232 * range of `minType` to `maxType`, inclusive. If you need to remove a single
|
|
|
1233 * event type, use SDL_FlushEvent() instead.
|
|
|
1234 *
|
|
|
1235 * It's also normal to just ignore events you don't care about in your event
|
|
|
1236 * loop without calling this function.
|
|
|
1237 *
|
|
|
1238 * This function only affects currently queued events. If you want to make
|
|
|
1239 * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
|
|
|
1240 * on the main thread immediately before the flush call.
|
|
|
1241 *
|
|
|
1242 * \param minType the low end of event type to be cleared, inclusive; see
|
|
|
1243 * SDL_EventType for details.
|
|
|
1244 * \param maxType the high end of event type to be cleared, inclusive; see
|
|
|
1245 * SDL_EventType for details.
|
|
|
1246 *
|
|
|
1247 * \threadsafety It is safe to call this function from any thread.
|
|
|
1248 *
|
|
|
1249 * \since This function is available since SDL 3.2.0.
|
|
|
1250 *
|
|
|
1251 * \sa SDL_FlushEvent
|
|
|
1252 */
|
|
|
1253 extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
|
|
|
1254
|
|
|
1255 /**
|
|
|
1256 * Poll for currently pending events.
|
|
|
1257 *
|
|
|
1258 * If `event` is not NULL, the next event is removed from the queue and stored
|
|
|
1259 * in the SDL_Event structure pointed to by `event`. The 1 returned refers to
|
|
|
1260 * this event, immediately stored in the SDL Event structure -- not an event
|
|
|
1261 * to follow.
|
|
|
1262 *
|
|
|
1263 * If `event` is NULL, it simply returns 1 if there is an event in the queue,
|
|
|
1264 * but will not remove it from the queue.
|
|
|
1265 *
|
|
|
1266 * As this function may implicitly call SDL_PumpEvents(), you can only call
|
|
|
1267 * this function in the thread that set the video mode.
|
|
|
1268 *
|
|
|
1269 * SDL_PollEvent() is the favored way of receiving system events since it can
|
|
|
1270 * be done from the main loop and does not suspend the main loop while waiting
|
|
|
1271 * on an event to be posted.
|
|
|
1272 *
|
|
|
1273 * The common practice is to fully process the event queue once every frame,
|
|
|
1274 * usually as a first step before updating the game's state:
|
|
|
1275 *
|
|
|
1276 * ```c
|
|
|
1277 * while (game_is_still_running) {
|
|
|
1278 * SDL_Event event;
|
|
|
1279 * while (SDL_PollEvent(&event)) { // poll until all events are handled!
|
|
|
1280 * // decide what to do with this event.
|
|
|
1281 * }
|
|
|
1282 *
|
|
|
1283 * // update game state, draw the current frame
|
|
|
1284 * }
|
|
|
1285 * ```
|
|
|
1286 *
|
|
|
1287 * Note that Windows (and possibly other platforms) has a quirk about how it
|
|
|
1288 * handles events while dragging/resizing a window, which can cause this
|
|
|
1289 * function to block for significant amounts of time. Technical explanations
|
|
|
1290 * and solutions are discussed on the wiki:
|
|
|
1291 *
|
|
|
1292 * https://wiki.libsdl.org/SDL3/AppFreezeDuringDrag
|
|
|
1293 *
|
|
|
1294 * \param event the SDL_Event structure to be filled with the next event from
|
|
|
1295 * the queue, or NULL.
|
|
|
1296 * \returns true if this got an event or false if there are none available.
|
|
|
1297 *
|
|
|
1298 * \threadsafety This function should only be called on the main thread.
|
|
|
1299 *
|
|
|
1300 * \since This function is available since SDL 3.2.0.
|
|
|
1301 *
|
|
|
1302 * \sa SDL_PushEvent
|
|
|
1303 * \sa SDL_WaitEvent
|
|
|
1304 * \sa SDL_WaitEventTimeout
|
|
|
1305 */
|
|
|
1306 extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event);
|
|
|
1307
|
|
|
1308 /**
|
|
|
1309 * Wait indefinitely for the next available event.
|
|
|
1310 *
|
|
|
1311 * If `event` is not NULL, the next event is removed from the queue and stored
|
|
|
1312 * in the SDL_Event structure pointed to by `event`.
|
|
|
1313 *
|
|
|
1314 * As this function may implicitly call SDL_PumpEvents(), you can only call
|
|
|
1315 * this function in the thread that initialized the video subsystem.
|
|
|
1316 *
|
|
|
1317 * \param event the SDL_Event structure to be filled in with the next event
|
|
|
1318 * from the queue, or NULL.
|
|
|
1319 * \returns true on success or false if there was an error while waiting for
|
|
|
1320 * events; call SDL_GetError() for more information.
|
|
|
1321 *
|
|
|
1322 * \threadsafety This function should only be called on the main thread.
|
|
|
1323 *
|
|
|
1324 * \since This function is available since SDL 3.2.0.
|
|
|
1325 *
|
|
|
1326 * \sa SDL_PollEvent
|
|
|
1327 * \sa SDL_PushEvent
|
|
|
1328 * \sa SDL_WaitEventTimeout
|
|
|
1329 */
|
|
|
1330 extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event);
|
|
|
1331
|
|
|
1332 /**
|
|
|
1333 * Wait until the specified timeout (in milliseconds) for the next available
|
|
|
1334 * event.
|
|
|
1335 *
|
|
|
1336 * If `event` is not NULL, the next event is removed from the queue and stored
|
|
|
1337 * in the SDL_Event structure pointed to by `event`.
|
|
|
1338 *
|
|
|
1339 * As this function may implicitly call SDL_PumpEvents(), you can only call
|
|
|
1340 * this function in the thread that initialized the video subsystem.
|
|
|
1341 *
|
|
|
1342 * The timeout is not guaranteed, the actual wait time could be longer due to
|
|
|
1343 * system scheduling.
|
|
|
1344 *
|
|
|
1345 * \param event the SDL_Event structure to be filled in with the next event
|
|
|
1346 * from the queue, or NULL.
|
|
|
1347 * \param timeoutMS the maximum number of milliseconds to wait for the next
|
|
|
1348 * available event.
|
|
|
1349 * \returns true if this got an event or false if the timeout elapsed without
|
|
|
1350 * any events available.
|
|
|
1351 *
|
|
|
1352 * \threadsafety This function should only be called on the main thread.
|
|
|
1353 *
|
|
|
1354 * \since This function is available since SDL 3.2.0.
|
|
|
1355 *
|
|
|
1356 * \sa SDL_PollEvent
|
|
|
1357 * \sa SDL_PushEvent
|
|
|
1358 * \sa SDL_WaitEvent
|
|
|
1359 */
|
|
|
1360 extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS);
|
|
|
1361
|
|
|
1362 /**
|
|
|
1363 * Add an event to the event queue.
|
|
|
1364 *
|
|
|
1365 * The event queue can actually be used as a two way communication channel.
|
|
|
1366 * Not only can events be read from the queue, but the user can also push
|
|
|
1367 * their own events onto it. `event` is a pointer to the event structure you
|
|
|
1368 * wish to push onto the queue. The event is copied into the queue, and the
|
|
|
1369 * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
|
|
|
1370 *
|
|
|
1371 * Note: Pushing device input events onto the queue doesn't modify the state
|
|
|
1372 * of the device within SDL.
|
|
|
1373 *
|
|
|
1374 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
|
|
|
1375 * the event filter but events added with SDL_PeepEvents() do not.
|
|
|
1376 *
|
|
|
1377 * For pushing application-specific events, please use SDL_RegisterEvents() to
|
|
|
1378 * get an event type that does not conflict with other code that also wants
|
|
|
1379 * its own custom event types.
|
|
|
1380 *
|
|
|
1381 * \param event the SDL_Event to be added to the queue.
|
|
|
1382 * \returns true on success, false if the event was filtered or on failure;
|
|
|
1383 * call SDL_GetError() for more information. A common reason for
|
|
|
1384 * error is the event queue being full.
|
|
|
1385 *
|
|
|
1386 * \threadsafety It is safe to call this function from any thread.
|
|
|
1387 *
|
|
|
1388 * \since This function is available since SDL 3.2.0.
|
|
|
1389 *
|
|
|
1390 * \sa SDL_PeepEvents
|
|
|
1391 * \sa SDL_PollEvent
|
|
|
1392 * \sa SDL_RegisterEvents
|
|
|
1393 */
|
|
|
1394 extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event);
|
|
|
1395
|
|
|
1396 /**
|
|
|
1397 * A function pointer used for callbacks that watch the event queue.
|
|
|
1398 *
|
|
|
1399 * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
|
|
|
1400 * SDL_AddEventWatch, etc.
|
|
|
1401 * \param event the event that triggered the callback.
|
|
|
1402 * \returns true to permit event to be added to the queue, and false to
|
|
|
1403 * disallow it. When used with SDL_AddEventWatch, the return value is
|
|
|
1404 * ignored.
|
|
|
1405 *
|
|
|
1406 * \threadsafety SDL may call this callback at any time from any thread; the
|
|
|
1407 * application is responsible for locking resources the callback
|
|
|
1408 * touches that need to be protected.
|
|
|
1409 *
|
|
|
1410 * \since This datatype is available since SDL 3.2.0.
|
|
|
1411 *
|
|
|
1412 * \sa SDL_SetEventFilter
|
|
|
1413 * \sa SDL_AddEventWatch
|
|
|
1414 */
|
|
|
1415 typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
|
|
|
1416
|
|
|
1417 /**
|
|
|
1418 * Set up a filter to process all events before they are added to the internal
|
|
|
1419 * event queue.
|
|
|
1420 *
|
|
|
1421 * If you just want to see events without modifying them or preventing them
|
|
|
1422 * from being queued, you should use SDL_AddEventWatch() instead.
|
|
|
1423 *
|
|
|
1424 * If the filter function returns true when called, then the event will be
|
|
|
1425 * added to the internal queue. If it returns false, then the event will be
|
|
|
1426 * dropped from the queue, but the internal state will still be updated. This
|
|
|
1427 * allows selective filtering of dynamically arriving events.
|
|
|
1428 *
|
|
|
1429 * **WARNING**: Be very careful of what you do in the event filter function,
|
|
|
1430 * as it may run in a different thread! The exception is handling of
|
|
|
1431 * SDL_EVENT_WINDOW_EXPOSED, which is guaranteed to be sent from the OS on the
|
|
|
1432 * main thread and you are expected to redraw your window in response to this
|
|
|
1433 * event.
|
|
|
1434 *
|
|
|
1435 * On platforms that support it, if the quit event is generated by an
|
|
|
1436 * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
|
|
|
1437 * application at the next event poll.
|
|
|
1438 *
|
|
|
1439 * Note: Disabled events never make it to the event filter function; see
|
|
|
1440 * SDL_SetEventEnabled().
|
|
|
1441 *
|
|
|
1442 * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
|
|
|
1443 * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
|
|
|
1444 * not.
|
|
|
1445 *
|
|
|
1446 * \param filter a function to call when an event happens.
|
|
|
1447 * \param userdata a pointer that is passed to `filter`.
|
|
|
1448 *
|
|
|
1449 * \threadsafety It is safe to call this function from any thread.
|
|
|
1450 *
|
|
|
1451 * \since This function is available since SDL 3.2.0.
|
|
|
1452 *
|
|
|
1453 * \sa SDL_AddEventWatch
|
|
|
1454 * \sa SDL_SetEventEnabled
|
|
|
1455 * \sa SDL_GetEventFilter
|
|
|
1456 * \sa SDL_PeepEvents
|
|
|
1457 * \sa SDL_PushEvent
|
|
|
1458 */
|
|
|
1459 extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void *userdata);
|
|
|
1460
|
|
|
1461 /**
|
|
|
1462 * Query the current event filter.
|
|
|
1463 *
|
|
|
1464 * This function can be used to "chain" filters, by saving the existing filter
|
|
|
1465 * before replacing it with a function that will call that saved filter.
|
|
|
1466 *
|
|
|
1467 * \param filter the current callback function will be stored here.
|
|
|
1468 * \param userdata the pointer that is passed to the current event filter will
|
|
|
1469 * be stored here.
|
|
|
1470 * \returns true on success or false if there is no event filter set.
|
|
|
1471 *
|
|
|
1472 * \threadsafety It is safe to call this function from any thread.
|
|
|
1473 *
|
|
|
1474 * \since This function is available since SDL 3.2.0.
|
|
|
1475 *
|
|
|
1476 * \sa SDL_SetEventFilter
|
|
|
1477 */
|
|
|
1478 extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata);
|
|
|
1479
|
|
|
1480 /**
|
|
|
1481 * Add a callback to be triggered when an event is added to the event queue.
|
|
|
1482 *
|
|
|
1483 * `filter` will be called when an event happens, and its return value is
|
|
|
1484 * ignored.
|
|
|
1485 *
|
|
|
1486 * **WARNING**: Be very careful of what you do in the event filter function,
|
|
|
1487 * as it may run in a different thread!
|
|
|
1488 *
|
|
|
1489 * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
|
|
|
1490 * the internal queue and be delivered to the watch callback immediately, and
|
|
|
1491 * arrive at the next event poll.
|
|
|
1492 *
|
|
|
1493 * Note: the callback is called for events posted by the user through
|
|
|
1494 * SDL_PushEvent(), but not for disabled events, nor for events by a filter
|
|
|
1495 * callback set with SDL_SetEventFilter(), nor for events posted by the user
|
|
|
1496 * through SDL_PeepEvents().
|
|
|
1497 *
|
|
|
1498 * \param filter an SDL_EventFilter function to call when an event happens.
|
|
|
1499 * \param userdata a pointer that is passed to `filter`.
|
|
|
1500 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1501 * information.
|
|
|
1502 *
|
|
|
1503 * \threadsafety It is safe to call this function from any thread.
|
|
|
1504 *
|
|
|
1505 * \since This function is available since SDL 3.2.0.
|
|
|
1506 *
|
|
|
1507 * \sa SDL_RemoveEventWatch
|
|
|
1508 * \sa SDL_SetEventFilter
|
|
|
1509 */
|
|
|
1510 extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata);
|
|
|
1511
|
|
|
1512 /**
|
|
|
1513 * Remove an event watch callback added with SDL_AddEventWatch().
|
|
|
1514 *
|
|
|
1515 * This function takes the same input as SDL_AddEventWatch() to identify and
|
|
|
1516 * delete the corresponding callback.
|
|
|
1517 *
|
|
|
1518 * \param filter the function originally passed to SDL_AddEventWatch().
|
|
|
1519 * \param userdata the pointer originally passed to SDL_AddEventWatch().
|
|
|
1520 *
|
|
|
1521 * \threadsafety It is safe to call this function from any thread.
|
|
|
1522 *
|
|
|
1523 * \since This function is available since SDL 3.2.0.
|
|
|
1524 *
|
|
|
1525 * \sa SDL_AddEventWatch
|
|
|
1526 */
|
|
|
1527 extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, void *userdata);
|
|
|
1528
|
|
|
1529 /**
|
|
|
1530 * Run a specific filter function on the current event queue, removing any
|
|
|
1531 * events for which the filter returns false.
|
|
|
1532 *
|
|
|
1533 * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
|
|
|
1534 * this function does not change the filter permanently, it only uses the
|
|
|
1535 * supplied filter until this function returns.
|
|
|
1536 *
|
|
|
1537 * \param filter the SDL_EventFilter function to call when an event happens.
|
|
|
1538 * \param userdata a pointer that is passed to `filter`.
|
|
|
1539 *
|
|
|
1540 * \threadsafety It is safe to call this function from any thread.
|
|
|
1541 *
|
|
|
1542 * \since This function is available since SDL 3.2.0.
|
|
|
1543 *
|
|
|
1544 * \sa SDL_GetEventFilter
|
|
|
1545 * \sa SDL_SetEventFilter
|
|
|
1546 */
|
|
|
1547 extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *userdata);
|
|
|
1548
|
|
|
1549 /**
|
|
|
1550 * Set the state of processing events by type.
|
|
|
1551 *
|
|
|
1552 * \param type the type of event; see SDL_EventType for details.
|
|
|
1553 * \param enabled whether to process the event or not.
|
|
|
1554 *
|
|
|
1555 * \threadsafety It is safe to call this function from any thread.
|
|
|
1556 *
|
|
|
1557 * \since This function is available since SDL 3.2.0.
|
|
|
1558 *
|
|
|
1559 * \sa SDL_EventEnabled
|
|
|
1560 */
|
|
|
1561 extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled);
|
|
|
1562
|
|
|
1563 /**
|
|
|
1564 * Query the state of processing events by type.
|
|
|
1565 *
|
|
|
1566 * \param type the type of event; see SDL_EventType for details.
|
|
|
1567 * \returns true if the event is being processed, false otherwise.
|
|
|
1568 *
|
|
|
1569 * \threadsafety It is safe to call this function from any thread.
|
|
|
1570 *
|
|
|
1571 * \since This function is available since SDL 3.2.0.
|
|
|
1572 *
|
|
|
1573 * \sa SDL_SetEventEnabled
|
|
|
1574 */
|
|
|
1575 extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type);
|
|
|
1576
|
|
|
1577 /**
|
|
|
1578 * Allocate a set of user-defined events, and return the beginning event
|
|
|
1579 * number for that set of events.
|
|
|
1580 *
|
|
|
1581 * \param numevents the number of events to be allocated.
|
|
|
1582 * \returns the beginning event number, or 0 if numevents is invalid or if
|
|
|
1583 * there are not enough user-defined events left.
|
|
|
1584 *
|
|
|
1585 * \threadsafety It is safe to call this function from any thread.
|
|
|
1586 *
|
|
|
1587 * \since This function is available since SDL 3.2.0.
|
|
|
1588 *
|
|
|
1589 * \sa SDL_PushEvent
|
|
|
1590 */
|
|
|
1591 extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
|
|
|
1592
|
|
|
1593 /**
|
|
|
1594 * Get window associated with an event.
|
|
|
1595 *
|
|
|
1596 * \param event an event containing a `windowID`.
|
|
|
1597 * \returns the associated window on success or NULL if there is none.
|
|
|
1598 *
|
|
|
1599 * \threadsafety It is safe to call this function from any thread.
|
|
|
1600 *
|
|
|
1601 * \since This function is available since SDL 3.2.0.
|
|
|
1602 *
|
|
|
1603 * \sa SDL_PollEvent
|
|
|
1604 * \sa SDL_WaitEvent
|
|
|
1605 * \sa SDL_WaitEventTimeout
|
|
|
1606 */
|
|
|
1607 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromEvent(const SDL_Event *event);
|
|
|
1608
|
|
|
1609 /**
|
|
|
1610 * Generate an English description of an event.
|
|
|
1611 *
|
|
|
1612 * This will fill `buf` with a null-terminated string that might look
|
|
|
1613 * something like this:
|
|
|
1614 *
|
|
|
1615 * ```
|
|
|
1616 * SDL_EVENT_MOUSE_MOTION (timestamp=1140256324 windowid=2 which=0 state=0 x=492.99 y=139.09 xrel=52 yrel=6)
|
|
|
1617 * ```
|
|
|
1618 *
|
|
|
1619 * The exact format of the string is not guaranteed; it is intended for
|
|
|
1620 * logging purposes, to be read by a human, and not parsed by a computer.
|
|
|
1621 *
|
|
|
1622 * The returned value follows the same rules as SDL_snprintf(): `buf` will
|
|
|
1623 * always be NULL-terminated (unless `buflen` is zero), and will be truncated
|
|
|
1624 * if `buflen` is too small. The return code is the number of bytes needed for
|
|
|
1625 * the complete string, not counting the NULL-terminator, whether the string
|
|
|
1626 * was truncated or not. Unlike SDL_snprintf(), though, this function never
|
|
|
1627 * returns -1.
|
|
|
1628 *
|
|
|
1629 * \param event an event to describe. May be NULL.
|
|
|
1630 * \param buf the buffer to fill with the description string. May be NULL.
|
|
|
1631 * \param buflen the maximum bytes that can be written to `buf`.
|
|
|
1632 * \returns number of bytes needed for the full string, not counting the
|
|
|
1633 * null-terminator byte.
|
|
|
1634 *
|
|
|
1635 * \threadsafety It is safe to call this function from any thread.
|
|
|
1636 *
|
|
|
1637 * \since This function is available since SDL 3.4.0.
|
|
|
1638 */
|
|
|
1639 extern SDL_DECLSPEC int SDLCALL SDL_GetEventDescription(const SDL_Event *event, char *buf, int buflen);
|
|
|
1640
|
|
|
1641 /* Ends C function definitions when using C++ */
|
|
|
1642 #ifdef __cplusplus
|
|
|
1643 }
|
|
|
1644 #endif
|
|
|
1645 #include <SDL3/SDL_close_code.h>
|
|
|
1646
|
|
|
1647 #endif /* SDL_events_h_ */
|
