DragHandler QML Type

Manejador para arrastrar. Más...

• Lista de todos los miembros, incluidos los heredados
• Miembros obsoletos

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 manejador que se utiliza para mover interactivamente un Item. Como otros Manejadores de Entrada, por defecto es completamente funcional, y manipula su target.

import QtQuick

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

Tiene propiedades para restringir el rango de arrastre.

Si se declara dentro de un Elemento pero se le asigna un target diferente, entonces maneja eventos dentro de los límites del Elemento parent pero manipula el Elemento target en su lugar:

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 propiedades 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 necesitará arrastrar tantos dedos en la misma dirección para empezar a arrastrar. Un gesto de arrastre con varios dedos puede ser detectado independientemente de un DragHandler (por defecto) de un solo dedo y de un PinchHandler en el mismo Item, y por lo tanto puede ser utilizado 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. Pero si el target es un Item, centroid es el punto en el que comienza el arrastre y al que se moverá el target (sujeto a restricciones).

DragHandler puede utilizarse junto con la propiedad adjunta Drag para implementar la función arrastrar y soltar.

Ver también Drag, MouseArea, y Qt Quick Ejemplos - Manejadores de puntero.

Documentación de la propiedad

acceptedButtons : flags

Los botones del ratón que pueden activar este DragHandler.

Por defecto, esta propiedad se establece en Qt.LeftButton. Puede establecerse en una combinación OR de botones del ratón, e ignorará los eventos de otros botones.

Por ejemplo, si un componente (como TextEdit) ya gestiona los arrastres con el botón izquierdo a su manera, puede aumentarse con un DragHandler que haga algo diferente cuando se arrastra mediante 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 señaladores que pueden activar este DragHandler.

Por defecto, esta propiedad está establecida a PointerDevice.AllDevices. Si la estableces a una combinación OR de tipos de dispositivos, ignorará los eventos de los dispositivos que no coincidan.

acceptedModifiers : flags

Si esta propiedad está establecida, requerirá que los modificadores de teclado dados estén pulsados para reaccionar a los eventos de puntero, y en caso contrario los ignorará.

Por ejemplo, dos DragHandlers pueden realizar dos operaciones de arrastrar y soltar diferentes, dependiendo de si el modificador Control está pulsado:

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), entonces el DragHandler ignora las teclas modificadoras.

Si se establece acceptedModifiers a una combinación OR de teclas modificadoras, significa que todos esos modificadores deben estar pulsados para activar el manejador.

Los modificadores disponibles son los siguientes:

Véase también Qt::KeyboardModifier.

acceptedPointerTypes : flags

Los tipos de instrumentos señaladores (dedo, lápiz óptico, goma de borrar, etc.) que pueden activar este DragHandler.

Por defecto, esta propiedad se establece en PointerDevice.AllPointerTypes. Si se establece en una combinación OR de tipos de dispositivos, se ignorarán los eventos de los que no coincidan devices.

active : bool [read-only]

Esto se mantiene true siempre que este Manejador de Entrada haya tomado la responsabilidad exclusiva de manejar uno o más eventPoints, tomando con éxito un agarre exclusivo de esos puntos. Esto significa que está manteniendo sus propiedades actualizadas de acuerdo con los movimientos de esos eventPoints y manipulando activamente su target (si existe).

activeTranslation : vector2d [read-only]

La traslación mientras se realiza el gesto de arrastre. Es 0, 0 cuando comienza el gesto, y aumenta a medida que el(los) punto(s) del evento se arrastra(n) hacia abajo y hacia la derecha. Una vez finalizado el gesto, se mantiene igual; y cuando comienza el siguiente gesto de arrastre, se restablece a 0, 0 de nuevo.

cursorShape : Qt::CursorShape

Esta propiedad contiene la forma del cursor que aparecerá siempre que el ratón pase por encima del elemento parent mientras active esté true.

Las formas de cursor disponibles son:

• 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.CursorManoCerrada
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

El valor por defecto no está establecido, lo que permite que aparezca el elemento cursor de parent. Esta propiedad puede restablecerse a la misma condición inicial estableciéndola a undefined.

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 trate como un gesto de arrastre.

El valor por defecto depende de la plataforma y de la resolución de pantalla. Se puede restablecer al valor por defecto estableciéndolo como indefinido. El comportamiento cuando comienza un gesto de arrastre varía en los distintos manejadores.

enabled : bool

Si un PointerHandler está desactivado, rechazará todos los eventos y no se emitirá ninguna señal.

Si un PointerHandler's parent es disabled, el manejador también será efectivamente desactivado, incluso cuando la propiedad enabled permanezca true.

grabPermissions : flags

Esta propiedad especifica los permisos cuando la lógica de este manejador decide hacerse cargo de la toma exclusiva, o cuando se le pide que apruebe la toma o cancelación de la toma por parte de otro manejador.

El valor predeterminado es PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything que permite la mayoría de los escenarios de toma, pero evita, por ejemplo, dos PinchHandlers luchando por los mismos puntos de contacto.

margin : real

El margen más allá de los límites del elemento parent dentro del cual un eventPoint puede activar este manejador. Por ejemplo, puede facilitar el arrastre de elementos pequeños permitiendo al usuario arrastrar 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 manejador; el Item en el que fue declarado. El manejador manejará eventos en nombre de este Item, lo que significa que un evento de puntero es relevante si al menos uno de sus eventPoints ocurre dentro del interior del Item. Inicialmente target() es el mismo, pero puede ser reasignado.

Véase también target y QObject::parent().

persistentTranslation : vector2d

La traducción que se aplicará a target si no es null. En caso contrario, se pueden utilizar bindings para hacer cosas arbitrarias con este valor. Mientras se realiza el gesto de arrastre, se le añade continuamente activeTranslation; una vez finalizado el gesto, permanece igual.

snapMode : enumeration

Esta propiedad contiene el modo de ajuste.

El modo de ajuste configura el ajuste del centro del elemento target a eventPoint.

Valores posibles:

target : Item

Elemento que manipulará este controlador.

Por defecto, es el mismo que parent, el Item dentro del cual se declara el manejador. Sin embargo, a veces puede ser útil establecer el objetivo a un elemento diferente, con el fin de manejar eventos dentro de un elemento pero manipular otro; o a null, para desactivar el comportamiento por defecto y hacer otra cosa en su lugar.

xAxis group

xAxis controla las restricciones para el arrastre horizontal.

minimum es el valor mínimo aceptable de x que debe aplicarse a target. maximum es el valor máximo aceptable de x que debe aplicarse 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 por el que ha cambiado. Esto está pensado para ajustar incrementalmente una propiedad a través de múltiples manejadores.

yAxis group

yAxis controla las restricciones para el arrastre vertical.

minimum es el valor mínimo aceptable de y que debe aplicarse a target. maximum es el valor máximo aceptable de y que debe aplicarse a target. Si enabled es verdadero, se permite el arrastre vertical. activeValue es lo mismo que activeTranslation.y.

La señal activeValueChanged se emite cuando cambia activeValue, para proporcionar el incremento por el que ha cambiado. Esto está pensado para ajustar una propiedad de forma incremental a través de múltiples manejadores:

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 la señal

canceled(eventPoint point)

Si este manejador ya ha agarrado el point dado, esta señal es emitida cuando el agarre es robado por un Manejador de Punteros o Item diferente.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Esta señal se emite cuando la cuchara ha cambiado de alguna manera que es relevante para este controlador.

El transition (verbo) dice lo que ha pasado. El point (objeto) es el punto que fue agarrado o no agarrado.

Los valores válidos para transition son: