/*
Simple DirectMedia Layer
- Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
* Include file for SDL mouse event handling.
*/
-#ifndef _SDL_mouse_h
-#define _SDL_mouse_h
+#ifndef SDL_mouse_h_
+#define SDL_mouse_h_
#include "SDL_stdinc.h"
#include "SDL_error.h"
extern "C" {
#endif
-typedef struct SDL_Cursor SDL_Cursor; /* Implementation dependent */
+typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */
/**
- * \brief Cursor types for SDL_CreateSystemCursor.
+ * \brief Cursor types for SDL_CreateSystemCursor().
*/
typedef enum
{
SDL_NUM_SYSTEM_CURSORS
} SDL_SystemCursor;
+/**
+ * \brief Scroll direction types for the Scroll event
+ */
+typedef enum
+{
+ SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */
+ SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */
+} SDL_MouseWheelDirection;
+
/* Function prototypes */
/**
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
+/**
+ * \brief Get the current state of the mouse, in relation to the desktop
+ *
+ * This works just like SDL_GetMouseState(), but the coordinates will be
+ * reported relative to the top-left of the desktop. This can be useful if
+ * you need to track the mouse outside of a specific window and
+ * SDL_CaptureMouse() doesn't fit your needs. For example, it could be
+ * useful if you need to track the mouse while dragging a window, where
+ * coordinates relative to a window might not be in sync at all times.
+ *
+ * \note SDL_GetMouseState() returns the mouse position as SDL understands
+ * it from the last pump of the event queue. This function, however,
+ * queries the OS for the current mouse position, and as such, might
+ * be a slightly less efficient function. Unless you know what you're
+ * doing and have a good reason to use this function, you probably want
+ * SDL_GetMouseState() instead.
+ *
+ * \param x Returns the current X coord, relative to the desktop. Can be NULL.
+ * \param y Returns the current Y coord, relative to the desktop. Can be NULL.
+ * \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
+ *
+ * \sa SDL_GetMouseState
+ */
+extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
+
/**
* \brief Retrieve the relative state of the mouse.
*
extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
int x, int y);
+/**
+ * \brief Moves the mouse to the given position in global screen space.
+ *
+ * \param x The x coordinate
+ * \param y The y coordinate
+ * \return 0 on success, -1 on error (usually: unsupported by a platform).
+ *
+ * \note This function generates a mouse motion event
+ */
+extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
+
/**
* \brief Set relative mouse mode.
*
*/
extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
+/**
+ * \brief Capture the mouse, to track input outside an SDL window.
+ *
+ * \param enabled Whether or not to enable capturing
+ *
+ * Capturing enables your app to obtain mouse events globally, instead of
+ * just within your window. Not all video targets support this function.
+ * When capturing is enabled, the current window will get all mouse events,
+ * but unlike relative mode, no change is made to the cursor and it is
+ * not restrained to your window.
+ *
+ * This function may also deny mouse input to other windows--both those in
+ * your application and others on the system--so you should use this
+ * function sparingly, and in small bursts. For example, you might want to
+ * track the mouse while the user is dragging something, until the user
+ * releases a mouse button. It is not recommended that you capture the mouse
+ * for long periods of time, such as the entire time your app is running.
+ *
+ * While captured, mouse events still report coordinates relative to the
+ * current (foreground) window, but those coordinates may be outside the
+ * bounds of the window (including negative values). Capturing is only
+ * allowed for the foreground window. If the window loses focus while
+ * capturing, the capture will be disabled automatically.
+ *
+ * While capturing is enabled, the current window will have the
+ * SDL_WINDOW_MOUSE_CAPTURE flag set.
+ *
+ * \return 0 on success, or -1 if not supported.
+ */
+extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
+
/**
* \brief Query whether relative mouse mode is enabled.
*
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
/**
- * \brief Frees a cursor created with SDL_CreateCursor().
+ * \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
*
* \sa SDL_CreateCursor()
+ * \sa SDL_CreateColorCursor()
+ * \sa SDL_CreateSystemCursor()
*/
extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
#endif
#include "close_code.h"
-#endif /* _SDL_mouse_h */
+#endif /* SDL_mouse_h_ */
/* vi: set ts=4 sw=4 expandtab: */