18 Joysticks

9.0.0.11

Racket

18 Joysticks🔗ℹ

This section covers low-level joystick access. For a higher-level API with standardized button names, see Gamepads.

18.1 Detection🔗ℹ

procedure
(has-joystick?) → boolean?

Returns #t if any joysticks are connected.

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

Returns a list of connected joystick instance IDs.

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

Returns the number of connected joysticks.

18.2 Opening and Closing🔗ℹ

procedure
(open-joystick instance-id) → joystick?
instance-id : exact-nonnegative-integer?

Opens a joystick by its instance ID.

The joystick is registered with the current custodian for automatic cleanup.

procedure
(joystick? v) → boolean?
v : any/c

Returns #t if v is a joystick.

procedure
(joystick-connected? joy) → boolean?
joy : joystick?

Returns #t if the joystick is still connected.

procedure
(joystick-destroy! joy) → void?
joy : joystick?

Closes a joystick.

Note: Joysticks are automatically closed when their custodian shuts down.

18.3 Joystick Information🔗ℹ

procedure
(joystick-name joy) → (or/c string? #f)
joy : joystick?

Returns the joystick name.

procedure
(joystick-path joy) → (or/c string? #f)
joy : joystick?

Returns the device path.

procedure
(joystick-id joy) → exact-nonnegative-integer?
joy : joystick?

Returns the instance ID.

procedure
(joystick-type joy) → symbol?
joy : joystick?

Returns the joystick type.

Values: 'unknown, 'gamepad, 'wheel, 'arcade-stick, 'flight-stick, 'dance-pad, 'guitar, 'drum-kit, 'arcade-pad, 'throttle.

procedure
(joystick-vendor joy) → exact-nonnegative-integer?
joy : joystick?

Returns the USB vendor ID.

procedure
(joystick-product joy) → exact-nonnegative-integer?
joy : joystick?

Returns the USB product ID.

procedure
(joystick-serial joy) → (or/c string? #f)
joy : joystick?

Returns the serial number.

18.3.1 Info by ID (before opening)🔗ℹ

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

Returns the name of a joystick before opening it.

procedure
(get-joystick-type-for-id instance-id) → symbol?
instance-id : exact-nonnegative-integer?

Returns the type of a joystick before opening it.

18.4 Capabilities🔗ℹ

procedure
(joystick-num-axes joy) → exact-nonnegative-integer?
joy : joystick?

Returns the number of axes.

procedure
(joystick-num-buttons joy) → exact-nonnegative-integer?
joy : joystick?

Returns the number of buttons.

procedure
(joystick-num-hats joy) → exact-nonnegative-integer?
joy : joystick?

Returns the number of hat switches (D-pads).

procedure
(joystick-num-balls joy) → exact-nonnegative-integer?
joy : joystick?

Returns the number of trackballs.

18.5 Reading State🔗ℹ

procedure
(joystick-axis joy axis-index) → exact-integer?
joy : joystick?
axis-index : exact-nonnegative-integer?

Returns the current value of an axis (-32768 to 32767).

procedure
(joystick-button joy button-index) → boolean?
joy : joystick?
button-index : exact-nonnegative-integer?

Returns #t if the button is pressed.

procedure
(joystick-hat joy hat-index) → symbol?
joy : joystick?
hat-index : exact-nonnegative-integer?

Returns the current hat position as a symbol.

Values: 'centered, 'up, 'down, 'left, 'right, 'up-right, 'up-left, 'down-right, 'down-left.

procedure
(joystick-ball joy ball-index) →
exact-integer? exact-integer?
joy : joystick?
ball-index : exact-nonnegative-integer?

Returns the trackball delta since the last call.

Returns (values dx dy).

18.6 Hat Value Conversion🔗ℹ

procedure
(hat-value->symbol v) → symbol?
v : exact-nonnegative-integer?

Converts an SDL hat value to a direction symbol.

procedure
(hat-value->list v) → (listof symbol?)
v : exact-nonnegative-integer?

Converts an SDL hat value to a list of active directions.

For compound directions (like up-right), returns '(up right).

18.7 Player Index🔗ℹ

procedure
(joystick-player-index joy) → exact-integer?
joy : joystick?

Returns the player index (-1 if not set).

procedure
(set-joystick-player-index! joy index) → void?
joy : joystick?
index : exact-integer?

Sets the player index.

18.8 Rumble🔗ℹ

procedure
(joystick-rumble! joy low high [duration-ms]) → boolean?
  joy : joystick?
  low : exact-nonnegative-integer?
  high : exact-nonnegative-integer?
  duration-ms : exact-nonnegative-integer? = 0

Starts a rumble effect.

low and high are motor intensities (0-65535). duration-ms is the duration in milliseconds (0 = infinite).

procedure
(joystick-rumble-triggers! joy
left
right
[ duration-ms]) → boolean?
  joy : joystick?
  left : exact-nonnegative-integer?
  right : exact-nonnegative-integer?
  duration-ms : exact-nonnegative-integer? = 0

Starts a trigger rumble effect (Xbox-style controllers).

18.9 LED🔗ℹ

procedure
(joystick-set-led! joy r g b) → boolean?
  joy : joystick?
  r : byte?
  g : byte?
  b : byte?

Sets the LED color (if supported).

18.10 Power🔗ℹ

procedure
(joystick-power-info joy) →
symbol? exact-integer?
joy : joystick?

Returns the power state and battery percentage.

Power states: 'unknown, 'on-battery, 'no-battery, 'charging, 'charged, 'error.

Percentage is 0-100, or -1 if unknown.

procedure
(joystick-connection-state joy) → symbol?
joy : joystick?

Returns the connection type.

Values: 'unknown, 'wired, 'wireless, 'invalid.

18.11 Type Conversion🔗ℹ

procedure
(joystick-type->symbol type) → symbol?
type : exact-nonnegative-integer?

Converts an SDL joystick type to a symbol.

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

18.1	Detection
18.2	Opening and Closing
18.3	Joystick Information
18.4	Capabilities
18.5	Reading State
18.6	Hat Value Conversion
18.7	Player Index
18.8	Rumble
18.9	LED
18.10	Power
18.11	Type Conversion