DragHandler QML Type
Controlador para arrastrar. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- 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
Señales
- canceled(eventPoint point)
- grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
Descripción detallada
DragHandler es un controlador que se utiliza para mover de forma interactiva un elemento (Item). Al igual que otros controladores de entrada (Input Handlers), por defecto es totalmente funcional y manipula su elemento de control ( target).
import QtQuick
Rectangle {
width: 100
height: 100
color: "lightsteelblue"
DragHandler { }
}Dispone de propiedades para restringir el rango de arrastre.
Si se declara dentro de un elemento pero se le asigna un target diferente, gestiona los eventos dentro de los límites del elemento parent, pero manipula en su lugar el elemento 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
}
}Una tercera forma de utilizarlo es establecer ` target ` en ` null ` y reaccionar a los cambios de propiedad de alguna otra manera:
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
}
}Si minimumPointCount y maximumPointCount se establecen en valores superiores a 1, el usuario deberá arrastrar ese número de dedos en la misma dirección para iniciar el arrastre. Un gesto de arrastre con varios dedos se puede detectar independientemente tanto de un `DragHandler` de un solo dedo (por defecto) como de un ` PinchHandler ` en el mismo elemento, por lo que se puede utilizar para ajustar alguna otra característica independientemente del comportamiento habitual de pellizco: por ejemplo, ajustar una transformación de inclinación o ajustar algún otro valor numérico, si el ` target ` se establece en `null`. Sin embargo, si el ` target ` es un `Item`, ` centroid ` es el punto en el que comienza el arrastre y al que se desplazará el ` target ` (sujeto a restricciones).
DragHandler se puede utilizar junto con la propiedad adjunta Drag para implementar la función de arrastrar y soltar.
Véase también Drag, MouseArea y Qt Quick Ejemplos: controladores de puntero.
Documentación de la propiedad
acceptedButtons : flags
Los botones del ratón que pueden activar esta función DragHandler.
Por defecto, esta propiedad está configurada como « Qt.LeftButton ». Se puede configurar con una combinación OR de botones del ratón e ignorará los eventos de los demás botones.
Por ejemplo, si un componente (como TextEdit) ya gestiona los arrastres con el botón izquierdo a su manera, se le puede añadir un DragHandler que realice una acción diferente cuando se arrastre con el botón derecho:
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
Los tipos de dispositivos de señalación que pueden activar esta DragHandler.
De forma predeterminada, esta propiedad está configurada en PointerDevice.AllDevices. Si la configuras con una combinación «O» de tipos de dispositivos, ignorará los eventos procedentes de dispositivos que no coincidan.
Nota: Todavíano todas las plataformas son capaces de distinguir entre el ratón y el panel táctil; y en aquellas que sí lo hacen, a menudo se desea que el comportamiento del ratón y del panel táctil sea el mismo.
acceptedModifiers : flags
Si se activa esta propiedad, será necesario pulsar los modificadores de teclado indicados para que se responda a los eventos del puntero; de lo contrario, estos se ignorarán.
Por ejemplo, dos DragHandlers pueden realizar dos operaciones de arrastrar y soltar diferentes, dependiendo de si se pulsa el modificador « 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
}
}
}
}Si esta propiedad se establece en « Qt.KeyboardModifierMask » (el valor por defecto), el « DragHandler » ignorará las teclas modificadoras.
Si se establece « acceptedModifiers » en una combinación «O» de teclas modificadoras, significa que todas esas teclas deben estar pulsadas para activar el controlador.
Los modificadores disponibles son los siguientes:
| Constante | Descripción |
|---|---|
NoModifier | No se permite ninguna tecla modificadora. |
ShiftModifier | Se debe pulsar la tecla «Shift» del teclado. |
ControlModifier | Se debe pulsar la tecla Ctrl del teclado. |
AltModifier | Se debe pulsar la tecla Alt del teclado. |
MetaModifier | Se debe pulsar la tecla Meta del teclado. |
KeypadModifier | Se debe pulsar una tecla del teclado numérico. |
GroupSwitchModifier | Solo en X11 (a menos que se active en Windows mediante un argumento de línea de comandos). Se debe pulsar una tecla Mode_switch del teclado. |
KeyboardModifierMask | Al controlador no le importa qué modificadores se pulsen. |
Véase también Qt::KeyboardModifier.
acceptedPointerTypes : flags
Los tipos de dispositivos de señalación (dedo, lápiz óptico, borrador, etc.) que pueden activar este DragHandler.
De forma predeterminada, esta propiedad está configurada en PointerDevice.AllPointerTypes. Si la configuras en una combinación «O» de tipos de dispositivos, ignorará los eventos de los devices que no coincidan.
active : bool [read-only]
Esto se cumple true siempre que este gestor de entrada haya asumido la responsabilidad exclusiva de gestionar uno o más « eventPoints », al haber conseguido una «captura exclusiva» de dichos puntos. Esto significa que mantiene sus propiedades actualizadas de acuerdo con los movimientos de esos «eventPoints» y que manipula activamente sus « target » (si los hay).
activeTranslation : vector2d [read-only]
El desplazamiento mientras se realiza el gesto de arrastre. Al inicio del gesto, el valor es de 0, 0 y va aumentando a medida que los puntos del evento se arrastran hacia abajo y hacia la derecha. Una vez finalizado el gesto, el valor se mantiene igual; y cuando comienza el siguiente gesto de arrastre, vuelve a restablecerse a 0, 0.
cursorShape : Qt::CursorShape
Esta propiedad define la forma del cursor que aparecerá cada vez que el ratón se sitúe sobre el elemento « parent » mientras « active » tenga el valor « true ».
Las formas de cursor disponibles son:
- Qt.ArrowCursor
- Qt.UpArrowCursor
- Qt.CrossCursor
- Qt.WaitCursor
- Qt.IBeamCursor
- Qt.CursorVerticalDeTamaño
- Qt.CursorDeTamañoHorizontal
- Qt.CursorDiagonalBDiagonal
- Qt.SizeFDiagCursor
- Qt.SizeAllCursor
- Qt.Cursor en blanco
- Qt.CursorDivisiónVertical
- Qt.Cursor de división horizontal
- Qt.CursorManoSeñalando
- Qt.CursorProhibido
- Qt.Cursor«¿Qué es esto?»
- Qt.CursorOcupado
- Qt.Cursor de mano abierta
- Qt.Cursor de mano cerrada
- Qt.CursorDeArrastreYCopia
- Qt.CursorArrastrarMover
- Qt.DragLinkCursor
El valor por defecto no está establecido, lo que permite que aparezca el « cursor » del elemento « parent ». Esta propiedad se puede restablecer a su estado inicial asignándole el valor «undefined».
Nota: Cuando esta propiedad no se ha establecido, o se ha establecido en « undefined », si se lee el valor, devolverá « Qt.ArrowCursor ».
Véase también « Qt::CursorShape », « QQuickItem::cursor()» y « HoverHandler::cursorShape ».
dragThreshold : int
La distancia en píxeles que el usuario debe arrastrar un « eventPoint » para que se considere un gesto de arrastre.
El valor por defecto depende de la plataforma y de la resolución de la pantalla. Se puede restablecer al valor por defecto estableciéndolo en «undefined». El comportamiento al iniciar un gesto de arrastre varía según los distintos controladores.
enabled : bool
Si se desactiva un « PointerHandler », rechazará todos los eventos y no se emitirá ninguna señal.
Si la propiedad « parent » de un « PointerHandler » tiene el valor « disabled », el controlador también quedará desactivado de forma efectiva, incluso cuando la propiedad « enabled » siga teniendo el valor « true ».
Nota: HoverHandler se comporta de forma diferente: consulta la documentación de su propiedad enabled para obtener más información.
grabPermissions : flags
Esta propiedad especifica los permisos cuando la lógica de este controlador decide hacerse cargo del control exclusivo, o cuando otro controlador le solicita que apruebe la toma de control o la cancelación de dicho control.
| Constante | Descripción |
|---|---|
PointerHandler.TakeOverForbidden | Este controlador no toma ni concede permiso de control a ningún tipo de elemento o controlador. |
PointerHandler.CanTakeOverFromHandlersOfSameType | Este controlador puede tomar el control exclusivo de otro controlador de la misma clase. |
PointerHandler.CanTakeOverFromHandlersOfDifferentType | Este controlador puede tomar el control exclusivo de cualquier tipo de controlador. |
PointerHandler.CanTakeOverFromItems | Este controlador puede tomar el control exclusivo de cualquier tipo de elemento. |
PointerHandler.CanTakeOverFromAnything | Este controlador puede tomar el control exclusivo de cualquier tipo de elemento o controlador. |
PointerHandler.ApprovesTakeOverByHandlersOfSameType | Este controlador concede permiso a otro controlador de la misma clase para que adquiera el control. |
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType | Este controlador concede permiso a cualquier tipo de controlador para que adquiera el control. |
PointerHandler.ApprovesTakeOverByItems | Este controlador permite que cualquier tipo de elemento adquiera el control exclusivo. |
PointerHandler.ApprovesCancellation | Este controlador permitirá que su control se establezca en nulo. |
PointerHandler.ApprovesTakeOverByAnything | Este controlador permite que cualquier tipo de elemento o controlador tome el control. |
El valor por defecto es « PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything », lo que permite la mayoría de los casos de toma de control, pero evita, por ejemplo, que dos «PinchHandlers» compitan por los mismos puntos táctiles.
margin : real
El margen más allá de los límites del elemento « parent » dentro del cual un « eventPoint » puede activar este controlador. Por ejemplo, puedes facilitar el arrastre de elementos pequeños permitiendo que el usuario los arrastre desde una posición cercana:
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
El ` Item `, que es el ámbito del controlador; el `Item` en el que se declaró. El controlador gestionará los eventos en nombre de este `Item`, lo que significa que un evento de puntero es relevante si al menos uno de sus ` eventPoints ` tiene lugar dentro del interior del `Item`. Inicialmente, ` target() ` es el mismo, pero se puede reasignar.
Véase también target y QObject::parent().
persistentTranslation : vector2d
La conversión que se aplicará a ` target ` si no es ` null`. De lo contrario, se pueden utilizar enlaces para realizar acciones arbitrarias con este valor. Mientras se realiza el gesto de arrastre, se le va sumando continuamente ` activeTranslation `; una vez finalizado el gesto, el valor permanece igual.
snapMode : enumeration
Esta propiedad define el modo de ajuste.
El modo de ajuste configura el ajuste del centro del elemento « target » al « eventPoint ».
Valores posibles:
| Constante | Descripción |
|---|---|
DragHandler.NoSnap | Nunca alinear |
DragHandler.SnapAuto | El elemento target se alinea si se ha pulsado el botón eventPoint fuera del elemento target y el elemento target es un descendiente del elemento parent (por defecto) |
DragHandler.SnapWhenPressedOutsideTarget | El target se ajusta si se ha pulsado el eventPoint fuera del target |
DragHandler.SnapAlways | «Ajustar siempre» |
target : Item
El elemento que este controlador manipulará.
Por defecto, es el mismo que el « parent », es decir, el «Item» en el que se declara el controlador. Sin embargo, a veces puede resultar útil establecer el objetivo en un «Item» diferente, con el fin de gestionar eventos dentro de un elemento pero manipular otro; o bien « null », para desactivar el comportamiento predeterminado y realizar otra acción en su lugar.
xAxis group
xAxis controla las restricciones para el arrastre horizontal.
minimum es el valor mínimo aceptable de « x » que se aplicará a « target ». « maximum » es el valor máximo aceptable de « x » que se aplicará a « target ». Si « enabled » es verdadero, se permite el arrastre horizontal. « activeValue » es lo mismo que « activeTranslation.x ».
La señal « activeValueChanged » se emite cuando cambia « activeValue », para proporcionar el incremento en el que ha variado. Está pensada para ajustar de forma incremental una propiedad mediante múltiples controladores.
yAxis group
yAxis controla las restricciones para el arrastre vertical.
minimum es el valor mínimo aceptable de « y » que se aplicará a « target ». « maximum » es el valor máximo aceptable de « y » que se aplicará a « target ». Si « enabled » es verdadero, se permite el arrastre vertical. « activeValue » es igual a « activeTranslation.y ».
La señal « activeValueChanged » se emite cuando cambia « activeValue », para proporcionar el incremento en el que ha cambiado. Está pensada para ajustar de forma incremental una propiedad mediante varios controladores:
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 }
}
}Documentación de señales
canceled(eventPoint point)
Si este gestor ya ha capturado el point indicado, esta señal se emite cuando otro gestor de punteros o elemento le arrebata la captura.
Nota: El controlador correspondiente es onCanceled.
grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
Esta señal se emite cuando el «grab» ha sufrido algún cambio relevante para este controlador.
El verbo « transition » indica lo que ha ocurrido. El objeto « point » es el punto que se ha seleccionado o deseleccionado.
Los valores válidos para « transition » son:
| Constante | Descripción |
|---|---|
PointerDevice.GrabExclusive | Este manejador ha asumido la responsabilidad principal de gestionar el ` point`. |
PointerDevice.UngrabExclusive | Este controlador ha renunciado a su control exclusivo anterior. |
PointerDevice.CancelGrabExclusive | El control exclusivo de este controlador ha sido asumido por otro o se ha cancelado. |
PointerDevice.GrabPassive | Este controlador ha adquirido una controlación pasiva para supervisar el point. |
PointerDevice.UngrabPassive | Este gestor ha renunciado a su control pasivo anterior. |
PointerDevice.CancelGrabPassive | El control pasivo anterior de este controlador ha finalizado de forma anómala. |
Nota: El controlador correspondiente es 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.