pyglet.input

支持操纵杆、游戏控制器、平板电脑和USB HID设备。

除了提供的常规鼠标和键盘支持外，此模块还为几乎所有输入设备提供统一接口 Window 。在最低层， get_devices() 可用于检索所有受支持设备的列表，包括操纵杆、平板电脑、空间控制器、车轮、踏板、遥控器、键盘和鼠标。退回的设备集根据操作系统的不同而有很大不同(当然，还有插入的设备)。

在这个级别上，pyglet不会尝试解释 what 一个特定的设备仅仅是它提供的控制。一个 Control 可以是一个按钮，其值为 True 或 False ，或者值为浮点型的相对轴或绝对值轴。有时可以提供控件的名称(例如， x 表示操纵杆的水平轴)，但通常不是。在这些情况下，设备API可能仍然有用--必须要求用户依次按下每个按钮或分别移动每个轴以识别它们。

为操纵杆、游戏控制器、平板电脑和苹果遥控器提供了更高级别的界面。这些设备通常可以由pyglet肯定地识别，并且每个设备的基本功能级别通过公共接口提供。

要使用输入设备，请执行以下操作：

打电话 get_devices() ， get_apple_remote() ， get_controllers() 或 get_joysticks() 以检索和识别设备。
对于低级设备(由检索 get_devices() )，查询控件的设备列表并确定您感兴趣的控件。对于高级接口，控件集由接口提供。
可以选择将事件处理程序附加到设备上的控件。对于高级别接口，可以使用其他事件。
打电话 Device.open() 开始在设备上接收事件。您可以在此时间之后开始查询控制值；它们将被异步更新。
打电话 Device.close() 当您使用完设备时(如果您的应用程序此时退出，则不需要)。

要使用平板电脑，请按照上述步骤使用 get_tablets() ，但请注意，没有可用的控制列表；相反，调用 Tablet.open() 返回一个 TabletCanvas 您应该在其上设置事件处理程序。

对于游戏控制器， ControllerManager 是可用的。这提供了一种方便的方式来处理控制器的热插拔。

在 1.2 版本加入.

班级

class ControllerManager

用于管理游戏控制器的高级界面。

此类提供了一种方便的方法来处理设备的连接和断开。所有已连接控制器的列表可以随时使用 get_controllers 方法。对于热插拔，事件被调度到 on_connect 和 on_disconnect 。要使用ControllerManager，首先创建一个实例：：

controller_man = pyglet.input.ControllerManager()

在游戏开始时，查询所有已连接的控制器：

controllers = controller_man.get_controllers()

要处理在游戏开始后连接或断开的控制器，请注册相应事件的处理程序：

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

在 1.2 版本加入.

方法

get_controllers()

获取所有已连接控制器的列表

返回类型:: 清单 Controller

事件

on_connect(controller)

已连接控制器。如果这是正在重新连接的先前断开的控制器，则将返回相同的控制器实例。

参数:

controller控制器: 未打开的控制器实例。

活动:

on_disconnect(controller)

控制器已断开连接。

参数:

controller控制器: 未打开的控制器实例。

活动:

class Device(display, name)

基类：object

输入设备。

变量:

显示： pyglet.canvas.Displaypyglet.canvas.Display: 显示此设备所连接到的内容。
名字应力: 设备固件所描述的设备名称。
制造商应力: 设备制造商的名称，或 None 如果信息不可用。

close(): 关闭设备。

get_controls()

获取设备提供的控件列表。

返回类型:: 清单 Control

get_guid()

获取SDL2格式的设备GUID。

返回包含唯一设备标识字符串的字符串。这是从硬件标识符中生成的，其格式与SDL2推广的格式相同。GUID因平台而异，但通常为32个十六进制字符。

返回类型:: str containing the device's GUID.

open(window=None, exclusive=False)

打开设备以开始接收来自它的输入。

参数:

window窗户: 与设备关联的可选窗口。此参数的行为取决于设备和操作系统。对于大多数设备，它通常可以省略。
exclusive布尔尔: 如果 True 该设备将以独占方式打开，这样其他应用程序都无法使用它。该方法将提高 DeviceExclusiveException 如果设备无法以这种方式打开(例如，因为另一个应用程序已将其打开)。

property is_open

class Control(name, raw_name=None, inverted=False)

基类：EventDispatcher

由设备提供的单值输入。

当设备打开时，可以查询控件的值。可以将事件处理程序附加到要在值更改时调用的控件。

这个 min 和 max 属性按设备公布的方式提供；在某些情况下，控件的值将超出此范围。

变量:

name应力: 控件的名称，或 None 如果未知
raw_name应力: 由操作系统提供的控件的未修改名称；或 None 如果未知的话。
inverted布尔尔: 如果 True ，报告的值实际上与设备报告的值相反；这通常是为了提供跨操作系统的一致性。

事件

on_change(value)

值已更改。

参数:

value浮动: 控件的当前值。

活动:

属性

value

控件的当前值。

该值的范围取决于设备；对于绝对控件，该范围由 min 和 max (但是，该值可能超过此范围)；对于相对控件，范围未定义。

类型:: 浮动

class RelativeAxis(name, raw_name=None, inverted=False)

基类：Control

其值表示相对于上一个值的相对变化的轴。

RX = 'rx': 旋转X轴控件的名称

RY = 'ry': 旋转Y轴控件的名称

RZ = 'rz': 旋转Z轴控件的名称

WHEEL = 'wheel': 滚动轮控件的名称

X = 'x': 水平轴控件的名称

Y = 'y': 垂直轴控件的名称

Z = 'z': Z轴控件的名称。

property value

控件的当前值。

该值的范围取决于设备；对于绝对控件，该范围由 min 和 max (但是，该值可能超过此范围)；对于相对控件，范围未定义。

类型:: 浮动

class AbsoluteAxis(name, minimum, maximum, raw_name=None, inverted=False)

基类：Control

其值表示来自设备的物理测量的轴。

该值被公告为范围在 minimum 和 maximum 。

变量:

minimum浮动: 广告的最低价值。
maximum浮动: 通告的最大值。

HAT = 'hat': 当单个控件枚举HAT的所有位置时，HAT(POV)控件的名称。

HAT_X = 'hat_x': 当帽子位置由两个正交控件描述时，帽子(POV)的水平控件的名称。

HAT_Y = 'hat_y': 帽子(POV)垂直控件的名称，当帽子位置由两个正交控件描述时。

RX = 'rx': 旋转X轴控件的名称

RY = 'ry': 旋转Y轴控件的名称

RZ = 'rz': 旋转Z轴控件的名称

X = 'x': 水平轴控件的名称

Y = 'y': 垂直轴控件的名称

Z = 'z': Z轴控件的名称。

class Button(name, raw_name=None, inverted=False)

基类：Control

值为布尔值的控件。

事件

on_press()

按钮被按下了。

活动:

on_release()

按钮被松开了。

活动:

属性

value

class Controller(device, mapping)

基类：EventDispatcher

方法

open(window=None, exclusive=False): 打开控制器。看见 Device.open 。

close(): 关闭控制器。看见 Device.close 。

事件

on_stick_motion(controller, stick, xvalue, yvalue)

控制器模拟棒的值发生了变化。

参数:

controller控制器: 模拟操纵杆发生变化的控制器。
stick细绳: 更改后的棒子的名称。
xvalue浮动: 当前X轴值，规格化为 [-1, 1] 。
yvalue浮动: 当前Y轴值，规格化为 [-1, 1] 。

on_dpad_motion(controller, dpleft, dpright, dpup, dpdown)

控制器的方向垫发生了变化。

参数:

controller控制器: 其HAT控件已更改的控制器。
dpleft布尔型: 如果在方向垫上按下Left，则为True。
dpright布尔型: 如果在方向垫上按下Right，则为True。
dpup布尔型: 如果在方向垫上按Up，则为True。
dpdown布尔型: 如果方向垫上按下了Down，则为True。

on_trigger_motion(controller, trigger, value)

控制器模拟棒的值发生了变化。

参数:

controller控制器: 模拟操纵杆发生变化的控制器。
trigger细绳: 更改的触发器的名称。
value浮动: 触发器的当前值，规范化为 [-1, 1] 。

on_button_press(controller, button)

按下了控制器上的按钮。

参数:

controller控制器: 按钮被按下的控制器。
button细绳: 按下的按钮的名称。

on_button_release(controller, button)

操纵杆上的一个按钮被释放了。

参数:

controller控制器: 按钮被释放的控制器。
button细绳: 释放的按钮的名称。

class Joystick(device)

基类：EventDispatcher

操纵杆类设备的高级接口。这包括各种各样的模拟和数字操纵杆、游戏手柄、控制器，甚至可能还有方向盘和其他输入设备。不幸的是，没有简单的方法来区分这些不同的设备类型中的大多数。

有关操纵杆的简化子集，请参阅 Controller 界面。它涵盖了各种流行的游戏机控制器。与操纵杆不同，控制器有严格定义的布局和输入。

要使用操纵杆，请先拨打 open ，然后在您的游戏循环中检查 x ， y 以此类推。这些值被归一化为范围 [-1.0, 1.0] 。

若要在轴的值更改时接收事件，请在操纵杆上附加on_joyAxis_Motion事件处理程序。这个 Joystick 实例、轴名称和当前值作为参数传递给此事件。

要处理按钮事件，应将ON_JOYBUTTON_PRESS和ON_joy_BUTTON_RELEASE事件处理程序附加到操纵杆。这两个 Joystick 实例和已更改按钮的索引作为参数传递给这些事件。

或者，您可以将事件处理程序附加到 button_controls 接收On_Press或On_Release事件。

要使用HAT开关，请将on_joyhat_Motion事件处理程序附加到操纵杆。每当HAT开关的值发生更改时，都会使用HAT_x和HAT_y值调用处理程序。

可以查询设备名称以获得操纵杆的名称。

变量:

device装置: 此操纵杆界面使用的底层设备。
x浮动: 当前X(水平)值范围从-1.0(左)到1.0(右)。
y浮动: 当前y(垂直)值范围为-1.0(顶部)到1.0(底部)。
z浮动: 当前Z值范围为-1.0到1.0。在操纵杆上，Z值通常是油门控制。在控制器上，Z值通常是拇指的次要垂直轴。
rx浮动: 当前旋转X值范围为-1.0到1.0。
ry浮动: 当前旋转Y值范围为-1.0到1.0。
rz浮动: 当前旋转Z值范围为-1.0到1.0。在操纵杆上，RZ值通常是操纵杆的扭曲。在游戏控制器上，RZ值通常是第二个拇指水平轴。
hat_x集成: 当前帽子(POV)水平位置；-1(左)、0(居中)或1(右)之一。
hat_y集成: 当前帽子(POV)垂直位置；-1(底部)、0(居中)或1(顶部)之一。
buttons布尔列表: 表示按钮当前状态的布尔值列表。这些都是按顺序排列的，因此按钮1的值为 buttons[0] 以此类推。
x_controlAbsoluteAxis: 的基础控制 x 值，或 None 如果不可用。
y_controlAbsoluteAxis: 的基础控制 y 值，或 None 如果不可用。
z_controlAbsoluteAxis: 的基础控制 z 值，或 None 如果不可用。
rx_controlAbsoluteAxis: 的基础控制 rx 值，或 None 如果不可用。
ry_controlAbsoluteAxis: 的基础控制 ry 值，或 None 如果不可用。
rz_controlAbsoluteAxis: 的基础控制 rz 值，或 None 如果不可用。
hat_x_controlAbsoluteAxis: 的基础控制 hat_x 值，或 None 如果不可用。
hat_y_controlAbsoluteAxis: 的基础控制 hat_y 值，或 None 如果不可用。
button_controls清单: 的基础控件 buttons 价值观。

方法

open(window=None, exclusive=False): 打开操纵杆设备。看见 Device.open 。

close(): 合上操纵杆装置。看见 Device.close 。

事件

on_joyaxis_motion(joystick, axis, value)

操纵杆轴的值已更改。

参数:

joystick操纵杆: 轴发生变化的操纵杆装置。
axis细绳: 更改的轴的名称。
value浮动: 轴的当前值，归一化为 [-1, 1] 。

on_joyhat_motion(joystick, hat_x, hat_y)

操纵杆帽子开关的值已更改。

参数:

joystick操纵杆: 帽子控制发生变化的操纵杆设备。
hat_x集成: 当前帽子(POV)水平位置；-1(左)、0(居中)或1(右)之一。
hat_y集成: 当前帽子(POV)垂直位置；-1(底部)、0(居中)或1(顶部)之一。

on_joybutton_press(joystick, button)

按下了操纵杆上的一个按钮。

参数:

joystick操纵杆: 按下按钮的操纵杆设备。
button集成: 索引(In) button_controls 按下的按钮)。

on_joybutton_release(joystick, button)

操纵杆上的一个按钮被释放了。

参数:

joystick操纵杆: 按钮被释放的操纵杆设备。
button集成: 索引(In) button_controls )按钮被释放。

class AppleRemote(device)

基类：EventDispatcher

苹果遥控器的高级界面。

该界面提供对遥控器上的6个按钮控件的访问。按下并按住遥控器上的某些按钮被解释为单独的控件。

变量:

device装置: 此接口使用的底层设备。
left_control按钮: 左(上一)按钮的按钮控件。
left_hold_control按钮: 用于保持左键(倒带)的按钮控件。
right_control按钮: 右(下一)按钮的按钮控件。
right_hold_control按钮: 用于按住右按钮的按钮控件(快进)。
up_control按钮: Up(音量增加)按钮的按钮控制。
down_control按钮: 用于DOWN(音量减小)按钮的按钮控制。
select_control按钮: 选择(播放/暂停)按钮的按钮控制。
select_hold_control按钮: 用于保持选择按钮的按钮控件。
menu_control按钮: 菜单按钮的按钮控件。
menu_hold_control按钮: 用于保持菜单按钮的按钮控件。

方法

open(window=None, exclusive=False): 打开设备。看见 Device.open 。

close(): 关闭设备。看见 Device.close 。

事件

on_button_press(button)

遥控器上的一个按钮被按下了。

当第一次按下按钮时，只有‘向上’和‘向下’按钮才会生成事件。遥控器上的所有其他按钮将等待该按钮被释放，然后同时发送按下和释放事件。

参数:

buttonUnicode: 按下的按钮的名称。有效名称为‘UP’、‘DOWN’、‘LEFT’、‘RIGHT’、‘LEFT_HOLD’、‘RIGHT_HOLD’、‘MENU’、‘MENU_HOLD’、‘SELECT’和‘SELECT_HOLD’

活动:

on_button_release(button)

遥控器上的一个按钮被释放了。

无论用户是否已释放按钮，都会在相应的按下事件之后立即发送‘SELECT_HOLD’和‘MENU_HOLD’按钮释放事件。

参数:

button应力: 释放的按钮的名称。有效名称为‘UP’、‘DOWN’、‘LEFT’、‘RIGHT’、‘LEFT_HOLD’、‘RIGHT_HOLD’、‘MENU’、‘MENU_HOLD’、‘SELECT’和‘SELECT_HOLD’

活动:

class Tablet

与平板电脑设备的高级接口。

与其他设备不同，平板电脑必须为特定窗口打开，而不能以独占方式打开。这个 open 方法返回一个 TabletCanvas 对象，该对象支持Tablet提供的事件。

目前只能使用一个平板设备，尽管它可以在多个窗口中打开。如果连接了多个平板电脑，则行为未定义。

功能

get_apple_remote(display=None)

拿到苹果遥控器。

Apple Remote是最新款苹果台式机和笔记本电脑附带的白色6键小遥控器。这款遥控器只能在Mac OS X上使用。

参数:

显示： ~pyglet.canvas.Display~pyglet.canvas.Display: 当前已被忽略。

返回类型:

AppleRemote

返回:

远程设备，或 None 如果计算机不支持它。

get_devices(display=None)

获取所有连接的输入设备的列表。

参数:

显示： ~pyglet.canvas.Display~pyglet.canvas.Display: 要查询输入设备的显示设备。在Mac OS X和Windows上被忽略。在Linux上，默认为默认显示设备。

返回类型:

清单 Device

get_controllers(display=None)

获取已连接控制器的列表。

参数:

显示： ~pyglet.canvas.Display~pyglet.canvas.Display: 要查询输入设备的显示设备。在Mac OS X和Windows上被忽略。在Linux上，默认为默认显示设备。

返回类型:

清单 Controller

get_joysticks(display=None)

获取附加操纵杆的列表。

参数:

显示： ~pyglet.canvas.Display~pyglet.canvas.Display: 要查询输入设备的显示设备。在Mac OS X和Windows上被忽略。在Linux上，默认为默认显示设备。

返回类型:

清单 Joystick

get_tablets(display=None)

获取一份平板电脑清单。

即使没有连接平板设备，此函数也可能返回有效的平板设备(例如，在Mac OS X上无法确定是否连接了平板设备)。尽管返回了一份平板电脑列表，但pyglet目前不支持多台平板电脑，如果连接了多台平板电脑，其行为尚不确定。

参数:

显示： ~pyglet.canvas.Display~pyglet.canvas.Display: 要查询输入设备的显示设备。在Mac OS X和Windows上被忽略。在Linux上，默认为默认显示设备。

返回类型:

清单 Tablet

例外情况

class DeviceException

class DeviceOpenException

class DeviceExclusiveException