Back to Qt.io
Contact Us Blog Download Qt

DragHandler QML Type

ドラッグ用ハンドラ。もっと見る...

Import Statement: import QtQuick
Inherits:

MultiPointHandler

プロパティ

信号

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

詳細説明

DragHandler は、Item をインタラクティブに移動するためのハンドラです。他の入力ハンドラと同様に、デフォルトでは完全に機能し、target を操作します。

import QtQuick

Rectangle {
    width: 100
    height: 100
    color: "lightsteelblue"
    DragHandler { }
}

ドラッグの範囲を制限するプロパティを持っています。

もしそれが1つのItemの中で宣言され、異なるtarget 、parent Itemの境界内でイベントを処理するが、代わりにtarget Itemを操作する：

import QtQuick

Item {
    width: 640
    height: 480

    Rectangle {
        id: feedback
        border.color: "red"
        width: Math.max(10, handler.centroid.ellipseDiameters.width)
        height: Math.max(10, handler.centroid.ellipseDiameters.height)
        radius: Math.max(width, height) / 2
        visible: handler.active
    }

    DragHandler {
        id: handler
        target: feedback
    }
}

3つ目の使い方は、target をnull に設定し、他の方法でプロパティ変更に反応することである：

import QtQuick

Item {
    width: 640
    height: 480

    DragHandler {
        id: handler
        target: null
    }

    Text {
        color: handler.active ? "darkgreen" : "black"
        text: handler.centroid.position.x.toFixed(1) + "," + handler.centroid.position.y.toFixed(1)
        x: handler.centroid.position.x - width / 2
        y: handler.centroid.position.y - height
    }
}

minimumPointCountとmaximumPointCountが1より大きな値に設定されている場合、ユーザはドラッグを開始するために、同じ方向にその数だけ指をドラッグする必要があります。マルチフィンガードラッグジェスチャは、同じアイテム上の（デフォルトの）シングルフィンガー DragHandler とPinchHandler の両方から独立して検出できるため、通常のピンチ動作とは別に、他の機能を調整するために使用できます。たとえば、target が NULL に設定されている場合は、傾き変換を調整したり、他の数値を調整したりできます。しかし、target が Item の場合、centroid はドラッグが開始されるポイントであり、target が移動されるポイントです（制約に従います）。

DragHandler は、ドラッグ＆ドロップを実装するためにDrag 添付プロパティと一緒に使用することができます。

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

プロパティの説明

acceptedButtons : flags

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

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

たとえば、あるコンポーネント（TextEdit など）がすでに左ボタンによるドラッグを独自の方法で処理している場合、右ボタンでドラッグしたときに異なる動作をするDragHandler を追加することができます：

Rectangle {
    id: canvas
    width: 640
    height: 480
    color: "#333"
    property int highestZ: 0

    Repeater {
        model: FolderListModel { nameFilters: ["*.qml"] }

        delegate: Rectangle {
            required property string fileName
            required property url fileUrl
            required property int index

            id: frame
            x: index * 30; y: index * 30
            width: 320; height: 240
            property bool dragging: ldh.active || rdh.active
            onDraggingChanged: if (dragging) z = ++canvas.highestZ
            border { width: 2; color: dragging ? "red" : "steelblue" }
            color: "beige"
            clip: true

            TextEdit {
                // drag to select text
                id: textEdit
                textDocument.source: frame.fileUrl
                x: 3; y: 3

                BoundaryRule on y {
                    id: ybr
                    minimum: textEdit.parent.height - textEdit.height; maximum: 0
                    minimumOvershoot: 200; maximumOvershoot: 200
                    overshootFilter: BoundaryRule.Peak
                }
            }

            DragHandler {
                id: rdh
                // right-drag to position the "window"
                acceptedButtons: Qt.RightButton
            }

            WheelHandler {
                target: textEdit
                property: "y"
                onActiveChanged: if (!active) ybr.returnToBounds()
            }

            Rectangle {
                anchors.right: parent.right
                width: titleText.implicitWidth + 12
                height: titleText.implicitHeight + 6
                border { width: 2; color: parent.border.color }
                bottomLeftRadius: 6
                Text {
                    id: titleText
                    color: "saddlebrown"
                    anchors.centerIn: parent
                    text: frame.fileName
                    textFormat: Text.PlainText
                }
                DragHandler {
                    id: ldh
                    // left-drag to position the "window"
                    target: frame
                }
            }
        }
    }
}

acceptedDevices : flags

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

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

注意： まだすべてのプラットフォームがマウスとタッチパッドを区別できるわけではありません。区別できるプラットフォームでは、マウスとタッチパッドの動作を同じにしたい場合がよくあります。


acceptedModifiers : flags

このプロパティが設定されている場合、ポインタ・イベントに反応するためには、指定されたキーボード修飾子が押される必要があり、そうでない場合は無視されます。

例えば、2つのDragHandlerは、Control 修飾子が押されているかどうかによって、2つの異なるドラッグ・アンド・ドロップ操作を実行することができます：

GridView {
    id: root
    width: 320
    height: 480
    cellWidth: 80
    cellHeight: 80
    interactive: false

    displaced: Transition {
        NumberAnimation {
            properties: "x,y"
            easing.type: Easing.OutQuad
        }
    }

    model: DelegateModel {
        id: visualModel
        model: 24
        property var dropTarget: undefined
        property bool copy: false
        delegate: DropArea {
            id: delegateRoot

            width: 80
            height: 80

            onEntered: drag => {
                if (visualModel.copy) {
                    if (drag.source !== icon)
                        visualModel.dropTarget = icon
                } else {
                    visualModel.items.move(drag.source.DelegateModel.itemsIndex, icon.DelegateModel.itemsIndex)
                }
            }

            Rectangle {
                id: icon
                objectName: DelegateModel.itemsIndex

                property string text
                Component.onCompleted: {
                    color = Qt.rgba(0.2 + (48 - DelegateModel.itemsIndex) * Math.random() / 48,
                                    0.3 + DelegateModel.itemsIndex * Math.random() / 48,
                                    0.4 * Math.random(),
                                    1.0)
                    text = DelegateModel.itemsIndex
                }
                border.color: visualModel.dropTarget === this ? "black" : "transparent"
                border.width: 2
                radius: 3
                width: 72
                height: 72
                anchors {
                    horizontalCenter: parent.horizontalCenter
                    verticalCenter: parent.verticalCenter
                }

                states: [
                    State {
                        when: dragHandler.active || controlDragHandler.active
                        ParentChange {
                            target: icon
                            parent: root
                        }

                        AnchorChanges {
                            target: icon
                            anchors {
                                horizontalCenter: undefined
                                verticalCenter: undefined
                            }
                        }
                    }
                ]

                Text {
                    anchors.centerIn: parent
                    color: "white"
                    font.pointSize: 14
                    text: controlDragHandler.active ? "+" : icon.text
                }

                DragHandler {
                    id: dragHandler
                    acceptedModifiers: Qt.NoModifier
                    onActiveChanged: if (!active) visualModel.dropTarget = undefined
                }

                DragHandler {
                    id: controlDragHandler
                    acceptedModifiers: Qt.ControlModifier
                    onActiveChanged: {
                        visualModel.copy = active
                        if (!active) {
                            visualModel.dropTarget.text = icon.text
                            visualModel.dropTarget.color = icon.color
                            visualModel.dropTarget = undefined
                        }
                    }
                }

                Drag.active: dragHandler.active || controlDragHandler.active
                Drag.source: icon
                Drag.hotSpot.x: 36
                Drag.hotSpot.y: 36
            }
        }
    }
}

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

acceptedModifiers をモディファイアキーの OR の組み合わせに設定した場合、ハンドラをアクティブにするには、それらのモディファイアがすべて押される必要があることを意味します。

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

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

Qt::KeyboardModifierも参照のこと 。


acceptedPointerTypes : flags

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

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


active : bool [read-only]

これは、このInput Handlerが1つ以上のeventPoints 、それらの点の排他的なグラブを成功させることで、その点のハンドリングに単独で責任を負ったときはいつでも、true を保持する。これは、この入力ハンドラがそれらのイベントポイントの動きに応じてそのプロパティを最新に保ち、target （もしあれば）を積極的に操作していることを意味する。


activeTranslation : vector2d [read-only]

ドラッグジェスチャが実行されている間の並進。ジェスチャーが始まると0, 0 になり、イベントポイントが下へ右へとドラッグされるにつれて大きくなります。ジェスチャが終了すると、この値は変わりません。次のドラッグ ジェスチャが始まると、この値は再び0, 0 にリセットされます。


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も参照のこと 。


dragThreshold : int

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

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


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やハンドラにもグラブを取る許可を与えます。

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


margin : real

eventPoint がこのハンドラーをアクティブにできるparent アイテムの境界を超えたマージンです。例えば、ユーザーが近くの位置からドラッグできるようにすることで、小さなアイテムをドラッグしやすくすることができます：

Rectangle {
    width: 24
    height: 24
    border.color: "steelblue"
    Text {
        text: "it's\ntiny"
        font.pixelSize: 7
        rotation: -45
        anchors.centerIn: parent
    }

    DragHandler {
        margin: 12
    }
}

parent : Item

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

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


persistentTranslation : vector2d

null でない場合、ターゲットに適用される翻訳。そうでない場合は、バインディングを使用してこの値で任意のことを行うことができます。ドラッグジェスチャが実行されている間、activeTranslation は継続的に追加されます。ジェスチャが終了した後も、この値は変わりません。


snapMode : enumeration

このプロパティはスナップモードを保持します。

スナップ モードは、ターゲットアイテムの中心をeventPoint にスナップするように設定します。

指定可能な値

定数説明
DragHandler.NoSnapスナップしない
DragHandler.SnapAutoeventPoint がターゲットアイテムの外側で押され、 ターゲットが parent アイテムの子孫である場合、ターゲットはスナップします。
DragHandler.SnapWhenPressedOutsideTargeteventPoint がターゲットの外側で押された場合、ターゲットはスナップする。
DragHandler.SnapAlways常にスナップ

target : Item

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

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


xAxis group

xAxis.activeValue : real [read-only]

xAxis.enabled : bool

xAxis.maximum : real

xAxis.minimum : real

xAxis は、水平ドラッグの制約を制御します。

minimum は、 に適用される の許容可能な最小値です。 は、 に適用される の許容可能な最大値です。 が真の場合、水平ドラッグが許可されます。 は、 と同じです。target x maximum target x enabled activeValue activeTranslation.x

activeValue が変更されるとactiveValueChanged シグナルが発せられ、変更されたインクリメントを提供する。これは、複数のハンドラを介して1つのプロパティをインクリメンタルに調整するためのものです。


yAxis group

yAxis.activeValue : real [read-only]

yAxis.enabled : bool

yAxis.maximum : real

yAxis.minimum : real

yAxis は、垂直ドラッグの制約を制御します。

minimum は、 に適用される の許容可能な最小値です。 は、 に適用される の許容可能な最大値です。 が真の場合、垂直ドラッグが許可されます。 は、 と同じです。target y maximum target y enabled activeValue activeTranslation.y

activeValue が変更されるとactiveValueChanged シグナルが発せられ、変更されたインクリメントを提供する。これは、1つのプロパティを複数のハンドラでインクリメンタルに調整するためのものです：

import QtQuick

Rectangle {
    width: 50; height: 200

    Rectangle {
        id: knob
        width: parent.width; height: width; radius: width / 2
        anchors.centerIn: parent
        color: "lightsteelblue"

        Rectangle {
            antialiasing: true
            width: 4; height: 20
            x: parent.width / 2 - 2
        }

        WheelHandler {
            property: "rotation"
        }
    }

    DragHandler {
        target: null
        dragThreshold: 0
        yAxis.onActiveValueChanged: (delta)=> { knob.rotation -= delta }
    }
}

シグナルのドキュメント

canceled(eventPoint point)

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

注： 対応するハンドラは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.