How ActionScript 3.0 event handling differs from earlier versions
Flash Player 9 and later, Adobe AIR 1.0 and
The most noticeable difference between event handling in ActionScript
3.0 and event handling in previous versions of ActionScript is that
in ActionScript 3.0 there is only one system for event handling,
whereas in previous versions of ActionScript there are several different
event-handling systems. This section begins with an overview of
how event handling worked in previous versions of ActionScript,
and then discusses how event handling has changed for ActionScript
Event handling in previous versions of ActionScript
Versions of ActionScript before ActionScript 3.0 provided a number
of different ways to handle events:
on() event handlers that can be placed
directly on Button and MovieClip instances
onClipEvent() handlers that can be placed
directly on MovieClip instances
Callback function properties, such as XML.onload and Camera.onActivity
Event listeners that you register using the addListener() method
The UIEventDispatcher class that partially implemented the
DOM event model.
of these mechanisms presents its own set of advantages and limitations. The on() and onClipEvent() handlers
are easy to use, but make subsequent maintenance of projects more
difficult because code placed directly on buttons and movie clips
can be difficult to find. Callback functions are also simple to implement,
but limit you to only one callback function for any given event.
Event listeners are more difficult to implement—they require not
only the creation of a listener object and function, but also the
registration of the listener with the object that generates the
event. This increased overhead, however, enables you to create several
listener objects and register them all for the same event.
of components for ActionScript 2.0 engendered yet another event
model. This new model, embodied in the UIEventDispatcher class,
was based on a subset of the DOM Events Specification. Developers
who are familiar with component event handling will find the transition
to the new ActionScript 3.0 event model relatively painless.
Unfortunately, the syntax used by the various event models overlap
in various ways, and differ in others. For example, in ActionScript
2.0, some properties, such as TextField.onChanged,
can be used as either a callback function or an event listener.
However, the syntax for registering listener objects differs depending
on whether you are using one of the six classes that support listeners or
the UIEventDispatcher class. For the Key, Mouse, MovieClipLoader,
Selection, Stage, and TextField classes, you use the addListener() method,
but for components event handling, you use a method called addEventListener().
Another complexity introduced by the different event-handling
models was that the scope of the event handler function varied widely
depending on the mechanism used. In other words, the meaning of
the this keyword was not consistent among the event-handling
Event handling in ActionScript 3.0
ActionScript 3.0 introduces
a single event-handling model that replaces the many different event-handling
mechanisms that existed in previous versions of the language. The
new event model is based on the Document Object Model (DOM) Level
3 Events Specification. Although the SWF file format does not adhere
specifically to the Document Object Model standard, there are sufficient similarities
between the display list and the structure of the DOM to make implementation
of the DOM event model possible. An object on the display list is analogous
to a node in the DOM hierarchical structure, and the terms display list object and node are
used interchangeably throughout this discussion.
The Flash Player and AIR implementation
of the DOM event model includes a concept named default behaviors.
A default behavior is an action that Flash Player or AIR
executes as the normal consequence of certain events.
Developers are usually responsible for writing
code that responds to events. In some cases, however, a behavior
is so commonly associated with an event that Flash Player or AIR
automatically executes the behavior unless the developer adds code
to cancel it. Because Flash Player or AIR automatically exhibits
the behavior, such behaviors are called default behaviors.
example, when a user enters text into a TextField object, the expectation
that the text will be displayed in that TextField object is so common
that the behavior is built into Flash Player and AIR. If you do
not want this default behavior to occur, you can cancel it using
the new event-handling system. When a user inputs text into a TextField
object, Flash Player or AIR creates an instance of the TextEvent class
to represent that user input. To prevent Flash Player or AIR from
displaying the text in the TextField object, you must access that
specific TextEvent instance and call that instance’s preventDefault() method.
Not all default behaviors can be prevented.
For example, Flash Player and AIR generate a MouseEvent object when
a user double-clicks a word in a TextField object. The default behavior,
which cannot be prevented, is that the word under the cursor is
Many types of event objects do not have associated
default behaviors. For example, Flash Player dispatches a connect
event object when a network connection is established, but there
is no default behavior associated with it. The API documentation
for the Event class and its subclasses lists each type of event and
describes any associated default behavior, and whether that behavior
can be prevented.
It is important to understand that default
behaviors are associated only with event objects dispatched by Flash
Player or AIR, and do not exist for event objects dispatched programmatically
through ActionScript. For example, you can use the methods of the
EventDispatcher class to dispatch an event object of type textInput,
but that event object will not have a default behavior associated with
it. In other words, Flash Player and AIR will not display a character
in a TextField object as a result of a textInput event
that you dispatched programmatically.
What’s new for event listeners in ActionScript 3.0
For developers with experience using the
ActionScript 2.0 addListener() method, it may be
helpful to point out the differences between the ActionScript 2.0
event listener model and the ActionScript 3.0 event model. The following
list describes a few major differences between the two event models:
add event listeners in ActionScript 2.0, you use addListener() in
some cases and addEventListener() in others, whereas
in ActionScript 3.0, you use addEventListener() in
There is no event flow in ActionScript 2.0, which means that
the addListener() method can be called only on
the object that broadcasts the event, whereas in ActionScript 3.0,
the addEventListener() method can be called on
any object that is part of the event flow.
In ActionScript 2.0, event listeners can be either functions,
methods, or objects, whereas in ActionScript 3.0, only functions
or methods can be event listeners.