QInputDevice Class
QInputDevice 类描述了QInputEvent 的来源设备。更多内容...
| 头文件： | #include <QInputDevice> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
| 自： | Qt 6.0 |
| 继承自： | QObject |
| 被继承于： |
公共类型
| flags | Capabilities |
| enum class | Capability { None, Position, Area, Pressure, Velocity, …, All } |
| enum class | DeviceType { Unknown, Mouse, TouchScreen, TouchPad, Stylus, …, AllDevices } |
| flags | DeviceTypes |
属性
|
公共函数
| QInputDevice(QObject *parent = nullptr) | |
| QInputDevice(const QString &name, qint64 id, QInputDevice::DeviceType type, const QString &seatName = QString(), QObject *parent = nullptr) | |
| QRect | availableVirtualGeometry() const |
| QInputDevice::Capabilities | capabilities() const |
| bool | hasCapability(QInputDevice::Capability capability) const |
| QString | name() const |
| QString | seatName() const |
| qint64 | systemId() const |
| QInputDevice::DeviceType | type() const |
信号
| void | availableVirtualGeometryChanged(QRect area) |
| void | capabilitiesChanged(QInputDevice::Capabilities capabilities) |
静态公共成员
| QList<const QInputDevice *> | devices() |
| const QInputDevice * | primaryKeyboard(const QString &seatName = QString()) |
(since 6.3) QStringList | seatNames() |
受保护函数
| QInputDevice(const QInputDevice &) | |
| QInputDevice(QInputDevice &&) | |
| QInputDevice & | operator=(QInputDevice &&) |
| QInputDevice & | operator=(const QInputDevice &) |
详细说明
每个QInputEvent 都包含一个QInputDevice指针，用于访问类型、功能和座位等特定于设备的属性。 平台或通用插件有责任在生成任何涉及该设备的输入事件之前，通过 QWindowSystemInterface::registerInputDevice() 发现、创建并注册与每个可用输入设备相对应的该类实例。
应用程序无需实例化此类，但可以读取QInputEvent::device() 和QInputDevice::devices() 所指向的实例。
成员类型文档
enum class QInputDevice::Capability
flags QInputDevice::Capabilities
指示输入设备或其驱动程序能够提供何种信息。
| 常量 | 值 | 描述 |
|---|---|---|
QInputDevice::Capability::None | 0 | 没有关于输入设备功能的信息。 |
QInputDevice::Capability::Position | 0x0001 | 表示有位置信息可用，这意味着 touch points 中的 position() 函数族返回有效的点。 |
QInputDevice::Capability::Area | 0x0002 | 表示触摸区域信息可用，这意味着 touch points 中的QEventPoint::ellipseDiameters() 返回有效值。 |
QInputDevice::Capability::Pressure | 0x0004 | 表示压力信息可用，这意味着QEventPoint::pressure()返回有效值。 |
QInputDevice::Capability::Velocity | 0x0008 | 表示速度信息可用，这意味着QEventPoint::velocity() 返回一个有效的向量。 |
QInputDevice::Capability::NormalizedPosition | 0x0020 | 表示可获得归一化位置，这意味着 touchPoints 中的QEventPoint::normalizedPosition() 返回有效值。 |
QInputDevice::Capability::MouseEmulation | 0x0040 | 表示设备会合成鼠标事件。 |
QInputDevice::Capability::Scroll | 0x0100 | 表示该设备具有滚动功能。 |
QInputDevice::Capability::PixelScroll (since Qt 6.2) | 0x0080 | 表示该设备（通常为touchpad ）可通过pixel precision 进行滚动。 |
QInputDevice::Capability::Hover | 0x0200 | 表示该设备具有悬停功能。 |
QInputDevice::Capability::Rotation | 0x0400 | 表示可获得rotation 信息。 |
QInputDevice::Capability::XTilt | 0x0800 | 表示可获得 X 轴的tilt 信息。 |
QInputDevice::Capability::YTilt | 0x1000 | 表示 Y 轴有tilt 信息。 |
QInputDevice::Capability::TangentialPressure | 0x2000 | 表示可获取tangential pressure 信息。 |
QInputDevice::Capability::ZPosition | 0x4000 | 表示Z-axis 的位置信息可用。 |
QInputDevice::Capability::All | 0x7FFFFFFF |
“Capabilities”类型是QFlags<Capability> 的 typedef 定义。它存储了 Capability 值的按“或”运算组合。
enum class QInputDevice::DeviceType
flags QInputDevice::DeviceTypes
此枚举表示生成QPointerEvent 的设备类型。
| 常量 | 值 | 描述 |
|---|---|---|
QInputDevice::DeviceType::Unknown | 0x0000 | 无法识别该设备。 |
QInputDevice::DeviceType::Mouse | 0x0001 | 鼠标。 |
QInputDevice::DeviceType::TouchScreen | 0x0002 | 在此类设备中，触控表面与显示屏是一体的。 这意味着触摸表面和显示屏通常具有相同的大小，因此触摸点的物理位置与QEventPoint 报告的坐标之间存在直接关系。因此，Qt允许用户同时直接与多个QWidgets、QGraphicsItems或Qt Quick 项进行交互。 |
QInputDevice::DeviceType::TouchPad | 0x0004 | 在此类设备中，触摸表面与显示屏是分离的。 物理触摸位置与屏幕坐标之间不存在直接对应关系。相反，这些坐标是相对于当前鼠标位置计算得出的，用户必须使用触摸板来移动该参考点。与触摸屏不同，Qt 允许用户每次仅与单个QWidget 或QGraphicsItem 进行交互。 |
QInputDevice::DeviceType::Stylus | 0x0010 | 一种类似于笔的设备，用于图形绘图板（如 Wacom 绘图板）或具备独立触控笔感应功能的触摸屏上。 |
QInputDevice::DeviceType::Airbrush | 0x0020 | 一种带有拇指滚轮的触控笔，用于调整tangentialPressure 。 |
QInputDevice::DeviceType::Puck | 0x0008 | 一种类似于扁平鼠标的设备，上面有一个带有十字准线的透明圆圈。 |
QInputDevice::DeviceType::Keyboard | 0x1000 | 键盘。 |
QInputDevice::DeviceType::AllDevices | 0x7FFFFFFF | 上述任何一种（用作默认过滤值）。 |
DeviceTypes 类型是QFlags<DeviceType> 的 typedef。它存储 DeviceType 值的按“或”运算组合。
属性文档
[read-only] availableVirtualGeometry : QRect
该属性指定了该设备可在虚拟桌面内访问的区域。
例如，TouchScreen 输入设备固定在单个物理屏幕上，并且通常经过校准，使其区域与QScreen::geometry() 相同；而Mouse 通常能够访问虚拟桌面上的所有屏幕。
此外，Wacom 图形输入板可以配置为映射到所有屏幕，或者仅映射到用户偏好的绘图屏幕，或者仅映射到正在进行绘图的窗口。
与触摸屏集成的Stylus 设备在物理上可能仅限于该屏幕。
如果返回的矩形为null ，则表示该设备可以访问整个虚拟桌面。
访问函数：
| QRect | availableVirtualGeometry() const |
通知信号：
| void | availableVirtualGeometryChanged(QRect area) |
[read-only] capabilities : Capabilities
该属性存储了设备的功能。
访问函数：
| QInputDevice::Capabilities | capabilities() const |
通知信号：
| void | capabilitiesChanged(QInputDevice::Capabilities capabilities) |
[read-only] name : const QString
该属性存储设备名称。
访问函数：
| QString | name() const |
[read-only] seatName : const QString
该属性存储与该设备关联的座位。
访问函数：
| QString | seatName() const |
[read-only] systemId : const qint64
该属性存储平台特有的系统 ID。
访问函数：
| qint64 | systemId() const |
[read-only] type : const DeviceType
该属性存储设备类型
访问函数：
| QInputDevice::DeviceType | type() const |
成员函数文档
QInputDevice::QInputDevice(QObject *parent = nullptr)
创建一个新的无效输入设备实例，作为parent 的子节点。
QInputDevice::QInputDevice(const QString &name, qint64 id, QInputDevice::DeviceType type, const QString &seatName = QString(), QObject *parent = nullptr)
创建一个新的输入设备实例。给定的name 通常是制造商分配的型号名称（如有），或其它可识别的标识符；id 是一个平台专用的编号，每个设备都有唯一的编号（例如X11中的xinput ID）；type 用于标识设备类型。 在能够同时处理来自多个用户或多组输入设备的输入的窗口系统（如 Wayland 或 X11）中，seatName 用于标识将协同使用的设备组的名称。 如果该设备是子设备或从属设备（例如，可以轮流移动“核心指针”的几只鼠标之一），则应将主设备指定为parent 。
平台插件会创建、注册并持续拥有每个设备实例；通常出于内存管理目的，即使某个特定设备没有主设备，也应指定parent 。
默认情况下，capabilities() 为None 。
[protected delete] QInputDevice::QInputDevice(const QInputDevice &)
复制并构造一个QInputDevice 实例。该函数已被删除。
[protected delete] QInputDevice::QInputDevice(QInputDevice &&)
通过Move构造一个QInputDevice 实例。该函数已被删除。
QInputDevice::Capabilities QInputDevice::capabilities() const
返回设备功能。
注意： 这是“capabilities”属性的获取 函数。
[static] QList<const QInputDevice *> QInputDevice::devices()
返回所有已注册输入设备（键盘和指点设备）的列表。
注意： 在所有平台上，设备列表 并不总是完整的。 到目前为止，Linux平台在系统启动时以及响应热插拔时可提供最完整的信息。大多数其他平台仅能在接收到来自设备的事件后，才能提供各种类型的通用设备；而且大多数平台在运行时不会通知 Qt 设备何时被插入或拔出。
注意： 返回的列表不能用于添加新设备。若要为自动测试添加模拟触摸屏，可使用 `QTest::createTouchDevice()`。平台插件应在发现设备时调用 `QWindowSystemInterface::registerInputDevice()` 来添加设备。
bool QInputDevice::hasCapability(QInputDevice::Capability capability) const
返回设备功能是否包含给定的capability 。
QString QInputDevice::name() const
返回设备名称。
该字符串可能为空。但在拥有多个输入设备的系统上，它非常有用：可用于区分QPointerEvent 来自哪个设备。
注意： 这是用于“property name”属性的获取 函数。
[static] const QInputDevice *QInputDevice::primaryKeyboard(const QString &seatName = QString())
返回指定座位seatName 上的核心键盘或主键盘。
QString QInputDevice::seatName() const
返回与该设备关联的席位（如果已知）；否则返回空值。
intended to be used together by one user may be configured to have the same seat name. 目前仅在 Wayland 和 X11 平台上支持此功能。
注意： 这是属性 seatName 的获取 函数。
[static, since 6.3] QStringList QInputDevice::seatNames()
返回所有已注册输入设备（键盘和指点设备）的席位名称列表。
该函数在 Qt 6.3 中引入。
qint64 QInputDevice::systemId() const
返回特定平台的系统 ID（例如，在 X11 平台上的 xinput ID）。
所有平台都应为每个设备提供一个唯一的系统 ID。
注意： 这是属性 systemId 的获取 函数。
QInputDevice::DeviceType QInputDevice::type() const
返回设备类型。
注意： 这是用于属性 type 的获取器 函数。
[protected delete] QInputDevice &QInputDevice::operator=(QInputDevice &&)
将other 按移动赋值的方式赋值给此QInputDevice 实例。该函数已被删除。
[protected delete] QInputDevice &QInputDevice::operator=(const QInputDevice &)
将other 复制并赋值给此QInputDevice 实例。该函数已被删除。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
