PointerHandler QML Type (Uncreatable)
指针事件的抽象处理程序。更多...
| Import Statement: | import QtQuick |
| Inherited By: | DragHandler, HoverHandler, MultiPointHandler, PinchHandler, PointerDeviceHandler, PointHandler, SinglePointHandler, TapHandler, and WheelHandler |
注意：这是一个不可创建的类型。无法在 QML 中对其进行实例化。
属性
- active : bool
- cursorShape : Qt::CursorShape
- dragThreshold : int
- enabled : bool
- grabPermissions : flags
- margin : real
- parent : Item
- target : Item
信号
- canceled(eventPoint point)
- grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
详细说明
PointerHandler 是用于处理来自任何类型指点设备（触摸、鼠标或图形输入板）事件的输入处理程序基类（未注册为 QML 类型）。
属性文档
active : bool [read-only]
当该输入处理程序通过成功独占获取一个或多个事件点（eventPoints ）而承担起处理这些事件点的全部责任时，此方法将返回true 。这意味着它会根据这些事件点的移动情况实时更新其属性，并主动操作其target （如有）。
cursorShape : Qt::CursorShape
当鼠标悬停在parent 项上时，如果active 的值为true ，则此属性将确定此时显示的光标形状。
可用的光标形状包括：
- Qt.ArrowCursor
- Qt.UpArrowCursor
- Qt.CrossCursor
- Qt.WaitCursor
- Qt.IBeamCursor
- Qt.SizeVerCursor
- Qt.SizeHorCursor
- Qt.SizeBDiagCursor
- Qt.SizeFDiagCursor
- Qt.SizeAllCursor
- Qt.BlankCursor
- Qt.SplitV光标
- Qt.SplitHCursor
- Qt.指手光标
- Qt.禁止光标
- Qt.什么是这个光标
- Qt.BusyCursor
- Qt.张开手形光标
- Qt.紧握手形光标
- Qt.拖拽复制光标
- Qt.拖动移动光标
- Qt.DragLinkCursor
默认值未设置，这将使parent 项的cursor 显示出来。通过将该属性设置为undefined，可以将其重置为初始状态。
注意：当 该属性未被设置，或被设置为 `undefined`时 ，若读取其值，将返回 `Qt.ArrowCursor`。
另请参阅 Qt::CursorShape 、QQuickItem::cursor() 和HoverHandler::cursorShape 。
dragThreshold : int
用户必须将eventPoint 拖动多少像素，该操作才会被视为拖动手势。
默认值取决于平台和屏幕分辨率。将其设置为undefined可将其重置为默认值。不同处理程序在拖动手势开始时的行为各不相同。
enabled : bool
如果禁用了PointerHandler ，它将拒绝所有事件，且不会发出任何信号。
如果PointerHandler 的parent 属性设置为disabled ，则该处理程序也将被有效禁用，即使enabled 属性仍保持为true 。
注意： HoverHandler 的行为有所不同：有关更多信息，请参阅其enabled 属性的文档。
grabPermissions : flags
此属性指定了当该处理程序的逻辑决定接管独占抓取时，或者当被其他处理程序请求批准接管或取消抓取时，所适用的权限。
| 常量 | 描述 |
|---|---|
PointerHandler.TakeOverForbidden | 该处理程序既不会从任何类型的 Item 或 Handler 处获取抓取权限，也不会向其授予抓取权限。 |
PointerHandler.CanTakeOverFromHandlersOfSameType | 该处理程序可以从同一类的另一个处理程序处接管独占抓取。 |
PointerHandler.CanTakeOverFromHandlersOfDifferentType | 该处理程序可以从任何类型的处理程序手中夺取独占抓取。 |
PointerHandler.CanTakeOverFromItems | 此处理程序可以从任何类型的“项”中获取排他性抓取权限。 |
PointerHandler.CanTakeOverFromAnything | 此处理程序可以从任何类型的项目或处理程序处获取排他性抓取。 |
PointerHandler.ApprovesTakeOverByHandlersOfSameType | 此处理程序允许同一类的另一个处理程序获取抓取。 |
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType | 此处理程序允许任何类型的处理程序获取抓取。 |
PointerHandler.ApprovesTakeOverByItems | 此处理程序允许任何类型的项目获取抓取。 |
PointerHandler.ApprovesCancellation | 该处理程序允许将其抓取对象设置为 null。 |
PointerHandler.ApprovesTakeOverByAnything | 此处理程序允许任何类型的“项目”或“处理程序”接管抓取操作。 |
默认值为PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything ，这允许大多数接管情况，但可避免例如两个 PinchHandler 争夺同一触点的情况。
margin : real
这是超出parent 控件边界范围的区域，eventPoint 可以在该区域内触发此处理程序。例如，在PinchHandler 中，当target 同时也是parent 时，建议将此距离设置为至少相当于普通用户手指宽度的一半，这样即使parent 被缩放至非常小的尺寸，仍可执行捏合手势。 或者，如果将基于TapHandler 的按钮放置在屏幕边缘附近，则可利用此方法符合菲茨定律：即使该按钮在视觉上距离屏幕边缘有几像素的间距，也能对屏幕边缘的鼠标点击做出响应。
默认值为 0。
parent : Item
Item ，即处理程序的作用域；即声明该处理程序的 Item。处理程序将代表该 Item 处理事件，这意味着如果指针事件的任意一个eventPoints 发生在该 Item 的内部，则该事件与该 Item 相关。初始时，target() 与该 Item 相同，但可以被重新赋值。
另请参阅 target 以及QObject::parent()。
target : Item
该处理程序将操作的项。
默认情况下，它与parent 相同，即声明该处理程序的那个Item。不过，有时将目标设置为另一个Item会很有用，以便在某个Item中处理事件但操作另一个Item；或者设置为null ，以禁用默认行为并执行其他操作。
Signal 文档
canceled(eventPoint point)
如果该处理程序已经抓取了给定的point ，当另一个指针处理程序或项目抢走该抓取时，将发出此信号。
注意： 对应的处理程序 是onCanceled 。
grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
当抓取操作发生与该处理程序相关的某种变化时，会发出此信号。
transition （动词）说明发生了什么。point （对象）是被抓取或释放的点。
transition 的有效值包括：
| 常量 | 描述 |
|---|---|
PointerDevice.GrabExclusive | 该处理程序已承担起处理point 的主要责任。 |
PointerDevice.UngrabExclusive | 该处理程序已放弃其先前的独占占用。 |
PointerDevice.CancelGrabExclusive | 该处理程序的独占控制已被接管或取消。 |
PointerDevice.GrabPassive | 该处理程序已获得被动抓取，用于监视point 。 |
PointerDevice.UngrabPassive | 该处理程序已放弃其先前的被动抓取。 |
PointerDevice.CancelGrabPassive | 该处理程序之前的被动捕获已异常终止。 |
注： 相应的处理程序 是onGrabChanged 。
© 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.
