About Flex events

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 used interchangeably.

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 Flash Platform.

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

The 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

The 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

The 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:

  • spark.events.*

  • mx.events.*

  • flash.events.*

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 and mx.logging.LogEvent.

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 event.

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.