Drag QML Type

Permet de spécifier les événements de glisser-déposer pour les éléments déplacés. Plus...

Import Statement: import QtQuick

Propriétés attachées

Signaux attachés

Méthodes attachées

Description détaillée

Grâce à la propriété Drag attached, n'importe quel élément peut devenir une source d'événements de glisser-déposer dans une scène.

Lorsqu'un glisser est active sur un élément, tout changement dans la position de cet élément génère un événement de glisser qui est envoyé à tout DropArea qui croise la nouvelle position de l'élément. Les autres éléments qui mettent en œuvre des gestionnaires d'événements de glisser-déposer peuvent également recevoir ces événements.

L'extrait suivant montre comment un élément peut être déplacé à l'aide d'une souris ( MouseArea). Cependant, le déplacement ne se limite pas à la souris ; tout ce qui peut déplacer un élément peut générer des événements de déplacement, y compris les événements tactiles, les animations et les liaisons.

import QtQuick

Item {
    width: 200; height: 200

    DropArea {
        x: 75; y: 75
        width: 50; height: 50

        Rectangle {
            anchors.fill: parent
            color: "green"

            visible: parent.containsDrag
        }
    }

    Rectangle {
        x: 10; y: 10
        width: 20; height: 20
        color: "red"

        Drag.active: dragArea.drag.active
        Drag.hotSpot.x: 10
        Drag.hotSpot.y: 10

        MouseArea {
            id: dragArea
            anchors.fill: parent

            drag.target: parent
        }
    }
}

Un glissement peut être interrompu soit en l'annulant avec Drag.cancel() ou en définissant Drag.active sur false, soit avec un événement de chute en appelant Drag.drop(). Si l'événement de dépôt est accepté, Drag.drop() renverra le drop action choisi par le destinataire de l'événement, sinon il renverra Qt.IgnoreAction.

Voir également Qt Quick Exemples - Glisser-déposer.

Documentation de la propriété Attached

Drag.active : bool [read-only]

Cette propriété indique si une séquence d'événements de glissement est actuellement active.

En liant cette propriété à la propriété active de MouseArea::drag, startDrag sera appelé lorsque l'utilisateur commencera à glisser.

La définition de cette propriété à true enverra également un événement QDragEnter à la scène avec la position actuelle de l'élément. En lui attribuant la valeur false, un événement QDragLeave est envoyé.

Lorsqu'un glissement est actif, tout changement de position d'un élément envoie à la scène un événement QDragMove indiquant la nouvelle position de l'élément.


Drag.dragType : enumeration

Cette propriété indique s'il faut lancer automatiquement les déplacements, ne rien faire ou utiliser des déplacements internes rétrocompatibles. La valeur par défaut est d'utiliser des déplacements internes compatibles avec la rétrocompatibilité.

Un déplacement peut également être lancé manuellement à l'aide de startDrag.

ConstanteDescription
Drag.Nonene pas démarrer les dragues automatiquement
Drag.Automaticdémarre les dragues automatiquement
Drag.Internal(par défaut) démarre automatiquement les drags compatibles avec la rétrocompatibilité

Lorsque vous utilisez Drag.Automatic, vous devez également définir mimeData et lier la propriété active à la propriété active de MouseArea: MouseArea::drag.active


Drag.hotSpot : point

Cette propriété définit la position du curseur par rapport au coin supérieur gauche de l'élément.

Par défaut, cette position est (0, 0).

Les modifications apportées au point chaud déclenchent un nouveau déplacement avec la position mise à jour.


Drag.imageSource : url

Cette propriété contient l'URL de l'image qui sera utilisée pour représenter les données lors de l'opération de glisser-déposer. La modification de cette propriété après le début de l'opération de glisser-déposer n'aura aucun effet.

L'exemple ci-dessous utilise le contenu d'un élément comme image de glissement :

import QtQuick

Item {
    width: 200; height: 200

    Rectangle {
        anchors.centerIn: parent
        width: text.implicitWidth + 20; height: text.implicitHeight + 10
        color: "green"
        radius: 5

        Drag.dragType: Drag.Automatic
        Drag.supportedActions: Qt.CopyAction
        Drag.mimeData: {
            "text/plain": "Copied text"
        }

        Text {
            id: text
            anchors.centerIn: parent
            text: "Drag me"
        }

        DragHandler {
            id: dragHandler
            onActiveChanged:
                if (active) {
                    parent.grabToImage(function(result) {
                        parent.Drag.imageSource = result.url
                        parent.Drag.active = true
                    })
                } else {
                    parent.Drag.active = false
                }
        }
    }
}

Voir aussi Item::grabToImage().


Drag.imageSourceSize : size [since 6.8]

Cette propriété définit la taille de l'image qui sera utilisée pour représenter les données lors de l'opération de glisser-déposer. La modification de cette propriété après le début de l'opération de glisser-déposer n'aura aucun effet.

Cette propriété définit le nombre maximum de pixels stockés pour l'image chargée afin que les grandes images n'utilisent pas plus de mémoire que nécessaire. Voir Image.sourceSize pour plus de détails.

L'exemple ci-dessous montre une image SVG rendue à une taille donnée, et la rend à une taille différente pour l'image glissée :

import QtQuick

Item {
    width: 200; height: 200

    Image {
        anchors.centerIn: parent
        source: "images/qt_logo.svg"
        sourceSize.width: 96

        Drag.dragType: Drag.Automatic
        Drag.supportedActions: Qt.CopyAction
        Drag.mimeData: {
            "text/plain": "Qt Quick rocks!"
        }
        Drag.imageSource: "images/qt_logo.svg"
        Drag.imageSourceSize: Qt.size(48, 35)
        Drag.active: dragHandler.active

        DragHandler {
            id: dragHandler
        }
    }
}

Cette propriété a été introduite dans Qt 6.8.

Voir également imageSource et Item::grabToImage().


Drag.keys : stringlist

Cette propriété contient une liste de clés qui peuvent être utilisées par DropArea pour filtrer les événements de glissement.

La modification des clés pendant qu'un déplacement est actif réinitialise la séquence des événements de déplacement en envoyant un événement de sortie de déplacement suivi d'un événement d'entrée de déplacement avec la nouvelle source.


Drag.mimeData : var

Cette propriété contient une correspondance entre le type de mime et les données utilisées pendant startDrag. Les données mime doivent être d'un type correspondant au type mime (par exemple, une chaîne de caractères si le type mime est "text/plain", ou une image si le type mime est "image/png"), ou une adresse ArrayBuffer dont les données sont encodées selon le type mime.


Drag.proposedAction : enumeration

Cette propriété contient une action recommandée par la source de drag comme valeur de retour de Drag.drop().

Les modifications apportées à proposedAction déclenchent un événement de déplacement avec la proposition mise à jour.


Drag.source : Object

Cette propriété contient un objet qui est identifié par les destinataires des événements de glissement comme étant la source des événements. Par défaut, il s'agit de l'élément auquel la propriété Drag est attachée.

La modification de la source alors qu'un déplacement est actif réinitialise la séquence des événements de déplacement en envoyant un événement de sortie de déplacement suivi d'un événement d'entrée de déplacement avec la nouvelle source.


Drag.supportedActions : flags

Cette propriété contient les valeurs de retour de Drag.drop() prises en charge par la source de glissement.

Si l'on modifie les actions prises en charge alors qu'un déplacement est actif, la séquence d'événements de déplacement est réinitialisée par l'envoi d'un événement de départ de déplacement suivi d'un événement d'entrée de déplacement avec la nouvelle source.


Drag.target : Object

Lorsqu'un déplacement est actif, cette propriété contient le dernier objet à accepter un événement d'entrée de la part de l'élément déplacé. Si la position actuelle du déplacement ne croise aucune cible acceptée, cette propriété est nulle.

Lorsqu'un glisser n'est pas actif, cette propriété contient l'objet qui a accepté l'événement de dépôt qui a mis fin au glisser, si aucun objet n'a accepté le dépôt ou si le glisser a été annulé, la cible sera alors nulle.


Documentation du signal attaché

dragFinished(DropAction dropAction)

Ce signal est émis lorsqu'un glisser se termine et que le glisser a été démarré avec la méthode startDrag() ou démarré automatiquement à l'aide de la propriété dragType.

dropAction contient l'action acceptée par l'élément cible.

Remarque : le gestionnaire correspondant est onDragFinished.

Voir également drop().


dragStarted()

Ce signal est émis lorsqu'un drag est démarré avec la méthode startDrag() ou lorsqu'il est démarré automatiquement à l'aide de la propriété dragType.

Remarque : le gestionnaire correspondant est onDragStarted.


Documentation de la méthode attachée

void cancel()

Met fin à une séquence de glissement.


enumeration drop()

Met fin à une séquence de glissement en envoyant un événement de chute à l'élément cible.

Renvoie l'action acceptée par l'élément cible. Si l'élément cible ou un parent n'accepte pas l'événement de dépôt, Qt.IgnoreAction sera renvoyé.

L'action de dépôt renvoyée peut être l'une des suivantes

ConstanteDescription
Qt.CopyActionCopier les données vers la cible
Qt.MoveActionDéplacer les données de la source vers la cible
Qt.LinkActionCréer un lien entre la source et la cible.
Qt.IgnoreActionIgnore l'action (ne fait rien avec les données).

void start(flags supportedActions)

Commence à envoyer des événements de glissement. Utilisé pour démarrer les drafts internes à l'ancienne. startDrag est la nouvelle méthode préférée pour démarrer les drags.

L'argument facultatif supportedActions peut être utilisé pour remplacer la propriété supportedActions pour la séquence démarrée.


void startDrag(flags supportedActions)

Commence à envoyer des événements de traînées.

L'argument facultatif supportedActions peut être utilisé pour remplacer la propriété supportedActions de la séquence commencée.


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