En esta página

DragHandler QML Type

Controlador para arrastrar. Más...

Import Statement: import QtQuick
Inherits:

MultiPointHandler

Propiedades

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:

ConstanteDescripción
NoModifierNo se permite ninguna tecla modificadora.
ShiftModifierSe debe pulsar la tecla «Shift» del teclado.
ControlModifierSe debe pulsar la tecla Ctrl del teclado.
AltModifierSe debe pulsar la tecla Alt del teclado.
MetaModifierSe debe pulsar la tecla Meta del teclado.
KeypadModifierSe debe pulsar una tecla del teclado numérico.
GroupSwitchModifierSolo 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.
KeyboardModifierMaskAl 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.

ConstanteDescripción
PointerHandler.TakeOverForbiddenEste controlador no toma ni concede permiso de control a ningún tipo de elemento o controlador.
PointerHandler.CanTakeOverFromHandlersOfSameTypeEste controlador puede tomar el control exclusivo de otro controlador de la misma clase.
PointerHandler.CanTakeOverFromHandlersOfDifferentTypeEste controlador puede tomar el control exclusivo de cualquier tipo de controlador.
PointerHandler.CanTakeOverFromItemsEste controlador puede tomar el control exclusivo de cualquier tipo de elemento.
PointerHandler.CanTakeOverFromAnythingEste controlador puede tomar el control exclusivo de cualquier tipo de elemento o controlador.
PointerHandler.ApprovesTakeOverByHandlersOfSameTypeEste controlador concede permiso a otro controlador de la misma clase para que adquiera el control.
PointerHandler.ApprovesTakeOverByHandlersOfDifferentTypeEste controlador concede permiso a cualquier tipo de controlador para que adquiera el control.
PointerHandler.ApprovesTakeOverByItemsEste controlador permite que cualquier tipo de elemento adquiera el control exclusivo.
PointerHandler.ApprovesCancellationEste controlador permitirá que su control se establezca en nulo.
PointerHandler.ApprovesTakeOverByAnythingEste 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:

ConstanteDescripción
DragHandler.NoSnapNunca alinear
DragHandler.SnapAutoEl 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.SnapWhenPressedOutsideTargetEl 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.activeValue : real [read-only]

xAxis.enabled : bool

xAxis.maximum : real

xAxis.minimum : real

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.activeValue : real [read-only]

yAxis.enabled : bool

yAxis.maximum : real

yAxis.minimum : real

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:

ConstanteDescripción
PointerDevice.GrabExclusiveEste manejador ha asumido la responsabilidad principal de gestionar el ` point`.
PointerDevice.UngrabExclusiveEste controlador ha renunciado a su control exclusivo anterior.
PointerDevice.CancelGrabExclusiveEl control exclusivo de este controlador ha sido asumido por otro o se ha cancelado.
PointerDevice.GrabPassiveEste controlador ha adquirido una controlación pasiva para supervisar el point.
PointerDevice.UngrabPassiveEste gestor ha renunciado a su control pasivo anterior.
PointerDevice.CancelGrabPassiveEl 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.