flash.events
public class EventDispatcher
继承EventDispatcher Inheritance Object
实现 IEventDispatcher
子类 AbstractInvoker, ApplicationUpdater, ApplicationUpdaterUI, AsyncToken, AxisBase, Camera, Channel, ChannelSet, ChartItem, ConstraintColumn, ConstraintRow, CSSStyleDeclaration, DataTransform, DisplayObject, DRMManager, Effect, EffectInstance, EffectManager, FileReference, FileReferenceList, FileStream, FlexClient, FlexNativeMenu, GradientBase, GradientEntry, HierarchicalCollectionView, HierarchicalCollectionViewCursor, HierarchicalData, Icon, IME, LayoutManager, LoaderInfo, LocalConnection, LogLogger, MessageAgent, Microphone, ModuleBase, NativeApplication, NativeMenu, NativeMenuItem, NativeWindow, NetConnection, NetStream, NetStreamPlayOptions, PrintJob, RadioButtonGroup, ResourceManagerImpl, Screen, ServiceMonitor, SetEventHandler, ShaderJob, SharedObject, Socket, SolidColor, Sort, SortField, Sound, SoundChannel, SQLConnection, SQLStatement, State, StreamingConnectionHandler, Stroke, StyleSheet, Timer, ToolTipManager, Tween, UIComponentAutomationImpl, UIMovieClipAutomationImpl, URLLoader, URLStream, Validator, XMLSignatureValidator, XMLSocket

语言版本: ActionScript 3.0
运行时版本: AIR 1.0 Flash Player 9

EventDispatcher 类是可调度事件的所有运行时类的基类。EventDispatcher 类实现 IEventDispatcher 接口,并且是 DisplayObject 类的基类。 EventDispatcher 类允许显示列表上的任何对象都是一个事件目标,同样允许使用 IEventDispatcher 接口的方法。

事件目标是 Flash® Player 和 Adobe® AIR™ 事件模型的重要组成部分。事件目标是事件如何通过显示列表层次结构这一问题的焦点。当发生鼠标单击或按键等事件时,Flash Player 或 AIR 应用程序会将事件对象调度到从显示列表根开始的事件流中。然后该事件对象在显示列表中前进,直到到达事件目标,然后从这一点开始其在显示列表中的回程。在概念上,到事件目标的此往返行程被划分为三个阶段:捕获阶段包括从根到事件目标节点之前的最后一个节点的行程,目标阶段仅包括事件目标节点,冒泡阶段包括回程上遇到的任何后续节点到显示列表的根。

通常,使用户定义的类能够调度事件的最简单方法是扩展 EventDispatcher。如果无法扩展(即,如果该类已经扩展了另一个类),则可以实现 IEventDispatcher 接口,创建 EventDispatcher 成员,并编写一些简单的挂钩,将调用连接到聚合的 EventDispatcher 中。

可以通过调用调度该事件的对象的 addEventListener() 方法来注册函数以处理运行时事件。

查看示例



公共属性
 属性定义方
 Inheritedconstructor : Object
对类对象或给定对象实例的构造函数的引用。
Object
 Inheritedprototype : Object
[静态] 对类或函数对象的原型对象的引用。
Object
公共方法
 方法定义方
  
聚合 EventDispatcher 类的实例。
EventDispatcher
  
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
使用 EventDispatcher 对象注册事件侦听器对象,以使侦听器能够接收事件通知。
EventDispatcher
  
将事件调度到事件流中。
EventDispatcher
  
检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。
EventDispatcher
 Inherited
指示对象是否已经定义了指定的属性。
Object
 Inherited
指示 Object 类的实例是否在指定为参数的对象的原型链中。
Object
 Inherited
指示指定的属性是否存在、是否可枚举。
Object
  
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
从 EventDispatcher 对象中删除侦听器。
EventDispatcher
 Inherited
设置循环操作动态属性的可用性。
Object
 Inherited
返回指定对象的字符串表示形式。
Object
 Inherited
返回指定对象的原始值。
Object
  
检查是否用此 EventDispatcher 对象或其任何始祖为指定事件类型注册了事件侦听器。
EventDispatcher
事件
 事件 摘要 定义方
  [广播事件] Flash Player 或 AIR 应用程序获得操作系统焦点并变为活动状态时将调度此事件。EventDispatcher
  [广播事件] Flash Player 或 AIR 应用程序失去操作系统焦点并变为非活动状态时将调度此事件。EventDispatcher
构造函数详细信息
EventDispatcher()构造函数
public function EventDispatcher(target:IEventDispatcher = null)

语言版本: ActionScript 3.0
运行时版本: AIR 1.0 Flash Player 9

聚合 EventDispatcher 类的实例。

EventDispatcher 类通常在 SWF 内容使用的 ActionScript 3.0 代码中用作基类,这意味着大多数 JavaScript 开发人员都无需使用此构造函数。但是,实现 IEventDispatcher 接口的高级开发人员则需要使用此构造函数。如果您无法扩展 EventDispatcher 类并且必须实现 IEventDispatcher 接口,请使用此构造函数来聚合 EventDispatcher 类的实例。

参数
target:IEventDispatcher (default = null) — 调度到 EventDispatcher 对象的事件的目标对象。当 EventDispatcher 实例由实现 IEventDispatcher 的类聚合时,使用此参数;此参数是必需的,以便包含对象可以是事件的目标。请勿在类扩展了 EventDispatcher 的简单情况下使用此参数。 目标对象仅在 SWF 内容的显示对象中有效,它们使用 ActionScript 3.0 显示列表体系结构。
方法详细信息
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 对象注册事件侦听器对象,以使侦听器能够接收事件通知。可以为特定类型的事件、阶段和优先级在显示列表的所有节点上注册事件侦听器。

AIR 运行时中的 JavaScript 代码使用此方法注册 AIR API 定义的事件的事件侦听器。对于其它 JavaScript 事件(如 DOM body 对象的 onload 事件),您可以像对浏览器中运行的内容一样使用标准事件处理技术。

成功注册一个事件侦听器后,无法通过额外调用 addEventListener() 来更改其优先级。要更改侦听器的优先级,必须首先调用 removeListener()。然后,可以使用新的优先级再次注册该侦听器。

请记住,注册该侦听器后,如果继续调用具有不同 typeuseCapture 值的 addEventListener(),则会创建单独的侦听器注册。例如,如果首先注册 useCapture 设置为 true 的侦听器,则该侦听器只在捕获阶段进行侦听。如果使用同一个侦听器对象再次调用 addEventListener(),并将 useCapture 设置为 false,那么便会拥有两个单独的侦听器:一个在捕获阶段进行侦听,另一个在目标和冒泡阶段进行侦听。

不能只为目标阶段或冒泡阶段注册事件侦听器。这些阶段在注册期间是成对出现的,因为冒泡阶段只适用于目标节点的始祖。

如果不再需要某个事件侦听器,可调用 removeEventListener() 删除它,否则会产生内存问题。由于垃圾回收器不会删除仍包含引用的对象,因此不会从内存中自动删除使用已注册事件侦听器的对象。

复制 EventDispatcher 实例时并不复制其中附加的事件侦听器。(如果新近创建的节点需要一个事件侦听器,必须在创建该节点后附加该侦听器。) 但是,如果移动 EventDispatcher 实例,则其中附加的事件侦听器也会随之移动。

如果在正在处理事件的节点上注册事件侦听器,则不会在当前阶段触发事件侦听器,但会在事件流的稍后阶段触发,如冒泡阶段。

如果从正在处理事件的节点中删除事件侦听器,则该事件侦听器仍由当前操作触发。删除事件侦听器后,决不会再次调用该事件侦听器(除非再次注册以备将来处理)。

参数

type:String — 事件的类型。
 
listener:Function — 处理事件的侦听器函数。此函数必须接受 Event 对象作为其唯一的参数,并且不能返回任何结果,如下面的示例所示:
function(evt:Event):void

函数可以有任何名称。

 
useCapture:Boolean (default = false)此参数适用于 SWF 内容所使用的 ActionScript 3.0 显示列表体系结构中的显示对象。确定侦听器是运行于捕获阶段、目标阶段还是冒泡阶段。 如果将 useCapture 设置为 true,则侦听器只在捕获阶段处理事件,而不在目标或冒泡阶段处理事件。如果 useCapturefalse,则侦听器只在目标或冒泡阶段处理事件。要在所有三个阶段都侦听事件,请调用 addEventListener 两次:一次将 useCapture 设置为 true,一次将 useCapture 设置为 false .
 
priority:int (default = 0) — 事件侦听器的优先级。优先级由一个带符号的 32 位整数指定。数字越大,优先级越高。优先级为 n 的所有侦听器会在优先级为 n -1 的侦听器之前得到处理。如果两个或更多个侦听器共享相同的优先级,则按照它们的添加顺序进行处理。默认优先级为 0。
 
useWeakReference:Boolean (default = false) — 确定对侦听器的引用是强引用,还是弱引用。强引用(默认值)可防止您的侦听器被当作垃圾回收。弱引用则没有此作用。

类级别成员函数不属于垃圾回收的对象,因此可以对类级别成员函数将 useWeakReference 设置为 true 而不会使它们受垃圾回收的影响。如果对作为嵌套内部函数的侦听器将 useWeakReference 设置为 true,则该函数将作为垃圾回收并且不再是永久函数。如果创建对该内部函数的引用(将该函数保存到另一个变量中),则该函数将不作为垃圾回收并仍将保持永久。


引发
ArgumentError — 指定的 listener 不是一个函数。

另请参见

dispatchEvent()方法 
public function dispatchEvent(event:Event):Boolean

语言版本: ActionScript 3.0
运行时版本: AIR 1.0 Flash Player 9

将事件调度到事件流中。事件目标是对其调用 dispatchEvent() 方法的 EventDispatcher 对象。

参数

event:Event — 调度到事件流中的 Event 对象。如果正在重新调度事件,则会自动创建此事件的一个克隆。在调度了事件后,其 target 属性将无法更改,因此您必须创建此事件的一个新副本以能够重新调度。

返回
Boolean — 如果成功调度了事件,则值为 true。值 false 表示失败或对事件调用了 preventDefault()

引发
Error — 已达到事件调度递归限制。
hasEventListener()方法 
public function hasEventListener(type:String):Boolean

语言版本: ActionScript 3.0
运行时版本: AIR 1.0 Flash Player 9

检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。这样,您就可以确定 EventDispatcher 对象在事件流层次结构中的哪个位置改变了对事件类型的处理。要确定特定事件类型是否确实触发了事件侦听器,请使用 willTrigger()

hasEventListener()willTrigger() 的区别是:hasEventListener() 只检查它所属的对象,而 willTrigger() 检查整个事件流以查找由 type 参数指定的事件。事件流适用于 SWF 内容中使用的 ActionScript 3.0 显示列表。

当从 LoaderInfo 对象调用 hasEventListener() 时,只考虑调用方可以访问的侦听器。

参数

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)此参数适用于 SWF 内容所使用的 ActionScript 3.0 显示列表体系结构中的显示对象。指出是否为捕获阶段或目标阶段和冒泡阶段注册了侦听器。如果为捕获阶段以及目标和冒泡阶段注册了侦听器,则需要对 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 参数指定的事件。事件流适用于 SWF 内容中使用的 ActionScript 3.0 显示列表。

当从 LoaderInfo 对象调用 willTrigger() 时,只考虑调用方可以访问的侦听器。

参数

type:String — 事件的类型。

返回
Boolean — 如果将会触发指定类型的侦听器,则值为 true;否则,值为 false
事件详细信息
activate 事件
事件对象类型: flash.events.Event
属性 Event.type = flash.events.Event.ACTIVATE

语言版本: ActionScript 3.0
运行时版本: AIR 1.0 Flash Player 9

[广播事件] Flash Player 或 AIR 应用程序获得操作系统焦点并变为活动状态时将调度此事件。此事件为广播事件,这意味着将由所有具有注册了此事件的侦听器的 EventDispatcher 对象调度此事件。有关广播事件的详细信息,请参阅 DisplayObject 类。

ACTIVATE 常量定义 activate 事件对象的 type 属性的值。

注意:此事件既不具有“捕获阶段”也不具有“冒泡阶段”,这意味着必须直接将事件侦听器添加到任何潜在的目标,而无论目标是否位于显示列表中。

此事件具有以下属性:

属性
bubbles false
cancelable false;没有要取消的默认行为。
currentTarget 当前正在使用某个事件侦听器处理 Event 对象的对象。
target 具有为 activate 事件注册的侦听器的任何 DisplayObject 实例。

另请参见

deactivate 事件  
事件对象类型: flash.events.Event
属性 Event.type = flash.events.Event.DEACTIVATE

语言版本: ActionScript 3.0
运行时版本: AIR 1.0 Flash Player 9

[广播事件] Flash Player 或 AIR 应用程序失去操作系统焦点并变为非活动状态时将调度此事件。此事件为广播事件,这意味着将由所有具有注册了此事件的侦听器的 EventDispatcher 对象调度此事件。有关广播事件的详细信息,请参阅 DisplayObject 类。

Event.DEACTIVATE 常量定义 deactivate 事件对象的 type 属性值。

注意:此事件既不具有“捕获阶段”也不具有“冒泡阶段”,这意味着必须直接将事件侦听器添加到任何潜在的目标,而无论目标是否位于显示列表中。

此事件具有以下属性:

属性
bubbles false
cancelable false;没有要取消的默认行为。
currentTarget 当前正在使用某个事件侦听器处理 Event 对象的对象。
target 具有为 deactivate 事件注册的侦听器的任何 DisplayObject 实例。

另请参见

示例 如何使用示例
EventDispatcherExample.as

以下示例使用 EventDispatcherExampleCustomDispatcher 类(EventDispatcher 的子类)来说明如何创建和调度自定义事件。该示例执行下列任务:
  1. EventDispatcherExample 的构造函数创建一个局部变量 dispatcher,并将其赋给新的 CustomDispatcher 实例。
  2. CustomDispatcher 内,设置一个字符串以便事件具有名称 action,并且声明 doAction() 方法。当调用此方法时,此方法将创建 action 事件并使用 EventDispatcher.dispatchEvent() 调度该事件。
  3. 然后使用 dispatcher 属性添加 action 事件侦听器和关联的订阅者方法 actionHandler(),这样在调度事件时可以只输出有关该事件的信息。
  4. 调用 doAction() 方法,从而调度 action 事件。
package {
    import flash.display.Sprite;
    import flash.events.Event;

    public class EventDispatcherExample extends Sprite {

        public function EventDispatcherExample() {
            var dispatcher:CustomDispatcher = new CustomDispatcher();
            dispatcher.addEventListener(CustomDispatcher.ACTION, actionHandler);
            dispatcher.doAction();
        }

        private function actionHandler(event:Event):void {
            trace("actionHandler: " + event);
        }
    }
}

import flash.events.EventDispatcher;
import flash.events.Event;

class CustomDispatcher extends EventDispatcher {
    public static var ACTION:String = "action";

    public function doAction():void {
        dispatchEvent(new Event(CustomDispatcher.ACTION));
    }
}