|
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 * # CategoryMouse
|
|
|
24 *
|
|
|
25 * Any GUI application has to deal with the mouse, and SDL provides functions
|
|
|
26 * to manage mouse input and the displayed cursor.
|
|
|
27 *
|
|
|
28 * Most interactions with the mouse will come through the event subsystem.
|
|
|
29 * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button
|
|
|
30 * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the
|
|
|
31 * current state of the mouse at any time with SDL_GetMouseState().
|
|
|
32 *
|
|
|
33 * For certain games, it's useful to disassociate the mouse cursor from mouse
|
|
|
34 * input. An FPS, for example, would not want the player's motion to stop as
|
|
|
35 * the mouse hits the edge of the window. For these scenarios, use
|
|
|
36 * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input
|
|
|
37 * to the window, and reads mouse input no matter how far it moves.
|
|
|
38 *
|
|
|
39 * Games that want the system to track the mouse but want to draw their own
|
|
|
40 * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more
|
|
|
41 * efficient to let the system manage the cursor, if possible, using
|
|
|
42 * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(),
|
|
|
43 * or perhaps just a specific system cursor from SDL_CreateSystemCursor().
|
|
|
44 *
|
|
|
45 * SDL can, on many platforms, differentiate between multiple connected mice,
|
|
|
46 * allowing for interesting input scenarios and multiplayer games. They can be
|
|
|
47 * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and
|
|
|
48 * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged.
|
|
|
49 *
|
|
|
50 * Since many apps only care about basic mouse input, SDL offers a virtual
|
|
|
51 * mouse device for touch and pen input, which often can make a desktop
|
|
|
52 * application work on a touchscreen phone without any code changes. Apps that
|
|
|
53 * care about touch/pen separately from mouse input should filter out events
|
|
|
54 * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID.
|
|
|
55 */
|
|
|
56
|
|
|
57 #ifndef SDL_mouse_h_
|
|
|
58 #define SDL_mouse_h_
|
|
|
59
|
|
|
60 #include <SDL3/SDL_stdinc.h>
|
|
|
61 #include <SDL3/SDL_error.h>
|
|
|
62 #include <SDL3/SDL_surface.h>
|
|
|
63 #include <SDL3/SDL_video.h>
|
|
|
64
|
|
|
65 #include <SDL3/SDL_begin_code.h>
|
|
|
66 /* Set up for C function definitions, even when using C++ */
|
|
|
67 #ifdef __cplusplus
|
|
|
68 extern "C" {
|
|
|
69 #endif
|
|
|
70
|
|
|
71 /**
|
|
|
72 * This is a unique ID for a mouse for the time it is connected to the system,
|
|
|
73 * and is never reused for the lifetime of the application.
|
|
|
74 *
|
|
|
75 * If the mouse is disconnected and reconnected, it will get a new ID.
|
|
|
76 *
|
|
|
77 * The value 0 is an invalid ID.
|
|
|
78 *
|
|
|
79 * \since This datatype is available since SDL 3.2.0.
|
|
|
80 */
|
|
|
81 typedef Uint32 SDL_MouseID;
|
|
|
82
|
|
|
83 /**
|
|
|
84 * The structure used to identify an SDL cursor.
|
|
|
85 *
|
|
|
86 * This is opaque data.
|
|
|
87 *
|
|
|
88 * \since This struct is available since SDL 3.2.0.
|
|
|
89 */
|
|
|
90 typedef struct SDL_Cursor SDL_Cursor;
|
|
|
91
|
|
|
92 /**
|
|
|
93 * Cursor types for SDL_CreateSystemCursor().
|
|
|
94 *
|
|
|
95 * \since This enum is available since SDL 3.2.0.
|
|
|
96 */
|
|
|
97 typedef enum SDL_SystemCursor
|
|
|
98 {
|
|
|
99 SDL_SYSTEM_CURSOR_DEFAULT, /**< Default cursor. Usually an arrow. */
|
|
|
100 SDL_SYSTEM_CURSOR_TEXT, /**< Text selection. Usually an I-beam. */
|
|
|
101 SDL_SYSTEM_CURSOR_WAIT, /**< Wait. Usually an hourglass or watch or spinning ball. */
|
|
|
102 SDL_SYSTEM_CURSOR_CROSSHAIR, /**< Crosshair. */
|
|
|
103 SDL_SYSTEM_CURSOR_PROGRESS, /**< Program is busy but still interactive. Usually it's WAIT with an arrow. */
|
|
|
104 SDL_SYSTEM_CURSOR_NWSE_RESIZE, /**< Double arrow pointing northwest and southeast. */
|
|
|
105 SDL_SYSTEM_CURSOR_NESW_RESIZE, /**< Double arrow pointing northeast and southwest. */
|
|
|
106 SDL_SYSTEM_CURSOR_EW_RESIZE, /**< Double arrow pointing west and east. */
|
|
|
107 SDL_SYSTEM_CURSOR_NS_RESIZE, /**< Double arrow pointing north and south. */
|
|
|
108 SDL_SYSTEM_CURSOR_MOVE, /**< Four pointed arrow pointing north, south, east, and west. */
|
|
|
109 SDL_SYSTEM_CURSOR_NOT_ALLOWED, /**< Not permitted. Usually a slashed circle or crossbones. */
|
|
|
110 SDL_SYSTEM_CURSOR_POINTER, /**< Pointer that indicates a link. Usually a pointing hand. */
|
|
|
111 SDL_SYSTEM_CURSOR_NW_RESIZE, /**< Window resize top-left. This may be a single arrow or a double arrow like NWSE_RESIZE. */
|
|
|
112 SDL_SYSTEM_CURSOR_N_RESIZE, /**< Window resize top. May be NS_RESIZE. */
|
|
|
113 SDL_SYSTEM_CURSOR_NE_RESIZE, /**< Window resize top-right. May be NESW_RESIZE. */
|
|
|
114 SDL_SYSTEM_CURSOR_E_RESIZE, /**< Window resize right. May be EW_RESIZE. */
|
|
|
115 SDL_SYSTEM_CURSOR_SE_RESIZE, /**< Window resize bottom-right. May be NWSE_RESIZE. */
|
|
|
116 SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */
|
|
|
117 SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */
|
|
|
118 SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */
|
|
|
119 SDL_SYSTEM_CURSOR_COUNT
|
|
|
120 } SDL_SystemCursor;
|
|
|
121
|
|
|
122 /**
|
|
|
123 * Scroll direction types for the Scroll event
|
|
|
124 *
|
|
|
125 * \since This enum is available since SDL 3.2.0.
|
|
|
126 */
|
|
|
127 typedef enum SDL_MouseWheelDirection
|
|
|
128 {
|
|
|
129 SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */
|
|
|
130 SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */
|
|
|
131 } SDL_MouseWheelDirection;
|
|
|
132
|
|
|
133 /**
|
|
|
134 * Animated cursor frame info.
|
|
|
135 *
|
|
|
136 * \since This struct is available since SDL 3.4.0.
|
|
|
137 */
|
|
|
138 typedef struct SDL_CursorFrameInfo
|
|
|
139 {
|
|
|
140 SDL_Surface *surface; /**< The surface data for this frame */
|
|
|
141 Uint32 duration; /**< The frame duration in milliseconds (a duration of 0 is infinite) */
|
|
|
142 } SDL_CursorFrameInfo;
|
|
|
143
|
|
|
144 /**
|
|
|
145 * A bitmask of pressed mouse buttons, as reported by SDL_GetMouseState, etc.
|
|
|
146 *
|
|
|
147 * - Button 1: Left mouse button
|
|
|
148 * - Button 2: Middle mouse button
|
|
|
149 * - Button 3: Right mouse button
|
|
|
150 * - Button 4: Side mouse button 1
|
|
|
151 * - Button 5: Side mouse button 2
|
|
|
152 *
|
|
|
153 * \since This datatype is available since SDL 3.2.0.
|
|
|
154 *
|
|
|
155 * \sa SDL_GetMouseState
|
|
|
156 * \sa SDL_GetGlobalMouseState
|
|
|
157 * \sa SDL_GetRelativeMouseState
|
|
|
158 */
|
|
|
159 typedef Uint32 SDL_MouseButtonFlags;
|
|
|
160
|
|
|
161 #define SDL_BUTTON_LEFT 1
|
|
|
162 #define SDL_BUTTON_MIDDLE 2
|
|
|
163 #define SDL_BUTTON_RIGHT 3
|
|
|
164 #define SDL_BUTTON_X1 4
|
|
|
165 #define SDL_BUTTON_X2 5
|
|
|
166
|
|
|
167 #define SDL_BUTTON_MASK(X) (1u << ((X)-1))
|
|
|
168 #define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT)
|
|
|
169 #define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE)
|
|
|
170 #define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)
|
|
|
171 #define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1)
|
|
|
172 #define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2)
|
|
|
173
|
|
|
174 /**
|
|
|
175 * A callback used to transform mouse motion delta from raw values.
|
|
|
176 *
|
|
|
177 * This is called during SDL's handling of platform mouse events to scale the
|
|
|
178 * values of the resulting motion delta.
|
|
|
179 *
|
|
|
180 * \param userdata what was passed as `userdata` to
|
|
|
181 * SDL_SetRelativeMouseTransform().
|
|
|
182 * \param timestamp the associated time at which this mouse motion event was
|
|
|
183 * received.
|
|
|
184 * \param window the associated window to which this mouse motion event was
|
|
|
185 * addressed.
|
|
|
186 * \param mouseID the associated mouse from which this mouse motion event was
|
|
|
187 * emitted.
|
|
|
188 * \param x pointer to a variable that will be treated as the resulting x-axis
|
|
|
189 * motion.
|
|
|
190 * \param y pointer to a variable that will be treated as the resulting y-axis
|
|
|
191 * motion.
|
|
|
192 *
|
|
|
193 * \threadsafety This callback is called by SDL's internal mouse input
|
|
|
194 * processing procedure, which may be a thread separate from the
|
|
|
195 * main event loop that is run at realtime priority. Stalling
|
|
|
196 * this thread with too much work in the callback can therefore
|
|
|
197 * potentially freeze the entire system. Care should be taken
|
|
|
198 * with proper synchronization practices when adding other side
|
|
|
199 * effects beyond mutation of the x and y values.
|
|
|
200 *
|
|
|
201 * \since This datatype is available since SDL 3.4.0.
|
|
|
202 *
|
|
|
203 * \sa SDL_SetRelativeMouseTransform
|
|
|
204 */
|
|
|
205 typedef void (SDLCALL *SDL_MouseMotionTransformCallback)(
|
|
|
206 void *userdata,
|
|
|
207 Uint64 timestamp,
|
|
|
208 SDL_Window *window,
|
|
|
209 SDL_MouseID mouseID,
|
|
|
210 float *x, float *y
|
|
|
211 );
|
|
|
212
|
|
|
213 /* Function prototypes */
|
|
|
214
|
|
|
215 /**
|
|
|
216 * Return whether a mouse is currently connected.
|
|
|
217 *
|
|
|
218 * \returns true if a mouse is connected, false otherwise.
|
|
|
219 *
|
|
|
220 * \threadsafety This function should only be called on the main thread.
|
|
|
221 *
|
|
|
222 * \since This function is available since SDL 3.2.0.
|
|
|
223 *
|
|
|
224 * \sa SDL_GetMice
|
|
|
225 */
|
|
|
226 extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void);
|
|
|
227
|
|
|
228 /**
|
|
|
229 * Get a list of currently connected mice.
|
|
|
230 *
|
|
|
231 * Note that this will include any device or virtual driver that includes
|
|
|
232 * mouse functionality, including some game controllers, KVM switches, etc.
|
|
|
233 * You should wait for input from a device before you consider it actively in
|
|
|
234 * use.
|
|
|
235 *
|
|
|
236 * \param count a pointer filled in with the number of mice returned, may be
|
|
|
237 * NULL.
|
|
|
238 * \returns a 0 terminated array of mouse instance IDs or NULL on failure;
|
|
|
239 * call SDL_GetError() for more information. This should be freed
|
|
|
240 * with SDL_free() when it is no longer needed.
|
|
|
241 *
|
|
|
242 * \threadsafety This function should only be called on the main thread.
|
|
|
243 *
|
|
|
244 * \since This function is available since SDL 3.2.0.
|
|
|
245 *
|
|
|
246 * \sa SDL_GetMouseNameForID
|
|
|
247 * \sa SDL_HasMouse
|
|
|
248 */
|
|
|
249 extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count);
|
|
|
250
|
|
|
251 /**
|
|
|
252 * Get the name of a mouse.
|
|
|
253 *
|
|
|
254 * This function returns "" if the mouse doesn't have a name.
|
|
|
255 *
|
|
|
256 * \param instance_id the mouse instance ID.
|
|
|
257 * \returns the name of the selected mouse, or NULL on failure; call
|
|
|
258 * SDL_GetError() for more information.
|
|
|
259 *
|
|
|
260 * \threadsafety This function should only be called on the main thread.
|
|
|
261 *
|
|
|
262 * \since This function is available since SDL 3.2.0.
|
|
|
263 *
|
|
|
264 * \sa SDL_GetMice
|
|
|
265 */
|
|
|
266 extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID instance_id);
|
|
|
267
|
|
|
268 /**
|
|
|
269 * Get the window which currently has mouse focus.
|
|
|
270 *
|
|
|
271 * \returns the window with mouse focus.
|
|
|
272 *
|
|
|
273 * \threadsafety This function should only be called on the main thread.
|
|
|
274 *
|
|
|
275 * \since This function is available since SDL 3.2.0.
|
|
|
276 */
|
|
|
277 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
|
|
|
278
|
|
|
279 /**
|
|
|
280 * Query SDL's cache for the synchronous mouse button state and the
|
|
|
281 * window-relative SDL-cursor position.
|
|
|
282 *
|
|
|
283 * This function returns the cached synchronous state as SDL understands it
|
|
|
284 * from the last pump of the event queue.
|
|
|
285 *
|
|
|
286 * To query the platform for immediate asynchronous state, use
|
|
|
287 * SDL_GetGlobalMouseState.
|
|
|
288 *
|
|
|
289 * Passing non-NULL pointers to `x` or `y` will write the destination with
|
|
|
290 * respective x or y coordinates relative to the focused window.
|
|
|
291 *
|
|
|
292 * In Relative Mode, the SDL-cursor's position usually contradicts the
|
|
|
293 * platform-cursor's position as manually calculated from
|
|
|
294 * SDL_GetGlobalMouseState() and SDL_GetWindowPosition.
|
|
|
295 *
|
|
|
296 * \param x a pointer to receive the SDL-cursor's x-position from the focused
|
|
|
297 * window's top left corner, can be NULL if unused.
|
|
|
298 * \param y a pointer to receive the SDL-cursor's y-position from the focused
|
|
|
299 * window's top left corner, can be NULL if unused.
|
|
|
300 * \returns a 32-bit bitmask of the button state that can be bitwise-compared
|
|
|
301 * against the SDL_BUTTON_MASK(X) macro.
|
|
|
302 *
|
|
|
303 * \threadsafety This function should only be called on the main thread.
|
|
|
304 *
|
|
|
305 * \since This function is available since SDL 3.2.0.
|
|
|
306 *
|
|
|
307 * \sa SDL_GetGlobalMouseState
|
|
|
308 * \sa SDL_GetRelativeMouseState
|
|
|
309 */
|
|
|
310 extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, float *y);
|
|
|
311
|
|
|
312 /**
|
|
|
313 * Query the platform for the asynchronous mouse button state and the
|
|
|
314 * desktop-relative platform-cursor position.
|
|
|
315 *
|
|
|
316 * This function immediately queries the platform for the most recent
|
|
|
317 * asynchronous state, more costly than retrieving SDL's cached state in
|
|
|
318 * SDL_GetMouseState().
|
|
|
319 *
|
|
|
320 * Passing non-NULL pointers to `x` or `y` will write the destination with
|
|
|
321 * respective x or y coordinates relative to the desktop.
|
|
|
322 *
|
|
|
323 * In Relative Mode, the platform-cursor's position usually contradicts the
|
|
|
324 * SDL-cursor's position as manually calculated from SDL_GetMouseState() and
|
|
|
325 * SDL_GetWindowPosition.
|
|
|
326 *
|
|
|
327 * This function can be useful if you need to track the mouse outside of a
|
|
|
328 * specific window and SDL_CaptureMouse() doesn't fit your needs. For example,
|
|
|
329 * it could be useful if you need to track the mouse while dragging a window,
|
|
|
330 * where coordinates relative to a window might not be in sync at all times.
|
|
|
331 *
|
|
|
332 * \param x a pointer to receive the platform-cursor's x-position from the
|
|
|
333 * desktop's top left corner, can be NULL if unused.
|
|
|
334 * \param y a pointer to receive the platform-cursor's y-position from the
|
|
|
335 * desktop's top left corner, can be NULL if unused.
|
|
|
336 * \returns a 32-bit bitmask of the button state that can be bitwise-compared
|
|
|
337 * against the SDL_BUTTON_MASK(X) macro.
|
|
|
338 *
|
|
|
339 * \threadsafety This function should only be called on the main thread.
|
|
|
340 *
|
|
|
341 * \since This function is available since SDL 3.2.0.
|
|
|
342 *
|
|
|
343 * \sa SDL_CaptureMouse
|
|
|
344 * \sa SDL_GetMouseState
|
|
|
345 * \sa SDL_GetGlobalMouseState
|
|
|
346 */
|
|
|
347 extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *x, float *y);
|
|
|
348
|
|
|
349 /**
|
|
|
350 * Query SDL's cache for the synchronous mouse button state and accumulated
|
|
|
351 * mouse delta since last call.
|
|
|
352 *
|
|
|
353 * This function returns the cached synchronous state as SDL understands it
|
|
|
354 * from the last pump of the event queue.
|
|
|
355 *
|
|
|
356 * To query the platform for immediate asynchronous state, use
|
|
|
357 * SDL_GetGlobalMouseState.
|
|
|
358 *
|
|
|
359 * Passing non-NULL pointers to `x` or `y` will write the destination with
|
|
|
360 * respective x or y deltas accumulated since the last call to this function
|
|
|
361 * (or since event initialization).
|
|
|
362 *
|
|
|
363 * This function is useful for reducing overhead by processing relative mouse
|
|
|
364 * inputs in one go per-frame instead of individually per-event, at the
|
|
|
365 * expense of losing the order between events within the frame (e.g. quickly
|
|
|
366 * pressing and releasing a button within the same frame).
|
|
|
367 *
|
|
|
368 * \param x a pointer to receive the x mouse delta accumulated since last
|
|
|
369 * call, can be NULL if unused.
|
|
|
370 * \param y a pointer to receive the y mouse delta accumulated since last
|
|
|
371 * call, can be NULL if unused.
|
|
|
372 * \returns a 32-bit bitmask of the button state that can be bitwise-compared
|
|
|
373 * against the SDL_BUTTON_MASK(X) macro.
|
|
|
374 *
|
|
|
375 * \threadsafety This function should only be called on the main thread.
|
|
|
376 *
|
|
|
377 * \since This function is available since SDL 3.2.0.
|
|
|
378 *
|
|
|
379 * \sa SDL_GetMouseState
|
|
|
380 * \sa SDL_GetGlobalMouseState
|
|
|
381 */
|
|
|
382 extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float *x, float *y);
|
|
|
383
|
|
|
384 /**
|
|
|
385 * Move the mouse cursor to the given position within the window.
|
|
|
386 *
|
|
|
387 * This function generates a mouse motion event if relative mode is not
|
|
|
388 * enabled. If relative mode is enabled, you can force mouse events for the
|
|
|
389 * warp by setting the SDL_HINT_MOUSE_RELATIVE_WARP_MOTION hint.
|
|
|
390 *
|
|
|
391 * Note that this function will appear to succeed, but not actually move the
|
|
|
392 * mouse when used over Microsoft Remote Desktop.
|
|
|
393 *
|
|
|
394 * \param window the window to move the mouse into, or NULL for the current
|
|
|
395 * mouse focus.
|
|
|
396 * \param x the x coordinate within the window.
|
|
|
397 * \param y the y coordinate within the window.
|
|
|
398 *
|
|
|
399 * \threadsafety This function should only be called on the main thread.
|
|
|
400 *
|
|
|
401 * \since This function is available since SDL 3.2.0.
|
|
|
402 *
|
|
|
403 * \sa SDL_WarpMouseGlobal
|
|
|
404 */
|
|
|
405 extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window *window,
|
|
|
406 float x, float y);
|
|
|
407
|
|
|
408 /**
|
|
|
409 * Move the mouse to the given position in global screen space.
|
|
|
410 *
|
|
|
411 * This function generates a mouse motion event.
|
|
|
412 *
|
|
|
413 * A failure of this function usually means that it is unsupported by a
|
|
|
414 * platform.
|
|
|
415 *
|
|
|
416 * Note that this function will appear to succeed, but not actually move the
|
|
|
417 * mouse when used over Microsoft Remote Desktop.
|
|
|
418 *
|
|
|
419 * \param x the x coordinate.
|
|
|
420 * \param y the y coordinate.
|
|
|
421 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
422 * information.
|
|
|
423 *
|
|
|
424 * \threadsafety This function should only be called on the main thread.
|
|
|
425 *
|
|
|
426 * \since This function is available since SDL 3.2.0.
|
|
|
427 *
|
|
|
428 * \sa SDL_WarpMouseInWindow
|
|
|
429 */
|
|
|
430 extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y);
|
|
|
431
|
|
|
432 /**
|
|
|
433 * Set a user-defined function by which to transform relative mouse inputs.
|
|
|
434 *
|
|
|
435 * This overrides the relative system scale and relative speed scale hints.
|
|
|
436 * Should be called prior to enabling relative mouse mode, fails otherwise.
|
|
|
437 *
|
|
|
438 * \param callback a callback used to transform relative mouse motion, or NULL
|
|
|
439 * for default behavior.
|
|
|
440 * \param userdata a pointer that will be passed to `callback`.
|
|
|
441 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
442 * information.
|
|
|
443 *
|
|
|
444 * \threadsafety This function should only be called on the main thread.
|
|
|
445 *
|
|
|
446 * \since This function is available since SDL 3.4.0.
|
|
|
447 */
|
|
|
448 extern SDL_DECLSPEC bool SDLCALL SDL_SetRelativeMouseTransform(SDL_MouseMotionTransformCallback callback, void *userdata);
|
|
|
449
|
|
|
450 /**
|
|
|
451 * Set relative mouse mode for a window.
|
|
|
452 *
|
|
|
453 * While the window has focus and relative mouse mode is enabled, the cursor
|
|
|
454 * is hidden, the mouse position is constrained to the window, and SDL will
|
|
|
455 * report continuous relative mouse motion even if the mouse is at the edge of
|
|
|
456 * the window.
|
|
|
457 *
|
|
|
458 * If you'd like to keep the mouse position fixed while in relative mode you
|
|
|
459 * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a
|
|
|
460 * specific location when relative mode ends, you should use
|
|
|
461 * SDL_WarpMouseInWindow() before disabling relative mode.
|
|
|
462 *
|
|
|
463 * This function will flush any pending mouse motion for this window.
|
|
|
464 *
|
|
|
465 * \param window the window to change.
|
|
|
466 * \param enabled true to enable relative mode, false to disable.
|
|
|
467 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
468 * information.
|
|
|
469 *
|
|
|
470 * \threadsafety This function should only be called on the main thread.
|
|
|
471 *
|
|
|
472 * \since This function is available since SDL 3.2.0.
|
|
|
473 *
|
|
|
474 * \sa SDL_GetWindowRelativeMouseMode
|
|
|
475 */
|
|
|
476 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled);
|
|
|
477
|
|
|
478 /**
|
|
|
479 * Query whether relative mouse mode is enabled for a window.
|
|
|
480 *
|
|
|
481 * \param window the window to query.
|
|
|
482 * \returns true if relative mode is enabled for a window or false otherwise.
|
|
|
483 *
|
|
|
484 * \threadsafety This function should only be called on the main thread.
|
|
|
485 *
|
|
|
486 * \since This function is available since SDL 3.2.0.
|
|
|
487 *
|
|
|
488 * \sa SDL_SetWindowRelativeMouseMode
|
|
|
489 */
|
|
|
490 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window);
|
|
|
491
|
|
|
492 /**
|
|
|
493 * Capture the mouse and to track input outside an SDL window.
|
|
|
494 *
|
|
|
495 * Capturing enables your app to obtain mouse events globally, instead of just
|
|
|
496 * within your window. Not all video targets support this function. When
|
|
|
497 * capturing is enabled, the current window will get all mouse events, but
|
|
|
498 * unlike relative mode, no change is made to the cursor and it is not
|
|
|
499 * restrained to your window.
|
|
|
500 *
|
|
|
501 * This function may also deny mouse input to other windows--both those in
|
|
|
502 * your application and others on the system--so you should use this function
|
|
|
503 * sparingly, and in small bursts. For example, you might want to track the
|
|
|
504 * mouse while the user is dragging something, until the user releases a mouse
|
|
|
505 * button. It is not recommended that you capture the mouse for long periods
|
|
|
506 * of time, such as the entire time your app is running. For that, you should
|
|
|
507 * probably use SDL_SetWindowRelativeMouseMode() or SDL_SetWindowMouseGrab(),
|
|
|
508 * depending on your goals.
|
|
|
509 *
|
|
|
510 * While captured, mouse events still report coordinates relative to the
|
|
|
511 * current (foreground) window, but those coordinates may be outside the
|
|
|
512 * bounds of the window (including negative values). Capturing is only allowed
|
|
|
513 * for the foreground window. If the window loses focus while capturing, the
|
|
|
514 * capture will be disabled automatically.
|
|
|
515 *
|
|
|
516 * While capturing is enabled, the current window will have the
|
|
|
517 * `SDL_WINDOW_MOUSE_CAPTURE` flag set.
|
|
|
518 *
|
|
|
519 * Please note that SDL will attempt to "auto capture" the mouse while the
|
|
|
520 * user is pressing a button; this is to try and make mouse behavior more
|
|
|
521 * consistent between platforms, and deal with the common case of a user
|
|
|
522 * dragging the mouse outside of the window. This means that if you are
|
|
|
523 * calling SDL_CaptureMouse() only to deal with this situation, you do not
|
|
|
524 * have to (although it is safe to do so). If this causes problems for your
|
|
|
525 * app, you can disable auto capture by setting the
|
|
|
526 * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero.
|
|
|
527 *
|
|
|
528 * \param enabled true to enable capturing, false to disable.
|
|
|
529 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
530 * information.
|
|
|
531 *
|
|
|
532 * \threadsafety This function should only be called on the main thread.
|
|
|
533 *
|
|
|
534 * \since This function is available since SDL 3.2.0.
|
|
|
535 *
|
|
|
536 * \sa SDL_GetGlobalMouseState
|
|
|
537 */
|
|
|
538 extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled);
|
|
|
539
|
|
|
540 /**
|
|
|
541 * Create a cursor using the specified bitmap data and mask (in MSB format).
|
|
|
542 *
|
|
|
543 * `mask` has to be in MSB (Most Significant Bit) format.
|
|
|
544 *
|
|
|
545 * The cursor width (`w`) must be a multiple of 8 bits.
|
|
|
546 *
|
|
|
547 * The cursor is created in black and white according to the following:
|
|
|
548 *
|
|
|
549 * - data=0, mask=1: white
|
|
|
550 * - data=1, mask=1: black
|
|
|
551 * - data=0, mask=0: transparent
|
|
|
552 * - data=1, mask=0: inverted color if possible, black if not.
|
|
|
553 *
|
|
|
554 * Cursors created with this function must be freed with SDL_DestroyCursor().
|
|
|
555 *
|
|
|
556 * If you want to have a color cursor, or create your cursor from an
|
|
|
557 * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can
|
|
|
558 * hide the cursor and draw your own as part of your game's rendering, but it
|
|
|
559 * will be bound to the framerate.
|
|
|
560 *
|
|
|
561 * Also, SDL_CreateSystemCursor() is available, which provides several
|
|
|
562 * readily-available system cursors to pick from.
|
|
|
563 *
|
|
|
564 * \param data the color value for each pixel of the cursor.
|
|
|
565 * \param mask the mask value for each pixel of the cursor.
|
|
|
566 * \param w the width of the cursor.
|
|
|
567 * \param h the height of the cursor.
|
|
|
568 * \param hot_x the x-axis offset from the left of the cursor image to the
|
|
|
569 * mouse x position, in the range of 0 to `w` - 1.
|
|
|
570 * \param hot_y the y-axis offset from the top of the cursor image to the
|
|
|
571 * mouse y position, in the range of 0 to `h` - 1.
|
|
|
572 * \returns a new cursor with the specified parameters on success or NULL on
|
|
|
573 * failure; call SDL_GetError() for more information.
|
|
|
574 *
|
|
|
575 * \threadsafety This function should only be called on the main thread.
|
|
|
576 *
|
|
|
577 * \since This function is available since SDL 3.2.0.
|
|
|
578 *
|
|
|
579 * \sa SDL_CreateAnimatedCursor
|
|
|
580 * \sa SDL_CreateColorCursor
|
|
|
581 * \sa SDL_CreateSystemCursor
|
|
|
582 * \sa SDL_DestroyCursor
|
|
|
583 * \sa SDL_SetCursor
|
|
|
584 */
|
|
|
585 extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 *data,
|
|
|
586 const Uint8 *mask,
|
|
|
587 int w, int h, int hot_x,
|
|
|
588 int hot_y);
|
|
|
589
|
|
|
590 /**
|
|
|
591 * Create a color cursor.
|
|
|
592 *
|
|
|
593 * If this function is passed a surface with alternate representations added
|
|
|
594 * with SDL_AddSurfaceAlternateImage(), the surface will be interpreted as the
|
|
|
595 * content to be used for 100% display scale, and the alternate
|
|
|
596 * representations will be used for high DPI situations if
|
|
|
597 * SDL_HINT_MOUSE_DPI_SCALE_CURSORS is enabled. For example, if the original
|
|
|
598 * surface is 32x32, then on a 2x macOS display or 200% display scale on
|
|
|
599 * Windows, a 64x64 version of the image will be used, if available. If a
|
|
|
600 * matching version of the image isn't available, the closest larger size
|
|
|
601 * image will be downscaled to the appropriate size and be used instead, if
|
|
|
602 * available. Otherwise, the closest smaller image will be upscaled and be
|
|
|
603 * used instead.
|
|
|
604 *
|
|
|
605 * \param surface an SDL_Surface structure representing the cursor image.
|
|
|
606 * \param hot_x the x position of the cursor hot spot.
|
|
|
607 * \param hot_y the y position of the cursor hot spot.
|
|
|
608 * \returns the new cursor on success or NULL on failure; call SDL_GetError()
|
|
|
609 * for more information.
|
|
|
610 *
|
|
|
611 * \threadsafety This function should only be called on the main thread.
|
|
|
612 *
|
|
|
613 * \since This function is available since SDL 3.2.0.
|
|
|
614 *
|
|
|
615 * \sa SDL_AddSurfaceAlternateImage
|
|
|
616 * \sa SDL_CreateAnimatedCursor
|
|
|
617 * \sa SDL_CreateCursor
|
|
|
618 * \sa SDL_CreateSystemCursor
|
|
|
619 * \sa SDL_DestroyCursor
|
|
|
620 * \sa SDL_SetCursor
|
|
|
621 */
|
|
|
622 extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
|
|
|
623 int hot_x,
|
|
|
624 int hot_y);
|
|
|
625
|
|
|
626 /**
|
|
|
627 * Create an animated color cursor.
|
|
|
628 *
|
|
|
629 * Animated cursors are composed of a sequential array of frames, specified as
|
|
|
630 * surfaces and durations in an array of SDL_CursorFrameInfo structs. The hot
|
|
|
631 * spot coordinates are universal to all frames, and all frames must have the
|
|
|
632 * same dimensions.
|
|
|
633 *
|
|
|
634 * Frame durations are specified in milliseconds. A duration of 0 implies an
|
|
|
635 * infinite frame time, and the animation will stop on that frame. To create a
|
|
|
636 * one-shot animation, set the duration of the last frame in the sequence to
|
|
|
637 * 0.
|
|
|
638 *
|
|
|
639 * If this function is passed surfaces with alternate representations added
|
|
|
640 * with SDL_AddSurfaceAlternateImage(), the surfaces will be interpreted as
|
|
|
641 * the content to be used for 100% display scale, and the alternate
|
|
|
642 * representations will be used for high DPI situations. For example, if the
|
|
|
643 * original surfaces are 32x32, then on a 2x macOS display or 200% display
|
|
|
644 * scale on Windows, a 64x64 version of the image will be used, if available.
|
|
|
645 * If a matching version of the image isn't available, the closest larger size
|
|
|
646 * image will be downscaled to the appropriate size and be used instead, if
|
|
|
647 * available. Otherwise, the closest smaller image will be upscaled and be
|
|
|
648 * used instead.
|
|
|
649 *
|
|
|
650 * If the underlying platform does not support animated cursors, this function
|
|
|
651 * will fall back to creating a static color cursor using the first frame in
|
|
|
652 * the sequence.
|
|
|
653 *
|
|
|
654 * \param frames an array of cursor images composing the animation.
|
|
|
655 * \param frame_count the number of frames in the sequence.
|
|
|
656 * \param hot_x the x position of the cursor hot spot.
|
|
|
657 * \param hot_y the y position of the cursor hot spot.
|
|
|
658 * \returns the new cursor on success or NULL on failure; call SDL_GetError()
|
|
|
659 * for more information.
|
|
|
660 *
|
|
|
661 * \threadsafety This function should only be called on the main thread.
|
|
|
662 *
|
|
|
663 * \since This function is available since SDL 3.4.0.
|
|
|
664 *
|
|
|
665 * \sa SDL_AddSurfaceAlternateImage
|
|
|
666 * \sa SDL_CreateCursor
|
|
|
667 * \sa SDL_CreateColorCursor
|
|
|
668 * \sa SDL_CreateSystemCursor
|
|
|
669 * \sa SDL_DestroyCursor
|
|
|
670 * \sa SDL_SetCursor
|
|
|
671 */
|
|
|
672 extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateAnimatedCursor(SDL_CursorFrameInfo *frames,
|
|
|
673 int frame_count,
|
|
|
674 int hot_x,
|
|
|
675 int hot_y);
|
|
|
676
|
|
|
677 /**
|
|
|
678 * Create a system cursor.
|
|
|
679 *
|
|
|
680 * \param id an SDL_SystemCursor enum value.
|
|
|
681 * \returns a cursor on success or NULL on failure; call SDL_GetError() for
|
|
|
682 * more information.
|
|
|
683 *
|
|
|
684 * \threadsafety This function should only be called on the main thread.
|
|
|
685 *
|
|
|
686 * \since This function is available since SDL 3.2.0.
|
|
|
687 *
|
|
|
688 * \sa SDL_DestroyCursor
|
|
|
689 */
|
|
|
690 extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
|
|
|
691
|
|
|
692 /**
|
|
|
693 * Set the active cursor.
|
|
|
694 *
|
|
|
695 * This function sets the currently active cursor to the specified one. If the
|
|
|
696 * cursor is currently visible, the change will be immediately represented on
|
|
|
697 * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
|
|
|
698 * this is desired for any reason.
|
|
|
699 *
|
|
|
700 * \param cursor a cursor to make active.
|
|
|
701 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
702 * information.
|
|
|
703 *
|
|
|
704 * \threadsafety This function should only be called on the main thread.
|
|
|
705 *
|
|
|
706 * \since This function is available since SDL 3.2.0.
|
|
|
707 *
|
|
|
708 * \sa SDL_GetCursor
|
|
|
709 */
|
|
|
710 extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor);
|
|
|
711
|
|
|
712 /**
|
|
|
713 * Get the active cursor.
|
|
|
714 *
|
|
|
715 * This function returns a pointer to the current cursor which is owned by the
|
|
|
716 * library. It is not necessary to free the cursor with SDL_DestroyCursor().
|
|
|
717 *
|
|
|
718 * \returns the active cursor or NULL if there is no mouse.
|
|
|
719 *
|
|
|
720 * \threadsafety This function should only be called on the main thread.
|
|
|
721 *
|
|
|
722 * \since This function is available since SDL 3.2.0.
|
|
|
723 *
|
|
|
724 * \sa SDL_SetCursor
|
|
|
725 */
|
|
|
726 extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
|
|
|
727
|
|
|
728 /**
|
|
|
729 * Get the default cursor.
|
|
|
730 *
|
|
|
731 * You do not have to call SDL_DestroyCursor() on the return value, but it is
|
|
|
732 * safe to do so.
|
|
|
733 *
|
|
|
734 * \returns the default cursor on success or NULL on failure; call
|
|
|
735 * SDL_GetError() for more information.
|
|
|
736 *
|
|
|
737 * \threadsafety This function should only be called on the main thread.
|
|
|
738 *
|
|
|
739 * \since This function is available since SDL 3.2.0.
|
|
|
740 */
|
|
|
741 extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void);
|
|
|
742
|
|
|
743 /**
|
|
|
744 * Free a previously-created cursor.
|
|
|
745 *
|
|
|
746 * Use this function to free cursor resources created with SDL_CreateCursor(),
|
|
|
747 * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
|
|
|
748 *
|
|
|
749 * \param cursor the cursor to free.
|
|
|
750 *
|
|
|
751 * \threadsafety This function should only be called on the main thread.
|
|
|
752 *
|
|
|
753 * \since This function is available since SDL 3.2.0.
|
|
|
754 *
|
|
|
755 * \sa SDL_CreateAnimatedCursor
|
|
|
756 * \sa SDL_CreateColorCursor
|
|
|
757 * \sa SDL_CreateCursor
|
|
|
758 * \sa SDL_CreateSystemCursor
|
|
|
759 */
|
|
|
760 extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor);
|
|
|
761
|
|
|
762 /**
|
|
|
763 * Show the cursor.
|
|
|
764 *
|
|
|
765 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
766 * information.
|
|
|
767 *
|
|
|
768 * \threadsafety This function should only be called on the main thread.
|
|
|
769 *
|
|
|
770 * \since This function is available since SDL 3.2.0.
|
|
|
771 *
|
|
|
772 * \sa SDL_CursorVisible
|
|
|
773 * \sa SDL_HideCursor
|
|
|
774 */
|
|
|
775 extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void);
|
|
|
776
|
|
|
777 /**
|
|
|
778 * Hide the cursor.
|
|
|
779 *
|
|
|
780 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
781 * information.
|
|
|
782 *
|
|
|
783 * \threadsafety This function should only be called on the main thread.
|
|
|
784 *
|
|
|
785 * \since This function is available since SDL 3.2.0.
|
|
|
786 *
|
|
|
787 * \sa SDL_CursorVisible
|
|
|
788 * \sa SDL_ShowCursor
|
|
|
789 */
|
|
|
790 extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void);
|
|
|
791
|
|
|
792 /**
|
|
|
793 * Return whether the cursor is currently being shown.
|
|
|
794 *
|
|
|
795 * \returns `true` if the cursor is being shown, or `false` if the cursor is
|
|
|
796 * hidden.
|
|
|
797 *
|
|
|
798 * \threadsafety This function should only be called on the main thread.
|
|
|
799 *
|
|
|
800 * \since This function is available since SDL 3.2.0.
|
|
|
801 *
|
|
|
802 * \sa SDL_HideCursor
|
|
|
803 * \sa SDL_ShowCursor
|
|
|
804 */
|
|
|
805 extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void);
|
|
|
806
|
|
|
807 /* Ends C function definitions when using C++ */
|
|
|
808 #ifdef __cplusplus
|
|
|
809 }
|
|
|
810 #endif
|
|
|
811 #include <SDL3/SDL_close_code.h>
|
|
|
812
|
|
|
813 #endif /* SDL_mouse_h_ */
|
