16 Mouse Functions

9.0.0.11

Racket

16 Mouse Functions🔗ℹ

This section covers mouse input handling, including mouse state polling, cursor control, and relative mouse mode for FPS-style input.

16.1 Mouse State🔗ℹ

procedure
(get-mouse-state) →
real? real? exact-nonnegative-integer?

Returns the current mouse position and button state within the focused window.

Returns three values:

x — The x coordinate relative to the window
y — The y coordinate relative to the window
buttons — A bitmask of pressed buttons

Use mouse-button-pressed? to check individual buttons:

(define-values (x y buttons) (get-mouse-state))
(when (mouse-button-pressed? buttons SDL_BUTTON_LMASK)
(printf "Left button pressed at (~a, ~a)~n" x y))

procedure
(get-global-mouse-state)
→
real? real? exact-nonnegative-integer?

Returns the mouse position in global screen coordinates and button state.

Returns three values:

x — The x coordinate in screen space
y — The y coordinate in screen space
buttons — A bitmask of pressed buttons

procedure
(get-relative-mouse-state)
→
real? real? exact-nonnegative-integer?

Returns the relative mouse motion since the last call and button state.

Returns three values:

dx — Relative motion in x direction
dy — Relative motion in y direction
buttons — A bitmask of pressed buttons

Useful for implementing mouse look in games.

procedure
(mouse-button-pressed? mask button) → boolean?
mask : exact-nonnegative-integer?
button : exact-nonnegative-integer?

Returns #t if the specified button is pressed in the button mask.

Button masks include:

SDL_BUTTON_LMASK — Left mouse button
SDL_BUTTON_MMASK — Middle mouse button
SDL_BUTTON_RMASK — Right mouse button
SDL_BUTTON_X1MASK — Extra button 1
SDL_BUTTON_X2MASK — Extra button 2

(define-values (x y buttons) (get-mouse-state))
(when (mouse-button-pressed? buttons SDL_BUTTON_LMASK)
(handle-left-click x y))
(when (mouse-button-pressed? buttons SDL_BUTTON_RMASK)
(handle-right-click x y))

16.2 Mouse Enumeration🔗ℹ

procedure
(has-mouse?) → boolean?

Returns #t if a mouse is available.

procedure
(get-mice) → (listof exact-nonnegative-integer?)

Returns a list of mouse device instance IDs.

procedure
(get-mouse-count) → exact-nonnegative-integer?

Returns the number of connected mice.

procedure
(get-mouse-name-for-id id) → (or/c string? #f)
id : exact-nonnegative-integer?

Returns the name of the mouse with the given instance ID, or #f if not found.

procedure
(get-mouse-focus) → (or/c cpointer? #f)

Returns the window that currently has mouse focus, or #f if none.

16.3 Mouse Warping🔗ℹ

procedure
(warp-mouse! win x y) → void?
  win : (or/c window? #f)
  x : real?
  y : real?

Moves the mouse cursor to a position within a window.

If win is #f, uses the currently focused window.

;; Move cursor to center of window
(warp-mouse! win 400 300)

procedure
(warp-mouse-global! x y) → void?
x : real?
y : real?

Moves the mouse cursor to a position in global screen coordinates.

Note: This may not be supported on all platforms.

16.4 Mouse Capture🔗ℹ

procedure
(capture-mouse! enabled?) → void?
enabled? : boolean?

Enables or disables mouse capture.

When enabled, the window receives mouse events even when the cursor is outside the window. This is useful for drag operations where you want to track the mouse even if it leaves the window.

;; Start a drag operation
(capture-mouse! #t)

;; ... handle drag ...

;; End the drag
(capture-mouse! #f)

16.5 Relative Mouse Mode🔗ℹ

Relative mouse mode is used for FPS-style input where the cursor is hidden and mouse motion reports relative deltas rather than absolute positions.

procedure
(set-relative-mouse-mode! win on?) → void?
win : window?
on? : boolean?

Enables or disables relative mouse mode for a window.

When enabled:

The cursor is hidden
Mouse motion reports relative deltas instead of absolute positions
The cursor is confined to the window

;; Enable FPS-style mouse look
(set-relative-mouse-mode! win #t)

;; Handle mouse motion events for camera control
;; motion-event-xrel and motion-event-yrel give deltas

procedure
(relative-mouse-mode? win) → boolean?
win : window?

Returns #t if relative mouse mode is enabled for the window.

16.6 Cursor Visibility🔗ℹ

procedure
(show-cursor!) → void?

Shows the mouse cursor.

procedure
(hide-cursor!) → void?

Hides the mouse cursor.

procedure
(cursor-visible?) → boolean?

Returns #t if the cursor is currently visible.

16.7 System Cursors🔗ℹ

SDL provides standard system cursors that you can use instead of the default arrow cursor.

procedure
(create-system-cursor cursor-type) → cpointer?
cursor-type : (or/c symbol? exact-nonnegative-integer?)

Creates a system cursor of the specified type.

Cursor type symbols include:

'default or 'arrow — Standard arrow cursor
'text or 'ibeam — Text editing cursor
'wait or 'hourglass — Wait/busy cursor
'crosshair — Crosshair cursor
'progress — Progress indicator
'pointer or 'hand — Pointing hand (for links)
'move — Move/drag cursor
'not-allowed or 'no — Not allowed cursor
'ew-resize — Horizontal resize
'ns-resize — Vertical resize
'nwse-resize — Diagonal resize (NW-SE)
'nesw-resize — Diagonal resize (NE-SW)
'n-resize, 'e-resize, etc. — Edge resize cursors

The returned cursor must be freed with destroy-cursor! when no longer needed.

procedure
(set-cursor! cursor) → void?
cursor : (or/c cpointer? #f)

Sets the active cursor. Pass #f to reset to the default cursor.

procedure
(destroy-cursor! cursor) → void?
cursor : cpointer?

Destroys a cursor created with create-system-cursor.

syntax
(with-system-cursor cursor-type body ...)

Temporarily uses a system cursor, then restores the previous cursor.

;; Show crosshair while aiming
(with-system-cursor 'crosshair
  (handle-aiming))

;; Show pointer when hovering over a button
(when (mouse-over-button? x y)
  (with-system-cursor 'pointer
    (draw-button-hover)))

16.8 Cursor Type Conversion🔗ℹ

procedure
(symbol->system-cursor sym) → exact-nonnegative-integer?
sym : symbol?

Converts a cursor type symbol to its SDL constant. Raises an error if the symbol is not recognized.

procedure
(system-cursor->symbol id) → symbol?
id : exact-nonnegative-integer?

Converts an SDL system cursor constant to a symbol. Returns 'unknown if not recognized.

16.9 Mouse Button Constants🔗ℹ

These constants identify individual mouse buttons:

value
SDL_BUTTON_LEFT : exact-nonnegative-integer?

Left mouse button (1).

value
SDL_BUTTON_MIDDLE : exact-nonnegative-integer?

Middle mouse button (2).

value
SDL_BUTTON_RIGHT : exact-nonnegative-integer?

Right mouse button (3).

value
SDL_BUTTON_X1 : exact-nonnegative-integer?

Extra button 1 (4).

value
SDL_BUTTON_X2 : exact-nonnegative-integer?

Extra button 2 (5).

These constants are bitmasks for checking button state:

value
SDL_BUTTON_LMASK : exact-nonnegative-integer?

Left button mask.

value
SDL_BUTTON_MMASK : exact-nonnegative-integer?

Middle button mask.

value
SDL_BUTTON_RMASK : exact-nonnegative-integer?

Right button mask.

value
SDL_BUTTON_X1MASK : exact-nonnegative-integer?

Extra button 1 mask.

value
SDL_BUTTON_X2MASK : exact-nonnegative-integer?

Extra button 2 mask.

1	Overview
2	Quick Start
3	Resource Management
4	Initialization
5	Windows and Renderers
6	Timer Functions
7	Configuration Hints
8	Properties
9	Drawing
10	Textures
11	Images and Surfaces
12	True Type Fonts
13	Rectangle Collision Detection
14	Events
15	Keyboard Functions
16	Mouse Functions
17	Gamepads
18	Joysticks
19	Audio
20	Camera
21	Display Information
22	Clipboard
23	Dialogs
24	System Tray
25	Open GL
26	Vulkan
27	GPU API

16.1	Mouse State
16.2	Mouse Enumeration
16.3	Mouse Warping
16.4	Mouse Capture
16.5	Relative Mouse Mode
16.6	Cursor Visibility
16.7	System Cursors
16.8	Cursor Type Conversion
16.9	Mouse Button Constants