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の各インスタンスは、その時点でまだ「取られていない」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でアクセスできる「ガラスペイン」にし、他のItemや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 に反応させる必要があります。

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

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

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

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。ハンドラはこのItemに代わってイベントを処理する。つまり、ポインタイベントは、そのeventPoints の少なくとも1つがItemの内部で発生する場合に関連する。最初はtarget() が同じであるが、再割り当てが可能である。

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

point : handlerPoint [read-only]

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

target : real

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

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

シグナル・ドキュメント

canceled(eventPoint point)

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

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

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

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

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