Drag QML Type

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

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

Propriétés attachées

• active : bool
• dragType : enumeration
• hotSpot : point
• imageSource : url
• imageSourceSize : size (since 6.8)
• keys : stringlist
• mimeData : var
• proposedAction : enumeration
• source : Object
• supportedActions : flags
• target : Object

Signaux attachés

• dragFinished(DropAction dropAction)
• dragStarted()

Méthodes attachées

• void cancel()
• enumeration drop()
• void start(flags supportedActions)
• void startDrag(flags supportedActions)

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 sur 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 à faire glisser l'élément.

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, toute modification de la 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 convient de lancer automatiquement les drafts, de ne rien faire ou d'utiliser des drags internes rétrocompatibles. La valeur par défaut est l'utilisation de drags internes compatibles avec le retour en arrière.

Il est également possible de lancer manuellement un dragage à l'aide de startDrag.

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

Toute modification du point chaud déclenche 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. Modifier 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. Modifier 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 maximal 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 pouvant ê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 si le type mime est "text/plain", ou une image si le type mime est "image/png"), ou un 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 déplacement comme valeur de retour de Drag.drop().

Les modifications apportées à proposedAction déclencheront 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 de ces événements. Par défaut, il s'agit de l'élément auquel la propriété Drag est attachée.

Si la source est modifiée alors qu'un glissement est actif, la séquence des événements de glissement est réinitialisée par l'envoi d'un événement de sortie de glissement suivi d'un événement d'entrée de glissement avec la nouvelle source.

Drag.supportedActions : flags

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

La modification des actions prises en charge 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.target : Object

Lorsqu'un glissement est actif, cette propriété contient le dernier objet à avoir accepté un événement d'entrée de l'élément glissé, si la position actuelle du glissement ne croise aucune cible acceptante, elle 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 sur les signaux attachés

dragFinished(DropAction dropAction)

Ce signal est émis lorsqu'un drag se termine et que le drag 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.

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.

Documentation de la méthode attachée

void cancel()

Termine une séquence de déplacement.

enumeration drop()

Termine 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

void start(flags supportedActions)

Commence à envoyer des événements de drague. Utilisé pour démarrer les drags 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 glissement.

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