PointHandler QML Type

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

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

プロパティ

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• point : handlerPoint
• target : real

信号

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

詳細な説明

PointHandler を使用すると、タッチポイントやマウスの位置に関するフィードバックを表示したり、ポインタイベントに対して何らかの反応を行ったりすることができます。

押下イベントが発生すると、PointHandlerの各インスタンスは、その時点でまだ「占有」されていない単一の点を選択します： その押下がPointerHandler::parent の境界内で発生し、かつ同じPointerHandler::parent 内の兄弟PointHandlerがそのポイントに対してまだパッシブグラブを取得しておらず、さらにacceptedButtons やacceptedDevices などの他の制約条件が満たされている場合、そのポイントは適格とみなされ、PointHandlerはパッシブグラブを取得します。 このように、PointerHandler::parent は排他的なグループのように機能します。つまり、PointHandlerのインスタンスは複数存在し得、押されているタッチポイントのセットはそれらの間で分配されます。追跡するポイントを選択した各PointHandlerには、active プロパティ（true ）が設定されます。その後、そのPointHandlerは、ポイントが解放されるまで選択したポイントの追跡を継続し、point のプロパティは常に最新の状態に保たれます。 任意のItemはこれらのプロパティにバインドすることができ、それによってポイントの動きを追跡できます。

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

イベントポイントの直交監視を目的とする場合、以前の代替手段としてQObject::installEventFilter()がありましたが、これはQtQuick の組み込み機能ではありませんでした。QQuickItem のサブクラスなど、C++コードが必要となります。 PointHandlerはそれよりも効率的です。なぜなら、QQuickWindow における通常のイベント配信の過程で、ポインタイベントのみがPointHandlerに配信されるのに対し、イベントフィルタはあらゆるタイプのQEventをすべてフィルタリングする必要があるため、イベント配信のボトルネックとなる可能性があるからです。

考えられるユースケースの一つとして、このハンドラを（z の値を高く設定することで）シーンの他の要素よりも最前面に配置された透明なItemに追加することが挙げられます。これにより、ポイントが新たに押された際、そのイベントが最初にそのItemとそのハンドラに配信され、パッシブグラブを可能な限り早期に取得できるようになります。 このようなアイテム（UI全体を覆うガラスのパネルなど）は、常に最前面に表示される必要がある反応型のフィードバックを可視化する他のアイテムにとって便利な親アイテムとなり得ます。同様に、ポップアップ、ポップオーバー、ダイアログなどの親としても機能します。 そのように使用する場合、main.cpp で `QQmlContext::setContextProperty()` を使用して、UI 全体から ID によって「ガラスパネル」にアクセスできるようにしておくと便利です。そうすることで、他のアイテムや PointHandler をそのアイテムに再親付けできるようになります。

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 に反応させるには、バインディングを使用する必要があります。

MultiPointTouchArea 、HoverHandler 、およびQt Quick の「例 - ポインタハンドラ」も参照してください 。

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

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
    }
}

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」組み合わせに設定した場合、そのハンドラーを有効にするには、それらの修飾キーがすべて押されている必要があります。

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

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 の例 - ポインタハンドラ」には、グラフィックタブレットを使用して Canvas に描画する、より複雑な例が含まれています。

active : bool [read-only]

制約条件が満たされているときは常に `true ` が成立し、この `PointHandler ` は反応しています。これは、制約条件を満たす `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.SplitVカーソル
• Qt.SplitHCursor
• Qt.指差しカーソル
• Qt.ForbiddenCursor
• Qt.WhatIsThisカーソル
• Qt.BusyCursor
• Qt.開いた手のカーソル
• Qt.閉じた手のカーソル
• Qt.ドラッグコピーカーソル
• Qt.DragMoveCursor
• Qt.DragLinkCursor

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

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

enabled : bool

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

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

grabPermissions : flags

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

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

margin : real

parent 項目の境界の外側にある余白で、eventPoint がこのハンドラを起動できる範囲です。

デフォルト値は `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です。ハンドラはこの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 を明示的に設定する必要があります。

デフォルトでは、これはparent 、つまりハンドラが宣言されているItemと同じになります。

シグナルのドキュメント

canceled(eventPoint point)

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

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

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

transition （動詞）は、何が起きたかを示します。point （目的語）は、グラブされた、またはグラブが解除されたポイントです。

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