Joystick Class

Inheritance diagram of Joystick

class Joystick(device)

High-level interface for joystick-like devices. This includes analogue and digital joysticks, gamepads, game controllers, and possibly even steering wheels and other input devices. There is unfortunately no way to distinguish between these different device types.

To use a joystick, first call open, then in your game loop examine the values of x, y, and so on. These values are normalized to the range [-1.0, 1.0].

To receive events when the value of an axis changes, attach an on_joyaxis_motion event handler to the joystick. The Joystick instance, axis name, and current value are passed as parameters to this event.

To handle button events, you should attach on_joybutton_press and on_joy_button_release event handlers to the joystick. Both the Joystick instance and the index of the changed button are passed as parameters to these events.

Alternately, you may attach event handlers to each individual button in button_controls to receive on_press or on_release events.

To use the hat switch, attach an on_joyhat_motion event handler to the joystick. The handler will be called with both the hat_x and hat_y values whenever the value of the hat switch changes.

The device name can be queried to get the name of the joystick.

Variables:
  • device – The underlying device used by this joystick interface.
  • x – Current X (horizontal) value ranging from -1.0 (left) to 1.0 (right).
  • y – Current y (vertical) value ranging from -1.0 (top) to 1.0 (bottom).
  • z – Current Z value ranging from -1.0 to 1.0. On joysticks the Z value is usually the throttle control. On game controllers the Z value is usually the secondary thumb vertical axis.
  • rx – Current rotational X value ranging from -1.0 to 1.0.
  • ry – Current rotational Y value ranging from -1.0 to 1.0.
  • rz – Current rotational Z value ranging from -1.0 to 1.0. On joysticks the RZ value is usually the twist of the stick. On game controllers the RZ value is usually the secondary thumb horizontal axis.
  • hat_x – Current hat (POV) horizontal position; one of -1 (left), 0 (centered) or 1 (right).
  • hat_y – Current hat (POV) vertical position; one of -1 (bottom), 0 (centered) or 1 (top).
  • buttons – List of boolean values representing current states of the buttons. These are in order, so that button 1 has value at buttons[0], and so on.
  • x_control – Underlying control for x value, or None if not available.
  • y_control – Underlying control for y value, or None if not available.
  • z_control – Underlying control for z value, or None if not available.
  • rx_control – Underlying control for rx value, or None if not available.
  • ry_control – Underlying control for ry value, or None if not available.
  • rz_control – Underlying control for rz value, or None if not available.
  • hat_x_control – Underlying control for hat_x value, or None if not available.
  • hat_y_control – Underlying control for hat_y value, or None if not available.
  • button_controls – Underlying controls for buttons values.

Constructor:

__init__(device)

Methods:

close() Close the joystick device.
dispatch_event(event_type, *args) Dispatch a single event to the attached handlers.
event(*args) Function decorator for an event handler.
open([window, exclusive]) Open the joystick device.
pop_handlers() Pop the top level of event handlers off the stack.
push_handlers(*args, **kwargs) Push a level onto the top of the handler stack, then attach zero or more event handlers.
register_event_type(name) Register an event type with the dispatcher.
remove_handler(name, handler) Remove a single event handler.
remove_handlers(*args, **kwargs) Remove event handlers from the event stack.
set_handler(name, handler) Attach a single event handler.
set_handlers(*args, **kwargs) Attach one or more event handlers to the top level of the handler stack.

Events:

on_joyaxis_motion(joystick, axis, value) The value of a joystick axis changed.
on_joybutton_press(joystick, button) A button on the joystick was pressed.
on_joybutton_release(joystick, button) A button on the joystick was released.
on_joyhat_motion(joystick, hat_x, hat_y) The value of the joystick hat switch changed.

Attributes:

event_types Type: list

Methods

Joystick.close()

Close the joystick device. See Device.close.

Joystick.open(window=None, exclusive=False)

Open the joystick device. See Device.open.

Events

Joystick.on_joyaxis_motion(joystick, axis, value)

The value of a joystick axis changed.

Parameters:
  • joystick (Joystick) – The joystick device whose axis changed.
  • axis (string) – The name of the axis that changed.
  • value (float) – The current value of the axis, normalized to [-1, 1].
Joystick.on_joybutton_press(joystick, button)

A button on the joystick was pressed.

Parameters:
  • joystick (Joystick) – The joystick device whose button was pressed.
  • button (int) – The index (in button_controls) of the button that was pressed.
Joystick.on_joybutton_release(joystick, button)

A button on the joystick was released.

Parameters:
  • joystick (Joystick) – The joystick device whose button was released.
  • button (int) – The index (in button_controls) of the button that was released.
Joystick.on_joyhat_motion(joystick, hat_x, hat_y)

The value of the joystick hat switch changed.

Parameters:
  • joystick (Joystick) – The joystick device whose hat control changed.
  • hat_x (int) – Current hat (POV) horizontal position; one of -1 (left), 0 (centered) or 1 (right).
  • hat_y (int) – Current hat (POV) vertical position; one of -1 (bottom), 0 (centered) or 1 (top).

Attributes

Joystick.event_types = ['on_joyaxis_motion', 'on_joybutton_press', 'on_joybutton_release', 'on_joyhat_motion']

Inherited members

Methods

Joystick.dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters:
  • event_type (str) – Name of the event.
  • args (sequence) – Arguments to pass to the event handler.
Return type:

bool or None

Returns:

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earler, the return value is always None.

Joystick.event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
Joystick.pop_handlers()

Pop the top level of event handlers off the stack.

Joystick.push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

classmethod Joystick.register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters:name (str) – Name of the event to register.
Joystick.remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers; and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters:
  • name (str) – Name of the event type to remove.
  • handler (callable) – Event handler to remove.
Joystick.remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers and pop_handlers.

Joystick.set_handler(name, handler)

Attach a single event handler.

Parameters:
  • name (str) – Name of the event type to attach to.
  • handler (callable) – Event handler to attach.
Joystick.set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers for the accepted argument types.

Table Of Contents

Previous topic

Device Class

Next topic

RelativeAxis Class