DragHandler QML Type

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

Import Statement: import QtQuick
Inherits:

MultiPointHandler

Propriétés

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 de la propriété

acceptedButtons : flags

Les boutons de la souris qui peuvent activer ce 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 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 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 cette propriété 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 dispositifs, elle ignorera les événements provenant de dispositifs ne correspondant pas.

Remarque : toutes les plateformes ne sont pas encore en mesure de faire la distinction entre la souris et le pavé tactile ; et sur celles qui le font, vous souhaitez souvent que le comportement de la souris et du pavé tactile soit le même.


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 les ignorer dans le cas contraire.

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 :

ConstanteDescription
NoModifierAucune touche de modification n'est autorisée.
ShiftModifierUne touche Shift du clavier doit être enfoncée.
ControlModifierUne touche Ctrl du clavier doit être enfoncée.
AltModifierUne touche Alt du clavier doit être enfoncée.
MetaModifierUne touche Meta du clavier doit être enfoncée.
KeypadModifierUne touche du clavier doit être enfoncée.
GroupSwitchModifierX11 uniquement (sauf s'il est activé sous Windows par un argument de ligne de commande). Une touche Mode_switch du clavier doit être enfoncée.
KeyboardModifierMaskLe gestionnaire ne se préoccupe pas des modificateurs enfoncés.

Voir également Qt::KeyboardModifier.


acceptedPointerTypes : flags

Types d'instruments de pointage (doigt, stylet, gomme, etc.) pouvant 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 d'appareils ne correspondant pas à devices.


active : bool [read-only]

La propriété true est conservée chaque fois que le gestionnaire d'entrée a assumé la responsabilité exclusive de la transmission d'un ou de plusieurs points eventPoints, en réussissant à s'emparer exclusivement de ces points. Cela signifie qu'il maintient ses propriétés à jour en fonction des mouvements de ces points d'événement et qu'il manipule activement son site target (le cas échéant).


activeTranslation : vector2d [read-only]

La traduction pendant l'exécution du geste de glissement. 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. Une fois le geste terminé, elle reste inchangée ; et lorsque le prochain geste de glissement commence, 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.

Remarque : lorsque cette propriété n'a pas été définie ou qu'elle a été définie à undefined, la lecture de la valeur renvoie Qt.ArrowCursor.

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 une page PointerHandler est désactivée, elle rejettera tous les événements et aucun signal ne sera émis.


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.

ConstanteDescription
PointerHandler.TakeOverForbiddenCe gestionnaire ne prend ni ne donne la permission de saisie à aucun type d'élément ou de gestionnaire.
PointerHandler.CanTakeOverFromHandlersOfSameTypeCe gestionnaire peut prendre la prise exclusive d'un autre gestionnaire de la même classe.
PointerHandler.CanTakeOverFromHandlersOfDifferentTypeCe handler peut prendre l'exclusivité de la prise de n'importe quel type de handler.
PointerHandler.CanTakeOverFromItemsCe gestionnaire peut s'approprier l'exclusivité de n'importe quel type d'objet.
PointerHandler.CanTakeOverFromAnythingCe handler peut s'approprier l'exclusivité de n'importe quel type d'objet ou de handler.
PointerHandler.ApprovesTakeOverByHandlersOfSameTypeCe handler autorise un autre handler de la même classe à s'emparer de la prise.
PointerHandler.ApprovesTakeOverByHandlersOfDifferentTypeCe handler autorise n'importe quel type de handler à s'emparer de la prise.
PointerHandler.ApprovesTakeOverByItemsCe handler autorise n'importe quel type d'item à prendre la prise.
PointerHandler.ApprovesCancellationCe gestionnaire permettra à sa prise d'être fixée à null.
PointerHandler.ApprovesTakeOverByAnythingCe gestionnaire autorise n'importe quel type d'élément ou de gestionnaire à s'emparer de la prise.

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 dans laquelle un eventPoint peut activer ce gestionnaire. Par exemple, vous pouvez faciliter le déplacement de petits objets en permettant à l'utilisateur de les déplacer à 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 le champ d'application 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 à la cible si elle n'est pas null. Sinon, les liaisons peuvent être utilisées pour faire des choses arbitraires avec cette valeur. Pendant l'exécution du geste de glissement, activeTranslation est continuellement ajouté à celui-ci ; à la fin du geste, il reste inchangé.


snapMode : enumeration

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

Le mode d'accrochage configure l'accrochage du centre de l'élément cible au eventPoint.

Valeurs possibles :

ConstanteDescription
DragHandler.NoSnapJamais d'accrochage
DragHandler.SnapAutoLa cible s'accroche si la touche eventPoint a été pressée en dehors de l'élément cible et que la cible est un descendant de l'élément parent (valeur par défaut).
DragHandler.SnapWhenPressedOutsideTargetLa cible s'enclenche si la touche eventPoint a été pressée en dehors de la cible.
DragHandler.SnapAlwaysToujours enclencher

target : Item

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

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

xAxis.enabled : bool

xAxis.maximum : real

xAxis.minimum : real

xAxis contrôle les contraintes de 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é. Cela permet d'ajuster progressivement une propriété par l'intermédiaire de plusieurs gestionnaires.


yAxis group

yAxis.activeValue : real [read-only]

yAxis.enabled : bool

yAxis.maximum : real

yAxis.minimum : real

yAxis contrôle les contraintes de déplacement 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 du signal

canceled(eventPoint point)

Si ce gestionnaire a déjà saisi l'objet point, ce signal est émis lorsque la saisie est volée par un autre gestionnaire de pointeurs ou un autre objet.

Note : Le gestionnaire correspondant est onCanceled.


grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque la prise 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

ConstanteDescription
PointerDevice.GrabExclusiveCe gestionnaire a pris la responsabilité principale du traitement de point.
PointerDevice.UngrabExclusiveCe gestionnaire a renoncé à sa prise exclusive précédente.
PointerDevice.CancelGrabExclusiveLa prise exclusive de ce gestionnaire a été reprise ou annulée.
PointerDevice.GrabPassiveCe gestionnaire a acquis une prise passive, pour surveiller le point.
PointerDevice.UngrabPassiveCe handler a renoncé à sa prise passive précédente.
PointerDevice.CancelGrabPassiveLa prise passive précédente de ce gestionnaire s'est terminée de manière anormale.

Note : Le gestionnaire correspondant est onGrabChanged.


© 2025 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.