이 페이지에서

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

세 번째 사용 방법은 ` 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보다 큰 값으로 설정된 경우, 사용자는 드래그를 시작하기 위해 해당 수만큼의 손가락을 같은 방향으로 드래그해야 합니다. 다중 손가락 드래그 제스처는 동일한 Item에 설정된 (기본) 단일 손가락 DragHandler 및 PinchHandler 와 독립적으로 감지될 수 있으므로, 일반적인 핀치 동작과 별개로 다른 기능을 조정하는 데 사용할 수 있습니다. 예를 들어, target 가 null로 설정된 경우 틸트 변환을 조정하거나 다른 수치 값을 조정할 수 있습니다. 그러나 드래그 대상( target )이 Item인 경우, 드래그 시작점( centroid )은 드래그가 시작되는 지점이자 드래그 핸들러( target )가 이동하게 될 지점입니다(제약 조건에 따름).

DragHandler는 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

이 속성이 설정된 경우, 포인터 이벤트에 반응하려면 지정된 키보드 수정 키를 눌러야 하며, 그렇지 않으면 해당 이벤트를 무시합니다.

예를 들어, 두 개의 DragHandler는 ' 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키보드의 Meta 키를 눌러야 합니다.
KeypadModifier키패드 버튼을 눌러야 합니다.
GroupSwitchModifierX11 전용 (Windows에서 명령줄 인자로 활성화된 경우는 제외). 키보드의 Mode_switch 키를 눌러야 합니다.
KeyboardModifierMask핸들러는 어떤 수정 키가 눌렸는지는 상관하지 않습니다.

Qt::KeyboardModifier도 참조하십시오 .

acceptedPointerTypes : flags

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

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

active : bool [read-only]

이 메서드는 해당 입력 핸들러가 하나 이상의 이벤트 포인트( eventPoints)에 대한 배타적 그랩(exclusive grab)을 성공적으로 수행하여 해당 포인트들을 단독으로 처리할 책임을 맡게 될 때마다 ` 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.SplitV커서
  • Qt.SplitHCursor
  • Qt.손가락커서
  • Qt.금지 커서
  • Qt.이건뭐지커서
  • Qt.바쁜 커서
  • 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이 핸들러는 어떤 유형의 아이템이나 핸들러로부터도 그랩 권한을 가져오거나 부여하지 않습니다.
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 `이며, 이는 대부분의 인수 시나리오를 허용하되, 예를 들어 두 개의 `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 중 적어도 하나가 해당 Item의 내부에서 발생하는 경우 해당 이벤트가 관련이 있음을 의미합니다. 초기에는 target() 가 동일하지만, 재할당될 수 있습니다.

target 및 QObject::parent()도 참조하십시오 .

persistentTranslation : vector2d

target 에 적용될 변환 값으로, 해당 값이 null 가 아닐 경우에만 사용됩니다. 그렇지 않은 경우, 바인딩을 사용하여 이 값으로 임의의 작업을 수행할 수 있습니다. 드래그 제스처가 수행되는 동안 activeTranslation 가 지속적으로 추가되며, 제스처가 종료된 후에는 값이 그대로 유지됩니다.

snapMode : enumeration

이 속성은 스냅 모드를 지정합니다.

스냅 모드는 ‘ target ’ 항목의 중심이 ‘ eventPoint ’에 스냅되도록 구성합니다.

사용 가능한 값:

상수설명
DragHandler.NoSnap절대 스냅하지 않음
DragHandler.SnapAuto' target ' 항목은 ' eventPoint ' 버튼이 ' target ' 항목 외부에서 눌렸을 때 , ' target '가 ' parent ' 항목의 하위 요소인 경우 스냅됩니다(기본값).
DragHandler.SnapWhenPressedOutsideTargeteventPoint 가 항목 외부에서 눌렸고, 가 항목의 하위 요소인 경우 target 가 스냅됩니다(기본값). target
DragHandler.SnapAlways항상 스냅

target : Item

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

기본적으로 이는 ` parent`과 동일하며, 핸들러가 선언된 `Item`입니다. 그러나 한 `Item` 내에서 이벤트를 처리하되 다른 `Item`을 조작하기 위해, 또는 ` null`을 호출하여 기본 동작을 비활성화하고 대신 다른 작업을 수행하기 위해 대상 `Item`을 다른 `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 가 변경될 때 발생하며, 변경된 증분 값을 제공합니다. 이는 여러 핸들러를 통해 하나의 속성을 점진적으로 조정하기 위한 것입니다.

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 가 변경될 때 발생하며, 변경된 증가량을 제공합니다. 이는 여러 핸들러를 통해 하나의 속성을 점진적으로 조정하기 위한 것입니다:

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.