QDrag

La classe QDrag fournit la prise en charge des transferts de données par glisser-déposer basés sur les types MIME. Plus d'informations...

#include <QDrag>

Voir la position dans l'arbre des classes.

Héritage

Hérite de QObject.

Description détaillée

La classe QDrag fournit la prise en charge des transferts de données par glisser-déposer basés sur les types MIME.

Le glisser-déposer est une façon intuitive pour l?utilisateur de copier ou de déplacer des données dans une application et est utilisé dans beaucoup d?environnements bureautiques comme mécanisme de copie de données entre les applications. La prise en charge du glisser-déposer dans Qt est centrée autour de la classe QDrag qui gère la plupart des détails des opérations de glisser-déposer.

Les données à transférer par l?opération de glisser-déposer sont contenues dans un objet QMimeData. Elles sont spécifiées avec la fonction setMimeData() de la façon suivante :

         QDrag *drag = new QDrag(this);
         QMimeData *mimeData = new QMimeData;
 
         mimeData->setText(commentEdit->toPlainText());
         drag->setMimeData(mimeData);

À noter que setMimeData() rend l'objet QDrag propriétaire de l?objet QMimeData. L?objet QDrag doit être construit sur le tas (heap) avec un parent QWidget pour s?assurer que Qt peut libérer les ressources une fois que l?opération de glisser-déposer est terminée.

Une pixmap peut être utilisée pour représenter la donnée au cours du glisser-déposer et elle va se déplacer avec le pointeur jusqu?à la cible de dépôt. Typiquement, cette pixmap montre une icône qui représente le type MIME de la donnée en cours de transfert, mais n?importe quelle pixmap peut être affectée avec la fonction setPixmap(). Le hotspot du pointeur peut être donné en tant que position relative au coin supérieur gauche de la pixmap avec la fonction setHotSpot(). Le code suivant positionne le pixmap de sorte que le hotspot du pointeur soit au centre de son bord inférieur :

     drag->setHotSpot(QPoint(drag->pixmap().width()/2,
                             drag->pixmap().height()));

À noter : sous X11, la pixmap peut ne pas être capable de suivre les mouvements de la souris si le hotspot est configuré de manière à ce que la pixmap doive être affichée directement sous le pointeur.

Les widgets source et cible peuvent être retrouvés avec les fonctions source() et target(). Ces fonctions sont souvent utilisées pour déterminer si l?opération de glisser-déposer démarre et se termine sur le même widget, pour permettre l?implémentation d?un comportement particulier.

QDrag ne traite que l?opération de glisser-déposer elle-même. La décision du moment où une opération de glisser démarre et de la façon dont un objet QDrag doit être construit et utilisé reste à la charge du développeur. Pour un widget donné, il est souvent nécessaire de réimplémenter la fonction mousePressEvent() pour déterminer si l?utilisateur a pressé un bouton de souris, et la fonction mouseMoveEvent() pour vérifier si un objet QDrag est requis.

Voir aussi le glisser-déposer, QClipboard, QMimeData, QWindowsMime, QMacPasteboardMime, exemple d?icône glissable, exemple de texte glissable, exemple d?emplacement de pose et exemple d?aimants.

Fonctions membres

QDrag::QDrag ( QWidget * dragSource )

Construit un nouvel objet de glissement pour le widget spécifié par dragSource.

QDrag::~QDrag ()

Détruit l?objet de glissement.

void QDrag::actionChanged ( Qt::DropAction action ) [signal]

Ce signal est émis lorsque l?action associée au glissement est modifiée.

Voir aussi targetChanged().

Qt::DropAction QDrag::exec ( Qt::DropActions supportedActions = Qt::MoveAction )

Démarre l?opération de glisser-déposer et retourne une valeur indiquant l?action de dépôt demandée quand elle est terminée. Les actions de dépôt que l?utilisateur peut choisir sont spécifiées dans supportedActions. L?action proposée par défaut sera choisie parmi les actions autorisées dans l?ordre suivant : déplacement (Move), copie (Copy) ou lien (Link).

À noter : sous Linux et Mac OS X, l?opération de glisser-déposer peut prendre un certain temps, mais cette fonction ne bloque pas la boucle d?événements. Les autres événements sont toujours transmis à l?application lorsque cette opération est en cours de réalisation. Sous Windows, la boucle d?événements Qt est bloquée au cours de l?opération. Toutefois, sous Windows, QDrag::exec() provoque l?appel fréquent de processEvents() pour conserver la réactivité de l?IHM. Si une boucle ou une opération est appelée durant une opération de glissement, elle va bloquer l?opération de glissement.

Cette fonction a été introduite dans Qt 4.3.

Qt::DropAction QDrag::exec ( Qt::DropActions supportedActions, Qt::DropAction defaultDropAction )

Démarre l?opération de glisser-déposer et retourne une valeur indiquant l?action de dépôt demandée quand elle est terminée. Les actions de dépôt que l?utilisateur peut choisir sont spécifiées dans supportedActions.

L?action par défaut defaultDropAction détermine quelle action sera proposée lorsque l?utilisateur réalise un glissement sans utiliser de touche de modification.

À noter : sous Linux et Mac OS X, l?opération de glisser-déposer peut prendre un certain temps, mais cette fonction ne bloque pas la boucle d?événements. Les autres événements sont toujours transmis à l?application lorsque cette opération est en cours de réalisation. Sous Windows, la boucle d?événements Qt est bloquée au cours de l?opération. Toutefois, sous Windows, QDrag::exec() provoque l?appel fréquent de processEvents() pour conserver la réactivité de l?IHM. Si une boucle ou une opération est appelée durant une opération de glissement, elle va bloquer l?opération de glissement.

Cette fonction a été introduite dans Qt 4.3.

QPoint QDrag::hotSpot () const

Retourne la position du hotspot par rapport au coin supérieur gauche du pointeur.

Voir aussi setHotSpot().

QMimeData * QDrag::mimeData () const

Retourne la donnée MIME encapsulée dans l?objet de glissement.

Voir aussi setMimeData().

QPixmap QDrag::pixmap () const

Retourne le pixmap utilisé pour représenter la donnée dans une opération de glisser-déposer.

Voir aussi setPixmap().

void QDrag::setDragCursor ( const QPixmap & cursor, Qt::DropAction action )

Définit le pointeur cursor de glissement pour l?action. Ceci permet d?écraser les pointeurs natifs par défaut. Pour revenir au pointeur natif pour l?action, on passe un QPixmap nul en tant que cursor.

L?action peut seulement être une CopyAction, une MoveAction ou une LinkAction. Toutes les autres valeurs de DropAction sont ignorées.

void QDrag::setHotSpot ( const QPoint & hotspot )

Définit la position du hotspot par rapport au coin supérieur gauche du pointeur utilisé au point spécifié par hotspot.

À noter : sous X11, la pixmap peut ne pas être capable de suivre les mouvements de la souris si le hotspot est configuré de manière à ce que la pixmap doive être affichée directement sous le pointeur.

Voir aussi hotSpot().

void QDrag::setMimeData ( QMimeData * data )

Définit la donnée à envoyer à la donnée MIME data. La possession de la donnée est transférée à l?objet QDrag.

Voir aussi mimeData().

void QDrag::setPixmap ( const QPixmap & pixmap )

Définit pixmap comme étant la pixmap utilisée pour représenter la donnée lors d?une opération de glisser-déposer. On peut définir une pixmap seulement avant le début du glissement.

Voir aussi pixmap().

QWidget * QDrag::source () const

Retourne la source de l?objet de glissement. Il s?agit du widget dont l?opération de glisser-déposer est originaire.

QWidget * QDrag::target () const

Retourne la cible de l?objet de glissement. Il s?agit du widget sur lequel l?objet de glissement a été déposé.

void QDrag::targetChanged ( QWidget * newTarget ) [signal]

Ce signal est émis lorsque la cible de l?opération de glisser-déposer est modifiée, newTarget étant la nouvelle cible.

Voir aussi target() et actionChanged().

Remerciements

Merci à Lo?c Leguay pour la traduction, ainsi qu'à Ilya Diallo, David Taralla et Claude Leloup pour la relecture !