DragHandler QML Type
드래그용 핸들러. 더 보기...
Import Statement: | import QtQuick |
Inherits: |
속성
- acceptedButtons : flags
- acceptedDevices : flags
- acceptedModifiers : flags
- acceptedPointerTypes : flags
- active : bool
- activeTranslation : vector2d
- cursorShape : Qt::CursorShape
- dragThreshold : int
- enabled : bool
- grabPermissions : flags
- margin : real
- parent : Item
- persistentTranslation : vector2d
- snapMode : enumeration
- target : Item
- xAxis
- xAxis.activeValue : real
- xAxis.enabled : bool
- xAxis.maximum : real
- xAxis.minimum : real
- yAxis
- yAxis.activeValue : real
- yAxis.enabled : bool
- yAxis.maximum : real
- yAxis.minimum : real
신호
- 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 } }
세 번째 사용 방법은 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 } }
최소 포인트 수와 최대 포인트 수를 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 | 키패드 버튼을 눌러야 합니다. |
GroupSwitchModifier | X11 전용(Windows에서 명령줄 인수로 활성화하지 않은 경우). 키보드의 Mode_switch 키를 눌러야 합니다. |
KeyboardModifierMask | 핸들러는 어떤 수정자를 눌렀는지는 신경 쓰지 않습니다. |
Qt::KeyboardModifier 를참조하세요 .
acceptedPointerTypes : flags |
이를 활성화할 수 있는 포인팅 도구(손가락, 스타일러스, 지우개 등)의 유형 DragHandler.
기본적으로 이 속성은 PointerDevice.AllPointerTypes 으로 설정되어 있습니다. 장치 유형의 OR 조합으로 설정하면 일치하지 않는 devices 의 이벤트는 무시됩니다.
active : bool |
이 입력 핸들러가 하나 이상의 eventPoints 을 성공적으로 독점적으로 가져와서 처리할 때마다 true
을 유지합니다. 즉, 해당 이벤트포인트의 움직임에 따라 프로퍼티를 최신 상태로 유지하고 target (있는 경우)를 적극적으로 조작한다는 뜻입니다.
activeTranslation : vector2d |
드래그 제스처가 수행되는 동안의 번역. 제스처가 시작될 때는 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
로 설정된 경우 값을 읽으면 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() 은 동일하지만 재할당할 수 있습니다.
target 및 QObject::parent()도 참조하세요 .
persistentTranslation : vector2d |
null
이 아닌 경우 대상에 적용될 번역입니다. 그렇지 않으면 바인딩을 사용하여 이 값으로 임의의 작업을 수행할 수 있습니다. 드래그 제스처가 수행되는 동안에는 activeTranslation 이 계속 추가되고 제스처가 종료된 후에는 그대로 유지됩니다.
snapMode : enumeration |
이 속성은 스냅 모드를 보유합니다.
스냅 모드는 대상 항목의 중앙을 eventPoint 에 스냅하도록 구성합니다.
가능한 값은 다음과 같습니다:
Constant | 설명 |
---|---|
DragHandler.NoSnap | 절대 스냅 안 함 |
DragHandler.SnapAuto | eventPoint 을 대상 항목 외부에서 눌렀고 대상 항목이 parent 항목의 하위 항목인 경우 대상이 스냅됩니다(기본값). |
DragHandler.SnapWhenPressedOutsideTarget | eventPoint 을 대상 외부에서 눌렀을 경우 대상이 스냅됩니다. |
DragHandler.SnapAlways | 항상 스냅 |
target : Item |
이 핸들러가 조작할 항목입니다.
기본적으로 이 핸들러가 선언된 Item은 parent 과 동일합니다. 그러나 한 항목 내에서 이벤트를 처리하지만 다른 항목을 조작하기 위해 대상을 다른 항목으로 설정하거나, 기본 동작을 비활성화하고 대신 다른 작업을 수행하려면 null
로 설정하는 것이 유용할 수 있습니다.
xAxis
는 가로 드래그에 대한 제약 조건을 제어합니다.
minimum
는 target 에 적용할 수 있는 최소 허용 값 x 이며 maximum
는 target 에 적용할 수 있는 최대 허용 값 x 입니다. enabled
이 참이면 수평 드래그가 허용되며 activeValue
은 activeTranslation.x 과 동일합니다.
activeValue
이 변경되면 activeValueChanged
신호가 발생하여 변경된 증분값을 알려줍니다. 이는 여러 핸들러를 통해 하나의 프로퍼티를 점진적으로 조정하기 위한 것입니다.
yAxis
는 수직 드래그에 대한 제약 조건을 제어합니다.
minimum
y target 은 target 에 적용할 수 있는 최소값이고 maximum
은 y 에 적용할 수 있는 최대값입니다. enabled
이 참이면 수직 드래그가 허용됩니다. activeValue
은 activeTranslation.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.