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, space 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()
orget_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.
New 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)
New in version 1.2.
Methods
- get_controllers()
Get a list of all connected Controllers
- Return type:
list of
Controller
Events
- on_connect(controller)
A Controller has been connected. If this is a previously dissconnected Controller that is being re-connected, the same Controller instance will be returned.
- Parameters:
- controller
Controller
An un-opened Controller instance.
- controller
- Event:
- on_disconnect(controller)
A Controller has been disconnected.
- Parameters:
- controller
Controller
An un-opened Controller instance.
- controller
- Event:
- class Device(display, name)
Bases:
object
Input device.
- Ivariables:
- displaypyglet.canvas.Display
Display this device is connected to.
- namestr
Name of the device, as described by the device firmware.
- manufacturerstr
Name of the device manufacturer, or
None
if the information is not available.
- close()
Close the device.
- get_controls()
Get a list of controls provided by the device.
- Return type:
list of Control
- get_guid()
Get the device GUID, in SDL2 format.
Return a str containing a unique device identification string. This is generated from the hardware identifiers, and is in the same format as was popularized by SDL2. GUIDs differ between platforms, but are generally 32 hexidecimal characters.
- Return type:
str containing the device’s GUID.
- open(window=None, exclusive=False)
Open the device to begin receiving input from it.
- Parameters:
- windowWindow
Optional window to associate with the device. The behaviour of this parameter is device and operating system dependant. It can usually be omitted for most devices.
- exclusivebool
If
True
the device will be opened exclusively so that no other application can use it. The method will raise DeviceExclusiveException if the device cannot be opened this way (for example, because another application has already opened it).
- property is_open
- class Control(name, raw_name=None, inverted=False)
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.
- Ivariables:
- namestr
Name of the control, or
None
if unknown- raw_namestr
Unmodified name of the control, as presented by the operating system; or
None
if unknown.- invertedbool
If
True
, the value reported is actually inverted from what the device reported; usually this is to provide consistency across operating systems.
Events
- on_change(value)
The value changed.
- Parameters:
- valuefloat
Current value of the control.
- Event:
Attributes
- class RelativeAxis(name, raw_name=None, inverted=False)
Bases:
Control
An axis whose value represents a relative change from the previous value.
- RX = 'rx'
Name of the rotational-X axis control
- RY = 'ry'
Name of the rotational-Y axis control
- RZ = 'rz'
Name of the rotational-Z axis control
- WHEEL = 'wheel'
Name of the scroll wheel control
- X = 'x'
Name of the horizontal axis control
- Y = 'y'
Name of the vertical axis control
- Z = 'z'
Name of the Z axis control.
- class AbsoluteAxis(name, minimum, maximum, raw_name=None, inverted=False)
Bases:
Control
An axis whose value represents a physical measurement from the device.
The value is advertised to range over
minimum
andmaximum
.- Ivariables:
- minimumfloat
Minimum advertised value.
- maximumfloat
Maximum advertised value.
- HAT = 'hat'
Name of the hat (POV) control, when a single control enumerates all of the hat’s positions.
- HAT_X = 'hat_x'
Name of the hat’s (POV’s) horizontal control, when the hat position is described by two orthogonal controls.
- HAT_Y = 'hat_y'
Name of the hat’s (POV’s) vertical control, when the hat position is described by two orthogonal controls.
- RX = 'rx'
Name of the rotational-X axis control
- RY = 'ry'
Name of the rotational-Y axis control
- RZ = 'rz'
Name of the rotational-Z axis control
- X = 'x'
Name of the horizontal axis control
- Y = 'y'
Name of the vertical axis control
- Z = 'z'
Name of the Z axis control.
- class Button(name, raw_name=None, inverted=False)
Bases:
Control
A control whose value is boolean.
Events
- on_press()
The button was pressed.
- Event:
- on_release()
The button was released.
- Event:
Attributes
- value
- class Controller(device, mapping)
Bases:
EventDispatcher
Methods
- open(window=None, exclusive=False)
Open the controller. See Device.open.
- close()
Close the controller. See Device.close.
Events
- on_stick_motion(controller, stick, xvalue, yvalue)
The value of a controller analogue stick changed.
- Parameters:
- controllerController
The controller whose analogue stick changed.
- stickstring
The name of the stick that changed.
- xvaluefloat
The current X axis value, normalized to [-1, 1].
- yvaluefloat
The current Y axis value, normalized to [-1, 1].
- on_dpad_motion(controller, dpleft, dpright, dpup, dpdown)
The direction pad of the controller changed.
- Parameters:
- controllerController
The controller whose hat control changed.
- dpleftboolean
True if left is pressed on the directional pad.
- dprightboolean
True if right is pressed on the directional pad.
- dpupboolean
True if up is pressed on the directional pad.
- dpdownboolean
True if down is pressed on the directional pad.
- on_trigger_motion(controller, trigger, value)
The value of a controller analogue stick changed.
- Parameters:
- controllerController
The controller whose analogue stick changed.
- triggerstring
The name of the trigger that changed.
- valuefloat
The current value of the trigger, normalized to [-1, 1].
- on_button_press(controller, button)
A button on the controller was pressed.
- Parameters:
- controller
Controller
The controller whose button was pressed.
- buttonstring
The name of the button that was pressed.
- controller
- on_button_release(controller, button)
A button on the joystick was released.
- Parameters:
- controllerController
The controller whose button was released.
- buttonstring
The name of the button that was released.
- class Joystick(device)
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.
- Ivariables:
- deviceDevice
The underlying device used by this joystick interface.
- xfloat
Current X (horizontal) value ranging from -1.0 (left) to 1.0 (right).
- yfloat
Current y (vertical) value ranging from -1.0 (top) to 1.0 (bottom).
- zfloat
Current Z value ranging from -1.0 to 1.0. On joysticks the Z value is usually the throttle control. On controllers the Z value is usually the secondary thumb vertical axis.
- rxfloat
Current rotational X value ranging from -1.0 to 1.0.
- ryfloat
Current rotational Y value ranging from -1.0 to 1.0.
- rzfloat
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_xint
Current hat (POV) horizontal position; one of -1 (left), 0 (centered) or 1 (right).
- hat_yint
Current hat (POV) vertical position; one of -1 (bottom), 0 (centered) or 1 (top).
- buttonslist of bool
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_controlAbsoluteAxis
Underlying control for x value, or
None
if not available.- y_controlAbsoluteAxis
Underlying control for y value, or
None
if not available.- z_controlAbsoluteAxis
Underlying control for z value, or
None
if not available.- rx_controlAbsoluteAxis
Underlying control for rx value, or
None
if not available.- ry_controlAbsoluteAxis
Underlying control for ry value, or
None
if not available.- rz_controlAbsoluteAxis
Underlying control for rz value, or
None
if not available.- hat_x_controlAbsoluteAxis
Underlying control for hat_x value, or
None
if not available.- hat_y_controlAbsoluteAxis
Underlying control for hat_y value, or
None
if not available.- button_controlslist of Button
Underlying controls for buttons values.
Methods
- open(window=None, exclusive=False)
Open the joystick device. See Device.open.
- close()
Close the joystick device. See Device.close.
Events
- on_joyaxis_motion(joystick, axis, value)
The value of a joystick axis changed.
- Parameters:
- joystickJoystick
The joystick device whose axis changed.
- axisstring
The name of the axis that changed.
- valuefloat
The current value of the axis, normalized to [-1, 1].
- on_joyhat_motion(joystick, hat_x, hat_y)
The value of the joystick hat switch changed.
- Parameters:
- joystickJoystick
The joystick device whose hat control changed.
- hat_xint
Current hat (POV) horizontal position; one of -1 (left), 0 (centered) or 1 (right).
- hat_yint
Current hat (POV) vertical position; one of -1 (bottom), 0 (centered) or 1 (top).
- on_joybutton_press(joystick, button)
A button on the joystick was pressed.
- Parameters:
- joystickJoystick
The joystick device whose button was pressed.
- buttonint
The index (in button_controls) of the button that was pressed.
- on_joybutton_release(joystick, button)
A button on the joystick was released.
- Parameters:
- joystickJoystick
The joystick device whose button was released.
- buttonint
The index (in button_controls) of the button that was released.
- class AppleRemote(device)
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.
- Ivariables:
- deviceDevice
The underlying device used by this interface.
- left_controlButton
Button control for the left (prev) button.
- left_hold_controlButton
Button control for holding the left button (rewind).
- right_controlButton
Button control for the right (next) button.
- right_hold_controlButton
Button control for holding the right button (fast forward).
- up_controlButton
Button control for the up (volume increase) button.
- down_controlButton
Button control for the down (volume decrease) button.
- select_controlButton
Button control for the select (play/pause) button.
- select_hold_controlButton
Button control for holding the select button.
- menu_controlButton
Button control for the menu button.
- menu_hold_controlButton
Button control for holding the menu button.
Methods
- open(window=None, exclusive=False)
Open the device. See Device.open.
- close()
Close the device. See Device.close.
Events
- on_button_press(button)
A button on the remote was pressed.
Only the ‘up’ and ‘down’ buttons will generate an event when the button is first pressed. All other buttons on the remote will wait until the button is released and then send both the press and release events at the same time.
- Parameters:
- buttonunicode
The name of the button that was pressed. The valid names are ‘up’, ‘down’, ‘left’, ‘right’, ‘left_hold’, ‘right_hold’, ‘menu’, ‘menu_hold’, ‘select’, and ‘select_hold’
- Event:
- on_button_release(button)
A button on the remote was released.
The ‘select_hold’ and ‘menu_hold’ button release events are sent immediately after the corresponding press events regardless of whether the user has released the button.
- Parameters:
- buttonstr
The name of the button that was released. The valid names are ‘up’, ‘down’, ‘left’, ‘right’, ‘left_hold’, ‘right_hold’, ‘menu’, ‘menu_hold’, ‘select’, and ‘select_hold’
- Event:
- 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.
Functions
- get_apple_remote(display=None)
Get the Apple remote control device.
The Apple remote is the small white 6-button remote control that accompanies most recent Apple desktops and laptops. The remote can only be used with Mac OS X.
- Parameters:
- display~pyglet.canvas.Display
Currently ignored.
- Return type:
- Returns:
The remote device, or None if the computer does not support it.
- get_devices(display=None)
Get a list of all attached input devices.
- Parameters:
- display~pyglet.canvas.Display
The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
- Return type:
list of
Device
- get_controllers(display=None)
Get a list of attached controllers.
- Parameters:
- display~pyglet.canvas.Display
The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
- Return type:
list of
Controller
- get_joysticks(display=None)
Get a list of attached joysticks.
- Parameters:
- display~pyglet.canvas.Display
The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
- Return type:
list of
Joystick
- get_tablets(display=None)
Get a list of tablets.
This function may return a valid tablet device even if one is not attached (for example, it is not possible on Mac OS X to determine if a tablet device is connected). Despite returning a list of tablets, pyglet does not currently support multiple tablets, and the behaviour is undefined if more than one is attached.
- Parameters:
- display~pyglet.canvas.Display
The display device to query for input devices. Ignored on Mac OS X and Windows. On Linux, defaults to the default display device.
- Return type:
list of
Tablet
Exceptions
- class DeviceException
- class DeviceOpenException
- class DeviceExclusiveException