Navigation

pyglet.input

Joystick, 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, 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:

  1. Call get_devices(), get_apple_remote() or get_joysticks() to retrieve and identify the device.
  2. 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.
  3. Optionally attach event handlers to controls on the device.
  4. 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.
  5. 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.

New in version 1.2.

Classes

class Device(display, name)

Bases: object

Input device.

Variables:
  • display (pyglet.canvas.Display) – Display this device is connected to.
  • name (str) – Name of the device, as described by the device firmware.
  • manufacturer (str) – 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
open(window=None, exclusive=False)

Open the device to begin receiving input from it.

Parameters:
  • window (Window) – 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.
  • exclusive (bool) – 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).
class Control(name, raw_name=None)

Bases: pyglet.event.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.

Variables:
  • name (str) – Name of the control, or None if unknown
  • raw_name (str) – Unmodified name of the control, as presented by the operating system; or None if unknown.
  • inverted (bool) – 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:value (float) – Current value of the control.

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.

Type:float
class RelativeAxis(name, raw_name=None)

Bases: pyglet.input.base.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.

value
class AbsoluteAxis(name, min, max, raw_name=None)

Bases: pyglet.input.base.Control

An axis whose value represents a physical measurement from the device.

The value is advertised to range over min and max.

Variables:
  • min (float) – Minimum advertised value.
  • max (float) – 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)

Bases: pyglet.input.base.Control

A control whose value is boolean.

Events

on_press()

The button was pressed.

on_release()

The button was released.

Attributes

value
class Joystick(device)

Bases: pyglet.event.EventDispatcher

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 (Device) – The underlying device used by this joystick interface.
  • x (float) – Current X (horizontal) value ranging from -1.0 (left) to 1.0 (right).
  • y (float) – Current y (vertical) value ranging from -1.0 (top) to 1.0 (bottom).
  • z (float) – 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 (float) – Current rotational X value ranging from -1.0 to 1.0.
  • ry (float) – Current rotational Y value ranging from -1.0 to 1.0.
  • rz (float) – 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 (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).
  • buttons (list 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_control (AbsoluteAxis) – Underlying control for x value, or None if not available.
  • y_control (AbsoluteAxis) – Underlying control for y value, or None if not available.
  • z_control (AbsoluteAxis) – Underlying control for z value, or None if not available.
  • rx_control (AbsoluteAxis) – Underlying control for rx value, or None if not available.
  • ry_control (AbsoluteAxis) – Underlying control for ry value, or None if not available.
  • rz_control (AbsoluteAxis) – Underlying control for rz value, or None if not available.
  • hat_x_control (AbsoluteAxis) – Underlying control for hat_x value, or None if not available.
  • hat_y_control (AbsoluteAxis) – Underlying control for hat_y value, or None if not available.
  • button_controls (list 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:
  • 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].
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).
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.
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.
class AppleRemote(device)

Bases: pyglet.event.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.

Variables:
  • device (Device) – The underlying device used by this interface.
  • left_control (Button) – Button control for the left (prev) button.
  • left_hold_control (Button) – Button control for holding the left button (rewind).
  • right_control (Button) – Button control for the right (next) button.
  • right_hold_control (Button) – Button control for holding the right button (fast forward).
  • up_control (Button) – Button control for the up (volume increase) button.
  • down_control (Button) – Button control for the down (volume decrease) button.
  • select_control (Button) – Button control for the select (play/pause) button.
  • select_hold_control (Button) – Button control for holding the select button.
  • menu_control (Button) – Button control for the menu button.
  • menu_hold_control (Button) – 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:button (unicode) – 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’
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 or not the user has released the button.

Parameters:button (unicode) – 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’
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 (Display) – Currently ignored.
Return type:AppleRemote
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 (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_joysticks(display=None)

Get a list of attached joysticks.

Parameters:display (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 (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

Table Of Contents

Previous topic

pyglet.info

Next topic

pyglet.media

Navigation

© Copyright 2006-2015, Alex Holkner. Created using Sphinx 1.6.2.