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は、ユーザーがマウスホイールを回転させた際に、アイテムの数値プロパティを対話的に操作するために使用されるハンドラです。他の入力ハンドラと同様に、デフォルトでは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 には 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 情報を含むイベントを処理する場合、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 のうち少なくとも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

このハンドラが操作するアイテム。

デフォルトでは、これはparent 、つまりハンドラーが宣言されている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 を受信するたびに発火します。つまり、ホイールが動かされたり、スクロールジェスチャが更新されたりするたびに発火します。