DragHandler QML Type

Gestionnaire de glisser-déposer. En savoir plus...

• Liste de tous les membres, y compris les membres hérités
• Membres obsolètes

Propriétés

• 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

Signaux

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Description détaillée

DragHandler est un gestionnaire utilisé pour déplacer un élément de manière interactive. À l'instar des autres gestionnaires d'entrée, il est, par défaut, entièrement fonctionnel et manipule son target.

import QtQuick

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

Il dispose de propriétés permettant de limiter la plage de glissement.

S’il est déclaré au sein d’un élément mais qu’on lui attribue un « target » différent, il gère alors les événements dans les limites de l’élément « parent », mais manipule à la place l’élément « 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
    }
}

Une troisième façon de l’utiliser consiste à définir ` target ` sur ` null ` et à réagir aux changements de propriété d’une autre manière :

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` et `maximumPointCount` sont définis sur des valeurs supérieures à 1, l’utilisateur devra faire glisser autant de doigts dans la même direction pour lancer le glissement. Un geste de glissement à plusieurs doigts peut être détecté indépendamment à la fois d’un DragHandler à un seul doigt (par défaut) et d’un PinchHandler sur le même élément, et peut donc être utilisé pour ajuster une autre fonctionnalité indépendamment du comportement habituel de pincement : par exemple, ajuster une transformation d’inclinaison ou une autre valeur numérique, si l’ target est défini sur null. Mais si l’ target est un « Item », « centroid » correspond au point où le glissement commence et vers lequel l’« target » sera déplacé (sous réserve de contraintes).

DragHandler peut être utilisé conjointement avec la propriété attachée Drag pour implémenter le glisser-déposer.

Voir également Drag, MouseArea et Qt Quick Exemples - Gestionnaires de pointeurs.

Documentation sur les propriétés

acceptedButtons : flags

Les boutons de la souris pouvant déclencher cette DragHandler.

Par défaut, cette propriété est définie sur Qt.LeftButton. Elle peut être définie sur une combinaison (ou) de boutons de souris et ignorera les événements provenant des autres boutons.

Par exemple, si un composant (tel que TextEdit) gère déjà les glissements avec le bouton gauche à sa manière, il peut être complété par un DragHandler qui effectue une action différente lors d’un glissement avec le bouton droit :

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

Les types de périphériques de pointage pouvant déclencher cette DragHandler.

Par défaut, cette propriété est définie sur PointerDevice.AllDevices. Si vous la définissez sur une combinaison « OU » de types de périphériques, elle ignorera les événements provenant des périphériques qui ne correspondent pas.

acceptedModifiers : flags

Si cette propriété est définie, les événements du pointeur ne seront pris en compte que si les touches de modification spécifiées sont enfoncées ; dans le cas contraire, ils seront ignorés.

Par exemple, deux DragHandlers peuvent effectuer deux opérations de glisser-déposer différentes, selon que la touche de modification « Control » est enfoncée ou non :

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 cette propriété est définie sur « Qt.KeyboardModifierMask » (valeur par défaut), l’ DragHandler ignore les touches de modification.

Si vous définissez « acceptedModifiers » sur une combinaison « OU » de touches de modification, cela signifie que toutes ces touches doivent être enfoncées pour activer le gestionnaire.

Les modificateurs disponibles sont les suivants :

Voir également Qt::KeyboardModifier.

acceptedPointerTypes : flags

Les types de périphériques de pointage (doigt, stylet, gomme, etc.) capables d'activer cette DragHandler.

Par défaut, cette propriété est définie sur PointerDevice.AllPointerTypes. Si vous la définissez sur une combinaison « OU » de types de périphériques, elle ignorera les événements provenant d’ devices non correspondants.

active : bool [read-only]

Cette propriété prend la valeur « true » dès lors que ce gestionnaire d’entrée a pris la responsabilité exclusive de la gestion d’un ou plusieurs « eventPoints », en ayant réussi à s’approprier de manière exclusive ces points. Cela signifie qu’il maintient ses propriétés à jour en fonction des mouvements de ces « eventPoints » et qu’il manipule activement ses « target » (le cas échéant).

activeTranslation : vector2d [read-only]

La translation pendant l'exécution du geste de glissement. Elle est égale à 0, 0 au début du geste, puis augmente à mesure que le ou les points d'événement sont glissés vers le bas et vers la droite. Une fois le geste terminé, elle reste inchangée ; et lorsque le geste de glissement suivant commence, elle est réinitialisée à 0, 0.

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui s'affichera chaque fois que la souris survolera l'élément « parent » lorsque l'option « active » est activée ( true).

Les formes de curseur disponibles sont les suivantes :

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.CursorTailleVerticale
• Qt.CursorTailleHoriz
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.CurseurVide
• Qt.CursorDiviséVertical
• Qt.Cursor à division horizontale
• Qt.CursorMainPointante
• Qt.CursorInterdit
• Qt.Cursor« Qu'est-ce que c'est ? »
• Qt.Curseur-occupé
• Qt.CursorMainOuverte
• Qt.CurseurMainFermée
• Qt.CurseurGlisserCopier
• Qt.CurseurGlisserDéplacer
• Qt.DragLinkCursor

La valeur par défaut n'est pas définie, ce qui permet à l'élément « cursor » de l'parent d'apparaître. Cette propriété peut être réinitialisée à son état initial en lui attribuant la valeur « undefined ».

Voir également Qt::CursorShape, QQuickItem::cursor() et HoverHandler::cursorShape.

dragThreshold : int

Distance en pixels que l'utilisateur doit parcourir en faisant glisser un élément d'eventPoint pour que ce mouvement soit considéré comme un geste de glissement.

La valeur par défaut dépend de la plateforme et de la résolution de l'écran. Elle peut être réinitialisée à sa valeur par défaut en la définissant sur « undefined ». Le comportement lors du début d'un geste de glissement varie selon les gestionnaires.

enabled : bool

Si un « PointerHandler » est désactivé, il rejettera tous les événements et aucun signal ne sera émis.

Si la propriété « parent » d'une PointerHandler est définie sur « disabled », le gestionnaire sera également désactivé de fait, même si la propriété « enabled » reste définie sur « true ».

grabPermissions : flags

Cette propriété définit les autorisations lorsque la logique de ce gestionnaire décide de prendre le contrôle exclusif, ou lorsqu'il est invité à approuver la prise de contrôle ou l'annulation de celle-ci par un autre gestionnaire.

La valeur par défaut est « PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything », ce qui autorise la plupart des scénarios de prise de contrôle tout en évitant, par exemple, que deux PinchHandlers se disputent les mêmes points de contact.

margin : real

La marge située au-delà des limites de l'élément « parent », à l'intérieur de laquelle un « eventPoint » peut déclencher ce gestionnaire. Par exemple, vous pouvez faciliter le glissement de petits éléments en permettant à l'utilisateur de les faire glisser à partir d'une position proche :

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

L'objet ` Item `, qui correspond au champ d'application du gestionnaire ; l'`Item` dans lequel il a été déclaré. Le gestionnaire traitera les événements pour le compte de cet `Item`, ce qui signifie qu'un événement de pointeur est pertinent si au moins l'un de ses ` eventPoints ` se produit à l'intérieur de l'`Item`. Au départ, ` target() ` est identique, mais il peut être réattribué.

Voir également target et QObject::parent().

persistentTranslation : vector2d

La conversion à appliquer à l'target si celle-ci n'est pas de type null. Sinon, des liaisons peuvent être utilisées pour effectuer des opérations arbitraires sur cette valeur. Pendant l'exécution du geste de glissement, la valeur activeTranslation est continuellement ajoutée à celle-ci ; une fois le geste terminé, elle reste inchangée.

snapMode : enumeration

Cette propriété définit le mode d'alignement.

Le mode d'alignement permet de configurer l'alignement du centre de l'élément « target » par rapport à l'élément « eventPoint ».

Valeurs possibles :

target : Item

L'élément que ce gestionnaire va manipuler.

Par défaut, il s’agit de l’ parent, c’est-à-dire l’élément au sein duquel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un autre élément, afin de gérer les événements au sein d’un élément tout en manipulant un autre ; ou d’ null, pour désactiver le comportement par défaut et effectuer une autre action à la place.

xAxis group

xAxis définit les contraintes relatives au glissement horizontal.

minimum est la valeur minimale acceptable de « x » à appliquer à « target ». « maximum » est la valeur maximale acceptable de « x » à appliquer à « target ». Si « enabled » est vrai, le glissement horizontal est autorisé. « activeValue » est identique à « activeTranslation.x ».

Le signal « activeValueChanged » est émis lorsque « activeValue » change, afin de fournir l’incrément correspondant à cette modification. Il est destiné à permettre le réglage incrémental d’une propriété via plusieurs gestionnaires.

yAxis group

yAxis définit les contraintes relatives au glissement vertical.

minimum est la valeur minimale acceptable de ` y ` à appliquer à ` target`. ` maximum ` est la valeur maximale acceptable de ` y ` à appliquer à ` target`. Si ` enabled ` est vrai, le glissement vertical est autorisé. ` activeValue ` est identique à ` activeTranslation.y`.

Le signal « activeValueChanged » est émis lorsque la valeur de « activeValue » change, afin de fournir l’incrément correspondant à cette modification. Il est destiné à ajuster progressivement une propriété via plusieurs gestionnaires :

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

Documentation sur les signaux

canceled(eventPoint point)

Si ce gestionnaire a déjà saisi l'point donné, ce signal est émis lorsqu'un autre gestionnaire de pointeur ou un autre élément lui vole la saisie.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le « grab » a subi une modification pertinente pour ce gestionnaire.

Le verbe « transition » indique ce qui s’est produit. L’objet « point » correspond au point qui a été sélectionné ou désélectionné.

Les valeurs valides pour « transition » sont :