About Flex events
let a developer know when something happens within an application. They
can be generated by user devices, such as the mouse and keyboard,
or other external input, such as the return of a web service call.
Events are also triggered when changes happen in the appearance
or life cycle of a component, such as the creation or destruction
of a component or when the component is resized.
Any user interaction with your application can generate events.
Events can also occur without any direct user interaction, such
as when data finishes loading from a server or when an attached
camera becomes active. You can “handle” these events in your code
by adding an event handler. Event handlers are the functions
or methods that you write to respond to specific events. They are
also sometimes referred to as event listeners.
The Flex event model is based on the Document Object Model (DOM)
Level 3 events model. Although Flex does not adhere specifically
to the DOM standard, the implementations are very similar. The event
model in Flex comprises the Event object
and its subclasses, and the event dispatching model. For a quick start
in using events in Flex, see the sample code in Using events.
Components generate and dispatch events and consume (listen
to) other events. An object that requires information about another
object’s events registers a listener with that object. When an event
occurs, the object dispatches the event to all registered listeners
by calling a function that was requested during registration. To
receive multiple events from the same object, you must register
your listener for each event.
Components have built-in events that you can handle in ActionScript
blocks in your MXML applications. You can also take advantage of
the Flex event system’s dispatcher-listener model to define your
own event listeners outside of your applications, and define which
methods of your custom listeners will listen to certain events.
You can register listeners with the target object so that when the target
object dispatches an event, the listeners get called.
All visual objects, including Flex controls and containers, are
subclasses of the DisplayObject class.
They are in a tree of visible objects that make up your application.
The root of the tree is the Stage. Below that is the SystemManager
object, and then the Application object. Child containers and components
are leaf nodes of the tree. That tree is known as the display list.
An object on the display list is analogous to a node in the DOM
hierarchical structure. The terms display list object and node are
For information about each component’s events, see the component’s description
in UI Controls or the control’s entry in ActionScript 3.0 Reference for the Adobe
For a detailed description of a component’s startup life cycle,
including major events in that life cycle, see Create advanced MX visual components in ActionScript.
About the event flow
You can instruct any container or control to listen for
events dispatched by another container or control. When Adobe® Flash® Player
dispatches an Event object, that Event object makes a roundtrip
journey from the root of the display list to the target node, checking
each node for registered listeners. The target node is the
node in the display list where the event occurred. For example,
if a user clicks a Button control named Child1, Flash Player dispatches
an Event object with Child1 defined as the target node.
The event flow
is conceptually divided into three parts: the capturing phase, the targeting
phase, and the bubbling phase, as briefly described next. For more information
about the event flow, see Event propagation.
About the capturing phase
first part of the event flow is called the capturing phase.
This phase comprises all of the nodes from the root node to the
parent of the target node. During this phase, Flash Player examines
each node, starting with the root, to see if it has a listener registered
to handle the event. If it does, Flash Player sets the appropriate values
of the Event object and then calls that listener. Flash Player stops
after it reaches the target node’s parent and calls any listeners
registered on the parent. For more information, see Capturing phase.
About the targeting phase
second part of the event flow, the targeting phase, consists
solely of the target node. Flash Player sets the appropriate values
on the Event object, checks the target node for registered event
listeners, and then calls those listeners. For more information,
see Targeting phase.
About the bubbling phase
third part of the event flow, the bubbling phase, comprises
all of the nodes from the target node’s parent to the root node.
Starting with the target node’s parent, Flash Player sets the appropriate
values on the Event object and then calls event listeners on each
of these nodes. Flash Player stops after calling any listeners on
the root node. For more information about the bubbling phase, see Bubbling phase.
About the Event class
The Event class
is an ActionScript class with properties that contain information about
the event that occurred. An Event object is an implicitly created
object, similar to the request and response objects in a JavaServer
Page (JSP) that are implicitly created by the application server.
Flex creates an Event object each time an event is dispatched.
You can use the Event object inside an event listener to access
details about the event that was dispatched, or about the component
that dispatched the event. Passing an Event object to, and using
it in, an event listener is optional. However, if you want to access
the Event object’s properties inside your event listeners, you must
pass the Event object to the listener.
Flex creates only one Event object when an event is dispatched.
During the bubbling and capturing phases, Flex changes the values
on the Event object as it moves up or down the display list, rather
than creating a new Event object for each node.
About event subclasses
There are many classes that extend the flash.events.Event
class. These classes are defined mostly in the following packages:
The mx.events package defines event classes that are specific
to most Flex controls, including the DataGridEvent, DragEvent, and
ColorPickerEvent. The spark.events package defines event classes
that are specific to a few Spark controls, including the TextOperationEvent
and VideoEvent. The flash.events package describes events that are
not unique to Flex but are instead defined by Flash Player. These
event classes include MouseEvent, DataEvent,
and TextEvent. All
of these events are commonly used in applications.
In addition to these packages, some packages also define their
own event objects: for example, mx.messaging.events.ChannelEvent
Child classes of the Event class have additional properties and
methods that may be unique to them. In some cases, you will want
to use a more specific event type rather than the generic Event
object so that you can access these unique properties or methods.
For example, the LogEvent class has a getLevelString() method
that the Event class does not.
For information on using Event subclasses, see Using event subclasses.
About the EventDispatcher class
Every object in the display list can trace its class inheritance
back to the DisplayObject class.
The DisplayObject class, in turn, inherits from the EventDispatcher class.
The EventDispatcher class is a base class that provides important
event model functionality for every object on the display list.
Because the DisplayObject class inherits from the EventDispatcher
class, any object on the display list has access to the methods
of the EventDispatcher class.
This is significant because every item on the display list can
participate fully in the event model. Every object on the display
list can use its addEventListener() method—inherited
from the EventDispatcher class—to listen for a particular event,
but only if the listening object is part of the event flow for that
Although the name EventDispatcher seems to imply that this class’s
main purpose is to send (or dispatch) Event objects, the methods
of this class are used much more frequently to register event listeners,
check for event listeners, and remove event listeners.
The EventDispatcher class implements the IEventDispatcher interface.
This allows developers who create custom classes that cannot inherit
from EventDispatcher or one of its subclasses to implement the IEventDispatcher
interface to gain access to its methods.
The addEventListener() method is the most commonly
used method of this class. You use it to register your event listeners.
For information on using the addEventListener() method,
see Using the addEventListener() method.
Advanced programmers use the dispatchEvent() method
to manually dispatch an event or to send a custom Event object into
the event flow. For more information, see Manually dispatching events.
Several other methods of the EventDispatcher class provide useful
information about the existence of event listeners. The hasEventListener() method returns true if
an event listener is found for that specific event type on a particular
display list object. The willTrigger() method checks
for event listeners on a particular display list object, but it
also checks for listeners on all of that display list object’s ancestors
for all phases of the event flow. The method returns true if
it finds one.