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はパッシブグラブのみを使用して機能するため、他のItemやInput Handlerへのイベント配信を妨げることはありません。したがって、バインディングやJavaScriptコールバックを備えたTapHandlerを追加して、既存のコントロールやItemの挙動を変更したい場合には、デフォルトのgesturePolicy が役立ちます。

なお、ボタン（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 の「例 - ポインタハンドラ」も参照してください 。

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

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 が格納されます。つまり、この入力ハンドラは、それらのeventPointsの動きに応じて自身のプロパティを最新の状態に保ち、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.指差しカーソル
• 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 のままであっても、ハンドラは事実上無効化されます。

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

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

デフォルト値は、QStyleHints::mousePressAndHoldInterval() を秒単位に変換した値です。

margin : real

parent 項目の境界線から外れた領域のうち、eventPoint がこのハンドラを起動できる範囲です。たとえば、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]

マウスまたはタッチポイントが押されている間、かつ押下以降の移動が現在のgesturePolicy に準拠している場合は、常にtrueとなります。eventPoint が解放されたり、ポリシーに違反したりすると、pressedはfalseに変わります。

tapCount : int [read-only]

時間的および空間的な制約の範囲内で発生したタップの数。これらが単一のジェスチャーと見なされます。ボタンが切り替わった場合、カウンターは1にリセットされます。たとえば、3回タップを検出するには、次のように記述します：

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

target : Item

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

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

timeHeld : real [read-only]

ドラッグの閾値を超えて移動することなく、押されたポイントが押し続けられている時間の長さ（秒単位）。これは、レンダリングされるフレームごとに少なくとも1回更新されるため、長押しによってトリガーされるアクションへの進行状況を示すアニメーションをレンダリングすることが可能になります。また、押し続けられた時間に応じて、一連のアクションのうちの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 」アイテムが1回タップされたときに発火します。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)
    }
}