| 包 | flash.events |
| 接口 | public interface IEventDispatcher |
| 实现器 | AbstractService, EventDispatcher, OLAPCube |
| 语言版本: | ActionScript 3.0 |
| 运行时版本: | AIR 1.0 Flash Player 9 |
事件目标是 Flash ® Player 和 Adobe AIR 事件模型的重要组成部分。事件目标是事件如何通过显示列表层次结构这一问题的焦点。当发生鼠标单击或按键等事件时，会将事件对象调度到从显示列表根开始的事件流中。事件对象进行到事件目标的往返行程，在概念上，此往返行程被划分为三个阶段：捕获阶段包括从根到事件目标节点之前的最后一个节点的行程，目标阶段仅包括事件目标节点，冒泡阶段包括到显示列表的根的回程上遇到的任何后续节点。
通常，使用户定义的类能够调度事件的最简单方法是扩展 EventDispatcher。如果无法扩展（即，如果该类已经扩展了另一个类），则可以实现 IEventDispatcher 接口，创建 EventDispatcher 成员，并编写一些简单的挂钩，将调用连接到聚合的 EventDispatcher 中。
| 方法 | 定义方 | ||
|---|---|---|---|
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。 | IEventDispatcher | ||
将事件调度到事件流中。 | IEventDispatcher | ||
检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。 | IEventDispatcher | ||
从 EventDispatcher 对象中删除侦听器。 | IEventDispatcher | ||
检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。 | IEventDispatcher | ||
| addEventListener | () | 方法 |
public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void| 语言版本: | ActionScript 3.0 |
| 运行时版本: | AIR 1.0 Flash Player 9 |
使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。可以为特定类型的事件、阶段和优先级在显示列表的所有节点上注册事件侦听器。
成功注册一个事件侦听器后，无法通过额外调用 addEventListener() 来更改其优先级。若要更改侦听器的优先级，必须先调用 removeEventListener()。然后，可以使用新的优先级再次注册该侦听器。
注册该侦听器后，如果继续调用具有不同 type 或 useCapture 值的 addEventListener()，则会创建单独的侦听器注册。例如，如果首先注册 useCapture 设置为 true 的侦听器，则该侦听器只在捕获阶段进行侦听。如果您使用同一个侦听器对象再次调用 addEventListener()，但 useCapture 设置为 false，则您将有两个单独的侦听器：一个在捕获阶段侦听，另一个在目标阶段和冒泡阶段侦听。
不能只为目标阶段或冒泡阶段注册事件侦听器。这些阶段在注册期间是成对出现的，因为冒泡阶段只适用于目标节点的始祖。
如果不再需要某个事件侦听器，可调用 EventDispatcher.removeEventListener() 删除它；否则会产生内存问题。由于垃圾回收器不会删除仍包含引用的对象，因此不会从内存中自动删除使用已注册事件侦听器的对象。
复制 EventDispatcher 实例时并不复制其中附加的事件侦听器。（如果新近创建的节点需要一个事件侦听器，必须在创建该节点后附加该侦听器。） 但是，如果移动 EventDispatcher 实例，则其中附加的事件侦听器也会随之移动。
如果在正在处理事件的节点上注册事件侦听器，则不会在当前阶段触发事件侦听器，但会在事件流的稍后阶段触发，如冒泡阶段。
如果从正在处理事件的节点中删除事件侦听器，则该事件侦听器仍由当前操作触发。删除事件侦听器后，决不会再次调用该事件侦听器（除非再次注册以备将来处理）。
参数
type:String — 事件的类型。 | |
listener:Function —
处理事件的侦听器函数。此函数必须接受事件对象作为其唯一的参数，并且不能返回任何结果，如下面的示例所示：
| |
useCapture:Boolean (default = false)useCapture 设置为 true，则侦听器只在捕获阶段处理事件，而不在目标或冒泡阶段处理事件。如果 useCapture 为 false，则侦听器只在目标或冒泡阶段处理事件。若要在所有三个阶段都侦听事件，请调用两次 addEventListener()，一次将 useCapture 设置为 true，第二次再将 useCapture 设置为 false。
| |
priority:int (default = 0) | |
useWeakReference:Boolean (default = false)
类级别成员函数不属于垃圾回收的对象，因此可以对类级别成员函数将 |
| dispatchEvent | () | 方法 |
public function dispatchEvent(event:Event):Boolean| 语言版本: | ActionScript 3.0 |
| 运行时版本: | AIR 1.0 Flash Player 9 |
将事件调度到事件流中。事件目标是对其调用 dispatchEvent() 的 EventDispatcher 对象。
参数
event:Event — 调度到事件流中的事件对象。 |
Boolean —
除非对事件调用 preventDefault()（在这种情况下，它返回 false），否则值为 true。
|
| hasEventListener | () | 方法 |
public function hasEventListener(type:String):Boolean| 语言版本: | ActionScript 3.0 |
| 运行时版本: | AIR 1.0 Flash Player 9 |
检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。这样，您就可以确定 EventDispatcher 对象在事件流层次结构中的哪个位置改变了对事件类型的处理。若要确定特定事件类型是否确实会触发事件侦听器，请使用 IEventDispatcher.willTrigger()。
hasEventListener() 与 willTrigger() 的区别是：hasEventListener() 只检查它所属的对象，而 willTrigger() 检查整个事件流以查找由 type 参数指定的事件。
参数
type:String — 事件的类型。 |
Boolean —
如果指定类型的侦听器已注册，则值为 true；否则，值为 false。
|
另请参见
| removeEventListener | () | 方法 |
public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void| 语言版本: | ActionScript 3.0 |
| 运行时版本: | AIR 1.0 Flash Player 9 |
从 EventDispatcher 对象中删除侦听器。如果没有向 EventDispatcher 对象注册任何匹配的侦听器，则对此方法的调用没有任何效果。
参数
type:String — 事件的类型。 | |
listener:Function — 要删除的侦听器对象。 | |
useCapture:Boolean (default = false)removeEventListener() 进行两次调用才能将这两个侦听器删除：一次调用将 useCapture 设置为 true，另一次调用将 useCapture 设置为 false。
|
| willTrigger | () | 方法 |
public function willTrigger(type:String):Boolean| 语言版本: | ActionScript 3.0 |
| 运行时版本: | AIR 1.0 Flash Player 9 |
检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。将指定类型的事件调度给此 EventDispatcher 对象或其任一后代时，如果在事件流的任何阶段触发了事件侦听器，则此方法返回 true。
hasEventListener() 与 willTrigger() 的区别是：hasEventListener() 只检查它所属的对象，而 willTrigger() 检查整个事件流以查找由 type 参数指定的事件。
参数
type:String — 事件的类型。 |
Boolean —
如果将会触发指定类型的侦听器，则值为 true；否则，值为 false。
|
decorDispatcher），并使用 decorDispatcher 变量和自定义事件 doSomething 来调用 addEventListener()，然后由 didSomething() 进行处理，它可以使用 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);
}
}