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（および他のInput Handler）と組み合わせて、ターゲットプロパティが持つことができる値の許容範囲を宣言するのに非常に便利です。例えば、WheelHandlerとDragHandler の組み合わせを使ってスクロールを実装し、ユーザがホイールを回転させたり、タッチスクリーン上でアイテムをドラッグしたときに、スクロール可能なItemの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 Examples - Pointer Handlersも参照してください 。

プロパティ・ドキュメント

acceptedDevices : flags

このハンドラを起動できるポインティングデバイスの種類。

デフォルトでは、このプロパティはPointerDevice.Mouse に設定され、実際のマウスホイールからのイベントのみに反応するようになっています。

WheelHandler は、acceptedDevices をPointerDevice.Mouse | PointerDevice.TouchPad に設定することで、マウスホイールとタッチパッドの両方のスクロールに反応するようにすることができます。

acceptedModifiers : flags

このプロパティが設定されると、ホイールイベントに反応するために、指定されたキーボード修飾キーが押されることを要求し、そうでなければ無視する。

このプロパティがQt.KeyboardModifierMask （デフォルト値）に設定されている場合、WheelHandler は修飾キーを無視する。

例えば、Item は2つのハンドラを持つことができ、1つは必要なキーボード修飾子が押された場合のみ有効になり、もう1つはどの修飾子が押されてもイベントを無視する：

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 ms)。

いくつかのタッチパッドからのイベントなど、WheelHandler がscroll phase 情報を含むイベントを処理する場合、active プロパティはQt::ScrollEnd フェーズのイベントを受信するとすぐに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

WheelHandler が反応できるparent アイテムの境界を超えたマージン。たとえば、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 の少なくとも1つがItemの内部で発生する場合に関連する。最初はtarget() が同じであるが、再割り当てが可能である。

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。

デフォルトでは、ハンドラが宣言されているItem（parent ）と同じである。しかし、あるItem内のイベントを処理しながら別のItemを操作するために、ターゲットを別のItemに設定したり、null 、デフォルトの動作を無効にし、代わりに別のことを行うために、ターゲットを別のItemに設定すると便利な場合がある。

targetScaleMultiplier : real

rotation が 15 度変化するたびに、target scale 。これは、property が"scale" の場合にのみ関係する。

scale にはtargetScaleMultiplier ^{angleDelta *rotationScale / 15} が掛けられる。デフォルトは2 ^1/3 です。つまり、rotationScale がデフォルト値のままで、マウスホイールが1回「クリック」（15度）回転すると、target はおよそ1.25倍されます。3回「クリック」すると、ホイールの回転方向によって、そのサイズは2倍または半分になります。ホイールを2回クリックするごとに2倍または半分にしたい場合は、2 ^1/2(1.4142)に設定します。ホイールが回転する方向と逆にスケールさせたい場合は、rotationScale を負の値に設定します。

targetTransformAroundCursor : bool

property を調整している間、マウスカーソルの位置を中心に変形するようにtarget を自動的に再配置するかどうか。デフォルトはtrue である。

property が"rotation" に設定され、targetTransformAroundCursor がtrue である場合、ホイールが回転されると、target アイテムは、マウスカーソル位置を中心にその場で回転する。targetTransformAroundCursor がfalse の場合、代わりにtransformOrigin を中心に回転する。

シグナル・ドキュメント

wheel(WheelEvent event)

このシグナルは、このハンドラがQWheelEvent 型のevent を受け取るたびに、つまりホイールが動かされたりスクロールジェスチャが更新されたりするたびに発せられる。