struct Espresso::Joystick

Overview

Exposes connected joysticks and controllers, with both referred to as joysticks. GLFW supports up to sixteen joysticks. You can test whether a joystick is present/connected with #connected?. To access joysticks, use one of: #all, #each, #connected, or #each_connected.

Each joystick has zero or more axes, zero or more buttons, zero or more hats, a human-readable name, a user pointer and an SDL compatible GUID.

When GLFW is initialized, detected joysticks are added to the beginning of the array. Once a joystick is detected, it keeps its assigned ID until it is disconnected or the library is terminated, so as joysticks are connected and disconnected, there may appear gaps in the IDs.

Joystick axis, button, and hat state is updated when polled and does not require a window to be created or events to be processed. However, if you want joystick connection and disconnection events reliably delivered to the joystick #on_connect and #on_disconnect events, then you must process events.

Included Modules

Extended Modules

Defined in:

espresso/input/joystick.cr
espresso/input/joystick/events.cr

Class Method Summary

Instance Method Summary

Class Method Detail

def self.all : Enumerable(Joystick) #

Returns all possible joysticks, connected and disconnected. GLFW supports a maximum of 16 joysticks, so the collection returned by this method always has 16 elements.


[View source]
def self.connected : Enumerable(Joystick) #

Returns a list of all connected joysticks.


[View source]
def self.each(&) #

Iterates through all possible joysticks, connected and disconnected. The joystick is yielded to the block.


[View source]
def self.each_connected(&) #

Iterates through all connected joysticks. The joystick is yielded to the block.


[View source]
def self.on_connect(&block : JoystickConnectEvent -> ) #

Registers a listener to respond when a joystick is connected or disconnected. The block of code passed to this method will be invoked when a joystick (dis)connects. The joystick instance will be provided via the event passed as an argument to the block. To remove the listener, call #remove_connect_listener with the proc returned by this method.


[View source]
def self.remove_connect_listener(listener : JoystickConnectEvent -> ) : Nil #

Removes a previously registered listener that responded when a joystick is connected or disconnected. The proc argument should be the return value of the #on_connect method.


[View source]
def self.update_gamepad_mappings(string) : Nil #

Parses the specified ASCII encoded string and updates the internal list with any gamepad mappings it finds. This string may contain either a single gamepad mapping or many mappings separated by newlines. The parser supports the full format of the gamecontrollerdb.txt source file including empty lines and comments.

See Gamepad mappings for a description of the format.

If there is already a gamepad mapping for a given GUID in the internal list, it will be replaced by the one passed to this function. If the library is terminated and re-initialized the internal list will revert to the built-in default.


[View source]

Instance Method Detail

def axes : Indexable(Float) #

Retrieves the values of all axes of this joystick. Each element in the array is a value between -1.0 and 1.0.

If this joystick is not present (#connected?), this method will raise an error.

The returned Slice is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected or the library is terminated.


[View source]
def axes? : Indexable(Float) | Nil #

Retrieves the values of all axes of this joystick. Each element in the array is a value between -1.0 and 1.0.

If this joystick is not present (#connected?), this method will return nil, but will not raise an error. This can be used instead of first calling #connected?.

The returned Slice is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected or the library is terminated.


[View source]
def buttons : Indexable(ButtonState) #

Retrieves the state of all buttons of this joystick. Each element in the array is either ButtonState::Pressed or ButtonState::Released.

For backward compatibility with earlier versions of GLFW that did not have #hats?, the button array also includes all hats, each represented as four buttons. The hats are in the same order as returned by #hats? and are in the order up, right, down and left. To disable these extra buttons, set the joystick_hat_buttons hint before initialization (see Espresso#init).

If this joystick is not present (#connected?), this method will raise an error.

The returned Slice is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected or the library is terminated.


[View source]
def buttons? : Indexable(ButtonState) | Nil #

Retrieves the state of all buttons of this joystick. Each element in the array is either ButtonState::Pressed or ButtonState::Released.

For backward compatibility with earlier versions of GLFW that did not have #hats?, the button array also includes all hats, each represented as four buttons. The hats are in the same order as returned by #hats? and are in the order up, right, down and left. To disable these extra buttons, set the joystick_hat_buttons hint before initialization (see Espresso#init).

If this joystick is not present (#connected?), this method will return nil, but will not raise an error. This can be used instead of first calling #connected?.

The returned Slice is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected or the library is terminated.


[View source]
def connected? #

Checks if the joystick is currently connected (present).

There is no need to call this method before other methods in this type, as they all check for presence before performing any other work.


[View source]
def gamepad? #

Checks whether this joystick is both present and has a gamepad mapping.

If the specified joystick is present (#connected?) but does not have a gamepad mapping this method will return false but will not raise an error. Call #connected? to check if a joystick is present regardless of whether it has a mapping.


[View source]
def guid : String #

Retrieves the SDL compatible GUID, as a UTF-8 encoded hexadecimal string, of this joystick.

The GUID is what connects a joystick to a gamepad mapping. A connected joystick will always have a GUID even if there is no gamepad mapping assigned to it.

If this joystick is not present (#connected?), this method will raise an error.

The GUID uses the format introduced in SDL 2.0.5. This GUID tries to uniquely identify the make and model of a joystick but does not identify a specific unit, e.g. all wired Xbox 360 controllers will have the same GUID on that platform. The GUID for a unit may vary between platforms depending on what hardware information the platform specific APIs provide.


[View source]
def guid? : String | Nil #

Retrieves the SDL compatible GUID, as a UTF-8 encoded hexadecimal string, of this joystick.

The GUID is what connects a joystick to a gamepad mapping. A connected joystick will always have a GUID even if there is no gamepad mapping assigned to it.

If this joystick is not present (#connected?), this method will return nil, but will not raise an error. This can be used instead of first calling #connected?.

The GUID uses the format introduced in SDL 2.0.5. This GUID tries to uniquely identify the make and model of a joystick but does not identify a specific unit, e.g. all wired Xbox 360 controllers will have the same GUID on that platform. The GUID for a unit may vary between platforms depending on what hardware information the platform specific APIs provide.


[View source]
def hats : Indexable(JoystickHatState) #

Retrieves the state of all hats of this joystick. Each element in the array is a JoystickHatState.

The diagonal directions are bitwise combinations of the primary (up, right, down and left) directions.

If this joystick is not present (#connected?), this method will raise an error.

The returned Slice is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected or the library is terminated.


[View source]
def hats? : Indexable(JoystickHatState) | Nil #

Retrieves the state of all hats of this joystick. Each element in the array is a JoystickHatState.

The diagonal directions are bitwise combinations of the primary (up, right, down and left) directions.

If this joystick is not present (#connected?), this method will return nil, but will not raise an error. This can be used instead of first calling #connected?.

The returned Slice is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected or the library is terminated.


[View source]
def name : String #

Retrieves the name, encoded as UTF-8, of this joystick.

If this joystick is not present (#connected?), this method will raise an error.


[View source]
def name? : String | Nil #

Retrieves the name, encoded as UTF-8, of this joystick.

If this joystick is not present (#connected?), this method will return nil, but will not raise an error. This can be used instead of first calling #connected?.


[View source]
def on_disconnect(&block : JoystickConnectEvent -> ) #

Registers a listener to respond when this joystick is disconnected. The block of code passed to this method will be invoked when a joystick disconnects. This joystick instance will be provided via the event passed as an argument to the block. To remove the listener, call #remove_disconnect_listener with the proc returned by this method.


[View source]
def remove_disconnect_listener(listener : JoystickConnectEvent -> ) : Nil #

Removes a previously registered listener that responded when this joystick is disconnected. The proc argument should be the return value of the #on_disconnect method.


[View source]
def state : GamepadState #

Retrieves the state of the specified joystick remapped to an Xbox-like gamepad.

If the specified joystick is not present or does not have a gamepad mapping an error will be raised. Call #connected? to check whether it is present regardless of whether it has a mapping.

See also: #gamepad?


[View source]
def state? : GamepadState | Nil #

Retrieves the state of the specified joystick remapped to an Xbox-like gamepad.

If the specified joystick is not present or does not have a gamepad mapping this method will return nil, but will not raise an error. Call #connected? to check whether it is present regardless of whether it has a mapping.

See also: #gamepad?


[View source]
def to_s(io) #

String representation of the joystick.


[View source]
def to_unsafe : LibGLFW::Joystick #

Returns the underlying joystick ID.


[View source]
def user_pointer : Pointer #

Retrieves the current value of the user-defined pointer of this joystick. The initial value is nil.

This function may be called from the #on_disconnect callback.


[View source]
def user_pointer=(pointer) #

Sets the user-defined pointer of this joystick. The current value is retained until the joystick is disconnected. The initial value is nil.

This function may be called from the #on_disconnect callback.


[View source]