Any GUI application has to deal with the mouse, and SDL provides functions to manage mouse input and the displayed cursor. More...

Classes
struct	SDL::CursorBase
	The structure used to identify an SDL cursor. More...

struct	SDL::CursorRef
	Handle to a non owned cursor. More...

struct	SDL::Cursor
	Handle to an owned cursor. More...

Typedefs
using	SDL::SystemCursor = SDL_SystemCursor
	Cursor types for CursorBase.CursorBase().

using	SDL::MouseID = SDL_MouseID
	This is a unique ID for a mouse for the time it is connected to the system, and is never reused for the lifetime of the application.

using	SDL::MouseButton = Uint8
	Represents a button index.

using	SDL::MouseWheelDirection = SDL_MouseWheelDirection
	Scroll direction types for the Scroll event.

using	SDL::MouseButtonFlags = Uint32
	A bitmask of pressed mouse buttons, as reported by GetMouseState, etc.

Functions
constexpr MouseButtonFlags	SDL::ButtonMask (MouseButton button)
	Convert a button index to a button mask.

bool	SDL::HasMouse ()
	Return whether a mouse is currently connected.

OwnArray< MouseID >	SDL::GetMice ()
	Get a list of currently connected mice.

const char *	SDL::GetMouseNameForID (MouseID instance_id)
	Get the name of a mouse.

WindowRef	SDL::GetMouseFocus ()
	Get the window which currently has mouse focus.

MouseButtonFlags	SDL::GetMouseState (float x, float y)
	Query SDL's cache for the synchronous mouse button state and the window-relative SDL-cursor position.

MouseButtonFlags	SDL::GetGlobalMouseState (float x, float y)
	Query the platform for the asynchronous mouse button state and the desktop-relative platform-cursor position.

MouseButtonFlags	SDL::GetRelativeMouseState (float x, float y)
	Query SDL's cache for the synchronous mouse button state and accumulated mouse delta since last call.

void	SDL::WarpMouse (float x, float y)
	Move the mouse to the given position in global screen space.

void	SDL::CaptureMouse (bool enabled)
	Capture the mouse and to track input outside an SDL window.

void	SDL::SetCursor (CursorBase &cursor)
	Set the active cursor.

CursorRef	SDL::GetCursor ()
	Get the active cursor.

CursorRef	SDL::GetDefaultCursor ()
	Get the default cursor.

void	SDL::ShowCursor ()
	Show the cursor.

void	SDL::HideCursor ()
	Hide the cursor.

bool	SDL::CursorVisible ()
	Return whether the cursor is currently being shown.

void	SDL::WindowBase::WarpMouse (float x, float y)
	Move the mouse cursor to the given position within the window.

void	SDL::WindowBase::SetRelativeMouseMode (bool enabled)
	Set relative mouse mode for a window.

bool	SDL::WindowBase::GetRelativeMouseMode () const
	Query whether relative mouse mode is enabled for a window.

Variables
constexpr SystemCursor	SDL::SYSTEM_CURSOR_DEFAULT
	Default cursor. Usually an arrow.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_TEXT
	Text selection. Usually an I-beam.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_WAIT = SDL_SYSTEM_CURSOR_WAIT
	Wait.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_CROSSHAIR
	Crosshair.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_PROGRESS = SDL_SYSTEM_CURSOR_PROGRESS
	Program is busy but still interactive.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_NWSE_RESIZE
	Double arrow pointing northwest and southeast.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_NESW_RESIZE
	Double arrow pointing northeast and southwest.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_EW_RESIZE
	Double arrow pointing west and east.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_NS_RESIZE
	Double arrow pointing north and south.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_MOVE = SDL_SYSTEM_CURSOR_MOVE
	Four pointed arrow pointing north, south, east, and west.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_NOT_ALLOWED
	Not permitted.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_POINTER = SDL_SYSTEM_CURSOR_POINTER
	Pointer that indicates a link.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_NW_RESIZE = SDL_SYSTEM_CURSOR_NW_RESIZE
	Window resize top-left.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_N_RESIZE
	Window resize top. May be NS_RESIZE.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_NE_RESIZE
	Window resize top-right.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_E_RESIZE
	Window resize right. May be EW_RESIZE.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_SE_RESIZE
	Window resize bottom-right.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_S_RESIZE
	Window resize bottom. May be NS_RESIZE.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_SW_RESIZE
	Window resize bottom-left.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_W_RESIZE
	Window resize left. May be EW_RESIZE.

constexpr SystemCursor	SDL::SYSTEM_CURSOR_COUNT = SDL_SYSTEM_CURSOR_COUNT
	COUNT.

constexpr MouseButton	SDL::BUTTON_LEFT = SDL_BUTTON_LEFT
	Left button.

constexpr MouseButton	SDL::BUTTON_MIDDLE = SDL_BUTTON_MIDDLE
	Middle button.

constexpr MouseButton	SDL::BUTTON_RIGHT = SDL_BUTTON_RIGHT
	Right button.

constexpr MouseButton	SDL::BUTTON_X1 = SDL_BUTTON_X1
	X1 button.

constexpr MouseButton	SDL::BUTTON_X2 = SDL_BUTTON_X2
	X2 button.

constexpr MouseWheelDirection	SDL::MOUSEWHEEL_NORMAL
	The scroll direction is normal.

constexpr MouseWheelDirection	SDL::MOUSEWHEEL_FLIPPED
	The scroll direction is flipped / natural.

constexpr MouseButtonFlags	SDL::BUTTON_LMASK
	Left button mask.

constexpr MouseButtonFlags	SDL::BUTTON_MMASK
	Middle button mask.

constexpr MouseButtonFlags	SDL::BUTTON_RMASK
	Right button mask.

constexpr MouseButtonFlags	SDL::BUTTON_X1MASK
	X1 button mask.

constexpr MouseButtonFlags	SDL::BUTTON_X2MASK
	X2 button mask.

Detailed Description

Most interactions with the mouse will come through the event subsystem. Moving a mouse generates an EVENT_MOUSE_MOTION event, pushing a button generates EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the current state of the mouse at any time with GetMouseState().

For certain games, it's useful to disassociate the mouse cursor from mouse input. An FPS, for example, would not want the player's motion to stop as the mouse hits the edge of the window. For these scenarios, use WindowBase.SetRelativeMouseMode(), which hides the cursor, grabs mouse input to the window, and reads mouse input no matter how far it moves.

Games that want the system to track the mouse but want to draw their own cursor can use HideCursor() and ShowCursor(). It might be more efficient to let the system manage the cursor, if possible, using SetCursor() with a custom image made through CursorBase.CursorBase(), or perhaps just a specific system cursor from CursorBase.CursorBase().

SDL can, on many platforms, differentiate between multiple connected mice, allowing for interesting input scenarios and multiplayer games. They can be enumerated with GetMice(), and SDL will send EVENT_MOUSE_ADDED and EVENT_MOUSE_REMOVED events as they are connected and unplugged.

Since many apps only care about basic mouse input, SDL offers a virtual mouse device for touch and pen input, which often can make a desktop application work on a touchscreen phone without any code changes. Apps that care about touch/pen separately from mouse input should filter out events with a which field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID.

Typedef Documentation

◆ MouseButtonFlags

using SDL::MouseButtonFlags = typedef Uint32

Button 1: Left mouse button
Button 2: Middle mouse button
Button 3: Right mouse button
Button 4: Side mouse button 1
Button 5: Side mouse button 2

Since: This datatype is available since SDL 3.2.0.

See also: GetMouseState; GetGlobalMouseState; GetRelativeMouseState

◆ MouseID

using SDL::MouseID = typedef SDL_MouseID

If the mouse is disconnected and reconnected, it will get a new ID.

The value 0 is an invalid ID.

Since: This datatype is available since SDL 3.2.0.

◆ MouseWheelDirection

using SDL::MouseWheelDirection = typedef SDL_MouseWheelDirection

Since: This enum is available since SDL 3.2.0.

◆ SystemCursor

using SDL::SystemCursor = typedef SDL_SystemCursor

Since: This enum is available since SDL 3.2.0.

Function Documentation

◆ ButtonMask()

constexpr MouseButtonFlags SDL::ButtonMask ( MouseButton button )

constexpr

Parameters

button

Returns: constexpr MouseButtonFlags

◆ CaptureMouse()

void SDL::CaptureMouse ( bool enabled )

inline

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. For that, you should probably use WindowBase.SetRelativeMouseMode() or WindowBase.SetMouseGrab(), depending on your goals.

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 WINDOW_MOUSE_CAPTURE flag set.

Please note that SDL will attempt to "auto capture" the mouse while the user is pressing a button; this is to try and make mouse behavior more consistent between platforms, and deal with the common case of a user dragging the mouse outside of the window. This means that if you are calling CaptureMouse() only to deal with this situation, you do not have to (although it is safe to do so). If this causes problems for your app, you can disable auto capture by setting the SDL_HINT_MOUSE_AUTO_CAPTURE hint to zero.

Parameters

enabled true to enable capturing, false to disable.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetGlobalMouseState

◆ CursorVisible()

bool SDL::CursorVisible ( )

inline

Returns: true if the cursor is being shown, or false if the cursor is hidden.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: HideCursor; ShowCursor

◆ GetCursor()

CursorRef SDL::GetCursor ( )

inline

This function returns a pointer to the current cursor which is owned by the library. It is not necessary to free the cursor with CursorRef.reset().

Returns: the active cursor or nullptr if there is no mouse.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: SetCursor

◆ GetDefaultCursor()

CursorRef SDL::GetDefaultCursor ( )

inline

You do not have to call CursorRef.reset() on the return value, but it is safe to do so.

Returns: the default cursor on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GetGlobalMouseState()

MouseButtonFlags SDL::GetGlobalMouseState	(	float *	x,
		float *	y
	)

inline

This function immediately queries the platform for the most recent asynchronous state, more costly than retrieving SDL's cached state in GetMouseState().

Passing non-nullptr pointers to x or y will write the destination with respective x or y coordinates relative to the desktop.

In Relative Mode, the platform-cursor's position usually contradicts the SDL-cursor's position as manually calculated from GetMouseState() and WindowBase.GetPosition.

This function can be useful if you need to track the mouse outside of a specific window and 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.

Parameters

x	a pointer to receive the platform-cursor's x-position from the desktop's top left corner, can be nullptr if unused.
y	a pointer to receive the platform-cursor's y-position from the desktop's top left corner, can be nullptr if unused.

Returns: a 32-bit bitmask of the button state that can be bitwise-compared against the ButtonMask(X) macro.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: CaptureMouse; GetMouseState; GetGlobalMouseState

◆ GetMice()

OwnArray< MouseID > SDL::GetMice ( )

inline

Note that this will include any device or virtual driver that includes mouse functionality, including some game controllers, KVM switches, etc. You should wait for input from a device before you consider it actively in use.

Returns: a 0 terminated array of mouse instance IDs.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetMouseNameForID; HasMouse

◆ GetMouseFocus()

WindowRef SDL::GetMouseFocus ( )

inline

Returns: the window with mouse focus.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GetMouseNameForID()

const char * SDL::GetMouseNameForID ( MouseID instance_id )

inline

This function returns "" if the mouse doesn't have a name.

Parameters

instance_id the mouse instance ID.

Returns: the name of the selected mouse.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetMice

◆ GetMouseState()

MouseButtonFlags SDL::GetMouseState	(	float *	x,
		float *	y
	)

inline

This function returns the cached synchronous state as SDL understands it from the last pump of the event queue.

To query the platform for immediate asynchronous state, use GetGlobalMouseState.

Passing non-nullptr pointers to x or y will write the destination with respective x or y coordinates relative to the focused window.

In Relative Mode, the SDL-cursor's position usually contradicts the platform-cursor's position as manually calculated from GetGlobalMouseState() and WindowBase.GetPosition.

Parameters

x	a pointer to receive the SDL-cursor's x-position from the focused window's top left corner, can be nullptr if unused.
y	a pointer to receive the SDL-cursor's y-position from the focused window's top left corner, can be nullptr if unused.

Returns: a 32-bit bitmask of the button state that can be bitwise-compared against the ButtonMask(X) macro.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetGlobalMouseState; GetRelativeMouseState

◆ GetRelativeMouseMode()

bool SDL::WindowBase::GetRelativeMouseMode ( ) const

inline

Returns: true if relative mode is enabled for a window or false otherwise.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.SetRelativeMouseMode

◆ GetRelativeMouseState()

MouseButtonFlags SDL::GetRelativeMouseState	(	float *	x,
		float *	y
	)

inline

This function returns the cached synchronous state as SDL understands it from the last pump of the event queue.

To query the platform for immediate asynchronous state, use GetGlobalMouseState.

Passing non-nullptr pointers to x or y will write the destination with respective x or y deltas accumulated since the last call to this function (or since event initialization).

This function is useful for reducing overhead by processing relative mouse inputs in one go per-frame instead of individually per-event, at the expense of losing the order between events within the frame (e.g. quickly pressing and releasing a button within the same frame).

Parameters

x	a pointer to receive the x mouse delta accumulated since last call, can be nullptr if unused.
y	a pointer to receive the y mouse delta accumulated since last call, can be nullptr if unused.

Returns: a 32-bit bitmask of the button state that can be bitwise-compared against the ButtonMask(X) macro.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetMouseState; GetGlobalMouseState

◆ HasMouse()

bool SDL::HasMouse ( )

inline

Returns: true if a mouse is connected, false otherwise.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetMice

◆ HideCursor()

void SDL::HideCursor ( )

inline

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: CursorVisible; ShowCursor

◆ SetCursor()

void SDL::SetCursor ( CursorBase & cursor )

inline

This function sets the currently active cursor to the specified one. If the cursor is currently visible, the change will be immediately represented on the display. SetCursor(nullptr) can be used to force cursor redraw, if this is desired for any reason.

Parameters

cursor a cursor to make active.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetCursor

◆ SetRelativeMouseMode()

void SDL::WindowBase::SetRelativeMouseMode ( bool enabled )

inline

While the window has focus and relative mouse mode is enabled, the cursor is hidden, the mouse position is constrained to the window, and SDL will report continuous relative mouse motion even if the mouse is at the edge of the window.

If you'd like to keep the mouse position fixed while in relative mode you can use WindowBase.SetMouseRect(). If you'd like the cursor to be at a specific location when relative mode ends, you should use WindowBase.WarpMouse() before disabling relative mode.

This function will flush any pending mouse motion for this window.

Parameters

enabled true to enable relative mode, false to disable.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.GetRelativeMouseMode

◆ ShowCursor()

void SDL::ShowCursor ( )

inline

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: CursorVisible; HideCursor

◆ WarpMouse() [1/2]

void SDL::WarpMouse	(	float	x,
		float	y
	)

inline

This function generates a mouse motion event.

A failure of this function usually means that it is unsupported by a platform.

Note that this function will appear to succeed, but not actually move the mouse when used over Microsoft Remote Desktop.

Parameters

x	the x coordinate.
y	the y coordinate.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.WarpMouse

◆ WarpMouse() [2/2]

void SDL::WindowBase::WarpMouse	(	float	x,
		float	y
	)

inline

This function generates a mouse motion event if relative mode is not enabled. If relative mode is enabled, you can force mouse events for the warp by setting the SDL_HINT_MOUSE_RELATIVE_WARP_MOTION hint.

Note that this function will appear to succeed, but not actually move the mouse when used over Microsoft Remote Desktop.

          mouse focus.

Parameters

x	the x coordinate within the window.
y	the y coordinate within the window.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WarpMouse

SDL_SYSTEM_CURSOR_NE_RESIZE

May be NESW_RESIZE.

◆ SYSTEM_CURSOR_NESW_RESIZE

constexpr SystemCursor SDL::SYSTEM_CURSOR_NESW_RESIZE

constexpr

Initial value:

=

SDL_SYSTEM_CURSOR_NESW_RESIZE

◆ SYSTEM_CURSOR_NOT_ALLOWED

constexpr SystemCursor SDL::SYSTEM_CURSOR_NOT_ALLOWED

constexpr

Initial value:

=

SDL_SYSTEM_CURSOR_NOT_ALLOWED

Usually a slashed circle or crossbones.

◆ SYSTEM_CURSOR_NS_RESIZE

constexpr SystemCursor SDL::SYSTEM_CURSOR_NS_RESIZE

constexpr

Initial value:

=

SDL_SYSTEM_CURSOR_NS_RESIZE

◆ SYSTEM_CURSOR_NW_RESIZE

constexpr SystemCursor SDL::SYSTEM_CURSOR_NW_RESIZE = SDL_SYSTEM_CURSOR_NW_RESIZE

constexpr

This may be a single arrow or a double arrow like NWSE_RESIZE.

◆ SYSTEM_CURSOR_NWSE_RESIZE

constexpr SystemCursor SDL::SYSTEM_CURSOR_NWSE_RESIZE

constexpr

Initial value:

=

SDL_SYSTEM_CURSOR_NWSE_RESIZE

◆ SYSTEM_CURSOR_POINTER

constexpr SystemCursor SDL::SYSTEM_CURSOR_POINTER = SDL_SYSTEM_CURSOR_POINTER

constexpr

Usually a pointing hand.

◆ SYSTEM_CURSOR_PROGRESS

constexpr SystemCursor SDL::SYSTEM_CURSOR_PROGRESS = SDL_SYSTEM_CURSOR_PROGRESS

constexpr

Usually it's WAIT with an arrow.

constexpr SystemCursor SDL::SYSTEM_CURSOR_TEXT

constexpr

Initial value:

=

SDL_SYSTEM_CURSOR_TEXT

◆ SYSTEM_CURSOR_W_RESIZE

constexpr SystemCursor SDL::SYSTEM_CURSOR_W_RESIZE

constexpr

Initial value:

=

SDL_SYSTEM_CURSOR_W_RESIZE

◆ SYSTEM_CURSOR_WAIT

constexpr SystemCursor SDL::SYSTEM_CURSOR_WAIT = SDL_SYSTEM_CURSOR_WAIT

constexpr

Usually an hourglass or watch or spinning ball.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ MouseButtonFlags

◆ MouseID

◆ MouseWheelDirection

◆ SystemCursor

Function Documentation

◆ ButtonMask()

◆ CaptureMouse()

◆ CursorVisible()

◆ GetCursor()

◆ GetDefaultCursor()

◆ GetGlobalMouseState()

◆ GetMice()

◆ GetMouseFocus()

◆ GetMouseNameForID()

◆ GetMouseState()

◆ GetRelativeMouseMode()

◆ GetRelativeMouseState()

◆ HasMouse()

◆ HideCursor()

◆ SetCursor()

◆ SetRelativeMouseMode()

◆ ShowCursor()

◆ WarpMouse() [1/2]

◆ WarpMouse() [2/2]

Variable Documentation

◆ BUTTON_LMASK

◆ BUTTON_MMASK

◆ BUTTON_RMASK

◆ BUTTON_X1MASK

◆ BUTTON_X2MASK

◆ MOUSEWHEEL_FLIPPED

◆ MOUSEWHEEL_NORMAL

◆ SYSTEM_CURSOR_CROSSHAIR

◆ SYSTEM_CURSOR_DEFAULT

◆ SYSTEM_CURSOR_E_RESIZE

◆ SYSTEM_CURSOR_EW_RESIZE

◆ SYSTEM_CURSOR_N_RESIZE

◆ SYSTEM_CURSOR_NE_RESIZE

◆ SYSTEM_CURSOR_NESW_RESIZE

◆ SYSTEM_CURSOR_NOT_ALLOWED

◆ SYSTEM_CURSOR_NS_RESIZE

◆ SYSTEM_CURSOR_NW_RESIZE

◆ SYSTEM_CURSOR_NWSE_RESIZE

◆ SYSTEM_CURSOR_POINTER

◆ SYSTEM_CURSOR_PROGRESS

◆ SYSTEM_CURSOR_S_RESIZE

◆ SYSTEM_CURSOR_SE_RESIZE

◆ SYSTEM_CURSOR_SW_RESIZE

◆ SYSTEM_CURSOR_TEXT

◆ SYSTEM_CURSOR_W_RESIZE

◆ SYSTEM_CURSOR_WAIT