QPointingDevice Class
QPointingDevice 类描述了一种产生鼠标、触摸或数位板事件的设备。更多内容...
| 头文件： | #include <QPointingDevice> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
| 自： | Qt 6.0 |
| 继承自： | QInputDevice |
- 所有成员列表（包括继承的成员）
- 已弃用的成员
- QPointingDevice 属于事件类。
公共类型
| enum | GrabTransition { GrabExclusive, UngrabExclusive, CancelGrabExclusive, GrabPassive, UngrabPassive, …, OverrideGrabPassive } |
| enum class | PointerType { Unknown, Generic, Finger, Pen, Eraser, …, AllPointerTypes } |
| flags | PointerTypes |
属性
- buttonCount : const int
- maximumPoints : const int
- pointerType : const PointerType
- uniqueId : const QPointingDeviceUniqueId
公共函数
| QPointingDevice(QObject *parent = nullptr) | |
| QPointingDevice(const QString &name, qint64 id, QInputDevice::DeviceType deviceType, QPointingDevice::PointerType pointerType, QInputDevice::Capabilities capabilities, int maxPoints, int buttonCount, const QString &seatName = QString(), QPointingDeviceUniqueId uniqueId = QPointingDeviceUniqueId(), QObject *parent = nullptr) | |
| int | buttonCount() const |
| int | maximumPoints() const |
| QPointingDevice::PointerType | pointerType() const |
| QPointingDeviceUniqueId | uniqueId() const |
信号
| void | grabChanged(QObject *grabber, QPointingDevice::GrabTransition transition, const QPointerEvent *event, const QEventPoint &point) const |
静态公共成员
| const QPointingDevice * | primaryPointingDevice(const QString &seatName = QString()) |
受保护函数
| QPointingDevice(const QPointingDevice &) | |
| QPointingDevice(QPointingDevice &&) | |
| QPointingDevice & | operator=(QPointingDevice &&) |
| QPointingDevice & | operator=(const QPointingDevice &) |
详细说明
每个QPointerEvent 都包含一个指向QPointingDevice的指针，用于访问类型和功能等设备特有的属性。平台或通用插件有责任在生成任何指针事件之前，通过QWindowSystemInterface注册可用的指点设备。应用程序无需实例化此类，只需访问QPointerEvent::device()所指向的全局实例即可。
成员类型文档
enum QPointingDevice::GrabTransition
该枚举表示从一个对象（可能是nullptr ）到另一个对象（可能是nullptr ）的排他或被动抓取转换。它作为QPointingDevice::grabChanged()信号的参数发出。
有效值为：
| 常量 | 值 | 描述 |
|---|---|---|
QPointingDevice::GrabExclusive | 0x10 | 在调用QPointerEvent::setExclusiveGrabber()后发出。 |
QPointingDevice::UngrabExclusive | 0x20 | 当抓取器被设置为nullptr 时，在QPointerEvent::setExclusiveGrabber()之后触发，用于通知抓取已正常终止。 |
QPointingDevice::CancelGrabExclusive | 0x30 | 当抓取器被设置为另一个对象时，在调用QPointerEvent::setExclusiveGrabber() 之后触发，以通知旧抓取器的抓取操作已被“窃取”。 |
QPointingDevice::GrabPassive | 0x01 | 在调用QPointerEvent::addPassiveGrabber() 之后触发。 |
QPointingDevice::UngrabPassive | 0x02 | 当被动抓取正常终止时触发，例如在调用 `QPointerEvent::removePassiveGrabber()` 之后。 |
QPointingDevice::CancelGrabPassive | 0x03 | 当被动抓取异常终止（手势被取消）时触发。 |
QPointingDevice::OverrideGrabPassive | 0x04 | 该值目前未被使用。 |
enum class QPointingDevice::PointerType
flags QPointingDevice::PointerTypes
此枚举表示与指点设备进行交互的对象。
该属性与QInputDevice::DeviceType 之间存在一些冗余。例如，如果使用触摸屏，则DeviceType 为TouchScreen ，而PointerType 为Finger （始终如此）。但在图形输入板上，通常可以同时使用触控笔的两端，程序需要对它们进行区分。 因此，该概念得到了扩展，使得每个QPointerEvent 都具有一个PointerType属性，这可以简化部分事件处理代码——无需关注DeviceType，仅根据PointerType采取不同的响应。
有效值包括：
| 常量 | 值 | 描述 |
|---|---|---|
QPointingDevice::PointerType::Unknown | 0 | 指针类型未知。 |
QPointingDevice::PointerType::Generic | 0x0001 | 鼠标或类似鼠标的行为（X11 中的核心指针）。 |
QPointingDevice::PointerType::Finger | 0x0002 | 用户的手指。 |
QPointingDevice::PointerType::Pen | 0x0004 | 触控笔的绘图端。 |
QPointingDevice::PointerType::Eraser | 0x0008 | 触控笔的另一端（如果另一端带有虚拟橡皮擦的话）。 |
QPointingDevice::PointerType::Cursor | 0x0010 | Puck 设备上常见的带有十字准线的透明圆圈。 |
QPointingDevice::PointerType::Palm (since Qt 6.12) | 0x0020 | 用户的手掌。 |
QPointingDevice::PointerType::AllPointerTypes | 0x7FFF | 上述任意一种（用作默认过滤值）。 |
PointerTypes 类型是QFlags<PointerType> 的 typedef 定义。它存储 PointerType 值的按“或”运算组合。
属性文档
[read-only] buttonCount : const int
该属性表示可检测到的设备上按钮的最大数量
访问功能：
| int | buttonCount() const |
[read-only] maximumPoints : const int
该属性表示可检测到的最大同时触点（手指）数量
访问功能：
| int | maximumPoints() const |
[read-only] pointerType : const PointerType
该属性存储指针类型
访问函数：
| QPointingDevice::PointerType | pointerType() const |
[read-only] uniqueId : const QPointingDeviceUniqueId
该属性存储了该设备的唯一标识符（其实用性存疑）
您可能更应该关注 QPointerEventPoint::uniqueId() 函数。
访问函数：
| QPointingDeviceUniqueId | uniqueId() const |
成员函数文档
QPointingDevice::QPointingDevice(QObject *parent = nullptr)
创建一个新的无效指点设备实例，并将其作为parent 的子节点。
QPointingDevice::QPointingDevice(const QString &name, qint64 id, QInputDevice::DeviceType deviceType, QPointingDevice::PointerType pointerType, QInputDevice::Capabilities capabilities, int maxPoints, int buttonCount, const QString &seatName = QString(), QPointingDeviceUniqueId uniqueId = QPointingDeviceUniqueId(), QObject *parent = nullptr)
使用给定的name 、deviceType 、pointerType 、capabilities 、maxPoints 、buttonCount 、seatName 、uniqueId 和parent 创建一个新的指点设备实例。
[protected delete] QPointingDevice::QPointingDevice(const QPointingDevice &)
复制并构造一个QPointingDevice 实例。该函数已被删除。
[protected delete] QPointingDevice::QPointingDevice(QPointingDevice &&)
通过移动构造一个QPointingDevice 实例。该函数已被删除。
int QPointingDevice::buttonCount() const
返回可检测到的设备上按钮的最大数量。
注意： 这是 buttonCount 属性的获取 函数。
[signal] void QPointingDevice::grabChanged(QObject *grabber, QPointingDevice::GrabTransition transition, const QPointerEvent *event, const QEventPoint &point) const
当grabber 对象在event 的传递过程中，获得或失去对point 的独占或被动抓取时，会发出此信号。transition 从grabber 对象的角度说明了发生的情况。
注意： 从一个对象到另一个对象的 抓取状态转换 会触发两个信号，一个用于通知某个对象已失去其抓取状态，另一个用于通知存在新的抓取者。在其他情况下，当转换至或离开非抓取状态时，仅会发出一个信号：grabber 参数绝不会是nullptr 。
另请参阅 QPointerEvent::setExclusiveGrabber()、QPointerEvent::addPassiveGrabber() 和QPointerEvent::removePassiveGrabber()。
int QPointingDevice::maximumPoints() const
返回可检测到的最大同时触点（手指）数量。
注意： 这是属性 maximumPoints 的获取 函数。
QPointingDevice::PointerType QPointingDevice::pointerType() const
返回指针类型。
注意： 这是属性 pointerType 的获取 函数。
[static] const QPointingDevice *QPointingDevice::primaryPointingDevice(const QString &seatName = QString())
返回给定座位seatName 上的主指点设备（核心指针，通常假定为鼠标）。
如果注册了多个指点设备，该函数会优先选择与给定的seatName 匹配且没有其他设备作为其父设备的鼠标或触摸板。 通常只有一个主设备或核心设备没有父设备。但如果找不到这样的设备，该函数会创建一个新的虚拟“核心指针”鼠标。因此，在尚未实现输入设备发现和注册的平台上，Qt 仍能正常运行。
QPointingDeviceUniqueId QPointingDevice::uniqueId() const
返回该设备的唯一标识符（其实用性值得商榷）。
您可能更应该关注 QPointerEventPoint::uniqueId() 方法。
注意： 这是 uniqueId 属性的获取函数 。
[protected delete] QPointingDevice &QPointingDevice::operator=(QPointingDevice &&)
将other 按移动赋值给此QPointingDevice 实例。该函数已被删除。
[protected delete] QPointingDevice &QPointingDevice::operator=(const QPointingDevice &)
将other 复制并赋值给此QPointingDevice 实例。该函数已被删除。
© 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.
