Module mouse

Available on crate feature dep_sdl3 only.

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

Most interactions with the mouse will come through the event subsystem. Moving a mouse generates an [SDL_EVENT_MOUSE_MOTION] event, pushing a button generates [SDL_EVENT_MOUSE_BUTTON_DOWN], etc, but one can also query the current state of the mouse at any time with SDL_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 SDL_SetWindowRelativeMouseMode(), 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 SDL_HideCursor() and SDL_ShowCursor(). It might be more efficient to let the system manage the cursor, if possible, using SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), or perhaps just a specific system cursor from SDL_CreateSystemCursor().

SDL can, on many platforms, differentiate between multiple connected mice, allowing for interesting input scenarios and multiplayer games. They can be enumerated with SDL_GetMice(), and SDL will send [SDL_EVENT_MOUSE_ADDED] and [SDL_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.

Structs

SDL_Cursor

The structure used to identify an SDL cursor.

SDL_MouseWheelDirection

Scroll direction types for the Scroll event

SDL_SystemCursor

Cursor types for SDL_CreateSystemCursor().

Constants

SDL_BUTTON_LEFT

SDL_BUTTON_LMASK

SDL_BUTTON_MIDDLE

SDL_BUTTON_MMASK

SDL_BUTTON_RIGHT

SDL_BUTTON_RMASK

SDL_BUTTON_X1

SDL_BUTTON_X2

SDL_BUTTON_X1MASK

SDL_BUTTON_X2MASK

SDL_MOUSEWHEEL_FLIPPED

The scroll direction is flipped / natural

SDL_MOUSEWHEEL_NORMAL

The scroll direction is normal

SDL_SYSTEM_CURSOR_COUNT

SDL_SYSTEM_CURSOR_CROSSHAIR

Crosshair.

SDL_SYSTEM_CURSOR_DEFAULT

Default cursor. Usually an arrow.

SDL_SYSTEM_CURSOR_EW_RESIZE

Double arrow pointing west and east.

SDL_SYSTEM_CURSOR_E_RESIZE

Window resize right. May be EW_RESIZE.

SDL_SYSTEM_CURSOR_MOVE

Four pointed arrow pointing north, south, east, and west.

SDL_SYSTEM_CURSOR_NESW_RESIZE

Double arrow pointing northeast and southwest.

SDL_SYSTEM_CURSOR_NE_RESIZE

Window resize top-right. May be NESW_RESIZE.

SDL_SYSTEM_CURSOR_NOT_ALLOWED

Not permitted. Usually a slashed circle or crossbones.

SDL_SYSTEM_CURSOR_NS_RESIZE

Double arrow pointing north and south.

SDL_SYSTEM_CURSOR_NWSE_RESIZE

Double arrow pointing northwest and southeast.

SDL_SYSTEM_CURSOR_NW_RESIZE

Window resize top-left. This may be a single arrow or a double arrow like NWSE_RESIZE.

SDL_SYSTEM_CURSOR_N_RESIZE

Window resize top. May be NS_RESIZE.

SDL_SYSTEM_CURSOR_POINTER

Pointer that indicates a link. Usually a pointing hand.

SDL_SYSTEM_CURSOR_PROGRESS

Program is busy but still interactive. Usually it’s WAIT with an arrow.

SDL_SYSTEM_CURSOR_SE_RESIZE

Window resize bottom-right. May be NWSE_RESIZE.

SDL_SYSTEM_CURSOR_SW_RESIZE

Window resize bottom-left. May be NESW_RESIZE.

SDL_SYSTEM_CURSOR_S_RESIZE

Window resize bottom. May be NS_RESIZE.

SDL_SYSTEM_CURSOR_TEXT

Text selection. Usually an I-beam.

SDL_SYSTEM_CURSOR_WAIT

Wait. Usually an hourglass or watch or spinning ball.

SDL_SYSTEM_CURSOR_W_RESIZE

Window resize left. May be EW_RESIZE.

Functions

SDL_BUTTON_MASK

SDL_CaptureMouse^⚠

Capture the mouse and to track input outside an SDL window.

SDL_CreateColorCursor^⚠

Create a color cursor.

SDL_CreateCursor^⚠

Create a cursor using the specified bitmap data and mask (in MSB format).

SDL_CreateSystemCursor^⚠

Create a system cursor.

SDL_CursorVisible^⚠

Return whether the cursor is currently being shown.

SDL_DestroyCursor^⚠

Free a previously-created cursor.

SDL_GetCursor^⚠

Get the active cursor.

SDL_GetDefaultCursor^⚠

Get the default cursor.

SDL_GetGlobalMouseState^⚠

Query the platform for the asynchronous mouse button state and the desktop-relative platform-cursor position.

SDL_GetMice^⚠

Get a list of currently connected mice.

SDL_GetMouseFocus^⚠

Get the window which currently has mouse focus.

SDL_GetMouseNameForID^⚠

Get the name of a mouse.

SDL_GetMouseState^⚠

Query SDL’s cache for the synchronous mouse button state and the window-relative SDL-cursor position.

SDL_GetRelativeMouseState^⚠

Query SDL’s cache for the synchronous mouse button state and accumulated mouse delta since last call.

SDL_GetWindowRelativeMouseMode^⚠

Query whether relative mouse mode is enabled for a window.

SDL_HasMouse^⚠

Return whether a mouse is currently connected.

SDL_HideCursor^⚠

Hide the cursor.

SDL_SetCursor^⚠

Set the active cursor.

SDL_SetWindowRelativeMouseMode^⚠

Set relative mouse mode for a window.

SDL_ShowCursor^⚠

Show the cursor.

SDL_WarpMouseGlobal^⚠

Move the mouse to the given position in global screen space.

SDL_WarpMouseInWindow^⚠

Move the mouse cursor to the given position within the window.

Type Aliases

SDL_MouseButtonFlags

A bitmask of pressed mouse buttons, as reported by SDL_GetMouseState, etc.

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.