このページでは

DragHandler QML Type

ドラッグ操作のハンドラ。詳細...

Import Statement: import QtQuick
Inherits:

MultiPointHandler

プロパティ

信号

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

詳細な説明

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

import QtQuick

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

ドラッグの範囲を制限するためのプロパティを備えています。

ある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]

この変数には、この入力ハンドラが1つ以上のeventPoints を排他的に取得することに成功し、それらの処理を単独で担当している間、true が格納されます。これは、この入力ハンドラが、それらのeventPointsの動きに応じて自身のプロパティを最新の状態に保ち、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.SplitVカーソル
  • Qt.SplitHCursor
  • Qt.指差しカーソル
  • Qt.ForbiddenCursor
  • Qt.WhatIsThisカーソル
  • Qt.BusyCursor
  • Qt.開いた手のカーソル
  • Qt.閉じた手のカーソル
  • Qt.ドラッグコピーカーソル
  • Qt.DragMoveCursor
  • Qt.DragLinkCursor

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

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

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

dragThreshold : int

eventPoint をドラッグジェスチャーとして認識させるために、ユーザーがドラッグしなければならないピクセル単位の距離。

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

enabled : bool

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

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

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

grabPermissions : flags

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

定数説明
PointerHandler.TakeOverForbiddenこのハンドラは、いかなるタイプの Item や Handler に対しても、グラブ権限を取得したり付与したりすることはありません。
PointerHandler.CanTakeOverFromHandlersOfSameType定数説明このハンドラは、いかなる種類のアイテムやハンドラからもグラブ権限を取得したり、付与したりすることはありません。
PointerHandler.CanTakeOverFromHandlersOfDifferentTypeこのハンドラは、あらゆる種類のハンドラから排他グラブを取得することができます。このハンドラは、あらゆる種類のアイテムから排他グラブを取得することができます。
PointerHandler.CanTakeOverFromItemsこのハンドラは、あらゆるタイプのアイテムから排他的なグラブを取得できます。
PointerHandler.CanTakeOverFromAnythingこのハンドラは、あらゆる種類のアイテムやハンドラから排他的なグラブを取得できます。
PointerHandler.ApprovesTakeOverByHandlersOfSameTypeこのハンドラは、同じクラスの別のハンドラがグラブを取得することを許可します。
PointerHandler.ApprovesTakeOverByHandlersOfDifferentTypeこのハンドラは、あらゆる種類のハンドラにグラブを許可します。
PointerHandler.ApprovesTakeOverByItemsこのハンドラは、あらゆる種類のアイテムがグラブを取得することを許可します。
PointerHandler.ApprovesCancellationこのハンドラは、自身のグラブが null に設定されることを許可します。
PointerHandler.ApprovesTakeOverByAnythingこのハンドラは、あらゆるタイプのアイテムまたはハンドラがグラブを取得することを許可します。

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

margin : real

parent 項目の境界線の外側にある余白で、eventPoint がこのハンドラを起動できる範囲です。たとえば、ユーザーが近くの位置からドラッグできるようにすることで、小さな項目のドラッグ操作を容易にすることができます:

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

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

snapMode : enumeration

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

スナップモードは、target 項目の中心をeventPoint にスナップさせる設定を行います。

指定可能な値:

定数説明
DragHandler.NoSnapスナップしない
DragHandler.SnapAuto「target 」アイテムの外側で「eventPoint 」が押された場合、かつ「target 」が「parent 」アイテムの子要素である場合に、「target 」がスナップします(既定値)
DragHandler.SnapWhenPressedOutsideTarget「target 」は、eventPoint がtarget
DragHandler.SnapAlways常にスナップ

target : Item

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

デフォルトでは、これはparent 、つまりハンドラが宣言されている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 がtrueの場合、水平方向のドラッグが許可されます。activeValue はactiveTranslation.x と同じです。

activeValueChanged シグナルは、activeValue が変更された際に発火し、変更された増分値を提供します。これは、複数のハンドラを介して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 がtrueの場合、垂直方向のドラッグが許可されます。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.