1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2022 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 * \file SDL_mouse.h
24 *
25 * Include file for SDL mouse event handling.
26 */
27
28#ifndef SDL_mouse_h_
29#define SDL_mouse_h_
30
31#include "SDL_stdinc.h"
32#include "SDL_error.h"
33#include "SDL_video.h"
34
35#include "begin_code.h"
36/* Set up for C function definitions, even when using C++ */
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */
42
43/**
44 * \brief Cursor types for SDL_CreateSystemCursor().
45 */
46typedef enum
47{
48 SDL_SYSTEM_CURSOR_ARROW, /**< Arrow */
49 SDL_SYSTEM_CURSOR_IBEAM, /**< I-beam */
50 SDL_SYSTEM_CURSOR_WAIT, /**< Wait */
51 SDL_SYSTEM_CURSOR_CROSSHAIR, /**< Crosshair */
52 SDL_SYSTEM_CURSOR_WAITARROW, /**< Small wait cursor (or Wait if not available) */
53 SDL_SYSTEM_CURSOR_SIZENWSE, /**< Double arrow pointing northwest and southeast */
54 SDL_SYSTEM_CURSOR_SIZENESW, /**< Double arrow pointing northeast and southwest */
55 SDL_SYSTEM_CURSOR_SIZEWE, /**< Double arrow pointing west and east */
56 SDL_SYSTEM_CURSOR_SIZENS, /**< Double arrow pointing north and south */
57 SDL_SYSTEM_CURSOR_SIZEALL, /**< Four pointed arrow pointing north, south, east, and west */
58 SDL_SYSTEM_CURSOR_NO, /**< Slashed circle or crossbones */
59 SDL_SYSTEM_CURSOR_HAND, /**< Hand */
60 SDL_NUM_SYSTEM_CURSORS
61} SDL_SystemCursor;
62
63/**
64 * \brief Scroll direction types for the Scroll event
65 */
66typedef enum
67{
68 SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */
69 SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */
70} SDL_MouseWheelDirection;
71
72/* Function prototypes */
73
74/**
75 * Get the window which currently has mouse focus.
76 *
77 * \returns the window with mouse focus.
78 *
79 * \since This function is available since SDL 2.0.0.
80 */
81extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
82
83/**
84 * Retrieve the current state of the mouse.
85 *
86 * The current button state is returned as a button bitmask, which can be
87 * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
88 * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
89 * mouse cursor position relative to the focus window. You can pass NULL for
90 * either `x` or `y`.
91 *
92 * \param x the x coordinate of the mouse cursor position relative to the
93 * focus window
94 * \param y the y coordinate of the mouse cursor position relative to the
95 * focus window
96 * \returns a 32-bit button bitmask of the current button state.
97 *
98 * \since This function is available since SDL 2.0.0.
99 *
100 * \sa SDL_GetGlobalMouseState
101 * \sa SDL_GetRelativeMouseState
102 * \sa SDL_PumpEvents
103 */
104extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
105
106/**
107 * Get the current state of the mouse in relation to the desktop.
108 *
109 * This works similarly to SDL_GetMouseState(), but the coordinates will be
110 * reported relative to the top-left of the desktop. This can be useful if you
111 * need to track the mouse outside of a specific window and SDL_CaptureMouse()
112 * doesn't fit your needs. For example, it could be useful if you need to
113 * track the mouse while dragging a window, where coordinates relative to a
114 * window might not be in sync at all times.
115 *
116 * Note: SDL_GetMouseState() returns the mouse position as SDL understands it
117 * from the last pump of the event queue. This function, however, queries the
118 * OS for the current mouse position, and as such, might be a slightly less
119 * efficient function. Unless you know what you're doing and have a good
120 * reason to use this function, you probably want SDL_GetMouseState() instead.
121 *
122 * \param x filled in with the current X coord relative to the desktop; can be
123 * NULL
124 * \param y filled in with the current Y coord relative to the desktop; can be
125 * NULL
126 * \returns the current button state as a bitmask which can be tested using
127 * the SDL_BUTTON(X) macros.
128 *
129 * \since This function is available since SDL 2.0.4.
130 *
131 * \sa SDL_CaptureMouse
132 */
133extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
134
135/**
136 * Retrieve the relative state of the mouse.
137 *
138 * The current button state is returned as a button bitmask, which can be
139 * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
140 * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
141 * mouse deltas since the last call to SDL_GetRelativeMouseState() or since
142 * event initialization. You can pass NULL for either `x` or `y`.
143 *
144 * \param x a pointer filled with the last recorded x coordinate of the mouse
145 * \param y a pointer filled with the last recorded y coordinate of the mouse
146 * \returns a 32-bit button bitmask of the relative button state.
147 *
148 * \since This function is available since SDL 2.0.0.
149 *
150 * \sa SDL_GetMouseState
151 */
152extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
153
154/**
155 * Move the mouse cursor to the given position within the window.
156 *
157 * This function generates a mouse motion event.
158 *
159 * Note that this function will appear to succeed, but not actually move the
160 * mouse when used over Microsoft Remote Desktop.
161 *
162 * \param window the window to move the mouse into, or NULL for the current
163 * mouse focus
164 * \param x the x coordinate within the window
165 * \param y the y coordinate within the window
166 *
167 * \since This function is available since SDL 2.0.0.
168 *
169 * \sa SDL_WarpMouseGlobal
170 */
171extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
172 int x, int y);
173
174/**
175 * Move the mouse to the given position in global screen space.
176 *
177 * This function generates a mouse motion event.
178 *
179 * A failure of this function usually means that it is unsupported by a
180 * platform.
181 *
182 * Note that this function will appear to succeed, but not actually move the
183 * mouse when used over Microsoft Remote Desktop.
184 *
185 * \param x the x coordinate
186 * \param y the y coordinate
187 * \returns 0 on success or a negative error code on failure; call
188 * SDL_GetError() for more information.
189 *
190 * \since This function is available since SDL 2.0.4.
191 *
192 * \sa SDL_WarpMouseInWindow
193 */
194extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
195
196/**
197 * Set relative mouse mode.
198 *
199 * While the mouse is in relative mode, the cursor is hidden, and the driver
200 * will try to report continuous motion in the current window. Only relative
201 * motion events will be delivered, the mouse position will not change.
202 *
203 * Note that this function will not be able to provide continuous relative
204 * motion when used over Microsoft Remote Desktop, instead motion is limited
205 * to the bounds of the screen.
206 *
207 * This function will flush any pending mouse motion.
208 *
209 * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable.
210 * \returns 0 on success or a negative error code on failure; call
211 * SDL_GetError() for more information.
212 *
213 * If relative mode is not supported, this returns -1.
214 *
215 * \since This function is available since SDL 2.0.0.
216 *
217 * \sa SDL_GetRelativeMouseMode
218 */
219extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
220
221/**
222 * Capture the mouse and to track input outside an SDL window.
223 *
224 * Capturing enables your app to obtain mouse events globally, instead of just
225 * within your window. Not all video targets support this function. When
226 * capturing is enabled, the current window will get all mouse events, but
227 * unlike relative mode, no change is made to the cursor and it is not
228 * restrained to your window.
229 *
230 * This function may also deny mouse input to other windows--both those in
231 * your application and others on the system--so you should use this function
232 * sparingly, and in small bursts. For example, you might want to track the
233 * mouse while the user is dragging something, until the user releases a mouse
234 * button. It is not recommended that you capture the mouse for long periods
235 * of time, such as the entire time your app is running. For that, you should
236 * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending
237 * on your goals.
238 *
239 * While captured, mouse events still report coordinates relative to the
240 * current (foreground) window, but those coordinates may be outside the
241 * bounds of the window (including negative values). Capturing is only allowed
242 * for the foreground window. If the window loses focus while capturing, the
243 * capture will be disabled automatically.
244 *
245 * While capturing is enabled, the current window will have the
246 * `SDL_WINDOW_MOUSE_CAPTURE` flag set.
247 *
248 * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
249 * \returns 0 on success or -1 if not supported; call SDL_GetError() for more
250 * information.
251 *
252 * \since This function is available since SDL 2.0.4.
253 *
254 * \sa SDL_GetGlobalMouseState
255 */
256extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
257
258/**
259 * Query whether relative mouse mode is enabled.
260 *
261 * \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise.
262 *
263 * \since This function is available since SDL 2.0.0.
264 *
265 * \sa SDL_SetRelativeMouseMode
266 */
267extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
268
269/**
270 * Create a cursor using the specified bitmap data and mask (in MSB format).
271 *
272 * `mask` has to be in MSB (Most Significant Bit) format.
273 *
274 * The cursor width (`w`) must be a multiple of 8 bits.
275 *
276 * The cursor is created in black and white according to the following:
277 *
278 * - data=0, mask=1: white
279 * - data=1, mask=1: black
280 * - data=0, mask=0: transparent
281 * - data=1, mask=0: inverted color if possible, black if not.
282 *
283 * Cursors created with this function must be freed with SDL_FreeCursor().
284 *
285 * If you want to have a color cursor, or create your cursor from an
286 * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can
287 * hide the cursor and draw your own as part of your game's rendering, but it
288 * will be bound to the framerate.
289 *
290 * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which
291 * provides twelve readily available system cursors to pick from.
292 *
293 * \param data the color value for each pixel of the cursor
294 * \param mask the mask value for each pixel of the cursor
295 * \param w the width of the cursor
296 * \param h the height of the cursor
297 * \param hot_x the X-axis location of the upper left corner of the cursor
298 * relative to the actual mouse position
299 * \param hot_y the Y-axis location of the upper left corner of the cursor
300 * relative to the actual mouse position
301 * \returns a new cursor with the specified parameters on success or NULL on
302 * failure; call SDL_GetError() for more information.
303 *
304 * \since This function is available since SDL 2.0.0.
305 *
306 * \sa SDL_FreeCursor
307 * \sa SDL_SetCursor
308 * \sa SDL_ShowCursor
309 */
310extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
311 const Uint8 * mask,
312 int w, int h, int hot_x,
313 int hot_y);
314
315/**
316 * Create a color cursor.
317 *
318 * \param surface an SDL_Surface structure representing the cursor image
319 * \param hot_x the x position of the cursor hot spot
320 * \param hot_y the y position of the cursor hot spot
321 * \returns the new cursor on success or NULL on failure; call SDL_GetError()
322 * for more information.
323 *
324 * \since This function is available since SDL 2.0.0.
325 *
326 * \sa SDL_CreateCursor
327 * \sa SDL_FreeCursor
328 */
329extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
330 int hot_x,
331 int hot_y);
332
333/**
334 * Create a system cursor.
335 *
336 * \param id an SDL_SystemCursor enum value
337 * \returns a cursor on success or NULL on failure; call SDL_GetError() for
338 * more information.
339 *
340 * \since This function is available since SDL 2.0.0.
341 *
342 * \sa SDL_FreeCursor
343 */
344extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
345
346/**
347 * Set the active cursor.
348 *
349 * This function sets the currently active cursor to the specified one. If the
350 * cursor is currently visible, the change will be immediately represented on
351 * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
352 * this is desired for any reason.
353 *
354 * \param cursor a cursor to make active
355 *
356 * \since This function is available since SDL 2.0.0.
357 *
358 * \sa SDL_CreateCursor
359 * \sa SDL_GetCursor
360 * \sa SDL_ShowCursor
361 */
362extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
363
364/**
365 * Get the active cursor.
366 *
367 * This function returns a pointer to the current cursor which is owned by the
368 * library. It is not necessary to free the cursor with SDL_FreeCursor().
369 *
370 * \returns the active cursor or NULL if there is no mouse.
371 *
372 * \since This function is available since SDL 2.0.0.
373 *
374 * \sa SDL_SetCursor
375 */
376extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
377
378/**
379 * Get the default cursor.
380 *
381 * \returns the default cursor on success or NULL on failure.
382 *
383 * \since This function is available since SDL 2.0.0.
384 *
385 * \sa SDL_CreateSystemCursor
386 */
387extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
388
389/**
390 * Free a previously-created cursor.
391 *
392 * Use this function to free cursor resources created with SDL_CreateCursor(),
393 * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
394 *
395 * \param cursor the cursor to free
396 *
397 * \since This function is available since SDL 2.0.0.
398 *
399 * \sa SDL_CreateColorCursor
400 * \sa SDL_CreateCursor
401 * \sa SDL_CreateSystemCursor
402 */
403extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
404
405/**
406 * Toggle whether or not the cursor is shown.
407 *
408 * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
409 * displays the cursor and passing `SDL_DISABLE` hides it.
410 *
411 * The current state of the mouse cursor can be queried by passing
412 * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
413 *
414 * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
415 * `SDL_QUERY` to query the current state without changing it.
416 * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the
417 * cursor is hidden, or a negative error code on failure; call
418 * SDL_GetError() for more information.
419 *
420 * \since This function is available since SDL 2.0.0.
421 *
422 * \sa SDL_CreateCursor
423 * \sa SDL_SetCursor
424 */
425extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
426
427/**
428 * Used as a mask when testing buttons in buttonstate.
429 *
430 * - Button 1: Left mouse button
431 * - Button 2: Middle mouse button
432 * - Button 3: Right mouse button
433 */
434#define SDL_BUTTON(X) (1 << ((X)-1))
435#define SDL_BUTTON_LEFT 1
436#define SDL_BUTTON_MIDDLE 2
437#define SDL_BUTTON_RIGHT 3
438#define SDL_BUTTON_X1 4
439#define SDL_BUTTON_X2 5
440#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT)
441#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE)
442#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT)
443#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1)
444#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2)
445
446/* Ends C function definitions when using C++ */
447#ifdef __cplusplus
448}
449#endif
450#include "close_code.h"
451
452#endif /* SDL_mouse_h_ */
453
454/* vi: set ts=4 sw=4 expandtab: */
455