pyglet.input

Joystick, Game Controller, Tablet and USB HID device support.

This module provides a unified interface to almost any input device, besides the regular mouse and keyboard support provided by Window. At the lowest level, get_devices() can be used to retrieve a list of all supported devices, including joysticks, tablets, game controllers, wheels, pedals, remote controls, keyboards and mice. The set of returned devices varies greatly depending on the operating system (and, of course, what’s plugged in).

At this level pyglet does not try to interpret what a particular device is, merely what controls it provides. A Control can be either a button, whose value is either True or False, or a relative or absolute-valued axis, whose value is a float. Sometimes the name of a control can be provided (for example, x, representing the horizontal axis of a joystick), but often not. In these cases the device API may still be useful – the user will have to be asked to press each button in turn or move each axis separately to identify them.

Higher-level interfaces are provided for joysticks, game controllers, tablets and the Apple remote control. These devices can usually be identified by pyglet positively, and a base level of functionality for each one provided through a common interface.

To use an input device:

Call get_devices(), get_apple_remote(), get_controllers() or get_joysticks() to retrieve and identify the device.
For low-level devices (retrieved by get_devices()), query the devices list of controls and determine which ones you are interested in. For high-level interfaces the set of controls is provided by the interface.
Optionally attach event handlers to controls on the device. For high-level interfaces, additional events are available.
Call Device.open() to begin receiving events on the device. You can begin querying the control values after this time; they will be updated asynchronously.
Call Device.close() when you are finished with the device (not needed if your application quits at this time).

To use a tablet, follow the procedure above using get_tablets(), but note that no control list is available; instead, calling Tablet.open() returns a TabletCanvas onto which you should set your event handlers.

For game controllers, the ControllerManager is available. This provides a convenient way to handle hot-plugging of controllers.

Added in version 1.2.

Classes

class ControllerManager

High level interface for managing game Controllers.

This class provides a convenient way to handle the connection and disconnection of devices. A list of all connected Controllers can be queried at any time with the get_controllers method. For hot-plugging, events are dispatched for on_connect and on_disconnect. To use the ControllerManager, first make an instance:

controller_man = pyglet.input.ControllerManager()

At the start of your game, query for any Controllers that are already connected:

controllers = controller_man.get_controllers()

To handle Controllers that are connected or disconnected after the start of your game, register handlers for the appropriate events:

@controller_man.event
def on_connect(controller):
    # code to handle newly connected
    # (or re-connected) controllers
    controller.open()
    print("Connect:", controller)

@controller_man.event
def on_disconnect(controller):
    # code to handle disconnected Controller
    print("Disconnect:", controller)

Added in version 2.0.

Methods

Events

__init__()

classmethod __new__(*args, **kwargs)

class Device

Bases: object

Low level input device.

connected: bool

property is_open: bool

manufacturer: str | None: The manufacturer name, if available

class Control

Bases: EventDispatcher

Single value input provided by a device.

A control’s value can be queried when the device is open. Event handlers can be attached to the control to be called when the value changes.

The min and max properties are provided as advertised by the device; in some cases the control’s value will be outside this range.

Events

Attributes

value

Current value of the control.

The range of the value is device-dependent; for absolute controls the range is given by min and max (however the value may exceed this range); for relative controls the range is undefined.

classmethod __new__(*args, **kwargs)

class RelativeAxis

Bases: Control

An axis whose value represents a relative change from the previous value.

This type of axis is used for controls that can scroll or move continuously, such as a scrolling or pointing input. The value is read as a delta change from the previous value.

RX: str = 'rx'

RY: str = 'ry'

RZ: str = 'rz'

WHEEL: str = 'wheel'

X: str = 'x'

Y: str = 'y'

Z: str = 'z'

property value: float

Current value of the control.

The range of the value is device-dependent; for absolute controls the range is given by min and max (however the value may exceed this range); for relative controls the range is undefined.

class AbsoluteAxis

Bases: Control

An axis whose value represents the current measurement from the device.

This type of axis is used for controls that have minimum and maximum positions. The value is a range between the min and max.

HAT: str = 'hat'

HAT_X: str = 'hat_x'

HAT_Y: str = 'hat_y'

RX: str = 'rx'

RY: str = 'ry'

RZ: str = 'rz'

X: str = 'x'

Y: str = 'y'

Z: str = 'z'

class Button

Bases: Control

A control whose value is boolean.

Events

on_press(): The button was pressed.

on_release(): The button was released.

Attributes

value

classmethod __new__(*args, **kwargs)

class Controller

Bases: EventDispatcher

High-level interface for Game Controllers.

Unlike Joysticks, Controllers have a strictly defined set of inputs that matches the layout of popular home video game console Controllers. This includes a variety of face and shoulder buttons, analog sticks and triggers, a directional pad, and optional rumble (force feedback) effects.

To use a Controller, you must first call open. Controllers will then dispatch various events whenever the inputs change. They can also be polled manually at any time to find the current value of any inputs. Analog stick inputs are normalized to the range [-1.0, 1.0], and triggers are normalized to the range [0.0, 1.0]. All other inputs are digital.

Note: A running application event loop is required

The following event types are dispatched:: on_button_press on_button_release on_stick_motion on_dpad_motion on_trigger_motion

Methods

Events

type

The type, or family, of the Controller

This property uses a simple heuristic query to attempt to determine which general family the controller falls into. For example, the controller may have Ⓐ,Ⓑ,Ⓧ,Ⓨ, or ✕,○,□,△ labels on the face buttons. Using this information, you can choose to display matching button prompt images in your game. For example:

if controller.type == 'PS':
    a_glyph = 'ps_cross_button.png'
    b_glyph = 'ps_circle_button.png'
    ...
elif controller.type == 'XB':
    a_glyph = 'ms_a_button.png'
    b_glyph = 'ms_b_button.png'
    ...
else:
    ...

Returns:: A string, currently one of “PS”, “XB”, or “GENERIC”.

classmethod __new__(*args, **kwargs)

class Joystick

Bases: EventDispatcher

High-level interface for joystick-like devices. This includes a wide range of analog and digital joysticks, gamepads, controllers, and possibly even steering wheels and other input devices. There is unfortunately no easy way to distinguish between most of these different device types.

For a simplified subset of Joysticks, see the Controller interface. This covers a variety of popular game console controllers. Unlike Joysticks, Controllers have strictly defined layouts and inputs.

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.

Methods

Events

__init__(device)

classmethod __new__(*args, **kwargs)

class AppleRemote

Bases: EventDispatcher

High-level interface for Apple remote control.

This interface provides access to the 6 button controls on the remote. Pressing and holding certain buttons on the remote is interpreted as a separate control.

Methods

close(): Close the device. See Device.close.

Events

__init__(device)

classmethod __new__(*args, **kwargs)

class Tablet

High-level interface to tablet devices.

Unlike other devices, tablets must be opened for a specific window, and cannot be opened exclusively. The open method returns a TabletCanvas object, which supports the events provided by the tablet.

Currently only one tablet device can be used, though it can be opened on multiple windows. If more than one tablet is connected, the behaviour is undefined.

__init__()

classmethod __new__(*args, **kwargs)

Functions

Exceptions

class DeviceException

class DeviceOpenException

class DeviceExclusiveException