Objets événement

Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures

Les objets événements jouent deux rôles essentiels dans le nouveau système de gestion des événements. Tout d’abord, ces objets représentent de véritables événements, puisqu’ils stockent dans un ensemble de propriétés des informations relatives à des événements précis. Ils contiennent en outre un jeu de méthodes qui vous permet de manipuler les objets événement et d’agir sur le comportement du système de gestion des événements.

Pour faciliter l’accès à ces propriétés et ces méthodes, l’API Flash Player définit une classe Event qui constitue la classe de base de tous les objets événements. La classe Event définit un jeu fondamental de propriétés et de méthodes commun à tous les objets événement.

Cette section commence par étudier les propriétés de la classe Event avant de décrire les méthodes de cette même classe, puis explique l’existence de sous-classes dans la classe Event.

Présentation des propriétés de la classe Event

La classe Event définit plusieurs propriétés et constantes en lecture seule qui fournissent des informations essentielles sur l’objet événement. Les points suivants revêtent une importance particulière :

  • Les types d’objet événement sont représentés par des constantes et stockés dans la propriété Event.type.

  • La possibilité d’éviter le comportement par défaut d’un événement est représentée par une valeur booléenne, stockée dans la propriété Event.cancelable.

  • Les informations relatives au flux d’événements se trouvent dans les propriétés restantes.

Types d’objets événement

Chaque objet événement est associé à un type d’événement. Les types d’événements sont stockés dans la propriété Event.type sous forme de chaîne. Il est utile de connaître le type d’un objet événement car votre code peut alors distinguer les objets de types différents. Par exemple, le code suivant spécifie que la fonction clickHandler() doit répondre à tous les objets événements clic de souris transmis à myDisplayObject :

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

La classe Event est elle-même associée à deux douzaines de types d’événement, représentés par des constantes de la classe Event. Dans cet extrait de la définition de la classe Event, certaines de ces constantes sont illustrées :

package flash.events 
{ 
    public class Event 
    { 
        // class constants 
        public static const ACTIVATE:String = "activate"; 
        public static const ADDED:String= "added"; 
        // remaining constants omitted for brevity 
    } 
}

Ces constantes permettent de faire facilement référence à des types d’événement précis. Vous devez utiliser ces constantes au lieu des chaînes qu’elles représentent. Si vous orthographiez de manière incorrecte un nom de constante dans votre code, le compilateur peut détecter l’erreur. Si vous utilisez les chaînes qu’elles représentent, une erreur de frappe ne sera pas forcément détectée lors de la compilation et pourrait provoquer un comportement inattendu, difficile à déboguer. Par exemple, utilisez le code suivant pour ajouter un écouteur d’événement :

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

plutôt que :

myDisplayObject.addEventListener("click", clickHandler);

Informations relatives aux comportements par défaut

Le code que vous écrivez est en mesure de vérifier si le comportement par défaut d’un objet événement donné peut être évité. Pour ce faire, il doit accéder à la propriété cancelable. La propriété cancelable contient une valeur booléenne qui indique si le comportement par défaut peut être évité ou non. Vous pouvez éviter, ou annuler, le comportement par défaut de quelques événements à l’aide de la méthode preventDefault(). Pour plus d’informations, voir Annulation d’un comportement associé par défaut à un événement sous Présentation des méthodes de la classe Event.

Informations de flux d’événements

Les propriétés restantes de la classe Event contiennent des informations importantes sur l’objet événement et ses relations au flux d’événements, comme l’explique la liste suivante :

  • La propriété bubbles contient des informations sur les parties du flux d’événements auquel participe l’objet événement.

  • La propriété eventPhase indique la phase actuelle du flux d’événements.

  • La propriété target stocke une référence à la cible d’événement.

  • La propriété currentTarget stocke une référence de l’objet de liste d’affichage qui traite actuellement l’objet événement.

La propriété bubbles

On dit d’un événement qu’il se propage lorsqu’il participe à la phase de propagation du flux d’événements, c’est-à-dire quand l’objet événement est transmis du nœud cible via ses ascendants jusqu’à la Scène. La propriété Event.bubbles stocke une valeur booléenne qui indique si l’objet événement participe à la phase de propagation. Tous les événements qui se propagent vers le haut participent également aux phases de capture et cible ; de tels événements participent donc aux trois phases du flux d’événements. Si la valeur est true, l’objet événement participe aux trois phrases. Si la valeur est false, l’objet événement ne participe pas à la phase de propagation.

La propriété eventPhase

Vous pouvez déterminer la phase d’événement de tout objet événement grâce à sa propriété eventPhase. La propriété eventPhase a pour valeur un entier non signé qui représente l’une des trois phases du flux d’événements. L’API de Flash Player définit une classe EventPhase distincte qui contient trois constantes correspondant aux trois valeurs entières non signées, comme illustré par l’extrait de code suivant :

package flash.events 
{ 
    public final class EventPhase 
    { 
        public static const CAPTURING_PHASE:uint = 1; 
        public static const AT_TARGET:uint = 2; 
        public static const BUBBLING_PHASE:uint= 3; 
    } 
}

Ces constantes correspondent aux trois valeurs valables pour la propriété eventPhase. Vous pouvez utiliser ces constantes pour améliorer la lisibilité de votre code. Supposons par exemple que vous souhaitiez être sûr qu’une fonction appelée myFunc() soit uniquement appelée lorsque la cible d’événement se trouve dans la scène cible. Le code suivant vous permet de tester cette condition :

if (event.eventPhase == EventPhase.AT_TARGET) 
{ 
    myFunc(); 
}

La propriété target

La propriété target contient une référence à l’objet cible de l’événement. Dans certains cas, ce système est simple, par exemple, lorsqu’un micro devient actif, la cible de l’objet événement est l’objet Microphone. Toutefois, si la cible se trouve sur la liste d’affichage, il faut tenir compte de la hiérarchie de cette dernière. Par exemple, si un utilisateur clique avec la souris sur un point correspondant à plusieurs objets de la liste d’affichage qui se chevauchent, Flash Player et AIR choisissent toujours comme cible d’événement l’objet qui se trouve le plus loin de la Scène.

Dans des fichiers SWF complexes, et particulièrement ceux dont les boutons sont régulièrement ornés d’objets enfant plus petits, la propriété target ne doit pas être utilisée fréquemment car elle pointera souvent vers l’objet enfant du bouton plutôt que vers le bouton lui-même. Dans de telles situations, il est courant d’ajouter des écouteurs d’événement au bouton et d’utiliser la propriété currentTarget. En effet, cette dernière pointe vers le bouton alors que la propriété target peut pointer vers l’un des enfants du bouton.

La propriété currentTarget

La propriété currentTarget contient une référence de l’objet de liste d’affichage qui traite actuellement l’objet événement. Même s’il peut paraître étrange de ne pas savoir quel nœud traite actuellement l’objet événement que vous étudiez, gardez à l’esprit que vous pouvez ajouter une fonction écouteur à n’importe quel objet d’affichage du flux d’événements de l’objet événement en question. En outre, cette fonction écouteur peut être placée à tout endroit. Par ailleurs, la même fonction écouteur peut être ajoutée à différents objets d’affichage. L’utilité de la propriété currentTarget augmente donc avec la taille et la complexité du projet.

Présentation des méthodes de la classe Event

La classe Event contient trois catégories de méthodes :

  • Les méthodes d’utilitaire, qui peuvent créer des copies d’un objet événement ou le convertir en chaîne

  • Les méthodes de flux d’événements, qui suppriment les objets événements du flux d’événements

  • Les méthodes de comportement par défaut, qui annulent le comportement par défaut ou vérifient s’il a été annulé

Méthodes d’utilitaire de la classe Event

La classe Event compte deux méthodes d’utilitaire. La méthode clone() permet de créer des copies d’un objet événement. La méthode toString() permet de représenter sous forme de chaînes les propriétés d’un objet événement ainsi que leurs valeurs. Bien qu’utilisées en interne par le modèle d’événements, ces deux méthodes sont mises à la disposition des développeurs pour un usage générique.

Pour les développeurs expérimentés qui souhaitent créer des sous-classes de la classe Event, il est nécessaire de redéfinir et d’implémenter des versions de ces deux méthodes d’utilitaires afin de garantir le bon fonctionnement de la sous-classe d’événement.

Arrêt du flux d’événements

La méthode Event.stopPropagation() ou Event.stopImmediatePropagation() vous permet d’arrêter le cheminement d’un objet événement dans le flux d’événements. Quasi identiques, ces deux méthodes diffèrent uniquement en ce que les autres écouteurs d’événement du nœud actuel sont autorisés ou non à s’exécuter :

  • La méthode Event.stopPropagation() empêche l’objet événement de passer au nœud suivant mais seulement après que tous les autres écouteurs du nœud actuel ont été autorisés à s’exécuter.

  • La méthode Event.stopImmediatePropagation() empêche l’objet événement de passer au nœud suivant sans autoriser les autres écouteurs du nœud actuel à s’exécuter.

Quelle que soit la méthode appelée, elle n’a aucun effet sur la réalisation du comportement par défaut de l’événement. Utilisez les méthodes de comportement par défaut de la classe Event pour éviter le comportement par défaut.

Annulation d’un comportement associé par défaut à un événement

Deux méthodes sont associées à l’annulation du comportement par défaut : preventDefault() et isDefaultPrevented(). Appelez la méthode preventDefault() pour annuler le comportement associé par défaut à un événement. Pour vérifier si preventDefault() a déjà été appelée sur un objet événement, appelez la méthode isDefaultPrevented(), qui renvoie la valeur true si la méthode a déjà été appelée, false dans le cas contraire.

La méthode preventDefault() fonctionne uniquement s’il est possible d’annuler le comportement par défaut de l’événement. Pour vérifier que c’est le cas, reportez-vous à la documentation de l’API de ce type d’événement ou examinez la propriété cancelable de l’objet événement à l’aide du code ActionScript.

L’annulation du comportement par défaut n’a aucun effet sur la progression d’un objet événement dans le flux d’événements. Utilisez les méthodes de flux d’événements de la classe Event pour supprimer un objet événement du flux d’événements.

Sous-classes de la classe Event

Pour de nombreux événements, le jeu de propriétés commun, défini dans la classe Event est suffisant. Néanmoins, d’autres événements présentent des caractéristiques exclusives qui ne peuvent être capturées par les propriétés disponibles dans la classe Event. Pour ces événements, ActionScript 3.0 définit plusieurs sous-classes de la classe Evénement.

Chaque sous-classe fournit d’autres propriétés et types d’événements propres à la catégorie d’événement considérée. Par exemple, les événements liés aux actions de la souris présentent plusieurs caractéristiques uniques, que les propriétés définies dans la classe Event ne peuvent capturer. La classe MouseEvent constitue une extension de la classe Event puisqu’elle ajoute dix propriétés contenant des informations telles que l’emplacement de l’événement de souris et les éventuelles touches actionnées en même temps.

Une sous-classe d’Event contient également des constantes qui représentent de types d’événement associés à la sous-classe. Par exemple, la classe MouseEvent définit des constantes pour plusieurs types d’événement de souris, notamment click, doubleClick, mouseDown et mouseUp.

Comme le décrit la section consacrée aux méthodes d’utilitaire de la classe Event dans Objets événement, lors de la création d’une sous-classe d’Event, vous devez bloquer les méthodes clone() et toString() pour fournir la fonctionnalité propre à la sous-classe.