Navigation

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.

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.

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.

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).

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.

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.

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’

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.