Tutoriel XUL:Glisser-Déposer

Un article de MDC.

Cette section indique comment implémenter des objets capables d'être déplacés et lâchés sur d'autres objets.

[modifier] L'interface glisser-déposer

De nombreuses interfaces graphiques permettent de glisser-déposer des objets. Il est par exemple possible de déplacer des fichiers d'un dossier à l'autre, ou de lâcher une icône sur une fenêtre pour ouvrir le document qui lui correspond. Mozilla et XUL fournissent une panoplie d'événements qui se déclenchent lorsque un utilisateur essaie de déplacer un objet.

L'utilisateur commence le glissement en cliquant et en déplaçant la souris sans relâcher le bouton. Le glissement finit quand l'utilisateur relâche le bouton. Des gestionnaires d'événements sont appelés dans ces deux situations, ainsi que lors de certaines étapes intermédiaires.

Mozilla implémente le glisser-déposer à l'aide d'une « session de glisser-déposer ». Quand un utilisateur demande à faire glisser un objet, et que celui-ci est susceptible d'être glissé-déposé, une session est initiée. La session se charge de modifier le curseur de la souris là où l'objet peut être déposé. Si l'objet ne supporte pas le glisser-déposer, la session n'est pas créée. L'utilisateur n'ayant en général qu'une souris, une seule session est active à un instant donné.

La liste qui suit décrit tous les gestionnaires d'événements pouvant être appelés, et que n'importe quel élément peut implémenter. Vous n'avez à définir que les événements qui vous intéressent.

ondraggesture 

Appelé quand l'utilisateur commence à glisser l'élément, ce qui arrive quand l'utilisateur garde le bouton de la souris appuyé et la déplace. Le script qui intercepte cet événement doit mettre en place une session de glisser-déposer.

ondragover 

Appelé pour un élément survolé par le glisser. Si l'objet peut être lâché ici, vous le signalez à la session.

ondragenter 

Appelé quand le glisser entre dans l'« espace aérien » de l'élément. Il permet à l'élément de changer d'apparence pour signifier à l'utilisateur qu'il peut lâcher ici.

ondragexit 

Appelé quand le glisser cesse de survoler l'élément, et également quand le glisser-déposer s'achève. Il permet ainsi de rétablir l'apparence de l'élément ou de faire d'autres choses.

ondragdrop 

Appelé quand le glisser-déposer s'achève sur l'élément. À ce moment-là, l'utilisateur a déjà relâché le bouton de la souris. L'élément peut choisir d'ignorer l'événement, ou réagir en insérant l'objet glissé par exemple.

Il y a deux façons de gérer les événements de glisser-déposer. La première passe par l'emploi direct des interfaces de glisser-déposer XPCOM. La seconde est de passer par un conteneur javascript qui vous décharge d'une partie du travail. Ce conteneur est inclus dans le paquet "toolkit" ou "global" de Mozilla.

[modifier] Le glisser-déposer avec XPCOM

Deux interfaces sont utilisées pour le glisser-déposer. La première est un service de glisser-déposer, nsIDragService, et la seconde est la session, nsIDragSession.

nsIDragService est responsable de la création de session quand le glissement commence, et de sa destruction quand le glissement s'achève. Sa fonction invokeDragSession doit être appelée pour commencer le glisser-déposer, dans le contexte d'un événement ondraggesture. Une fois cette fonction appelée, le glisser-déposer a commencé.

La fonction invokeDragSession prend quatre paramètres, décrits ci-après :

invokeDragSession(element,transferableArray,region,actions);

element 

Une référence à l'élément à glisser-déposer. On l'obtient en accédant à la propriété event.target dans le gestionnaire d'événement.

transferableArray 

Un tableau d'objets nsITransferable, un par élément glissé-déposé. On utilise un tableau pour pouvoir déplacer plusieurs éléments d'un coup, un ensemble de fichiers par exemple.

region 

Une région utilisée pour donner un retour à l'utilisateur. Mettre à 'null' dans la majorité des cas.

actions 

Les actions utilisées par le glisser-déposer. Elles peuvent prendre l'une des valeurs de constantes suivantes, ou une combinaison de ces valeurs. L'action peut être changée pendant le glisser-déposer selon l'élément qui est survolé :

• nsIDragSession.DRAGDROP_ACTION_NONE

  Indique qu'aucune action de glisser-déposer n'est valide.

  nsIDragSession.DRAGDROP_ACTION_COPY 

  L'élément glissé-déposé peut être copié lors du lâcher.

  nsIDragSession.DRAGDROP_ACTION_MOVE 

  L'élément peut être déplacé lors du lâcher.

  nsIDragSession.DRAGDROP_ACTION_LINK 

  Un lien (raccourci ou alias) peut être créé là où a lieu le lâcher.

L'interface nsIDragService fournit également la fonction getCurrentSession qui peut être appelée dans le contexte d'un des événements de glisser-déposer pour accéder à, et modifier, l'état du glisser-déposer. Cette fonction renvoie un objet implémentant nsIDragSession.

L'interface nsIDragSession sert à modifier les propriétés du glisser-déposer en cours. Elle exploite les propriétés et méthodes suivantes :

canDrop 

Affectez 'true' à cette propriété si l'élément en dessous du curseur pourrait accepter que l'élément glissé soit déposé, et 'false' si ce n'est pas envisageable. Modifiez cette valeur dans le contexte d'événements ondragover et ondragenter.

dragAction 

Détermine l'action à entreprendre au lâcher, sous forme d'une combinaison des constantes décrites plus haut. Permet de fournir un meilleur retour à l'utilisateur.

numDropItems 

Le nombre d'objets déplacés. Par exemple, si l'on déplace cinq marque-pages, ce sera '5'.

getData (transfer,index) 

Obtenir des objets déplacés. Le premier argument est un objet nsITransferable qui recevra la réponse, le second est l'indice de l'élément à retourner.

sourceDocument 

Le document où le glisser-déposer a commencé.

sourceNode 

Le nœud DOM où le glisser-déposer a commencé.

isDataFlavorSupported(flavour) 

Renvoie 'true' si la donnée déplacée contient un exemplaire dans le type (flavour) indiqué.

Dans la prochaine section, nous verrons comment utiliser le conteneur Javascript pour le glisser-déposer.