PinchHandler QML Type

ピンチジェスチャーのハンドラー。詳細...

• 継承されたメンバーを含むすべてのメンバーの一覧
• 非推奨のメンバ

プロパティ

• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• activeRotation : real
• activeScale : real
• activeTranslation : point
• centroid : QtQuick::handlerPoint
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• persistentRotation : real
• persistentScale : real
• persistentTranslation : point
• rotationAxis
  • rotationAxis.activeValue : real
  • rotationAxis.enabled : bool
  • rotationAxis.maximum : real
  • rotationAxis.minimum : real
• scaleAxis
  • scaleAxis.activeValue : real
  • scaleAxis.enabled : bool
  • scaleAxis.maximum : real
  • scaleAxis.minimum : real
• target : Item
• xAxis
  • xAxis.activeValue : real
  • xAxis.enabled : bool
  • xAxis.maximum : real
  • xAxis.minimum : real
• yAxis
  • yAxis.activeValue : real
  • yAxis.enabled : bool
  • yAxis.maximum : real
  • yAxis.minimum : real

信号

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• rotationChanged(qreal delta)
• scaleChanged(qreal delta)
• translationChanged(QVector2D delta)

詳細な説明

PinchHandlerは、複数指のジェスチャーを解釈して、アイテムをインタラクティブに回転、ズーム、ドラッグするためのハンドラです。他の入力ハンドラと同様に、デフォルトでは完全に機能しており、宣言されているアイテムであるtarget を操作します。

import QtQuick

Rectangle {
    width: 400
    height: 300
    color: "lightsteelblue"
    PinchHandler { }
}

ドラッグ、回転、ズームの範囲を制限するプロパティを備えています。

ある Item 内で宣言されているものの、別のtarget が割り当てられている場合、外側の Item の境界内でイベントを処理しますが、操作対象となるのはtarget アイテムになります：

import QtQuick

Item {
    width: 640
    height: 480

    Rectangle {
        id: map
        color: "aqua"
        width: 400
        height: 300
    }

    PinchHandler {
        target: map
    }
}

3つ目の使用方法は、target をnull に設定し、プロパティの変更に対して別の方法で反応させることです：

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}

関連項目： PinchArea 、QPointerEvent::pointCount()、QNativeGestureEvent::fingerCount()、およびQt Quick の例 - ポインタハンドラ。

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

acceptedDevices : flags

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

デフォルトでは、このプロパティはPointerDevice.AllDevices に設定されています。デバイスタイプの「OR」組み合わせに設定した場合、条件に一致しないデバイスからのイベントは無視されます。

たとえば、2つのハンドラを使用することで、コントロールがマウスやスタイラスのクリックにはある方法で、タッチスクリーンのタップには別の方法で反応するように設定できます。

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

acceptedModifiers : flags

このプロパティが設定されている場合、ポインタイベントに反応するには、指定されたキーボード修飾キーを押す必要があり、そうでない場合はそれらを無視します。

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

たとえば、Item には同じタイプのハンドラが2つあり、そのうち1つは必要なキーボード修飾キーが押されている場合にのみ有効になるように設定できます。

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

acceptedModifiers を修飾キーの「OR」組み合わせに設定した場合、そのハンドラーをアクティブにするには、それらの修飾キーがすべて押されている必要があります：

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も参照してください 。

acceptedPointerTypes : flags

このポインタハンドラを起動できるポインティングデバイスの種類（指、スタイラス、消しゴムなど）。

デフォルトでは、このプロパティはPointerDevice.AllPointerTypes に設定されています。デバイスタイプの「OR」組み合わせに設定した場合、一致しないdevices からのイベントは無視されます。

たとえば、あるコントロールがマウス、タッチ、スタイラスのクリックには何らかの形で反応するようにしつつ、グラフィックタブレット上の消しゴムツールでタップされた場合は自身を削除するようにするには、次の2つのハンドラを使用します。

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

active : bool [read-only]

このプロパティは、すべての制約（特に `minimumPointCount ` および `maximumPointCount`）が満たされ、かつ `target`（存在する場合）が操作されている場合に、true となります。

activeRotation : real [read-only]

ピンチジェスチャーの回転角度（単位：度）。正の値は時計回りを表します。ジェスチャーが開始された時点では、0 となります。target が null でない場合、この値は自動的にそのrotation に加算されます。それ以外の場合は、バインディングを使用してこの値を用いて任意の処理を行うことができます。

QtQuick::PinchHandler::rotationAxis.activeValueも参照してください 。

activeScale : real [read-only]

ピンチジェスチャー実行中の拡大率。ジェスチャーの開始時は 1.0 であり、タッチポイントが離れるにつれて増加し、タッチポイントが近づくにつれて減少します。target が null でない場合、そのscale には自動的にこの値が乗算されます。そうでない場合は、バインディングを使用してこの値で任意の処理を行うことができます。

QtQuick::PinchHandler::scaleAxis.activeValueも参照してください 。

activeTranslation : point [read-only]

ピンチジェスチャーの実行中の点群の並進量です。ジェスチャーが開始された時点では0, 0 となり、eventPoint(s) を右下方向にドラッグするにつれて増加します。ジェスチャーが終了した後もこの値は維持され、次のピンチジェスチャーが開始されると、再び0, 0 にリセットされます。

centroid : QtQuick::handlerPoint [read-only]

現在押されているタッチポイントのちょうど中央にある点です。target はこの点を軸として回転します。

cursorShape : Qt::CursorShape

このプロパティは、active がtrue に設定されている間、parent アイテムにマウスをホバーさせた際に表示されるカーソルの形状を保持します。

利用可能なカーソルの形状は以下の通りです:

• 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.ForbiddenCursor
• Qt.WhatIsThisカーソル
• Qt.BusyCursor
• Qt.開いた手のカーソル
• Qt.閉じた手のカーソル
• Qt.ドラッグコピーカーソル
• Qt.ドラッグ移動カーソル
• Qt.DragLinkCursor

デフォルト値は設定されておらず、これによりparent 項目のcursor が表示されます。このプロパティは、undefinedに設定することで、初期状態と同じ状態に戻すことができます。

関連項目： Qt::CursorShape 、QQuickItem::cursor()、およびHoverHandler::cursorShape 。

dragThreshold : int

eventPoint をドラッグジェスチャーとして認識させるために、ユーザーがドラッグしなければならないピクセル単位の距離。

デフォルト値はプラットフォームや画面解像度によって異なります。これを `undefined` に設定することで、デフォルト値に戻すことができます。ドラッグジェスチャが開始された際の動作は、ハンドラによって異なります。

enabled : bool

PointerHandler が無効になっている場合、すべてのイベントを拒否し、シグナルは一切発信されません。

PointerHandler のparent がdisabled に設定されている場合、enabled プロパティがtrue のままであっても、ハンドラーは事実上無効化されます。

grabPermissions : flags

このプロパティは、このハンドラのロジックが排他的なグラブを引き継ぐことを決定した場合、または別のハンドラからグラブの引き継ぎや取り消しの承認を求められた場合の権限を指定します。

デフォルトは `PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything ` であり、ほとんどの引き継ぎシナリオを許可しますが、例えば 2 つの `PinchHandler` が同じタッチポイントを奪い合うような事態は回避します。

margin : real

parent 項目の境界線の外側にある余白で、eventPoint がこのハンドラを起動できる範囲です。たとえば、PinchHandler で、target が同時にparent でもある場合、この値を一般的なユーザーの指の幅の少なくとも半分に設定しておくと便利です。そうすれば、parent が非常に小さなサイズに縮小されても、ピンチジェスチャが引き続き可能になります。 あるいは、TapHandler ベースのボタンを画面の端近くに配置する場合、これをフィッツの法則に準拠させるために利用できます。つまり、ボタンが視覚的には画面の端から数ピクセル離れているにもかかわらず、画面の端でのマウスクリックに反応するようにするのです。

デフォルト値は 0 です。

parent : Item

Item は、ハンドラの適用範囲であり、それが宣言されたItemです。ハンドラはこのItemに代わってイベントを処理します。つまり、ポインタイベントは、そのeventPoints のうち少なくとも1つがItemの内部で発生する場合にのみ関連します。初期状態では、target() は同一ですが、再割り当てが可能です。

target およびQObject::parent()も参照してください 。

persistentRotation : real

target がnullでない場合に、これに適用される回転です。そうでない場合、バインディングを使用してこの値に対して任意の処理を行うことができます。ピンチジェスチャーが実行されている間は、activeRotation が継続的に加算されます。ジェスチャーが終了した後は、その値は変更されず、次のピンチジェスチャーが開始されると、再びactiveRotation によって値が変更され始めます。

このプロパティを設定することで、例えば別のハンドラによって設定された回転など、他の方法で設定された回転と基底の回転を同期させることができます。このプロパティを直接設定しても、activeRotation は変更されず、rotationChanged(0) が発行されます。

persistentScale : real

target がnullでない場合に、自動的に設定されるスケール係数です。nullの場合、バインディングを使用してこの値で任意の処理を行うことができます。ピンチジェスチャーが実行されている間は、この値にactiveScale が継続的に乗算されます。ジェスチャーが終了した後は値が固定され、次のピンチジェスチャーが開始されると、再びactiveScale が乗算されるようになります。

このプロパティを設定することで、基底スケールを、例えば別のハンドラによって設定されたスケールと同期させることができます。このプロパティを直接設定しても、activeScale は変更されず、scaleChanged(1) が発行されます。

persistentTranslation : point

target がnull でない場合に適用される変換です。そうでない場合、バインディングを使用してこの値に対して任意の処理を行うことができます。ピンチジェスチャーが実行されている間、activeTranslation が継続的にこの値に加算されますが、ジェスチャーが終了した後は値は変わりません。

このプロパティを設定することで、ベースのトランスレーションを、別の方法（たとえば別のハンドラなど）で設定されたトランスレーションと同期させることができます。このプロパティを直接設定しても、activeTranslation は変化せず、translationChanged({0, 0}) が発行されます。

rotationAxis group

rotationAxis タッチポイントのグループの回転に応じて、target 項目のrotation を設定するための制約を制御します。

minimum は、許容される最小の回転角度です。maximum は、許容される最大の回転角度です。enabled がtrueの場合、回転が許可されます。activeValue は、QtQuick::PinchHandler::activeRotation と同じです。

activeValueChanged シグナルは、activeValue が変更された際に、その変更量を提供するために発火します。これは、複数のハンドラを介して1つのプロパティを段階的に調整することを目的としています。

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

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

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

scaleAxis group

scaleAxis タッチポイント間の距離に基づいて、target 項目のscale を設定するための制約を制御します。

minimum は、許容される最小スケールです。maximum は、許容される最大スケールです。enabled がtrueの場合、スケーリングが許可されます。activeValue は、QtQuick::PinchHandler::activeScale と同じです。

activeValueChanged シグナルは、activeValue が変更された際に発火し、増分変更の乗数を提供します。これは、複数のハンドラを介して1つのプロパティを増分的に調整することを目的としています。

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

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

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

target : Item

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

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

xAxis group

xAxis target 項目の水平方向の平行移動に関する制約を制御します。

minimum は、平行移動において許容される最小の x 座標です。maximum は、平行移動において許容される最大の x 座標です。enabled が true の場合、水平方向のドラッグが許可されます。

`activeValue `が変更されると、`activeValueChanged `シグナルが発信され、変更された増分値が提供されます。これは、複数のハンドラを介して1つのプロパティを段階的に調整することを目的としています。

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

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

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

yAxis group

yAxis target 項目の垂直方向の平行移動に関する制約を制御します。

minimum は、平行移動において許容される最小の y 座標です。maximum は、平行移動において許容される最大の y 座標です。enabled が true の場合、垂直方向のドラッグが許可されます。

`activeValue ` が変更されると、その変更量を示す `activeValueChanged ` シグナルが発行されます。これは、複数のハンドラを介して 1 つのプロパティを段階的に調整することを目的としています。

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

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

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

Signalのドキュメント

canceled(eventPoint point)

このハンドラーがすでに指定されたpoint を取得している場合、別のポインタハンドラーまたはアイテムによってその取得が奪われたときに、このシグナルが発行されます。

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

このシグナルは、グラブにこのハンドラに関連する何らかの変化が生じた際に発せられます。

transition （動詞）は、何が発生したかを示します。point （目的語）は、グラブまたはグラブ解除の対象となったポイントです。

transition の有効な値は次のとおりです：

rotationChanged(qreal delta)

rotationChanged シグナルは、activeRotation （したがってpersistentRotation ）が変化したときに発火します。delta の値は、回転の加算的な変化量を示します。たとえば、ユーザーが指を動かしてピンチ距離を変更し、activeRotation が10度から30度に変化した場合、rotationChanged(20) が発火します。これを利用して、アイテムの回転を段階的に変更することができます。

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

scaleChanged(qreal delta)

「scaleChanged 」シグナルは、activeScale （したがってpersistentScale ）が変化したときに発行されます。delta の値は、スケールの乗算的な変化量を示します。たとえば、ユーザーが指を動かしてピンチ距離を変更し、activeScale が2から2.5に変化した場合、「scaleChanged(1.25) 」が発行されます。これを利用して、アイテムのスケールを段階的に変更することができます：

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

translationChanged(QVector2D delta)

`translationChanged ` シグナルは、`activeTranslation `（したがって `persistentTranslation`）が変化したときに発火します。ベクトル `delta ` は、並進位置の変化量を示します。これを利用して、アイテムの位置を段階的に変更することができます：

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}