DragHandler QML Type

Gestionnaire pour les déplacements. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités
• les membres dépréciés

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. Comme les autres gestionnaires d'entrée, il est par défaut entièrement fonctionnel et manipule son site target.

import QtQuick

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

Il possède des propriétés permettant de restreindre la portée du déplacement.

S'il est déclaré dans un élément mais qu'on lui attribue un autre target, il traite les événements dans les limites de l'élément parent mais manipule l'élément target à la place :

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 est de définir target sur null et de 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 les valeurs minimumPointCount et maximumPointCount sont supérieures à 1, l'utilisateur devra faire glisser autant de doigts dans la même direction pour commencer à faire glisser. Un geste de glissement à plusieurs doigts peut être détecté indépendamment d'un DragHandler (par défaut) à un doigt et d'un PinchHandler sur le même élément, et peut donc être utilisé pour ajuster une autre caractéristique indépendamment du comportement de pincement habituel : par exemple, ajuster une transformation d'inclinaison, ou ajuster une autre valeur numérique, si le target est défini sur null. Mais si target est un élément, centroid est le point à partir duquel le déplacement commence et vers lequel target sera déplacé (sous réserve de contraintes).

DragHandler peut être utilisé avec la propriété attachée Drag pour mettre en œuvre le glisser-déposer.

Voir également Drag, MouseArea, et Qt Quick Exemples - Pointer Handlers.

Documentation sur les propriétés

acceptedButtons : flags

Les boutons de la souris qui peuvent activer ce site 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 la souris et ignorera les événements provenant d'autres boutons.

Par exemple, si un composant (tel que TextEdit) gère déjà à sa manière les déplacements avec le bouton gauche, il peut être complété par un composant DragHandler qui agit différemment lorsqu'il est déplacé 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 dispositifs de pointage qui peuvent activer ce site 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 de périphériques ne correspondant pas.

acceptedModifiers : flags

Si cette propriété est définie, il faudra appuyer sur les modificateurs de clavier donnés pour réagir aux événements de pointeur, et sinon les ignorer.

Par exemple, deux DragHandlers peuvent effectuer deux opérations de glisser-déposer différentes, selon que le modificateur Control est enfoncé 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 la valeur de cette propriété est Qt.KeyboardModifierMask (valeur par défaut), DragHandler ignore les touches de modification.

Si vous attribuez à acceptedModifiers la valeur d'une combinaison OU de touches de modification, cela signifie que tous ces modificateurs doivent être activés pour que le gestionnaire soit activé.

Les modificateurs disponibles sont les suivants :

Voir aussi Qt::KeyboardModifier.

acceptedPointerTypes : flags

Les types d'instruments de pointage (doigt, stylet, gomme, etc.) qui peuvent activer cette propriété DragHandler.

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

active : bool [read-only]

Il s'agit de true chaque fois que ce gestionnaire d'entrée a pris l'entière responsabilité de la transmission d'un ou de plusieurs eventPoints, en s'emparant avec succès de ces points de manière exclusive. Cela signifie qu'il tient ses propriétés à jour en fonction des mouvements de ces eventPoints et qu'il manipule activement son site target (le cas échéant).

activeTranslation : vector2d [read-only]

La traduction pendant que le geste de glissement est effectué. Elle est de 0, 0 au début du geste et augmente au fur et à mesure que le(s) point(s) d'événement est(sont) déplacé(s) vers le bas et vers la droite. À la fin du geste, elle reste inchangée et, au début du prochain geste de glissement, elle est à nouveau réinitialisée à 0, 0.

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui apparaîtra lorsque la souris survolera l'élément parent alors que active est true.

Les formes de curseur disponibles sont les suivantes :

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

La valeur par défaut n'est pas définie, ce qui permet à l'élément cursor de parent d'apparaître. Cette propriété peut être ramenée à la même condition initiale en lui attribuant la valeur undefined.

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

dragThreshold : int

La distance en pixels sur laquelle l'utilisateur doit faire glisser une page eventPoint pour que cela soit considéré comme un geste de glissement.

La valeur par défaut dépend de la plate-forme et de la résolution de l'écran. Elle peut être ramenée à la valeur par défaut en lui attribuant la valeur undefined. Le comportement au 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'un PointerHandler est disabled, le gestionnaire sera également désactivé, même si la propriété enabled reste true.

grabPermissions : flags

Cette propriété spécifie les autorisations lorsque la logique de ce gestionnaire décide de prendre en charge la saisie exclusive, ou lorsqu'il lui est demandé d'approuver la prise en charge ou l'annulation de la saisie par un autre gestionnaire.

La valeur par défaut est PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything, ce qui permet la plupart des scénarios de prise en charge mais évite, par exemple, que deux PinchHandler ne se disputent les mêmes points de contact.

margin : real

La marge au-delà des limites de l'élément parent à l'intérieur de laquelle eventPoint peut activer ce gestionnaire. Par exemple, vous pouvez faciliter le glissement de petits objets 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

Le Item qui est la portée du gestionnaire ; l'élément dans lequel il a été déclaré. Le gestionnaire traitera les événements au nom de cet élément, 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'élément. Initialement, target() est le même, mais il peut être réaffecté.

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

persistentTranslation : vector2d

La traduction à appliquer à target s'il ne s'agit pas de null. Sinon, les liaisons peuvent être utilisées pour faire des choses arbitraires avec cette valeur. Pendant l'exécution du geste de glisser, activeTranslation est continuellement ajouté à cette valeur ; après la fin du geste, elle reste inchangée.

snapMode : enumeration

Cette propriété contient le mode d'accrochage.

Le mode d'accrochage configure l'accrochage du centre de l'élément target sur le site eventPoint.

Valeurs possibles :

target : Item

L'élément que ce gestionnaire manipulera.

Par défaut, il est identique à parent, l'élément dans lequel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un élément différent, afin de gérer des événements dans un élément mais d'en manipuler un autre ; ou de null, pour désactiver le comportement par défaut et faire quelque chose d'autre à la place.

xAxis group

xAxis contrôle les contraintes pour le déplacement 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 par lequel il a changé. Ce signal est destiné à l'ajustement progressif d'une propriété via plusieurs gestionnaires.

yAxis group

yAxis contrôle les contraintes pour le 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 activeValue change, afin de fournir l'incrément par lequel il a changé. Ce signal est destiné à l'ajustement progressif d'une propriété par l'intermédiaire de 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'objet donné point, ce signal est émis lorsque la saisie est volée par un autre gestionnaire de pointeurs ou un autre objet.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le grab a changé d'une manière ou d'une autre, ce qui est pertinent pour ce gestionnaire.

Le transition (verbe) indique ce qui s'est passé. Le point (objet) est le point qui a été saisi ou désaisi.

Les valeurs valides pour transition sont les suivantes