WheelHandler QML Type

鼠标滚轮处理程序。更多...

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

属性

• acceptedDevices : flags
• acceptedModifiers : flags
• active : bool
• activeTimeout : real
• blocking : bool (since 6.3)
• enabled : bool
• invertible : bool
• margin : real
• orientation : enumeration
• parent : Item
• point : handlerPoint
• property : string
• rotation : real
• rotationScale : real
• target : Item
• targetScaleMultiplier : real
• targetTransformAroundCursor : bool

信号

• wheel(WheelEvent event)

详细说明

WheelHandler 是一种处理程序，用于在用户滚动鼠标滚轮时交互式地操作 Item 的某个数值属性。与其他输入处理程序一样，默认情况下它会操作其目标属性（target ）。声明 `property ` 可控制将要操作的目标属性：

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        onWheel: (event)=> console.log("rotation", event.angleDelta.y,
                                       "scaled", rotation, "@", point.position,
                                       "=>", parent.rotation)
    }
}

BoundaryRule 与WheelHandler（以及其他输入处理程序）结合使用时，该声明非常有用，可用于定义目标属性的允许值范围。 例如，可以通过结合使用 WheelHandler 和DragHandler 来实现滚动功能：当用户滚动鼠标滚轮或在触摸屏上拖动项目时，通过 操作可滚动项目的y 属性，同时使用BoundaryRule 限制从顶部到底部的移动范围：

import QtQuick
import Qt.labs.animation

Item {
    width: 320; height: 480
    Flow {
        id: content
        width: parent.width
        spacing: 2; padding: 2

        WheelHandler {
            orientation: Qt.Vertical
            property: "y"
            rotationScale: 15
            acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        DragHandler {
            xAxis.enabled: false
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        BoundaryRule on y {
            id: ybr
            minimum: content.parent.height - content.height
            maximum: 0
            minimumOvershoot: 400; maximumOvershoot: 400
            overshootFilter: BoundaryRule.Peak
        }

        Repeater {
            model: 1000
            Rectangle { color: "gray"; width: 10 + Math.random() * 100; height: 15 }
        }
    }
}

此外，如果未设置property 或target 为null，WheelHandler将不会自动进行任何操作；但可以将rotation 属性用于绑定以控制其他属性，或者实现onWheel 并直接处理滚轮事件。

默认情况下，WheelHandler 仅处理旋转鼠标滚轮；可通过设置 `acceptedDevices` 来更改此行为。

另请参阅 MouseArea 、Flickable 以及Qt Quick 示例——指针处理程序。

属性文档

acceptedDevices : flags

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

默认情况下，此属性设置为PointerDevice.Mouse ，以便仅响应来自真实鼠标滚轮的事件。

WheelHandler 通过将 acceptedDevices 设置为PointerDevice.Mouse | PointerDevice.TouchPad ，可使其同时响应鼠标滚轮和触摸板的滚动操作。

acceptedModifiers : flags

如果设置了此属性，则必须按下指定的键盘修饰键才能响应滚轮事件，否则将忽略这些事件。

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

例如，一个Item 可能有两个处理程序，其中一个仅在按下所需的键盘修饰键时才启用，而另一个则在按下任何修饰键时忽略事件：

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        acceptedModifiers: Qt.ControlModifier
    }

    WheelHandler {
        property: "scale"
        acceptedModifiers: Qt.NoModifier
    }
}

可用的修饰键如下：

另请参阅 Qt::KeyboardModifier 。

active : bool [read-only]

当WheelHandler 最近看到QWheelEvent ，正在保持其属性的最新状态，并且正在积极操作其target （如有）时，此条件成立：true 。

另请参阅 activeTimeout 。

activeTimeout : real

如果不再接收到滚轮事件，active 属性将在该时间（以秒为单位）后恢复为false 。默认值为0.1 （100毫秒）。

当WheelHandler 处理包含scroll phase 信息的事件（例如来自某些触控板的事件）时，一旦接收到具有Qt::ScrollEnd 阶段的事件，active 属性将立即变为false ；在这种情况下，超时设置便不再必要。 但带滚轮的传统鼠标不提供滚动阶段：鼠标无法检测到用户何时决定停止滚动，因此当时间经过这么久后，active 属性会过渡到false 。

另请参阅 QWheelEvent::phase()。

blocking : bool [since 6.3]

该处理程序是否阻止其后面的其他项目或处理程序处理相同的滚轮事件。该属性的默认值为true 。

该属性在 Qt 6.3 中引入。

enabled : bool

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

如果PointerHandler 的parent 属性设置为disabled ，则该处理程序也将被实质上禁用，即使enabled 属性仍保持为true 。

invertible : bool

当QWheelEvent::inverted 为true 时，是否反转属性更改的方向。默认值为true 。

如果操作系统具有“自然滚动”设置，使得滚动方向与手指移动方向一致，那么当此属性设置为true 时，且WheelHandler 直接对target 进行属性设置，移动方向将与系统设置保持一致。 如果此属性设置为false ，则会反转rotation ，从而使移动方向始终与手指移动方向一致。

margin : real

这是“parent ”项边界之外的区域，WheelHandler 可以在该区域内做出响应。例如，如果将margin 设置为10 ，则即使将光标移至该项可见边缘外最多10像素处，它仍会对滚轮操作做出响应：

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        margin: 10
    }
}

默认值为0 。

orientation : enumeration

应响应哪个滚轮。默认是Qt.Vertical 。

并非每只鼠标都配备Horizontal 滚轮；有时通过侧向倾斜滚轮来模拟该功能。触控板通常可以生成垂直和水平的滚轮事件。

parent : Item

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

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

point : handlerPoint [read-only]

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

property : string

当鼠标滚轮旋转时，target 上将被修改的属性。

默认情况下不修改任何属性（空字符串）。当没有目标属性被自动修改时，您可以使用绑定以任意方式响应鼠标滚轮的旋转。

您可以使用鼠标滚轮调整任何数值属性。例如，如果将property 设置为x ，那么随着滚轮的旋转，target 将水平移动。以下属性具有特殊行为：

给定目标属性的调整值始终按rotationScale 进行缩放。

rotation : real

自上次设置此属性以来，鼠标滚轮旋转的角度，单位为滚轮度。

正值表示滚轮向上/向右旋转；负值表示滚轮向下/向左旋转。

基本的鼠标滚轮以 15 度为一个步长工作。

启动时的默认值为0 。该值可随时通过编程方式设置为任意数值。随着用户旋转鼠标滚轮，该值将据此进行调整。

另请参阅 orientation 。

rotationScale : real

要应用于rotation 属性的缩放比例，以及target 项上的property （如有）的缩放比例。默认值为1，因此rotation 将以旋转角度为单位。可以将其设置为负数，以反转鼠标滚轮旋转方向的效果。

target : Item

该处理程序将操作的 Item。

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

targetScaleMultiplier : real

当rotation 变化15度时，target scale 应乘以的系数。仅当property 为"scale" 时，此参数才生效。

scale 将乘以targetScaleMultiplier ^{angleDelta *rotationScale / 15}。默认值为2 ^1/3，这意味着如果rotationScale 保持默认值，且鼠标滚轮旋转一个“点击”（15 度），则target 的缩放比例约为 1.25； 经过三次“点击”后，其大小将翻倍或减半，具体取决于滚轮的旋转方向。若希望每旋转两次滚轮就使大小翻倍或减半，请将此值设置为2 ^1/2(1.4142)。 若希望其缩放方向与滚轮旋转方向相反，请将“rotationScale ”设置为负值。

targetTransformAroundCursor : bool

在调整property 时，target 是否应自动重新定位，使其围绕鼠标光标位置进行变换。默认值为true 。

如果将“property ”设置为“"rotation" ”，且“targetTransformAroundCursor”为“true ”，则当滚轮旋转时，“target ”项将原地围绕鼠标光标位置旋转。如果“targetTransformAroundCursor ”为“false ”，则它将围绕其“transformOrigin ”旋转。

Signal 文档

wheel(WheelEvent event)

每当此处理程序接收到类型为QWheelEvent 的event 时，都会触发此信号：也就是说，每次滚轮移动或滚动手势更新时都会触发。