mouse topic

CategoryMouse

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.

Functions

sdlCaptureMouse(bool enabled) → bool mouse
Capture the mouse and to track input outside an SDL window.
sdlCreateColorCursor(Pointer<SdlSurface> surface, int hotX, int hotY) → Pointer<SdlCursor> mouse
Create a color cursor.
sdlCreateCursor(Pointer<Uint8> data, Pointer<Uint8> mask, int w, int h, int hotX, int hotY) → Pointer<SdlCursor> mouse
Create a cursor using the specified bitmap data and mask (in MSB format).
sdlCreateSystemCursor(int id) → Pointer<SdlCursor> mouse
Create a system cursor.
sdlCursorVisible() → bool mouse
Return whether the cursor is currently being shown.
sdlDestroyCursor(Pointer<SdlCursor> cursor) → void mouse
Free a previously-created cursor.
sdlGetCursor() → Pointer<SdlCursor> mouse
Get the active cursor.
sdlGetDefaultCursor() → Pointer<SdlCursor> mouse
Get the default cursor.
sdlGetGlobalMouseState(Pointer<Float> x, Pointer<Float> y) → int mouse
Query the platform for the asynchronous mouse button state and the desktop-relative platform-cursor position.
sdlGetMice(Pointer<Int32> count) → Pointer<Uint32> mouse
Get a list of currently connected mice.
sdlGetMouseFocus() → Pointer<SdlWindow> mouse
Get the window which currently has mouse focus.
sdlGetMouseNameForId(int instanceId) → String? mouse
Get the name of a mouse.
sdlGetMouseState(Pointer<Float> x, Pointer<Float> y) → int mouse
Query SDL's cache for the synchronous mouse button state and the window-relative SDL-cursor position.
sdlGetRelativeMouseState(Pointer<Float> x, Pointer<Float> y) → int mouse
Query SDL's cache for the synchronous mouse button state and accumulated mouse delta since last call.
sdlGetWindowRelativeMouseMode(Pointer<SdlWindow> window) → bool mouse
Query whether relative mouse mode is enabled for a window.
sdlHasMouse() → bool mouse
Return whether a mouse is currently connected.
sdlHideCursor() → bool mouse
Hide the cursor.
sdlSetCursor(Pointer<SdlCursor> cursor) → bool mouse
Set the active cursor.
sdlSetRelativeMouseTransform(Pointer<NativeFunction<SdlMouseMotionTransformCallback>> callback, Pointer<NativeType> userdata) → bool mouse
Set a user-defined function by which to transform relative mouse inputs.
sdlSetWindowRelativeMouseMode(Pointer<SdlWindow> window, bool enabled) → bool mouse
Set relative mouse mode for a window.
sdlShowCursor() → bool mouse
Show the cursor.
sdlWarpMouseGlobal(double x, double y) → bool mouse
Move the mouse to the given position in global screen space.
sdlWarpMouseInWindow(Pointer<SdlWindow> window, double x, double y) → void mouse
Move the mouse cursor to the given position within the window.