触摸处理器 QML 类型

可以激活此指针处理器的鼠标按钮。

默认情况下，此属性设置为 Qt.LeftButton。它可以将鼠标按钮设置为或操作组合，并忽略其他按钮的事件。

例如，一个控件可以通过两个处理程序以不同的方式响应左键和右键点击

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

可以激活此指针处理器的指点设备类型。

默认情况下，此属性设置为 PointerDevice.AllDevices。如果您将其设置为设备类型的或操作组合，它将忽略不匹配的设备的事件。

例如，一个控件可以通过两个处理程序以不同的方式（一个处理鼠标和笔触点击，另一个处理触摸屏轻击）进行响应

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

如果设置此属性，则必须按下指定的键盘修饰符才能对指针事件做出反应，否则忽略它们。

如果将此属性设置为 Qt.KeyboardModifierMask（默认值），则 PointerHandler 会忽略修饰键。

例如，Item 可以有两个相同类型的处理器，其中一个只有在所需的键盘修饰符按下时才启用

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

如果您将 acceptedModifiers 设置为修饰键的或操作组合，这意味着必须按下这些修饰符中的所有修饰符才能激活处理器

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}

以下是可以使用的修饰符

如果您需要的复杂行为超出了通过组合多个具有多个修饰标志的处理程序能够实现的范围，您可以在JavaScript代码中检查修饰键。

Item {
    TapHandler {
        onTapped:
            switch (point.modifiers) {
            case Qt.ControlModifier | Qt.AltModifier:
                console.log("CTRL+ALT");
                break;
            case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
                console.log("CTRL+META+ALT");
                break;
            default:
                console.log("other modifiers", point.modifiers);
                break;
            }
    }
}

另请参阅: Qt::KeyboardModifier.

此类Pointer Handler可以激活的类型指点设备（手指、笔、橡皮擦等）。

默认情况下，此属性设置为PointerDevice.AllPointerTypes。如果您将其设置为设备类型的或组合，它将忽略来自不匹配的设备的事件。

例如，可以通过两个处理程序，使一个控件以某种方式响应用户的鼠标、触摸和笔点击，但是如果用橡皮擦工具在绘图板上点击，则删除自己。

Rectangle {
   id: rect
   TapHandler {
       acceptedPointerTypes: PointerDevice.Generic | PointerDevice.Finger | PointerDevice.Pen
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedPointerTypes: PointerDevice.Eraser
       onTapped: rect.destroy()
   }
}

只要此输入处理程序成功独占捕获一个或多个eventPoints，此值就为true，这样就承担了对此或这些点的唯一处理责任。这意味着它将根据这些点的移动来保持其属性的最新状态，并积极操纵其target（如果有的话）。

此属性在鼠标悬停在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.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

默认值未设置，这允许cursor在parent项中出现。此属性可以通过将其设置为未定义来重置为其初始条件。

另请参阅： Qt::CursorShape、QQuickItem::cursor() 以及 HoverHandler::cursorShape.

用户必须拖动eventPoint的像素距离，才能将其视为拖动手势。

默认值取决于平台和屏幕分辨率。可以通过将其设置为未定义将其重置为默认值。拖动手势开始时的行为在不同的处理程序中会有所不同。

如果禁用PointerHandler，它将拒绝所有事件且不会发出任何信号。

确定singleTapped() 和 doubleTapped() 信号 exclusive Signals 的唯一性。

此属性自 Qt 6.5 起被引入。

轻轻触碰或长按手势被识别的空间约束，除在longPressThreshold之前必须释放之外。如果这些约束未满足，则tapped 信号不会发出，且tapCount 不会增加。如果违反空間约束，pressed 从 true 立即转变为 false，无论按住的时间长短如何。

gesturePolicy 还会影响以下所述的抓取行为。

Item {
    width: 120; height: 80

    component Button : Rectangle {
        TapHandler {
            id: tapHandler
            gesturePolicy: TapHandler.DragThreshold // the default
            onTapped: tapFlash.start()
        }
    }

    Button { x: 10; y: 10 }
    Button { x: 30; y: 30 }
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.WithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.ReleaseWithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: menuPopupHandler
    gesturePolicy: TapHandler.DragWithinBounds
    onPressedChanged:
        if (pressed) {
            menu.x = point.position.x - menu.width / 2
            menu.y = point.position.y - menu.height / 2
        } else {
            feedback.text = menu.highlightedMenuItem
            selectFlash.start()
        }
    onCanceled: feedback.text = "canceled"
}

Qt Quick 示例 - 指针处理器演示了这些用例的使用方法。

该属性指明了处理器逻辑决定接管独占捕获时或被其他处理器请求批准捕获接管或取消时的权限。

默认值为 PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything，允许大多数接管场景，但避免了例如两个 PinchHandlers 在相同触摸点上互相争夺的情况。

触发长按手势并发出 longPressed() 信号所需要按下 eventPoint 的秒数。如果该值大于 0。如果在规定时间内点被释放，且 gesturePolicy 约束得到满足，则可以检测到点击。如果 longPressThreshold 为 0，计时器将禁用且不会发出信号。如果 longPressThreshold 被设置为 undefined，则使用默认值，可以从此属性读取。

默认值为 QStyleHints::mousePressAndHoldInterval() 转换为秒。

此边缘超出了父项的边界，在此范围内 eventPoint 可以激活此处理器。例如，在 PinchHandler 中，如果 target 也是 parent，将其设置为至少与普通用户手指宽度一半的距离是有用的，这样即使 parent 缩小到非常小的尺寸，捏合手势仍然是可能的。或者，如果基于 TapHandler 的按钮放置在屏幕边缘附近，则可以用来符合菲茨定律：即使按钮在视觉上与边缘隔了几像素，也能对屏幕边缘的鼠标点击作出反应。

默认值是 0。

作为处理程序作用域的 Item；声明它的項目。处理程序将代表此项处理事件，这意味着如果其至少一个 eventPoints 发生在该项的内部，则指针事件是相关的。最初 target() 是相同的，但可以被重新分配。

另请参阅target 和 QObject::parent。

当前正在处理的 eventPoint。当没有正在处理点时，此对象将重置到默认值（所有坐标都是 0）。

当鼠标或触摸点按下，且从按下以来有任何移动都符合当前的 gesturePolicy 时，保持为真。当 eventPoint 释放或策略被违反时，pressed 将更改为 false。

在时间和空间约束内发生的点击次数，这些点击被视为单个手势。如果按钮更改，计数器将重置为 1。例如，要检测三连击，可以编写

Rectangle {
    width: 100; height: 30
    signal tripleTap
    TapHandler {
        acceptedButtons: Qt.AllButtons
        onTapped: if (tapCount == 3) tripleTap()
    }
}

此处理程序将操作的项目。

默认情况下，它与parent相同，即声明处理器所在的项目项。然而，有时将目标设置为不同的项目项可能会很有用；为了在一个项目项内处理事件但操作另一个项目；或者将目标设置为null，以禁用默认行为并执行其他操作。

按下点在不超过拖拽阈值的情况下保持的时间（秒）。它至少会在每帧渲染时更新一次，这允许渲染显示长按后将被触发的动作的进度的动画。还可能根据按住的时间触发一系列操作。

小于零的值表示在此处理器对应的Item中没有按下点。

如果这个处理器已经抓取了指定的point，当不同的Pointer Handler或Item抢走抓取时，将发射此信号。

当gesturePolicy设置为TapHandler.DragWithinBounds，而在较短时间内双击parent项目项，并在短时间内进行移动，则会发射此信号（QStyleHints::mouseDoubleClickInterval()和QStyleHints::mouseDoubleClickDistance()或QStyleHints::touchDoubleTapDistance）。此信号总是在singleTapped、tapped和tapCountChanged之后出现。信号参数eventPoint包含有关被点击点的释放事件信息，而button是在哪个鼠标按钮上点击的，或者是在触摸屏上为NoButton。

当抓取以某种与此处理器相关的方式发生变化时，将发射此信号。

动词transition表示发生了什么。对象point是被抓取或取消抓取的点。

transition的有效值

当父项Item被按下并保持一段时间，且这个时间超过longPressThreshold时，会发出此信号。也就是说，如果你按住一个触摸点或按钮，而任何移动都不超过拖动阈值，那么当timeHeld超过longPressThreshold时，将发出longPressed信号。

当父项Item被轻触一次时，会发出此信号。经过一段大于QStyleHints::mouseDoubleClickInterval的时间后，可以再次轻触；但如果两次轻触之间的时间更短，则tapCount会增加。eventPoint信号参数包含有关被轻触点的释放事件的信息，而button是被点击的鼠标按钮，或在触摸屏上的NoButton。

当父项Item被轻触一次或多次（在指定的时距范围内）且当前tapCount与上一tapCount不同时，会发出此信号。

每次父项Item被轻触时，都会发出此信号。

也就是说，如果你在小于longPressThreshold的时间周期内按下并释放一个触摸点或按钮，而任何移动都不超过拖动阈值，那么在释放的时刻将发出tapped信号。信号参数eventPoint包含有关被轻触点的释放事件的信息，而button是被点击的鼠标按钮，或在触摸屏上的NoButton。

import QtQuick

Rectangle {
    width: 100
    height: 100

    TapHandler {
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onTapped: (eventPoint, button)=> console.log("tapped", eventPoint.device.name,
                                             "button", button,
                                             "@", eventPoint.scenePosition)
    }
}