NativeDragManager  - AS3

Package	flash.desktop
Classe	public class NativeDragManager
Héritage	NativeDragManager Object

Versions du moteur d’exécution:

AIR 1.0

La classe NativeDragManager coordonne les opérations de glisser-déposer. L’API glisser-déposer native permet à l’utilisateur de faire glisser des données d’une application vers le système d’exploitation natif, d’une application AIR à une autre ou entre des composants d’une même application.

Les types de données suivants peuvent être transférés :

• Images bitmap
• Fichiers
• Texte
• Chaînes URL
• Objets sérialisés
• Références d’objet (valides uniquement dans l’application d’origine)

Remarque : tous les membres NativeDragManager sont statiques. Il n’est pas nécessaire de créer une occurrence de cette classe.

Une opération de glisser-déposer est un geste de l’interface utilisateur qui commence lorsque l’utilisateur clique sur un élément visible et le fait glisser vers un autre emplacement. Pendant l’action de déplacement, les objets interactifs de la liste d’affichage distribuent des événements de déplacement natifs tout au long du déplacement à travers la fenêtre de l’application AIR. Des gestionnaires de ces événements peuvent appeler les méthodes de la classe NativeDragManager pour indiquer si l’élément déplacé peut être déposé sur un objet. En réponse, la classe NativeDragManager change le pointeur de la souris pour prévenir l’utilisateur.

Prise en charge du profil AIR : cette fonctionnalité n’est pas prise en charge sur les périphériques AIR pour TV. En outre, elle n’est pas prise en charge sur tous les périphériques mobiles. Vous pouvez tester la prise en charge lors de l’exécution à l’aide de la propriété NativeDragManager.isSupported. Voir Prise en charge du profil AIR pour plus d’informations sur la prise en charge de l’API dans plusieurs profils.

Actions de déplacement

Les gestes de glisser-déposer sont généralement utilisés pour trois types d’opérations appelées actions. Comme la signification de ces actions dépend du contexte de l’application, le moteur d’exécution n’impose pas un comportement particulier par rapport à ces actions. Toutefois, une implémentation appropriée des actions améliore la convivialité de votre application pour l’utilisateur.

Les actions possibles sont :

• Copie : une copie des données est faite, sans que l’original n’en soit affecté (lors du déplacement d’objets au sein d’une application, faites attention à copier l’objet original lui-même plutôt que sa référence).
• Déplacement : les données sont déplacées du contexte d’origine vers le contexte défini par la cible visée, par exemple lors du déplacement d’un élément d’une liste à une autre.
• Lien : une référence ou un raccourci des données d’origine est créé, l’élément lui-même demeurant dans son contexte original.

Les actions autorisées pour un geste de déplacement peuvent être définies en fournissant un paramètre allowedActions dans l’appel NativeDragManager.doDrag() qui lance l’opération de déplacement. Si aucun paramètre allowedActions n’est fourni, toutes les actions sont autorisées. Les cibles de déplacement potentielles peuvent vérifier les actions autorisées à l’aide de la propriété allowedActions d’un objet NativeDragEvent, et ne doivent pas accepter de dépôt autorisant uniquement des actions incompatibles (cela n’est toutefois pas imposé par le moteur d’exécution).

Si la cible de dépôt n’implémente qu’une seule action, l’objet peut définir la propriété dropAction de NativeDragManager dans les gestionnaires des événements nativeDragEnter et nativeDragOver. La définition de la propriété avant le dépôt permet au gestionnaire de glissement d’actualiser le pointeur de la souris pour indiquer l’action prise en charge et empêcher l’utilisateur de choisir une action incompatible avec les touches de modification. Si l’action spécifiée ne correspond pas à l’une des actions autorisées, le dépôt n’est pas autorisé, même si la cible appelle la méthode acceptDrop().

Lorsqu’un dépôt est accepté, une cible de dépôt potentielle doit spécifier l’action choisie en définissant la propriété NativeDragManager.dropAction en réponse à l’événement nativeDragDrop. Cette action est signalée à l’objet d’affichage d’origine dans l’événement nativeDragComplete. Lorsque aucune action n’est définie par la cible de dépôt, une action par défaut est choisie parmi les actions autorisées dans cet ordre de priorité : copie, déplacement, lien. L’objet d’origine est responsable de la mise à jour de son état interne en réponse à l’action choisie.

Les constantes de chaîne des noms d’action sont définies dans la classe NativeDragActions.

Séquence des événements

Le geste de déplacement commence par un appel à la méthode NativeDragManager.doDrag() à l’intérieur d’un gestionnaire d’événement mouseDown ou mouseMove et suit la séquence d’événements suivante en réponse aux actions de l’utilisateur :

• Evénement nativeDragStart : lorsque la méthode NativeDragManager.doDrag() est appelée, l’objet interactif transmis sous forme de paramètre à la méthode devient l’objet initiateur et distribue un événement nativeDragStart.
• Evénement nativeDragUpdate : pendant que le déplacement se poursuit, l’objet initiateur distribue continuellement des événements nativeDragUpdate.
• Evénements nativeDragEnter, nativeDragOver : lorsqu’un geste de déplacement survole un objet interactif, ce dernier déclenche un événement nativeDragEnter. Tant que le geste de déplacement survole l’objet interactif, celui-ci déclenche continuellement des événements nativeDragOver. En réponse à l’un de ces événements, l’objet qui sert de cible de dépôt potentielle doit vérifier les propriétés de l’objet d’événement pour savoir s’il peut accepter le dépôt. Si le format des données et les actions autorisées sont appropriés, le gestionnaire de ces événements doit appeler la méthode NativeDragManager.acceptDrop(), en transmettant une référence à l’objet d’affichage servant de cible de glissement (généralement l’objet qui a déclenché l’événement nativeDragEnter ou nativeDragOver). L’utilisateur peut alors déposer l’élément déplacé sur sa cible.
• Evénement nativeDragExit : lorsque le geste de déplacement quitte un objet interactif, ce dernier déclenche un événement nativeDragExit. Si l’objet a été désigné comme la cible de dépôt par un appel précédent à la méthode NativeDragManager.acceptDrop(), cet appel n’est plus valide et la méthode acceptDrop() doit être appelée de nouveau si le geste revient survoler l’objet interactif.
• Evénement nativeDragDrop : l’objet d’affichage cible déclenche un événement nativeDragDrop lorsque l’utilisateur relâche le bouton de sa souris sur l’objet. Le gestionnaire de cet événement peut accéder aux données de la propriété transferable de l’objet d’événement et doit définir la propriété NativeDragManager.dropAction pour signaler l’action que doit effectuer l’objet initiateur.
• Evénement nativeDragComplete : lorsque l’utilisateur relâche le bouton de la souris à la fin du déplacement, l’objet initiateur déclenche un événement nativeDragComplete (que le dépôt lui-même ait été consommé ou non). Le gestionnaire de cet événement peut vérifier la propriété dropAction de l’objet d’événement pour savoir quelle modification, le cas échéant, doit être apportée à son état de données interne, telle que la suppression d’un élément sorti d’une liste. Si dropAction est NativeDragActions.NONE, l’élément déplacé n’a pas été déposé sur une cible qualifiée.

Gestes entre applications

Lorsqu’un geste de déplacement entre dans une fenêtre d’application AIR à partir d’une application non AIR, aucun objet initiateur ne déclenche l’événement nativeDragStart ou nativeDragComplete. Autrement, les événements déclenchés au cours du geste suivent le même schéma que dans un geste commençant et se terminant au sein de la même application AIR.

Lorsqu’un geste de déplacement quitte la fenêtre d’une application AIR, aucun objet cible ne déclenche les événements nativeDragEnter, nativeDragOver ou nativeDragDrop. L’objet initiateur déclenche toujours un événement nativeDragComplete, qui signale l’action de déplacement définie par le système d’exploitation natif (ou aucune si le dépôt n’a pas été accepté).

Lorsqu’un geste de déplacement passe d’une application AIR à une autre, les objets d’affichage initiateur et cible déclenchent des événements dans leurs applications respectives, comme d’habitude.

Transfert des informations

Les données transférées au cours d’un geste de glisser-déposer sont renfermées dans un objet Clipboard. Cet objet de données est ajouté à l’opération de déplacement avec la méthode NativeDragManager.doDrag() à l’origine du geste. Les cibles de dépôt potentielles peuvent accéder à l’objet Clipboard par l’intermédiaire de la propriété clipboard de l’objet d’événement de déplacement natif. Après le démarrage d’une opération de déplacement, l’objet Clipboard ne peut plus être accédé que dans le gestionnaire d’un événement NativeDragEvent. Tout autre tentative d’accès à l’objet génère une erreur à l’exécution.

Considérations de sécurité

Les sandbox de sécurité des objets initiateur et cible potentielle déterminent comment accéder aux données déplacées. Si les deux objets se trouvent dans le même sandbox, tout objet NativeDragEvent peut alors accéder aux données. Toutefois, si les objets initiateur et cible potentielle sont dans des sandbox différents, les données ne sont accessibles que dans le sandbox cible à l’intérieur du gestionnaire de l’événement nativeDragDrop. D’autres gestionnaires d’événement de déplacement natifs peuvent toujours accéder à l’objet Clipboard référencé dans la propriété clipboard de l’événement pour identifier les formats de données disponibles, mais un appel à la méthode clipboard.getData() génère une erreur de sécurité.

Plus d’exemples

Eléments de l’API associés

---