| Package | flash.events |
| Interface | public interface IEventDispatcher |
| Implémenteurs | EventDispatcher |
| Version du langage: | ActionScript 3.0 |
| Versions du moteur d'exécution: | AIR 1.0 Flash Player 9 |
Les cibles d’événement constituent une part importante du modèle d’événement de Flash® Player et d'Adobe AIR. La cible de l’événement détermine le flux d’événements dans la hiérarchie de la liste d’affichage. Lorsqu’un événement, tel qu'un clic de souris ou une pression sur une touche, se produit, un objet événement est distribué dans le flux d’événements, à partir de la racine de la liste d’affichage. L’objet événement effectue un aller-retour jusqu'à la cible de l’événement, divisé de manière conceptuelle en trois phases : La phase de capture correspond au trajet de la racine jusqu'au dernier nœud précédant le nœud de la cible de l’événement, la phase cible concerne uniquement le nœud de la cible de l’événement, tandis que la phase de propagation vers le haut (bubbling) comprend tous les nœuds rencontrés sur le trajet de retour à la racine de la liste d’affichage.
En règle générale, pour qu’une classe définie par l'utilisateur acquière des fonctions de distribution, le plus simple consiste à étendre EventDispatcher. Si cela est impossible (autrement dit, si cette classe étend déjà une autre classe), vous pouvez implémenter l'interface IEventDispatcher, créer un membre EventDispatcher et écrire des raccrochements simples pour acheminer les appels vers la classe EventDispatcher regroupée.
| Méthode | Défini par | ||
|---|---|---|---|
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Enregistre un objet écouteur d'événement auprès d'un objet EventDispatcher afin que l'écouteur soit averti d'un événement. | IEventDispatcher | ||
Distribue un événement dans le flux d'événements. | IEventDispatcher | ||
Vérifie si des écouteurs sont enregistrés auprès de l'objet EventDispatcher pour un type spécifique d'événement. | IEventDispatcher | ||
Supprime un écouteur de l'objet EventDispatcher. | IEventDispatcher | ||
Vérifie si un écouteur d'événement est enregistré auprès de cet objet EventDispatcher ou de ses ancêtres pour le type d'événement spécifié. | IEventDispatcher | ||
| addEventListener | () | méthode |
public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void| Version du langage: | ActionScript 3.0 |
| Versions du moteur d'exécution: | AIR 1.0 Flash Player 9 |
Enregistre un objet écouteur d'événement auprès d'un objet EventDispatcher afin que l'écouteur soit averti d'un événement. Vous pouvez enregistrer les écouteurs d'événement dans tous les nœuds de la liste d'affichage pour un type spécifique d'événement, de phase et de priorité.
Après l'enregistrement d'un écouteur d'événements, vous ne pouvez plus modifier sa priorité par d'autres appels de addEventListener(). Pour modifier la priorité d'un écouteur, vous devez d'abord appeler removeEventListener(). Vous pouvez ensuite réenregistrer l'écouteur avec le nouveau niveau de priorité.
Après l'enregistrement de l'écouteur, tous les futurs appels de addEventListener() avec une valeur type ou useCapture différente entraîneront la création d'un autre enregistrement d'écouteur. Si, par exemple, vous enregistrez un écouteur dans lequel la propriété useCapture est définie sur true, il écoute uniquement pendant la phase de capture. Si vous appelez addEventListener() à l'aide du même objet écouteur, mais en définissant useCapture sur false, vous obtenez deux écouteurs distincts : l'un qui écoute pendant la phase de capture et l'autre qui écoute pendant les phases cible et de propagation vers le haut (bubbling).
Il est impossible d'enregistrer un écouteur d'événement pour la phase cible ou la phase de propagation vers le haut (bubbling) uniquement. Ces deux phases sont associées pendant l'enregistrement car la propagation vers le haut (bubbling) s'applique uniquement aux ancêtres du nœud cible.
Si vous n'avez plus besoin d'un écouteur d'événements, supprimez-le en appelant EventDispatcher.removeEventListener(), pour éviter tout problème de mémoire. Les objets associés à des écouteurs d'événement enregistrés ne sont pas automatiquement supprimés de la mémoire, car le nettoyeur de mémoire n'efface pas les objets auxquels il est toujours fait référence.
Lors de la copie d'une occurrence d'EventDispatcher, les écouteurs d'événement qui lui sont associés ne sont pas pris en compte. (Si votre nouveau nœud nécessite un écouteur d'événements, vous devez associer celui-ci après la création du nœud.) Toutefois, si vous déplacez une occurrence d'EventDispatcher, les écouteurs d'événement qui lui sont associés la suivent.
Si un écouteur d'événement est enregistré sur un nœud alors qu'un événement est en cours de traitement sur ce nœud, l'écouteur n'est pas déclenché pendant la phase actuelle, mais il peut l'être pendant une phase ultérieure du flux d'événements, telle que la phase de propagation vers le haut (bubbling).
Si un écouteur d'événement est supprimé d'un nœud sur lequel un événement est en cours de traitement, il est cependant déclenché par les actions en cours. Une fois supprimé, l'écouteur d'événement n'est plus jamais appelé (à moins d'être réenregistré à des fins de traitement ultérieur).
Paramètres
type:String — Type d'événement. | |
listener:Function —
Fonction d'écouteur qui traite l’événement. Cette fonction doit accepter un objet Event comme paramètre unique et ne rien renvoyer, comme illustré ci-dessous :
| |
useCapture:Boolean (default = false)useCapture est défini sur true, l'écouteur traite l'événement pendant la phase de capture uniquement et non pendant les phases cible et de propagation vers le haut (bubbling). Si useCapture et défini sur false, l'écouteur traite l'événement pendant les phases cible et de propagation vers le haut (bubbling) seulement. Pour écouter l'événement dans les trois phases, appelez addEventListener() à deux reprises, une première fois avec useCapture défini sur true, puis une nouvelle fois avec useCapture défini sur false.
| |
priority:int (default = 0) | |
useWeakReference:Boolean (default = false)
Les fonctions de membres de niveau classe n'étant pas soumises au nettoyage, vous pouvez définir |
| dispatchEvent | () | méthode |
public function dispatchEvent(event:Event):Boolean| Version du langage: | ActionScript 3.0 |
| Versions du moteur d'exécution: | AIR 1.0 Flash Player 9 |
Distribue un événement dans le flux d’événements. La cible de l'événement est l'objet EventDispatcher sur lequel la méthode dispatchEvent() est appelée.
Paramètres
event:Event — Objet Event qui est distribué dans le flux d’événements. |
Boolean —
La valeur true sauf si preventDefault() est appelé sur l'événement, auquel cas il renvoie false.
|
| hasEventListener | () | méthode |
public function hasEventListener(type:String):Boolean| Version du langage: | ActionScript 3.0 |
| Versions du moteur d'exécution: | AIR 1.0 Flash Player 9 |
Vérifie si des écouteurs sont enregistrés auprès de l'objet EventDispatcher pour un type spécifique d'événement. Vous pouvez ainsi déterminer l'emplacement auquel un objet EventDispatcher a modifié la gestion d'un type d'événement dans la hiérarchie du flux d'événements. Pour savoir si un type d'événement spécifique déclenche réellement un écouteur d'événements, utilisez IEventDispatcher.willTrigger().
La différence entre les méthodes hasEventListener() et willTrigger() est la suivante : hasEventListener() examine uniquement l'objet auquel elle appartient, tandis que willTrigger() recherche dans la totalité du flux d'événements l'événement spécifié par le paramètre type.
Paramètres
type:String — Type d'événement. |
Boolean —
La valeur true est renvoyée si un écouteur du type spécifié est enregistré. La valeur false est renvoyée dans tous les autres cas.
|
Voir aussi
| removeEventListener | () | méthode |
public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void| Version du langage: | ActionScript 3.0 |
| Versions du moteur d'exécution: | AIR 1.0 Flash Player 9 |
Supprime un écouteur de l'objet EventDispatcher. Si aucun écouteur correspondant n'est enregistré auprès de l'objet EventDispatcher, appeler cette méthode n'a aucun effet.
Paramètres
type:String — Type d'événement. | |
listener:Function — Objet écouteur à supprimer. | |
useCapture:Boolean (default = false)removeEventListener() à deux reprises pour le supprimer : une première fois en définissant useCapture sur true, puis une seconde fois avecuseCapture défini sur false.
|
| willTrigger | () | méthode |
public function willTrigger(type:String):Boolean| Version du langage: | ActionScript 3.0 |
| Versions du moteur d'exécution: | AIR 1.0 Flash Player 9 |
Vérifie si un écouteur d'événement est enregistré auprès de cet objet EventDispatcher ou de ses ancêtres pour le type d'événement spécifié. Cette méthode renvoie true si un écouteur d'événement est déclenché pendant toute phase du flux d'événements lorsqu'un événement du type spécifié est distribué à cet objet EventDispatcher ou à l'un de ses descendants.
La différence entre les méthodes hasEventListener() et willTrigger() est la suivante : hasEventListener() examine uniquement l'objet auquel elle appartient, tandis que willTrigger() recherche dans la totalité du flux d'événements l'événement spécifié par le paramètre type.
Paramètres
type:String — Type d'événement. |
Boolean —
Renvoie true si un écouteur du type spécifié est enregistré, false dans tous les autres cas.
|
decorDispatcher) de la classe DecoratedDispatcher est construite et la variable decorDispatcher est utilisée pour appeler addEventListener() avec l'événement personnalisé doSomething, traité alors par didSomething(), qui imprime une ligne de texte à l'aide de trace().
package {
import flash.events.Event;
import flash.display.Sprite;
public class IEventDispatcherExample extends Sprite {
public function IEventDispatcherExample() {
var decorDispatcher:DecoratedDispatcher = new DecoratedDispatcher();
decorDispatcher.addEventListener("doSomething", didSomething);
decorDispatcher.dispatchEvent(new Event("doSomething"));
}
public function didSomething(evt:Event):void {
trace(">> didSomething");
}
}
}
import flash.events.IEventDispatcher;
import flash.events.EventDispatcher;
import flash.events.Event;
class DecoratedDispatcher implements IEventDispatcher {
private var dispatcher:EventDispatcher;
public function DecoratedDispatcher() {
dispatcher = new EventDispatcher(this);
}
public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void{
dispatcher.addEventListener(type, listener, useCapture, priority);
}
public function dispatchEvent(evt:Event):Boolean{
return dispatcher.dispatchEvent(evt);
}
public function hasEventListener(type:String):Boolean{
return dispatcher.hasEventListener(type);
}
public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void{
dispatcher.removeEventListener(type, listener, useCapture);
}
public function willTrigger(type:String):Boolean {
return dispatcher.willTrigger(type);
}
}