TapHandler QML Type

タップとクリックのハンドラ。もっと見る...

• 継承されたメンバーを含む全メンバーのリスト

プロパティ

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• exclusiveSignals : enumeration (since 6.5)
• gesturePolicy : enumeration
• grabPermissions : flags
• longPressThreshold : real
• margin : real
• parent : Item
• point : handlerPoint
• pressed : bool
• tapCount : int
• target : Item
• timeHeld : real

信号

• canceled(eventPoint point)
• doubleTapped(eventPoint eventPoint, Qt::MouseButton button)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• longPressed()
• singleTapped(eventPoint eventPoint, Qt::MouseButton button)
• tapCountChanged()
• tapped(eventPoint eventPoint, Qt::MouseButton button)

詳細説明

TapHandler は、タッチスクリーンのタップまたはマウスのクリックのハンドラです。

有効なタップジェスチャの検出はgesturePolicy に依存します。デフォルト値は DragThreshold で、押下と解放が空間的にも時間的にも近接している必要があります。この場合、TapHandler はパッシブグラブのみで機能するため、他のアイテムや入力ハンドラへのイベント配信を妨げません。したがって、デフォルトのgesturePolicy は、バインディングおよび/または JavaScript コールバックを持つ TapHandler を追加して、既存のコントロールまたはアイテムの動作を変更する場合に便利です。

QPushButtonボタンを押してから気が変わったら、クリックをキャンセルするためにボタンの端からずっとドラッグする必要があります。この使用例では、gesturePolicy をTapHandler.ReleaseWithinBounds に設定します。

import QtQuick

Rectangle {
    id: button
    signal clicked
    property alias text: buttonLabel.text

    height: Math.max(Screen.pixelDensity * 7, buttonLabel.implicitHeight * 1.2)
    width: Math.max(Screen.pixelDensity * 11, buttonLabel.implicitWidth * 1.3)
    radius: 3
    property color dark: Qt.darker(palette.button, 1.3)
    gradient: Gradient {
        GradientStop { position: 0.0; color: tapHandler.pressed ? dark : palette.button }
        GradientStop { position: 1.0; color: dark }
    }

    TapHandler {
        id: tapHandler
        gesturePolicy: TapHandler.ReleaseWithinBounds
        onTapped: button.clicked()
    }

    Text {
        id: buttonLabel
        text: "Click Me"
        color: palette.buttonText
        anchors.centerIn: parent
    }
}

マルチタップジェスチャー（ダブルタップ、トリプルタップなど）の場合、移動距離はマウスでQStyleHints::mouseDoubleClickDistance （）、タッチでQStyleHints::touchDoubleTapDistance （）を超えてはならず、タップ間の時間はQStyleHints::mouseDoubleClickInterval （）を超えてはなりません。

MouseArea とQt Quick Examples - Pointer Handlersも参照してください 。

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

acceptedButtons : flags

このポインタハンドラを起動できるマウスボタン。

デフォルトでは、このプロパティはQt.LeftButton に設定されています。 マウスボタンの OR の組み合わせに設定することができ、他のボタンからのイベントは無視されます。

例えば、コントロールが左クリックと右クリックに異なる方法で反応するように、2つのハンドラを設定することができます：

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

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]

これは、この入力ハンドラが1つ以上のeventPoints 、それらのポ イントの排他的なグラブに成功することで、それらのハンドラをハンドリングす るための唯一の責任を取ったときはいつでも、true を保持する。これは、この入力ハンドラが、それらのイベントポイントの動きに応じてその プロパティを最新に保ち、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.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

デフォルト値は設定されていないため、parent アイテムのcursor が表示されます。このプロパティは、undefined に設定することで、同じ初期状態に戻すことができます。

Qt::CursorShape 、QQuickItem::cursor()、HoverHandler::cursorShapeも参照のこと 。

dragThreshold : int

ドラッグ ジェスチャとして扱うために、ユーザーがeventPoint をドラッグする距離をピクセル単位で指定します。

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

enabled : bool

PointerHandler が無効化されると、すべてのイベントを拒否し、シグナルは発せられない。

PointerHandler のparent がdisabled の場合、enabled プロパティがtrue のままでも、ハンドラは事実上無効になる。

exclusiveSignals : enumeration [since 6.5]

singleTapped() とdoubleTapped() シグナルの排他性を決定する。

このプロパティはQt 6.5で導入されました。

gesturePolicy : enumeration

タップまたは長押しジェスチャーが認識されるための空間的制約。さらに、longPressThreshold が経過する前にリリースされなければならないという制約もある。これらの制約が満たされない場合、tapped シグナルは発せられず、tapCount はインクリメントされない。空間制約に違反した場合、pressed 、保持された時間に関係なく、直ちにtrueからfalseに遷移する。

gesturePolicy は、後述するグラブの動作にも影響する。

Item {
    width: 120; height: 80

    component Button : Rectangle {
        TapHandler {
            id: tapHandler
            gesturePolicy: TapHandler.DragThreshold // the default
            onTapped: tapFlash.start()
        }
    }

    Button { x: 10; y: 10 }
    Button { x: 30; y: 30 }
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.WithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.ReleaseWithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: menuPopupHandler
    gesturePolicy: TapHandler.DragWithinBounds
    onPressedChanged:
        if (pressed) {
            menu.x = point.position.x - menu.width / 2
            menu.y = point.position.y - menu.height / 2
        } else {
            feedback.text = menu.highlightedMenuItem
            selectFlash.start()
        }
    onCanceled: feedback.text = "canceled"
}

Qt Quick Examples - Pointer Handlersは、これらの使用例を示しています。

grabPermissions : flags

このプロパティは、このハンドラのロジックが排他グラブを引き継ぐことを決定した場合、または他のハンドラからグラブの引き継ぎやキャンセルを承認するよう求められた場合のパーミッションを指定します。

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

longPressThreshold : real

値が0 より大きい場合、長押しジェスチャをトリガしてlongPressed() シグナルを発するために、eventPoint が押されなければならない時間（秒）。この制限時間前にポイントが離された場合、gesturePolicy 制約が満たされていれば、タップを検出することができます。longPressThreshold が0 の場合、タイマーは無効になり、信号は発せられない。longPressThreshold がundefined に設定されている場合、代わりにデフォルト値が使用され、このプロパティから読み出すことができます。

デフォルト値は、秒に変換されたQStyleHints::mousePressAndHoldInterval() です。

margin : real

eventPoint がこのハンドラを起動できる、parent アイテムの境界を超えたマージン。例えば、target がparent でもあるようなPinchHandler では、parent が非常に小さいサイズに縮小されてもピンチジェスチャーが可能なように、一般的なユーザーの指の幅の半分以上の距離に設定すると便利です。また、TapHandler ベースのボタンが画面の端の近くに配置されている場合、フィッツの法則に準拠するために使用することができます：ボタンが視覚的に端から数ピクセル離れていても、画面の端でマウスクリックに反応します。

デフォルト値は0です。

parent : Item

ハンドラのスコープであるItem; それが宣言されたItem。ハンドラはこのItemに代わってイベントを処理する。つまり、ポインタイベントは、そのeventPoints の少なくとも1つがItemの内部で発生する場合に関連する。最初はtarget() が同じであるが、再割り当てが可能である。

target およびQObject::parent()も参照 。

point : handlerPoint [read-only]

eventPoint 現在扱われている点。現在扱われている点がない場合、このオブジェクトはデフォルト値（すべての座標が0）にリセットされる。

pressed : bool [read-only]

マウスまたはタッチポイントが押されるたびにtrueを保持し、押されてからの動きは現在のgesturePolicy に準拠する。eventPoint が離されるか、ポリシーに違反すると、pressed はfalse に変わる。

tapCount : int [read-only]

1つのジェスチャーとみなされる時間と空間の制約の中で発生したタップの数。ボタンが変更されると、カウンタは1にリセットされる。たとえば、トリプルタップを検出するには、次のように記述します：

Rectangle {
    width: 100; height: 30
    signal tripleTap
    TapHandler {
        acceptedButtons: Qt.AllButtons
        onTapped: if (tapCount == 3) tripleTap()
    }
}

target : Item

このハンドラが操作するItem。

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

timeHeld : real [read-only]

ドラッグのしきい値を超えることなく、押されたポイントが保持されている時間（秒）。レンダリングされるフレームごとに少なくとも1回更新され、長押しによってトリガーされるアクションの進行状況を示すアニメーションをレンダリングすることができます。また、長押しの長さに応じて、一連のアクションのいずれかをトリガーすることも可能です。

ゼロ未満の値は、このハンドラのItem 内にポイントが保持されていないことを意味する。

シグナル・ドキュメント

canceled(eventPoint point)

このハンドラがすでに与えられたpoint をグラブしている場合、グラブが別のポインタハンドラまたはアイテムによって盗まれると、このシグナルが発行されます。

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

この信号は、parent アイテムが短い時間 (QStyleHints::mouseDoubleClickInterval()) と距離 (QStyleHints::mouseDoubleClickDistance() またはQStyleHints::touchDoubleTapDistance()) の間に 2 回タップされたときに発せられる。このシグナルは常にsingleTapped 、tapped 、tapCountChanged の後に発生する。eventPoint シグナル・パラメータには、タップされたポイントに関するリリース・イベントの情報が含まれ、button はクリックされたmouse button であり、タッチスクリーンではNoButton である。

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

このシグナルは、グラブがこのハンドラに関連する何らかの方法で変更されたときに発せられる。

transition (動詞)は何が起こったかを示す。point (オブジェクト)は、グラブされた、またはグラブされなかったポイントです。

transition の有効な値は以下の通りです：

longPressed()

このシグナルは、parent アイテムが押され、longPressThreshold を超える時間保持されたときに発せられます。 つまり、タッチポイントやボタンを長押ししても、どの動きもドラッグしきい値を超えない場合、timeHeld がlongPressThreshold を超えた時点で、longPressed シグナルが発せられます。

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

この信号は、parent アイテムが一度タップされたときに発せられる。QStyleHints::mouseDoubleClickInterval を超える時間が経過すると、再度タップすることができますが、次のタップまでの時間が短い場合、tapCount が増加します。eventPoint シグナル・パラメータには、タップされたポイントに関するリリース・イベントの情報が含まれ、button はクリックされたmouse button であり、タッチスクリーンではNoButton である。

tapCountChanged()

このシグナルは、parent アイテムが（指定された時間と距離の範囲内で）1回以上タップされ、現在のtapCount が前のtapCount と異なるときに発せられる。

tapped(eventPoint eventPoint, Qt::MouseButton button)

この信号は、parent アイテムがタップされるたびに発せられる。

つまり、longPressThreshold 以下の時間内にタッチポイントまたはボタンを押してから離すと、どのような動きもドラッグしきい値を超えないため、tapped シグナルがリリース時に発信されます。eventPoint シグナル・パラメータには、タップされたポイントに関するリリース・イベントの情報が含まれ、button はクリックされたmouse button 、タッチスクリーンではNoButton です。

import QtQuick

Rectangle {
    width: 100
    height: 100

    TapHandler {
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onTapped: (eventPoint, button)=> console.log("tapped", eventPoint.device.name,
                                             "button", button,
                                             "@", eventPoint.scenePosition)
    }
}