このページでは

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の中で宣言され、異なるtargetparent 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つ目の使い方は、targetnull に設定し、他の方法でプロパティ変更に反応することである:

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 添付プロパティと一緒に使用することができます。

DragMouseAreaQt 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]

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

activeTranslation : vector2d [read-only]

ドラッグ ジェスチャが実行されている間の移動量。ジェスチャの開始時は0, 0 で、イベント ポイントが下方向および右方向にドラッグされるにつれて増加します。ジェスチャが終了すると、移動量は変わりません。次のドラッグ ジェスチャが始まると、移動量は再び0, 0 にリセットされます。

cursorShape : Qt::CursorShape

このプロパティは、activetrue である間、マウスが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::CursorShapeQQuickItem::cursor()、HoverHandler::cursorShapeも参照のこと

dragThreshold : int

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

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

enabled : bool

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

PointerHandlerparentdisabled の場合、enabled プロパティがtrue のままでも、ハンドラは事実上無効になる。

注: HoverHandler は異なる動作をします。詳しくはenabled プロパティのドキュメントを参照してください。

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

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

persistentTranslation : vector2d

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

snapMode : enumeration

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

スナップ・モードは、eventPoint に対するtarget アイテムの中心のスナップを設定する。

設定可能な値

定数説明
DragHandler.NoSnapスナップしない
DragHandler.SnapAutoeventPointtarget アイテムの外側で押され、 targetparent アイテムの子孫である場合、target はスナップします(デフォルト)。
DragHandler.SnapWhenPressedOutsideTargeteventPoint が、target の項目の外側で押された場合、 はスナップします。target
DragHandler.SnapAlways常にスナップする

target : Item

このハンドラが操作するItem。

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

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 と同じである。

activeValueChanged シグナルは、activeValue が変更されたときに発せられ、変更されたインクリメントを提供する。これは、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

© 2026 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.