HoverHandler QML Type

鼠标和数位板悬停处理程序。更多...

• 所有成员的列表，包括继承的成员

属性

• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• blocking : bool (since 6.3)
• cursorShape : Qt::CursorShape
• enabled : bool
• grabPermissions : flags
• hovered : bool
• margin : real
• parent : Item
• point : handlerPoint
• target : Item

信号

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

详细说明

HoverHandler 可检测鼠标或平板触控笔光标的悬停状态。

绑定到hovered 属性是当光标进入或离开parent 项时做出响应的最简单方法。point 属性提供了更多详细信息，包括光标位置。acceptedDevices 、acceptedPointerTypes 和acceptedModifiers 属性可用于限定行为，以检测特定类型设备的悬停状态，或在按住修饰键时的悬停状态。

cursorShape 属性允许在hovered 变为true 时更改光标。

另请参阅 MouseArea 、PointHandler 和Qt Quick 示例——指针处理程序。

属性文档

acceptedDevices : flags

可以触发指针处理程序的指点设备类型。

默认情况下，此属性设置为PointerDevice.AllDevices 。若将其设置为设备类型的“或”组合，则会忽略来自不匹配设备的指针事件。

例如，可以通过两个处理程序，使某个项目对鼠标悬停做出一种响应，对触控笔悬停做出另一种响应：

import QtQuick

Rectangle {
    width: 150; height: 50; radius: 3
    color: mouse.hovered ? "goldenrod" : stylus.hovered ? "tomato" : "wheat"

    HoverHandler {
        id: stylus
        acceptedDevices: PointerDevice.Stylus
        cursorShape: Qt.CrossCursor
    }

    HoverHandler {
        id: mouse
        acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad
        cursorShape: Qt.PointingHandCursor
    }
}

可用的设备类型如下：

另请参阅 QInputDevice::DeviceType 。

acceptedModifiers : flags

如果设置了此属性，则只有在按下指定的键盘修饰键时，才会处理悬停事件。如果未按下这些修饰键，则该事件将被忽略。

该属性默认设置为Qt.KeyboardModifierMask ，这意味着无论是否按下任何修饰键，都会处理悬停事件。

例如，一个Item 可以有两个同类型的处理程序，其中一个仅在按下所需的键盘修饰键时才启用：

import QtQuick

Rectangle {
    width: 150; height: 50; radius: 3
    color: control.hovered ? "goldenrod" : shift.hovered ? "wheat" : "beige"

    HoverHandler {
        id: control
        acceptedModifiers: Qt.ControlModifier
        cursorShape: Qt.PointingHandCursor
    }

    HoverHandler {
        id: shift
        acceptedModifiers: Qt.ShiftModifier
        cursorShape: Qt.CrossCursor
    }
}

可用的修饰键如下：

另请参阅 Qt::KeyboardModifier 。

acceptedPointerTypes : flags

可触发指针处理程序的指针设备类型（通用、触控笔、橡皮擦等）。

默认情况下，此属性设置为PointerDevice.AllPointerTypes 。若将其设置为设备类型的“或”组合，则会忽略来自不匹配设备的事件。

例如，您可以根据触控笔或橡皮擦是否悬停在图形输入板上方，通过改变光标来提供反馈：

import QtQuick

Rectangle {
    id: rect
    width: 150; height: 150

    HoverHandler {
        id: stylus
        acceptedPointerTypes: PointerDevice.Pen
        cursorShape: Qt.CrossCursor
    }

    HoverHandler {
        id: eraser
        acceptedPointerTypes: PointerDevice.Eraser
        cursorShape: Qt.BlankCursor
        target: Image {
            parent: rect
            source: "images/cursor-eraser.png"
            visible: eraser.hovered
            x: eraser.point.position.x
            y: eraser.point.position.y - 32
        }
    }
}

可用的指针类型如下：

另请参阅 QPointingDevice::PointerType 。

active : bool [read-only]

当该输入处理器通过成功独占获取一个或多个eventPoints ，从而承担起处理这些事件点的全部责任时，此方法将返回true 。这意味着它会根据这些事件点的移动情况实时更新其属性，并主动操作其target （如有）。

blocking : bool [since 6.3]

该处理程序是否会阻止其后面的其他项目或处理程序同时被悬停。该属性的默认值为false 。

该属性在 Qt 6.3 中引入。

cursorShape : Qt::CursorShape

该属性存储了在hovered 为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

该属性的默认值未设定，这允许同一父项上的任何活动处理程序决定光标形状。通过将其设置为undefined ，可将该属性重置为初始状态。

如果任何已定义cursorShape 的处理程序中，其active 为指定值，则将显示该光标。否则，如果HoverHandler 中定义了cursorShape ，则将显示该光标。否则，将显示父项的cursor 。

另请参阅 Qt::CursorShape 和QQuickItem::cursor()。

enabled : bool

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

如果HoverHandler 的parent 属性设置为disabled ，则HoverHandler 默认仍会响应悬停事件。这是因为即使控件处于禁用状态，悬停反馈效果和工具提示仍可能有用。若希望在父控件禁用时禁用HoverHandler ，可以添加一个绑定：

Item {
    HoverHandler {
        enabled: parent.enabled
    }
}

grabPermissions : flags

此属性指定了当该处理程序的逻辑决定接管独占抓取时，或者当被其他处理程序请求批准接管或取消抓取时的权限。

默认值为PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything ，这允许大多数接管场景，但可避免例如两个 PinchHandler 争夺同一触点的情况。

hovered : bool [read-only]

当任何指针设备光标（鼠标或数位板）位于parent 项的边界内时，此规则即成立；若存在margin ，则边界范围将相应扩展。

margin : real

这是超出parent 控件边界范围的边距，eventPoint 可以在该范围内触发此处理程序。例如，在PinchHandler 中，当target 同时也是parent 时，将此值设置为至少相当于普通用户手指宽度一半的距离会很有用，这样即使parent 被缩放至非常小的尺寸，仍然可以执行捏合手势。 或者，如果将一个基于TapHandler 的按钮放置在屏幕边缘附近，则可以利用它来符合菲茨定律：即使该按钮在视觉上距离屏幕边缘有几个像素的间距，也能对屏幕边缘的鼠标点击做出响应。

默认值为 0。

parent : Item

Item ，即处理程序的作用域；Item 即其被声明的对象。处理程序将代表该 Item 处理事件，这意味着如果指针事件的至少一个eventPoints 发生在该 Item 的内部，则该事件与该 Item 相关。初始时，target() 与该 Item 相同，但可以被重新赋值。

另请参阅 target 和QObject::parent()。

point : handlerPoint [read-only]

当前正在处理的eventPoint 。当没有点正在被处理时，该对象将重置为默认值（所有坐标均为0）。

target : Item

该处理程序将操作的项。

默认情况下，它与parent 相同，即声明该处理程序的Item。不过，有时将目标设置为另一个Item会很有用，以便在某个Item中处理事件但操作另一个Item；或者设置为null ，以禁用默认行为并执行其他操作。

Signal 文档

canceled(eventPoint point)

如果该处理程序已经获取了给定的point ，当该获取被另一个指针处理程序或项目抢走时，就会发出此信号。

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

当抓取发生与该处理程序相关的某种变化时，会发出此信号。

transition （动词）说明了发生了什么。point （对象）是被抓取或释放的点。

transition 的有效值包括：