DragHandler QML Type

Handler for dragging. More...

Properties

Detailed Description

\inheritsMultiPointHandler \inqmlmodule QtQuick \ingroup qtquick-input-handlers

DragHandler is a handler that is used to interactively move an Item. Like other Input Handlers, by default it is fully functional, and manipulates its target.

 import QtQuick

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

It has properties to restrict the range of dragging.

If it is declared within one Item but is assigned a different target, then it handles events within the bounds of the parent Item but manipulates the target Item instead:

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

A third way to use it is to set target to null and react to property changes in some other way:

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

If minimumPointCount and maximumPointCount are set to values larger than 1, the user will need to drag that many fingers in the same direction to start dragging. A multi-finger drag gesture can be detected independently of both a (default) single-finger DragHandler and a PinchHandler on the same Item, and thus can be used to adjust some other feature independently of the usual pinch behavior: for example adjust a tilt transformation, or adjust some other numeric value, if the target is set to null. But if the target is an Item, centroid is the point at which the drag begins and to which the target will be moved (subject to constraints).

At this time, drag-and-drop is not yet supported.

See also Drag, MouseArea, and Qt Quick Examples - Pointer Handlers.

Property Documentation

[read-only] activeTranslation : QVector2D

\readonly

The translation while the drag gesture is being performed. It is 0, 0 when the gesture begins, and increases as the event point(s) are dragged downward and to the right. After the gesture ends, it stays the same; and when the next drag gesture begins, it is reset to 0, 0 again.


persistentTranslation : QVector2D

The translation to be applied to the target if it is not null. Otherwise, bindings can be used to do arbitrary things with this value. While the drag gesture is being performed, activeTranslation is continuously added to it; after the gesture ends, it stays the same.


snapMode : enumeration

This property holds the snap mode.

The snap mode configures snapping of the target item's center to the eventPoint.

Possible values:

ConstantDescription
DragHandler.SnapNeverNever snap
DragHandler.SnapAutoThe target snaps if the eventPoint was pressed outside of the target item and the target is a descendant of parent item (default)
DragHandler.SnapWhenPressedOutsideTargetThe target snaps if the eventPoint was pressed outside of the target
DragHandler.SnapAlwaysAlways snap

[read-only] translation : QVector2D

\readonly \deprecated [6.2] Use activeTranslation


xAxis group

[read-only] xAxis.activeValue : real

xAxis.enabled : bool

xAxis.maximum : real

xAxis.minimum : real

xAxis controls the constraints for horizontal dragging.

minimum is the minimum acceptable value of x to be applied to the target. maximum is the maximum acceptable value of x to be applied to the target. If enabled is true, horizontal dragging is allowed. activeValue is the same as activeTranslation.x.

The activeValueChanged signal is emitted when activeValue changes, to provide the increment by which it changed. This is intended for incrementally adjusting one property via multiple handlers.


yAxis group

[read-only] yAxis.activeValue : real

yAxis.enabled : bool

yAxis.maximum : real

yAxis.minimum : real

yAxis controls the constraints for vertical dragging.

minimum is the minimum acceptable value of y to be applied to the target. maximum is the maximum acceptable value of y to be applied to the target. If enabled is true, vertical dragging is allowed. activeValue is the same as activeTranslation.y.

The activeValueChanged signal is emitted when activeValue changes, to provide the increment by which it changed. This is intended for incrementally adjusting one property via multiple handlers:

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