DragHandler QML Type

드래그용 핸들러. 더 보기...

Import Statement: import QtQuick
Inherits:

MultiPointHandler

속성

신호

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

상세 설명

드래그 핸들러는 아이템을 인터랙티브하게 이동하는 데 사용되는 핸들러입니다. 다른 입력 핸들러와 마찬가지로 기본적으로 모든 기능을 갖추고 있으며 target 을 조작합니다.

import QtQuick

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

드래그 범위를 제한하는 프로퍼티가 있습니다.

하나의 아이템 내에서 선언되었지만 다른 target 에 할당된 경우 parent 아이템의 범위 내에서 이벤트를 처리하지만 대신 target 아이템을 조작합니다:

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

세 번째 사용 방법은 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
    }
}

최소 포인트 수와 최대 포인트 수를 1보다 큰 값으로 설정하면 사용자는 드래그를 시작하려면 같은 방향으로 손가락을 그만큼 많이 드래그해야 합니다. 멀티핑거 드래그 제스처는 동일한 항목에서 (기본값인) 단일 손가락 드래그 핸들러와 PinchHandler 모두와 독립적으로 감지할 수 있으므로 일반적인 핀치 동작과 독립적으로 다른 기능을 조정하는 데 사용할 수 있습니다(예: 기울기 변환을 조정하거나 target 이 null로 설정된 경우 다른 숫자 값을 조정하는 등). 그러나 target 이 항목인 경우 centroid 은 드래그가 시작되고 target 이 이동되는 지점입니다(제약 조건에 따라 달라질 수 있음).

드래그 핸들러는 Drag 첨부 프로퍼티와 함께 사용하여 드래그 앤 드롭을 구현할 수 있습니다.

Drag, MouseArea, Qt Quick 예제 - 포인터 핸들러도참조하세요 .

프로퍼티 문서

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

이 속성을 설정하면 포인터 이벤트에 반응하려면 지정된 키보드 모디파이어를 눌러야 하고, 그렇지 않으면 무시합니다.

예를 들어 두 개의 드래그 핸들러는 Control 수정자의 누름 여부에 따라 서로 다른 두 가지 드래그 앤 드롭 작업을 수행할 수 있습니다:

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키보드의 메타 키를 눌러야 합니다.
KeypadModifier키패드 버튼을 눌러야 합니다.
GroupSwitchModifierX11 전용(Windows에서 명령줄 인수로 활성화하지 않은 경우). 키보드의 Mode_switch 키를 눌러야 합니다.
KeyboardModifierMask핸들러는 어떤 수정자를 눌렀는지는 신경 쓰지 않습니다.

Qt::KeyboardModifier참조하세요 .


acceptedPointerTypes : flags

이를 활성화할 수 있는 포인팅 도구(손가락, 스타일러스, 지우개 등)의 유형 DragHandler.

기본적으로 이 속성은 PointerDevice.AllPointerTypes 으로 설정되어 있습니다. 장치 유형의 OR 조합으로 설정하면 일치하지 않는 devices 의 이벤트는 무시됩니다.


active : bool [read-only]

이 입력 핸들러가 하나 이상의 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 로 설정된 경우 값을 읽으면 Qt.ArrowCursor 이 반환됩니다.

Qt::CursorShape, QQuickItem::cursor() 및 HoverHandler::cursorShape참조하세요 .


dragThreshold : int

드래그 제스처로 처리하기 위해 사용자가 eventPoint 을 드래그해야 하는 픽셀 단위의 거리입니다.

기본값은 플랫폼 및 화면 해상도에 따라 다릅니다. 이 값을 정의되지 않음으로 설정하면 기본값으로 다시 설정할 수 있습니다. 드래그 제스처가 시작될 때의 동작은 핸들러마다 다릅니다.


enabled : bool

PointerHandler 가 비활성화되면 모든 이벤트를 거부하고 신호를 보내지 않습니다.


grabPermissions : flags

이 속성은 이 핸들러의 로직이 독점 그랩을 인수하기로 결정하거나 다른 핸들러가 그랩 인수 또는 취소를 승인하도록 요청할 때 사용 권한을 지정합니다.

Constant설명
PointerHandler.TakeOverForbidden이 핸들러는 어떤 유형의 아이템이나 핸들러로부터도 그랩 권한을 받거나 주지 않습니다.
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 으로 대부분의 탈취 시나리오를 허용하지만 두 개의 핀치 핸들러가 같은 터치포인트를 놓고 싸우는 등의 상황을 방지합니다.


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, 핸들러가 선언된 항목. 핸들러는 이 아이템을 대신하여 이벤트를 처리하므로 eventPoints 중 하나 이상이 아이템 내부에서 발생하면 포인터 이벤트가 관련성이 있습니다. 처음에 target() 은 동일하지만 재할당할 수 있습니다.

targetQObject::parent()도 참조하세요 .


persistentTranslation : vector2d

null 이 아닌 경우 대상에 적용될 번역입니다. 그렇지 않으면 바인딩을 사용하여 이 값으로 임의의 작업을 수행할 수 있습니다. 드래그 제스처가 수행되는 동안에는 activeTranslation 이 계속 추가되고 제스처가 종료된 후에는 그대로 유지됩니다.


snapMode : enumeration

이 속성은 스냅 모드를 보유합니다.

스냅 모드는 대상 항목의 중앙을 eventPoint 에 스냅하도록 구성합니다.

가능한 값은 다음과 같습니다:

Constant설명
DragHandler.NoSnap절대 스냅 안 함
DragHandler.SnapAutoeventPoint대상 항목 외부에서 눌렀고 대상 항목이 parent 항목의 하위 항목인 경우 대상이 스냅됩니다(기본값).
DragHandler.SnapWhenPressedOutsideTargeteventPoint대상 외부에서 눌렀을 경우 대상이 스냅됩니다.
DragHandler.SnapAlways항상 스냅

target : Item

이 핸들러가 조작할 항목입니다.

기본적으로 이 핸들러가 선언된 Item은 parent 과 동일합니다. 그러나 한 항목 내에서 이벤트를 처리하지만 다른 항목을 조작하기 위해 대상을 다른 항목으로 설정하거나, 기본 동작을 비활성화하고 대신 다른 작업을 수행하려면 null 로 설정하는 것이 유용할 수 있습니다.


xAxis group

xAxis.activeValue : real [read-only]

xAxis.enabled : bool

xAxis.maximum : real

xAxis.minimum : real

xAxis 는 가로 드래그에 대한 제약 조건을 제어합니다.

minimumtarget 에 적용할 수 있는 최소 허용 값 x 이며 maximumtarget 에 적용할 수 있는 최대 허용 값 x 입니다. enabled 이 참이면 수평 드래그가 허용되며 activeValueactiveTranslation.x 과 동일합니다.

activeValue 이 변경되면 activeValueChanged 신호가 발생하여 변경된 증분값을 알려줍니다. 이는 여러 핸들러를 통해 하나의 프로퍼티를 점진적으로 조정하기 위한 것입니다.


yAxis group

yAxis.activeValue : real [read-only]

yAxis.enabled : bool

yAxis.maximum : real

yAxis.minimum : real

yAxis 는 수직 드래그에 대한 제약 조건을 제어합니다.

minimum y targettarget 에 적용할 수 있는 최소값이고 maximumy 에 적용할 수 있는 최대값입니다. enabled 이 참이면 수직 드래그가 허용됩니다. activeValueactiveTranslation.y 과 동일합니다.

activeValue 이 변경되면 activeValueChanged 신호가 발생하여 변경된 증분값을 제공합니다. 이는 여러 핸들러를 통해 하나의 프로퍼티를 점진적으로 조정하기 위한 것입니다:

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.