Events in Flex

About events

Events let a developer know when something happens within a Flex 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 Controls or the control's entry in ActionScript 3.0 Language Reference.

For a detailed description of a component's startup life cycle, including major events in that life cycle, see Advanced 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 flash.events.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 two packages:

* mx.events.*
* flash.events.*

The mx.events package defines event classes that are specific to Flex controls, including the DataGridEvent, DragEvent, and ColorPickerEvent. 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 Flex 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.