Back to Qt.io
Contact Us Blog Download Qt

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
继承于

QPointingDevice

公共类型

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

详细说明

每个QInputEvent 都包含一个 QInputDevice 指针，用于访问特定设备的属性，如类型、功能和位置。平台或通用插件有责任通过 QWindowSystemInterface::registerInputDevice()发现、创建并注册与每个可用输入设备相对应的该类实例，然后再生成任何引用该设备的输入事件。

应用程序无需实例化该类，但可以读取QInputEvent::device() 和QInputDevice::devices() 指向的实例。

成员类型文档

枚举类 QInputDevice::Capability
flags QInputDevice::Capabilities

表示输入设备或其驱动程序可以提供哪类信息。

常量值说明
QInputDevice::Capability::None0没有可用的输入设备能力信息。
QInputDevice::Capability::Position0x0001表示位置信息可用，即触摸点中的 position() 系列函数返回有效的点。
QInputDevice::Capability::Area0x0002表示触摸区域信息可用，即触摸点中的QEventPoint::ellipseDiameters() 返回有效值。
QInputDevice::Capability::Pressure0x0004表示压力信息可用，即QEventPoint::pressure() 返回有效值。
QInputDevice::Capability::Velocity0x0008表示速度信息可用，即QEventPoint::velocity() 返回有效矢量。
QInputDevice::Capability::NormalizedPosition0x0020表示归一化位置信息可用，即QEventPoint::globalPosition() 返回有效值。
QInputDevice::Capability::MouseEmulation0x0040表示设备可合成鼠标事件。
QInputDevice::Capability::Scroll0x0100表示设备具有滚动功能。
QInputDevice::Capability::PixelScroll (since Qt 6.2)0x0080表示设备（通常是touchpad ）通过pixel precision 滚动。
QInputDevice::Capability::Hover0x0200表示设备具有悬停功能。
QInputDevice::Capability::Rotation0x0400表示rotation 信息可用。
QInputDevice::Capability::XTilt0x0800表示tilt 信息可用于 X 轴。
QInputDevice::Capability::YTilt0x1000表示tilt 信息可用于 Y 轴。
QInputDevice::Capability::TangentialPressure0x2000表示tangential pressure 信息可用。
QInputDevice::Capability::ZPosition0x4000表示Z-axis 的位置信息可用。
QInputDevice::Capability::All0x7FFFFFFF

Capabilities 类型是QFlags<Capability> 的类型定义。它存储能力值的 OR 组合。

枚举类 QInputDevice::DeviceType
flags QInputDevice::DeviceTypes

该枚举表示生成QPointerEvent 的设备类型。

常量值描述
QInputDevice::DeviceType::Unknown0x0000无法识别设备。
QInputDevice::DeviceType::Mouse0x0001鼠标。
QInputDevice::DeviceType::TouchScreen0x0002在这种设备中，触摸表面和显示屏是一体的。这意味着表面和显示屏通常具有相同的尺寸，因此触摸点的物理位置与QEventPoint 报告的坐标之间存在直接关系。因此，Qt 允许用户同时与多个 QWidget、QGraphicsItems 或Qt Quick Items 直接交互。
QInputDevice::DeviceType::TouchPad0x0004在这种设备中，触摸表面与显示屏是分开的。物理触摸位置与屏幕坐标之间没有直接关系。相反，它们是相对于当前鼠标位置计算出来的，用户必须使用触摸板来移动这个参考点。与触摸屏不同，Qt XML 只允许用户同时与单个QWidget 或QGraphicsItem 进行交互。
QInputDevice::DeviceType::Stylus0x0010类似笔的设备，可用于 Wacom 手写板等绘图板，或具有独立触控笔感应功能的触摸屏。
QInputDevice::DeviceType::Airbrush0x0020带有拇指轮的触控笔，可调整tangentialPressure 。
QInputDevice::DeviceType::Puck0x0008一种类似于平面鼠标的设备，带有一个带十字准线的透明圆圈。
QInputDevice::DeviceType::Keyboard0x1000键盘。
QInputDevice::DeviceType::AllDevices0x7FFFFFFF以上任何一种（用作默认过滤值）。

DeviceTypes 类型是QFlags<DeviceType> 的类型定义。它存储设备类型值的 OR 组合。

成员函数文档

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 。

QRect QInputDevice::availableVirtualGeometry() const

返回virtual desktop 中该设备可以访问的区域。

例如，TouchScreen 输入设备固定在单个物理屏幕上，通常经过校准，该区域与QScreen::geometry() 相同；而Mouse 可能可以访问虚拟桌面上的所有屏幕。Wacom 图形板的配置方式可以是映射到所有屏幕，也可以是只映射到用户喜欢创建绘图的屏幕，或者是映射到绘图窗口。与触摸屏集成在一起的Stylus 设备可能仅限于该屏幕。

如果返回的矩形为null ，则表示该设备可以访问整个虚拟桌面。

注： 属性 availableVirtualGeometry 的获取函数。

QInputDevice::Capabilities QInputDevice::capabilities() const

返回设备能力。

注： 属性功能的获取函数。

[static] QList<const QInputDevice *> QInputDevice::devices()

返回所有已注册输入设备（键盘和指向设备）的列表。

注意： 并非所有平台上的设备列表都是完整的。到目前为止，X11平台上最完整的信息是在启动时和响应热插拔时提供的。其他大多数平台只能在接收到事件后提供各种类型的通用设备；而且大多数平台不会在运行时告诉 Qt 设备何时插入或何时拔出。

注意： 返回的列表不能用于添加新设备。要为自动测试添加模拟触摸屏，可使用QTest::createTouchDevice() 。平台插件应在发现设备时调用 QWindowSystemInterface::registerInputDevice() 添加设备。

bool QInputDevice::hasCapability(QInputDevice::Capability capability) const

返回设备功能是否包含给定的capability 。

QString QInputDevice::name() const

返回设备名称。

该字符串可能为空。不过，在有多个输入设备的系统中，这个字符串还是很有用的：它可以用来区分QPointerEvent 源自哪个设备。

注： 属性名称的获取函数。

[static] const QInputDevice *QInputDevice::primaryKeyboard(const QString &seatName = QString())

返回给定座位上的核心键盘或主键盘seatName 。

QString QInputDevice::seatName() const

如果已知，则返回与设备关联的座位；否则为空。

一个用户同时使用的设备可以配置为具有相同的席位名称。目前只有 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

返回设备类型。

注： 属性类型的获取函数。

© 2025 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.