Back to Qt.io
Contact Us Blog Download Qt

PointHandler QML Type

単一のタッチポイントに反応するハンドラ。詳細...

Import Statement: import QtQuick
Inherits:

SinglePointHandler

プロパティ

信号

  • canceled(eventPoint point)
  • grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

詳細説明

PointHandler は、タッチポイントやマウスの位置に関するフィードバックを表示したり、ポインタのイベントに反応したりするために使用できます。

押下イベントが発生すると、PointHandlerの各インスタンスは、その時点でまだ「取られていない」1点を選択します。押下がPointerHandler::parent の境界内で発生し、同じPointerHandler::parent 内の兄弟PointHandlerがまだその点のパッシブグラブを取得しておらず、acceptedButtons 、acceptedDevices などの他の制約が満たされていれば、その点は対象となり、PointHandlerはパッシブグラブを取得します。このように、PointerHandler::parent は排他的グループのように動作する。PointHandler のインスタンスは複数存在することができ、押されたタッチポイントのセットはそれらの間で分配される。追跡するポイントを選択した各 PointHandler は、そのactive プロパティtrue を持つ。point のプロパティは最新の状態に保たれる。どのItemもこれらのプロパティにバインドすることができ、それによってポイントの動きを追うことができる。

パッシブグラブであることによって、すべての動きを独立して監視し続けることができる。他のジェスチャーが検出され、排他的なグラブが発生した場合でも、パッシブグラブは盗まれたり上書きされたりすることはありません。

イベントポイントの直交監視が目的であれば、QObject::installEventFilter() がありますが、これはQtQuick のビルトイン機能ではありません。QQuickItem のサブクラスなど、いくつかの C++ コードが必要です。PointHandler はそれよりも効率的である。なぜなら、QQuickWindow の通常のイベント配信の過程で、ポインタイベントのみが PointHandler に配信されるからである。一方、イベントフィルターは、すべてのタイプのすべての QEvent をフィルターする必要があるため、それ自体がイベント配信のボトルネックになる可能性がある。

1つの可能なユースケースは、（高いz 値を持つことによって）シーンの残りの部分の上にある透明なアイテムにこのハンドラを追加することで、ポイントが押されたばかりのときに、そのアイテムとそのハンドラに最初に配信され、できるだけ早くパッシブグラブを取る機会を提供します。このようなアイテム（UI全体を覆うガラス板のようなもの）は、常に一番上になければならないリアクティブフィードバックを視覚化する他のアイテムの便利な親になることができます; 同様に、ポップアップ、ポップオーバー、ダイアログなどの親になることもできます。同様に、ポップアップやポップオーバー、ダイアログなどの親になることもできます。このような使い方をする場合、QQmlContext::setContextProperty() を使って、UI全体からIDでアクセスできる「ガラスペイン」にすると、他のアイテムやPointHandlerを再ペアレントできるようになるので、main.cppに便利です。

import QtQuick

Window {
    width: 480
    height: 320
    visible: true

    Item {
        id: glassPane
        z: 10000
        anchors.fill: parent

        PointHandler {
            id: handler
            acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
            target: Rectangle {
                parent: glassPane
                color: "red"
                visible: handler.active
                x: handler.point.position.x - width / 2
                y: handler.point.position.y - height / 2
                width: 20; height: width; radius: width / 2
            }
        }
    }
}

他の入力ハンドラ同様、PointHandlerにもtarget プロパティがあり、ポイント追跡Itemを置くのに便利な場所として使うことができます。しかし、PointHandlerはtarget アイテムを自動的に操作することはありません。バインディングを使用して、point に反応させる必要があります。

注意： macOSでは、PointHandlerはデフォルトではトラックパッド上の複数の指には反応しませんが、押されたポイント（マウスの位置）には反応します。これは、macOSがネイティブのジェスチャー認識か生のタッチポイントのどちらかを提供できますが、両方は提供できないためです。私たちはPinchHandler でネイティブのジェスチャー・イベントを使いたいので、タッチを有効にして無効にしたくありません。ただし、MultiPointTouchArea はタッチを有効にするため、ウィンドウ全体のネイティブ・ジェスチャー認識は無効になります。したがって、すべてのタッチポイントに反応したいだけで、スムーズなネイティブ・ジェスチャー体験を必要としない場合は、この方法を使用することもできます。

MultiPointTouchArea,HoverHandler,Qt Quick Examples - Pointer Handlersも参照してください 。

プロパティの説明

acceptedButtons : flags

このPointHandler をアクティブにできるマウスボタン。

デフォルトでは、このプロパティはQt.LeftButton に設定されています。 マウスボタンの OR の組み合わせに設定することができ、他のボタンが押されたり保持されたりするイベントは無視されます。このプロパティがQt.NoButton に設定されている場合、ボタンを全く気にしないことを意味し、すでに本物のeventPoint を処理しているデバイスから来る合成マウスイベントを無視します。

import QtQuick

Item {
    width: 480; height: 320

    Rectangle {
        color: handler.active ? "tomato" : "wheat"
        x: handler.point.position.x - width / 2
        y: handler.point.position.y - height / 2
        width: 20; height: width; radius: width / 2
    }

    PointHandler {
        id: handler
        acceptedButtons: Qt.MiddleButton | Qt.RightButton
    }
}

注： タッチスクリーンにはボタンがないため、このプロパティはPointHandler がタッチポイントに反応することを妨げません。

注： デフォルトでは、このプロパティがQt.LeftButton を保持しているとき、マウス以外のPointerDevice （タッチスクリーンやグラフィックタブレットのスタイラスなど）が合成マウスイベントを生成することが許可されている場合、それらは通常、マウスの左ボタンが押されたことを示し、それらのイベントは、デバイスからの本物のeventPoint にすでに反応していたPointHandler を一時的に非アクティブにすることができます。この問題を避けるために

acceptedButtons: \c Qt.NoButton

を宣言しておくと便利です。Qt::AA_SynthesizeMouseForUnhandledTouchEvents とQt::AA_SynthesizeMouseForUnhandledTabletEvents も参照してください。


acceptedDevices : flags

このPointHandler をアクティブにできるポインティングデバイスのタイプ。

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

PointHandler {
    id: handler
    acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
    target: Rectangle {
        parent: glassPane
        color: "red"
        visible: handler.active
        x: handler.point.position.x - width / 2
        y: handler.point.position.y - height / 2
        width: 20; height: width; radius: width / 2
    }
}

acceptedModifiers : flags

このプロパティが設定されている場合、PointHandler は、PointerEvents に反応するために、指定されたキーボード修飾子が押されていることを要求し、そうでない場合は無視します。

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

例えば、Item は2つのハンドラを持つことができ、そのうちの1つは、必要なキーボード修飾子が押された場合にのみ有効になります：

import QtQuick

Item {
    id: feedbackPane
    width: 480; height: 320

    PointHandler {
        id: control
        acceptedModifiers: Qt.ControlModifier
        cursorShape: Qt.PointingHandCursor
        target: Rectangle {
            parent: feedbackPane
            color: control.active ? "indianred" : "khaki"
            x: control.point.position.x - width / 2
            y: control.point.position.y - height / 2
            width: 20; height: width; radius: width / 2
        }
    }

    PointHandler {
        id: shift
        acceptedModifiers: Qt.ShiftModifier | Qt.MetaModifier
        cursorShape: Qt.CrossCursor
        target: Rectangle {
            parent: feedbackPane
            color: shift.active ? "darkslateblue" : "lightseagreen"
            x: shift.point.position.x - width / 2
            y: shift.point.position.y - height / 2
            width: 30; height: width; radius: width / 2
        }
    }
}

acceptedModifiers を修飾キーの OR の組み合わせに設定した場合、ハンドラを有効にするには、それらの修飾キーがすべて押されなければならないことを意味します。

使用可能な修飾子は以下の通りです：

定数説明
NoModifier修飾キーは使用できません。
ShiftModifierキーボードのShiftキーが押されていなければならない。
ControlModifierキーボードの Ctrl キーが押されていなければならない。
AltModifierキーボードのAltキーが押されていること。
MetaModifierキーボードのMetaキーが押されていなければならない。
KeypadModifierキーパッドのボタンが押されていること。
GroupSwitchModifierX11のみ（Windowsではコマンドライン引数で有効にしない）。キーボードのMode_switchキーが押されていなければならない。
KeyboardModifierMaskハンドラはどの修飾子が押されても気にしない。

Qt::KeyboardModifierも参照のこと 。


acceptedPointerTypes : flags

このPointHandler をアクティブにできるポインティング・インストゥルメントのタイプ（指、スタイラス、消しゴムなど）。

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

import QtQuick

Canvas {
    id: canvas
    width: 800
    height: 600
    antialiasing: true
    renderTarget: Canvas.FramebufferObject
    property var points: []
    onPaint: {
        if (points.length < 2)
            return
        var ctx = canvas.getContext('2d');
        ctx.save()
        ctx.strokeStyle = stylusHandler.active ? "blue" : "white"
        ctx.lineCap = "round"
        ctx.beginPath()
        ctx.moveTo(points[0].x, points[0].y)
        for (var i = 1; i < points.length; i++)
            ctx.lineTo(points[i].x, points[i].y)
        ctx.lineWidth = 3
        ctx.stroke()
        points = points.slice(points.length - 2, 1)
        ctx.restore()
    }

    PointHandler {
        id: stylusHandler
        acceptedPointerTypes: PointerDevice.Pen
        onPointChanged: {
            canvas.points.push(point.position)
            canvas.requestPaint()
        }
    }

    PointHandler {
        id: eraserHandler
        acceptedPointerTypes: PointerDevice.Eraser
        onPointChanged: {
            canvas.points.push(point.position)
            canvas.requestPaint()
        }
    }

    Rectangle {
        width: 10; height: 10
        color: stylusHandler.active ? "green" : eraserHandler.active ? "red" : "beige"
    }
}

Qt Quick Examples - Pointer Handlersには、グラフィックス・タブレットでキャンバスに描画するための、より複雑な例が含まれています。


active : bool [read-only]

これは、制約が満たされ、このPointHandler が反応しているときは常に、true を保持します。これは、制約を満たすeventPoints の動きに応じて、そのプロパティを最新に保つことを意味します。


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 に設定することで、同じ初期状態に戻すことができます。

注意： このプロパティが設定されていない場合、またはundefined に設定されている場合、値を読み取るとQt.ArrowCursor を返します。

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


enabled : bool

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


grabPermissions : flags

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

定数説明
PointerHandler.TakeOverForbiddenこのハンドラは、ItemまたはHandlerのどのタイプからもグラブパーミッションを取ることも与えることもできません。
PointerHandler.CanTakeOverFromHandlersOfSameTypeこのハンドラは、同じクラスの他のハンドラから排他的グラブを取ることができます。
PointerHandler.CanTakeOverFromHandlersOfDifferentTypeこのハンドラは、あらゆる種類のハンドラから排他的なグラブを取ることができます。
PointerHandler.CanTakeOverFromItemsこのハンドラは、どのタイプのItemからも排他的グラブを取ることができます。
PointerHandler.CanTakeOverFromAnythingこのハンドラは、どのタイプのアイテムまたはハンドラからも排他的グラブを取ることができます。
PointerHandler.ApprovesTakeOverByHandlersOfSameTypeこのハンドラーは、同じクラスの他のハンドラーがグラブを取ることを許可します。
PointerHandler.ApprovesTakeOverByHandlersOfDifferentTypeこのハンドラーは、あらゆる種類のハンドラーにグラブを取る許可を与えます。
PointerHandler.ApprovesTakeOverByItemsこのハンドラーは、あらゆる種類のItemがグラブを取ることを許可します。
PointerHandler.ApprovesCancellationこのハンドラは、そのグラブが null に設定されることを許可します。
PointerHandler.ApprovesTakeOverByAnythingこのハンドラは、任意のタイプのItemまたはHandlerがグラブを取ることを許可します。

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


margin : real

eventPoint がこのハンドラをアクティブにできるparent アイテムの境界を超えたマージン。

デフォルト値は0 です。

import QtQuick

Item {
    width: 480; height: 320

    Rectangle {
        anchors.fill: handlingContainer
        anchors.margins: -handler.margin
        color: "beige"
    }

    Rectangle {
        id: handlingContainer
        width: 200; height: 200
        anchors.centerIn: parent
        border.color: "green"
        color: handler.active ? "lightsteelblue" : "khaki"

        Text {
            text: "X"
            x: handler.point.position.x - width / 2
            y: handler.point.position.y - height / 2
            visible: handler.active
        }

        PointHandler {
            id: handler
            margin: 30
        }
    }

}

parent : Item

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

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


point : handlerPoint [read-only]

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


target : real

操作するアイテムやフィードバックを表示するアイテムを便利に保持できるプロパティ。他のポインタハンドラとは異なり、PointHandler は、それ自体ではtarget に対して何も行いません。通常は、SinglePointHandler::point やPointHandler::active などのプロパティに対するリアクティブバインディングを作成する必要があります。ここで Item インスタンスを宣言する場合、PointHandler は Item ではないので、明示的にparent を設定する必要があります。

デフォルトでは、ハンドラが宣言されているItemparent と同じです。


シグナル・ドキュメント

canceled(eventPoint point)

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

注意: 対応するハンドラはonCanceled です。


grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

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

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

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

定数説明
PointerDevice.GrabExclusiveこのハンドラは、point を処理する主な責任を負った。
PointerDevice.UngrabExclusiveこのハンドラは、以前の排他的グラブを放棄した。
PointerDevice.CancelGrabExclusiveこのハンドラの排他的グラブは引き継がれたかキャンセルされた。
PointerDevice.GrabPassiveこのハンドラは、point を監視するために、パッシブグラブを獲得した。
PointerDevice.UngrabPassiveこのハンドラーは以前のパッシブグラブを放棄した。
PointerDevice.CancelGrabPassiveこのハンドラの前のパッシブグラブが異常終了した。

注： 対応するハンドラはonGrabChanged 。


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.