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.

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.

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.

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.

You specify the object in a listener function's signature as type Event, as the following example shows:

 function myEventListener(e:Event):void { ... }

However, if you want to access properties that are specific to the type of event that was dispatched, you must instead specify a more specific event type, such as ToolTipEvent or KeyboardEvent, as the following example shows:

 import mx.events.ToolTip 
 function myEventListener(e:ToolTipEvent):void { ... }

In some cases, you must import the event's class in your ActionScript block.

Most objects have specific events that are associated with them, and most of them can dispatch more than one type of event.

If you declare an event of type Event, you can cast it to a more specific type to access its event-specific properties. For more information, see Using event subclasses.

Event objects include a reference to the instance of the dispatching component (or target), which means that you can access all the properties and methods of that instance in an event listener. The following example accesses the id of the Button control that triggered the event:

<?xml version="1.0"?> 
<!-- events/AccessingCurrentTarget.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 
    <fx:Script> 
        <![CDATA[ 
            import mx.controls.Alert; 
 
            private function myEventHandler(e:Event):void { 
                Alert.show("The button '" + e.currentTarget.id + "' was clicked."); 
            } 
        ]]> 
    </fx:Script> 
 
    <s:Button id="b1" label="Click Me" click="myEventHandler(event)"/> 
 
</s:Application>

You can access members of the currentTarget. If you do not cast the current target to a specific type, the compiler assumes that it is of type Object. Objects can have any property or method because the Object type is dynamic in ActionScript. Therefore, when accessing methods and properties of the currentTarget, it is best practice to cast currentTarget to whatever class you anticipate will dispatch that event. This gives you strong type checking at compile time, and helps avoid the risk of throwing a run-time error.

The following example casts the current target to a TextInput class before calling the selectRange() method, but does not cast it before trying to set the tmesis property. The tmesis property does not exist on the TextInput class. This illustrates that you will get a run-time error but not a compile-time error when you try to access members that don't exist, unless you cast currentTarget to a specific type so that type checking can occur:

<?xml version="1.0"?> 
<!-- events/InvokingOnCurrentTarget.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    width="500"> 
 
    <fx:Script> 
        <![CDATA[ 
        import mx.core.UIComponent; 
 
        private function tiHandler(e:Event):void { 
            /* 
            The following enforces type checking: 
            */ 
            TextInput(e.currentTarget).selectRange(0,3); 
 
            /* 
            The following throws a run-time error but not a compile-time error: 
            e.currentTarget.tmesis = 4; 
            */ 
 
            /* 
            ... unless you cast it to the expected type like the following. Then 
            the compiler throws an error. 
            TextInput(e.currentTarget).tmesis = 4; 
            */ 
        } 
        ]]> 
    </fx:Script> 
 
    <s:TextInput id="ti1" click="tiHandler(event)" 
        text="When you click on this control, the first three characters are selected." 
        width="400"/> 
 
</s:Application>

You could also cast currentTarget to UIComponent or some other more general class that still has methods of display objects. That way, if you don't know exactly which control will dispatch an event, at least you can ensure there is some type checking.

You can also access methods and properties of the target property, which contains a reference to the current node in the display list. For more information, see About the target and currentTarget properties.

There are several strategies that you can employ when you register event handlers with your Flex controls:

1. Define an event handler inline. This binds a call to the handler function to the control that triggers the event.

   <?xml version="1.0"?> 
   <!-- events/SimplerEventHandler.mxml --> 
   <s:Application 
       xmlns:fx="http://ns.adobe.com/mxml/2009"    
       xmlns:mx="library://ns.adobe.com/flex/mx"     
       xmlns:s="library://ns.adobe.com/flex/spark"> 
       
       <fx:Script> 
           <![CDATA[ 
           import mx.controls.Alert; 
    
           private function myEventHandler(event:Event):void { 
               Alert.show("An event occurred."); 
           } 
           ]]> 
       </fx:Script> 
    
       <s:Button id="b1" label="Click Me" click="myEventHandler(event)"/> 
    
   </s:Application>

   In this example, whenever the user clicks the Button control, Flex calls the myClickHandler() function.

   For more information on defining event handlers inline, see Defining event listeners inline.

2. Use the addEventListener() method, as follows:

   <?xml version="1.0"?> 
   <!-- events/SimpleEventHandler.mxml --> 
   <s:Application 
       xmlns:fx="http://ns.adobe.com/mxml/2009"    
       xmlns:mx="library://ns.adobe.com/flex/mx"     
       xmlns:s="library://ns.adobe.com/flex/spark" 
       creationComplete="initApp();"> 
    
       <fx:Script> 
           <![CDATA[ 
           import mx.controls.Alert; 
    
           private function initApp():void { 
               b1.addEventListener(MouseEvent.CLICK, myEventHandler); 
           } 
    
           private function myEventHandler(event:Event):void { 
               Alert.show("An event occurred."); 
           } 
           ]]> 
       </fx:Script> 
    
       <s:Button id="b1" label="Click Me"/> 
    
   </s:Application>

   As with the previous example, whenever the user clicks the Button control, Flex calls the myClickHandler() handler function. However, registering your event handlers using this method provides more flexibility. You can register multiple components with this event handler, add multiple handlers to a single component, or remove the handler. For more information, see Using the addEventListener() method.

3. Create an event handler class and register components to use the class for event handling. This approach to event handling promotes code reuse and lets you centralize event handling outside your MXML files. For more information on creating custom event handler classes, see Creating event handler classes.

You can define multiple event handler functions for a single event in two ways. When defining events inside MXML tags, you separate each new handler function with a semicolon. The following example adds the submitForm() and debugMessage() functions as handlers of the click event:

<?xml version="1.0"?> 
<!-- events/MultipleEventHandlersInline.mxml --> 
<s:Application     
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script><![CDATA[ 
        [Bindable] 
        private var s:String = ""; 
  
        private function submitForm(e:Event):void { 
            // Handle event here. 
            s += "The submitForm() method was called. "; 
        } 
        private function debugMessage(e:Event):void { 
            // Handle event here. 
            s += "The debugMessage() method was called. "; 
        } 
    ]]></fx:Script> 
  
    <s:Button id="b1" 
        label="Do Both Actions" 
        click='submitForm(event); debugMessage(event);' 
    /> 
    <s:Label id="l1" text="{s}"/> 
    
    <s:Button id="b2" label="Reset" click="s='';"/> 
    
</s:Application>

For events added with the addEventListener() method, you can add any number of handlers with additional calls to the addEventListener() method. Each call adds a handler function that you want to register to the specified object. The following example registers the submitForm() and debugMessage() handler functions with b1's click event:

<?xml version="1.0"?> 
<!-- events/MultipleEventHandlersAS.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="createHandlers(event)"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script><![CDATA[ 
        [Bindable] 
        private var s:String = ""; 
 
        public function createHandlers(e:Event):void { 
            b1.addEventListener(MouseEvent.CLICK, submitForm); 
            b1.addEventListener(MouseEvent.CLICK, debugMessage); 
        } 
 
        private function submitForm(e:Event):void { 
            // Handle event here. 
            s += "The submitForm() method was called. "; 
            
        } 
 
        private function debugMessage(e:Event):void { 
            // Handle event here. 
            s += "The debugMessage() method was called. ";            
        } 
 
    ]]></fx:Script> 
 
    <s:Button id="b1" label="Do Both Actions"/> 
 
    <s:Label id="l1" text="{s}"/> 
    
    <s:Button id="b2" label="Reset" click="s='';"/> 
 
</s:Application>

You can mix the methods of adding event handlers to any component; alternatively, you can add handlers inline and with the addEventListener() method. The following example adds a click event handler inline for the Button control, which calls the performAction() method. It then conditionally adds a second click handler to call the logAction() method, depending on the state of the CheckBox control.

<?xml version="1.0"?> 
<!-- events/ConditionalHandlers.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    initialize="initApp(event)"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            import mx.controls.Alert; 
 
            private function initApp(e:Event):void { 
               cb1.addEventListener(MouseEvent.CLICK, handleCheckBoxChange); 
               b1.addEventListener(MouseEvent.CLICK, logAction); 
            } 
 
            private function handleCheckBoxChange(e:Event):void { 
               if (cb1.selected) { 
                    b1.addEventListener(MouseEvent.CLICK, logAction); 
                    ta1.text += "Added log listener." + "\n"; 
                } else { 
                    b1.removeEventListener(MouseEvent.CLICK, logAction); 
                    ta1.text += "Removed log listener." + "\n"; 
                } 
            } 
 
            private function performAction(e:Event):void { 
                Alert.show("You performed the action."); 
            } 
 
            private function logAction(e:Event):void { 
                ta1.text += "Action performed: " + e.type + ".\n"; 
            } 
        ]]> 
    </fx:Script> 
 
    <s:Button label="Perform Action" id="b1" click="performAction(event)"/> 
    <s:CheckBox id="cb1" label="Log?" selected="true"/> 
    <s:TextArea id="ta1" height="200" width="300"/> 
 
</s:Application>

You can set the order in which event listeners are called by using the priority parameter of the addEventListener() method. You cannot set a priority for a listener function if you added the event listener using MXML inline. For more information on setting priorities, see Event priorities.

You can register the same listener function with any number of events of the same component, or events of different components. The following example registers a single listener function, submitForm(), with two different buttons:

<?xml version="1.0"?> 
<!-- events/OneHandlerTwoComponentsInline.mxml --> 
<s:Application     
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        import mx.controls.Alert; 
 
        private function submitForm(e:Event):void { 
            // Handle event here. 
            Alert.show("Current Target: " + e.currentTarget.id); 
        } 
 
        ]]> 
    </fx:Script> 
 
    <s:Button id="b1" 
        label="Click Me" 
        click="submitForm(event)"/> 
 
    <s:Button id="b2" 
        label="Click Me, Too" 
        click="submitForm(event)"/> 
        
</s:Application>

When you use the addEventListener() method to register a single listener to handle the events of multiple components, you must use a separate call to the addEventListener() method for each instance, as the following example shows:

<?xml version="1.0"?> 
<!-- events/OneHandlerTwoComponentsAS.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="createHandlers(event)"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        import mx.controls.Alert; 
 
        public function createHandlers(e:Event):void { 
            b1.addEventListener(MouseEvent.CLICK, submitForm); 
            b2.addEventListener(MouseEvent.CLICK, submitForm); 
        } 
 
        private function submitForm(e:Event):void { 
            // Handle event here. 
            Alert.show("Current Target: " + e.currentTarget.id); 
        } 
        ]]> 
    </fx:Script> 
 
    <s:Button id="b1" label="Click Me"/> 
 
    <s:Button id="b2" label="Click Me, Too"/> 
 
</s:Application>

When doing this, you should add logic to the event listener that processes the type of event. The event target (or object that dispatched the event) is added to the Event object for you. No matter what triggered the event, you can conditionalize the event processing based on the target or type properties of the Event object. Flex adds these two properties to all Event objects.

The following example registers a single listener function (myEventHandler()) to the click event of a Button control and the click event of a CheckBox control. To detect what type of object called the event listener, the listener checks the className property of the target in the Event object in a case statement.

<?xml version="1.0"?> 
<!-- events/ConditionalTargetHandler.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="initApp()"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        import mx.controls.Alert; 
    
        public function initApp():void { 
            button1.addEventListener(MouseEvent.CLICK, myEventHandler); 
            cb1.addEventListener(MouseEvent.CLICK, myEventHandler); 
        } 
 
        public function myEventHandler(event:Event):void { 
            switch (event.currentTarget.className) { 
                case "Button": 
                    // Process Button click. 
                    Alert.show("You clicked the Button control."); 
                    break; 
                case "CheckBox": 
                    // Process CheckBox click. 
                    Alert.show("You clicked the CheckBox control."); 
                    break; 
            } 
        } 
        ]]> 
    </fx:Script> 
 
    <s:Button label="Click Me" id="button1"/> 
    <s:CheckBox label="Select Me" id="cb1"/> 
 
</s:Application>

You can pass additional parameters to listener functions depending on how you add the listeners. If you add a listener with the addEventListener() method, you cannot pass any additional parameters to the listener function by arbitrarily adding new parameters to the function signature. The default listener function can declare only a single argument, the Event object (or one of its subclasses).

For example, the following code throws an error because the clickListener() method expects two arguments:

 <fx:Script> 
 	public function addListeners():void { 
 		b1.addEventListener(MouseEvent.CLICK,clickListener); 
 	} 
 	public function clickListener(e:MouseEvent, a:String):void { ... } 
 </fx:Script> 
 <mx:Button id="b1"/>

Because the second parameter of the addEventListener() method is a function, you can define that function and pass the event object plus any additional parameters through to a different handler. The following example creates a new function in the addEventListener() method, add two parameters to the new handler's call, and then handles all of the parameters in the myClickListener() method.

<?xml version="1.0" encoding="utf-8"?> 
<!-- events/CustomListenerFunction.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="initApp(event)"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            private var specialParam1:String; 
            private var specialParam2:String = "42"; 
 
            private function initApp(e:Event):void { 
                assignSpecialParam(e); 
                
                /* Change the value of specialParam whenever the user changes it 
                   in the TextInput and clicks the button. */ 
                ti1.addEventListener("focusOut", assignSpecialParam); 
                
                /* Define the pass-through method in the addEventListener() method call. 
                   You can add any number of parameters, as long as teh target method's 
                   signature agrees. */ 
                myButton.addEventListener(MouseEvent.CLICK, function (e:MouseEvent):void { 
                        myClickListener(e, specialParam1, specialParam2); 
                    } 
                );          
            } 
            
            private function assignSpecialParam(e:Event):void { 
                specialParam1 = ti1.text; 
            } 
            
            /* This method acts as the event listener, and it has any 
             number of parameters that we defined in the addEventListener() call. */ 
            private function myClickListener(e:MouseEvent, s1:String, s2:String) : void { 
                myButton.label = s1 + " " + s2; 
            }           
        ]]> 
    </fx:Script> 
    <s:Button id="myButton" label="Click Me"/> 
    <s:TextInput id="ti1" text="Enter a custom String here." width="250"/> 
 
</s:Application>

Another approach to passing additional parameters to the listener function is to define them in the listener function and then call the final method with those parameters. If you define an event listener inline (inside the MXML tag), you can add any number of parameters as long as the listener function's signature agrees with that number of parameters.

The following example passes a string and the Event object to the runMove() method:

<?xml version="1.0"?> 
<!-- events/MultipleHandlerParametersInline.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"> 
    
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        public function runMove(dir:String, e:Event):void { 
            if (dir == "up") { 
                moveableButton.y = moveableButton.y - 5; 
            } else if (dir == "down") { 
                moveableButton.y = moveableButton.y + 5; 
            } else if (dir == "left") { 
                moveableButton.x = moveableButton.x - 5; 
            } else if (dir == "right") { 
                moveableButton.x = moveableButton.x + 5; 
            } 
        } 
        ]]> 
    </fx:Script> 
 
  <mx:Canvas height="100%" width="100%"> 
     <s:Button id="moveableButton" 
        label="{moveableButton.x.toString()},{moveableButton.y.toString()}" 
        x="75" 
        y="100" 
        width="80" 
     /> 
  </mx:Canvas> 
 
  <s:VGroup horizontalAlign="center"> 
     <s:Button id="b1" 
        label="Up" 
        click='runMove("up",event);' 
        width="75"/> 
        <s:HGroup horizontalAlign="center"> 
           <mx:Button id="b2" 
            label="Left" 
            click='runMove("left",event);' 
            width="75"/> 
           <s:Button id="b3" 
            label="Right" 
            click='runMove("right",event);' 
            width="75"/> 
        </s:HGroup> 
     <s:Button id="b4" 
        label="Down" 
        click='runMove("down",event);' 
        width="75"/> 
  </s:VGroup> 
 
</s:Application>

Every Event object has a target and a currentTarget property that help you to keep track of where it is in the process of propagation. The target property refers to the dispatcher of the event. The currentTarget property refers to the current node that is being examined for event listeners.

When you handle a mouse event such as MouseEvent.CLICK by writing a listener on some component, the event.target property does not necessarily refer to that component; it is often a subcomponent, such as the Button control's UITextField, that defines the label.

When Flash Player or Adobe^® AIR™ dispatches an event, it dispatches the event from the frontmost object under the mouse. Because children are in front of parents, that means the player or AIR might dispatch the event from an internal subcomponent, such as the UITextField of a Button.

The event.target property is set to the object that dispatched the event (in this case, UITextField), not the object that is being listened to (in most cases, you have a Button control listen for a click event).

MouseEvent events bubble up the parent chain, and can be handled on any ancestor. As the event bubbles, the value of the event.target property stays the same (UITextField), but the value of the event.currentTarget property is set at each level to be the ancestor that is handling the event. Eventually, the currentTarget will be Button, at which time the Button control's event listener will handle the event. For this reason, you should use the event.currentTarget property rather than the event.target property; for example:

 <mx:Button label="OK" click="trace(event.currentTarget.label)"/>

In this case, in the Button event's click event listener, the event.currentTarget property always refers to the Button, while event.target might be either the Button or its UITextField, depending on where on the Button control the user clicked.

In the capturing phase, Flex examines an event target's ancestors in the display list to see which ones are registered as a listener for the event. Flex starts with the root ancestor and continues down the display list to the direct ancestor of the target. In most cases, the root ancestors are the Stage, then the SystemManager, and then the Application object.

For example, if you have an application with a Panel container that contains a TitleWindow container, which in turn contains a Button control, the structure appears as follows:

 Application 
 	Panel 
 		TitleWindow 
 			Button

If your listener is on the click event of the Button control, the following steps occur during the capturing phase if capturing is enabled:

1. Check the Application container for click event listeners.

2. Check the Panel container for click event listeners.

3. Check the TitleWindow container for click event listeners.

During the capturing phase, Flex changes the value of the currentTarget property on the Event object to match the current node whose listener is being called. The target property continues to refer to the dispatcher of the event.

By default, no container listens during the capturing phase. The default value of the use_capture argument is false. The only way to add a listener during this phase is to pass true for the use_capture argument when calling the addEventListener() method, as the following example shows:

 myPanel.addEventListener(MouseEvent.MOUSE_DOWN, clickHandler, true);

If you add an event listener inline with MXML, Flex sets this argument to false; you cannot override it.

If you set the use_capture argument to true—in other words, if an event is propagated through the capturing phase—the event can still bubble, but capture phase listeners will not react to it. If you want your event to traverse both the capturing and bubbling phases, you must call addEventListener() twice: once with use_capture set to true, and then again with use_capture set to false.

The capturing phase is very rarely used, and it can also be computationally intensive. By contrast, bubbling is much more common.

In the targeting phase, Flex invokes the event dispatcher's listeners. No other nodes on the display list are examined for event listeners. The values of the currentTarget and the target properties on the Event object during the targeting phase are the same.

In the bubbling phase, Flex examines an event's ancestors for event listeners. Flex starts with the dispatcher's immediate ancestor and continues up the display list to the root ancestor. This is the reverse of the capturing phase.

For example, if you have an application with a Panel container that contains a TitleWindow container that contains a Button control, the structure appears as follows:

 Application 
 	Panel 
 		TitleWindow 
 			Button

If your listener is on the click event of the Button control, the following steps occur during the bubble phase if bubbling is enabled:

1. Check the TitleWindow container for click event listeners.

2. Check the Panel container for click event listeners.

3. Check the Application container for click event listeners.

An event only bubbles if its bubbles property is set to true. Mouse events and keyboard events are among those that bubble; it is less common for higher-level events that are dispatched by Flex to bubble. Events that can be bubbled include change, click, doubleClick, keyDown, keyUp, mouseDown, and mouseUp. To determine whether an event bubbles, see the event's entry in the ActionScript 3.0 Reference for Apache Flex.

During the bubbling phase, Flex changes the value of the currentTarget property on the Event object to match the current node whose listener is being called. The target property continues to refer to the dispatcher of the event.

When Flex invokes an event listener, the Event object might have actually been dispatched by an object deeper in the display list. The object that originally dispatched the event is the target. The object that the event is currently bubbling through is the currentTarget. So, you should generally use the currentTarget property instead of the target property when referring to the current object in your event listeners.

If you set the useCapture property to true—in other words, if an event is propagated through the capturing phase—then it does not bubble, regardless of its default bubbling behavior. If you want your event to traverse both the capturing and bubbling phases, you must call addEventListener() twice: once with useCapture set to true, and then again with useCapture set to false.

An event only bubbles up the parent's chain of ancestors in the display list. Siblings, such as two Button controls inside the same container, do not intercept each other's events.

You can determine what phase you are in by using the Event object's eventPhase property. This property contains an integer that represents one of the following constants:

• 1 — Capturing phase (CAPTURING_PHASE)

• 2 — Targeting phase (AT_TARGET)

• 3 — Bubbling phase (BUBBLING_PHASE)

The following example displays the current phase and information about the current target:

<?xml version="1.0"?> 
<!-- events/DisplayCurrentTargetInfo.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 
    <fx:Script><![CDATA[ 
        import mx.controls.Alert; 
 
        private function showInfo(e:MouseEvent):void { 
            Alert.show("Phase: " + e.eventPhase + "\n" + 
                "ID: " + e.currentTarget.id + "\n" + 
                "Label: " + e.currentTarget.label + "\n" + 
                "Font Size: " + e.currentTarget.getStyle("fontSize"), "Current Target Info"); 
        } 
    ]]></fx:Script> 
 
    <s:Button id="b1" label="Click Me" click="showInfo(event)"/> 
 
</s:Application>

During any phase, you can stop the traversal of the display list by calling one of the following methods on the Event object:

• stopPropagation()

• stopImmediatePropagation()

You can call either the event's stopPropagation() method or the stopImmediatePropagation() method to prevent an Event object from continuing on its way through the event flow. The two methods are nearly identical and differ only in whether the current node's remaining event listeners are allowed to execute. The stopPropagation() method prevents the Event object from moving on to the next node, but only after any other event listeners on the current node are allowed to execute.

The stopImmediatePropagation() method also prevents the Event objects from moving on to the next node, but it does not allow any other event listeners on the current node to execute.

The following example creates a TitleWindow container inside a Panel container. Both containers are registered to listen for a mouseDown event. As a result, if you click on the TitleWindow container, the showAlert() method is called twice unless you add a call to the stopImmediatePropagation() method, as the following example shows:

<?xml version="1.0"?> 
<!-- events/StoppingPropagation.mxml --> 
<s:Application     
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    initialize="init(event);"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        import mx.controls.Alert; 
        import flash.events.MouseEvent; 
        import flash.events.Event; 
 
        public function init(e:Event):void { 
            p1.addEventListener(MouseEvent.MOUSE_DOWN, showAlert); 
            tw1.addEventListener(MouseEvent.MOUSE_DOWN, showAlert); 
            tw1.addEventListener(Event.CLOSE, closeWindow); 
 
            p2.addEventListener(MouseEvent.MOUSE_DOWN, showAlertWithoutStoppingPropagation); 
            tw2.addEventListener(MouseEvent.MOUSE_DOWN, showAlertWithoutStoppingPropagation); 
            tw2.addEventListener(Event.CLOSE, closeWindow); 
        } 
 
        public function showAlert(e:Event):void { 
            Alert.show("Alert!\n" + "Current Target: " + e.currentTarget + "\n" + 
                "Phase: " + e.eventPhase); 
            e.stopImmediatePropagation(); 
        } 
 
        public function showAlertWithoutStoppingPropagation(e:Event):void { 
            Alert.show("Alert!\n" + "Current Target: " + e.currentTarget + "\n" + 
                "Phase: " + e.eventPhase);          
        } 
 
        public function closeWindow(e:Event):void { 
            p1.removeChild(tw1); 
        } 
        ]]> 
    </fx:Script> 
 
    <s:Panel id="p1" title="Stops Propagation"> 
        <mx:TitleWindow id="tw1" 
            width="300" 
            height="100" 
            showCloseButton="true" 
            title="Title Window 1"> 
            <s:Button label="Click Me"/> 
            <s:TextArea id="ta1"/> 
        </mx:TitleWindow> 
    </s:Panel> 
 
    <s:Panel id="p2" title="Does Not Stop Propagation"> 
        <mx:TitleWindow id="tw2" 
            width="300" 
            height="100" 
            showCloseButton="true" 
            title="Title Window 2"> 
            <s:Button label="Click Me"/> 
            <s:TextArea id="ta2"/> 
        </mx:TitleWindow> 
    </s:Panel> 
 
</s:Application>

In the following example, the parent container's click handler disables the target control after the target handles the event. It shows that you can reuse the logic of a single listener (click the HGroup container) for multiple events (all the clicks).

<?xml version="1.0"?> 
<!-- events/NestedHandlers.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script><![CDATA[ 
        public function disableControl(event:MouseEvent):void { 
            // Use this same logic for all events. 
            event.currentTarget.enabled = false; 
        } 
 
        public function doSomething(event:MouseEvent):void { 
            b1.label = "clicked"; 
            ta1.text += "Something happened."; 
        } 
 
        public function doSomethingElse(event:MouseEvent):void { 
            b2.label = "clicked"; 
            ta1.text += "Something happened again."; 
        } 
    ]]></fx:Script> 
 
    <s:HGroup id="hb1" height="200" click="disableControl(event)"> 
        <s:Button id='b1' label="Click Me" click="doSomething(event)"/> 
        <s:Button id='b2' label="Click Me" click="doSomethingElse(event)"/> 
        <s:TextArea id="ta1"/> 
    </s:HGroup> 
 
    <s:Button id="resetButton" 
        label="Reset" 
        click="hb1.enabled=true;b1.enabled=true;b2.enabled=true;b1.label='Click Me';b2.label='Click Me';"/> 
 
</s:Application>

By having a single listener on a parent control instead of many listeners (one on each child control), you can reduce your code size and make your applications more efficient. Reducing the number of calls to the addEventListener() method potentially reduces application startup time and memory usage.

The following example registers an event handler for the Panel container, rather than registering a listener for each link. All children of the Panel container inherit this event handler. Since Flex invokes the handler on a bubbled event, you use the target property rather than the currentTarget property. In this handler, the currentTarget property would refer to the Panel control, whereas the target property refers to the LinkButton control, which has the label that you want.

<?xml version="1.0"?> 
<!-- events/SingleRegisterHandler.mxml --> 
<s:Application     xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="createLinkHandler();"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        private function linkHandler(event:MouseEvent):void { 
            try { 
                var url:URLRequest = new URLRequest("http://finance.google.com/finance?q=" + 
                event.target.label); 
                navigateToURL(url); 
            } catch (e:Error) { 
                /** 
                 *  Do nothing; just want to catch the error that occurs when a user clicks on 
                 *  the Panel and not one of the LinkButtons. 
                 **/                
            } 
        } 
        private function createLinkHandler():void { 
            p1.addEventListener(MouseEvent.CLICK,linkHandler); 
        } 
        ]]> 
    </fx:Script> 
    
    <s:Panel id="p1" title="Click on a stock ticker symbol"> 
        <s:layout> 
            <s:HorizontalLayout/> 
        </s:layout> 
        <mx:LinkButton label="ADBE"/> 
        <mx:LinkButton label="GE"/> 
        <mx:LinkButton label="IBM"/> 
        <mx:LinkButton label="INTC"/> 
    </s:Panel> 
</s:Application>

In some cases, you want to trap keys globally, meaning no matter where the user is in the application, their keystrokes are recognized by the application and the action is performed. Flex recognizes global keyboard events whether the user is hovering over a button or the focus is inside a TextInput control.

A common way to handle global key presses is to create a listener for the KeyboardEvent.KEY_DOWN or KeyboardEvent.KEY_UP event on the application. Listeners on the application container are triggered every time a key is pressed, regardless of where the focus is (as long as the focus is in the application on not in the browser controls or outside of the browser). Inside the handler, you can examine the key code or the character code using the charCode and keyCode properties of the KeyboardEvent class, as the following example shows:

<?xml version="1.0"?> 
<!-- events/TrapAllKeys.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="initApp();"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        import mx.core.FlexGlobals; 
        
        private function initApp():void { 
            FlexGlobals.topLevelApplication.addEventListener(KeyboardEvent.KEY_UP, keyHandler); 
        } 
 
        private function keyHandler(event:KeyboardEvent):void { 
            t1.text = event.keyCode + "/" + event.charCode; 
        } 
        ]]> 
    </fx:Script> 
 
    <s:TextInput id="myTextInput"/> 
    
    <s:Label id="t1"/> 
 
</s:Application>

To run this example, you must first set the focus to something inside the application, such as the TextInput control, by clicking on it.

Because any class that extends UIComponent dispatches the keyUp and keyDown events, you can also trap keys pressed when the focus is on an individual component.

You can access the keyCode and charCode properties to determine what key was pressed and trigger other actions as a result. The keyCode property is a numeric value that corresponds to the value of a key on the keyboard. The charCode property is the numeric value of that key in the current character set (the default character set is UTF-8, which supports ASCII). The primary difference between the key code and character values is that a key code value represents a particular key on the keyboard (the 1 on a keypad is different than the 1 in the top row, but the 1 on the keyboard and the key that generates the ! are the same key), and the character value represents a particular character (the R and r characters are different).

The mappings between keys and key codes are device and operating system dependent. ASCII values, on the other hand, are available in the ActionScript documentation.

The following example shows the character and key code values for the keys you press. When you run this example, you must be sure to put the focus in the application before beginning.

<?xml version="1.0"?> 
<!-- charts/ShowCharAndKeyCodes.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="init()" 
    width="650"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
  <fx:Script><![CDATA[ 
     import flash.events.KeyboardEvent; 
 
     private function init():void { 
        ti1.setFocus(); 
        this.addEventListener(KeyboardEvent.KEY_DOWN, trapKeys); 
     } 
            
     private function trapKeys(e:KeyboardEvent):void { 
        ta1.text = String(e.toString()); 
        
        l1.text = numToChar(e.charCode) + " (" + String(e.charCode) + ")"; 
        l2.text = numToChar(e.keyCode) + " (" + String(e.keyCode) + ")"; 
     } 
    
    private function numToChar(num:int):String { 
        if (num > 47 && num < 58) { 
            var strNums:String = "0123456789"; 
            return strNums.charAt(num - 48); 
        } else if (num > 64 && num < 91) { 
            var strCaps:String = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"; 
            return strCaps.charAt(num - 65); 
        } else if (num > 96 && num < 123) { 
            var strLow:String = "abcdefghijklmnopqrstuvwxyz"; 
            return strLow.charAt(num - 97); 
        } else { 
            return num.toString(); 
        } 
    }        
  ]]></fx:Script> 
 
  <s:TextInput width="50%" id="ti1"/> 
  
  <s:Panel id="mainPanel" width="100%" height="100%"> 
     <s:Form> 
        <s:FormItem label="Char (Code)"> 
           <s:Label id="l1"/> 
        </s:FormItem> 
        <s:FormItem label="Key (Code)"> 
           <s:Label id="l2"/> 
        </s:FormItem> 
        <s:FormItem label="Key Event"> 
           <s:TextArea id="ta1" width="500" height="200" editable="false"/> 
        </s:FormItem> 
     </s:Form> 
  </s:Panel>      
                
</s:Application>

You can listen for specific keys or combinations of keys by using a conditional operator in the KeyboardEvent handler. The following example listens for the combination of the Shift key plus the q key and prompts the user to close the browser window if they press those keys at the same time:

<?xml version="1.0"?> 
<!-- events/TrapQKey.mxml --> 
<s:Application     
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="initApp();"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        import mx.core.FlexGlobals; 
        
        private function initApp():void { 
            FlexGlobals.topLevelApplication.addEventListener(KeyboardEvent.KEY_UP,keyHandler); 
            
            // Set the focus somewhere inside the application. 
            ta1.setFocus(); 
        } 
 
        //This function quits the application if the user presses Shift+Q. 
        private function keyHandler(event:KeyboardEvent):void { 
            var bShiftPressed:Boolean = event.shiftKey; 
            if (bShiftPressed) { 
                var curKeyCode:int = event.keyCode; 
                if (curKeyCode == 81) { // 81 is the keycode value for the Q key 
 
                    /* Quit the application by closing the browser using JavaScript. 
                       This may not work in all browsers. */ 
                    var url:URLRequest = new 
                    URLRequest("javascript:window.close()"); 
                    navigateToURL(url,"_self");             
                } 
            } 
        } 
        ]]> 
    </fx:Script> 
 
    <s:TextArea id="ta1" text="Focus here so that Shift+Q will quit the browser."/> 
 
</s:Application>

Notice that this application must have focus when you run it in a browser so that the application can capture keyboard events.

If you define keyUp or keyDown event listeners for both a control and its parent, you will notice that the keyboard event is dispatched for each component because the event bubbles. The only difference is that the currentTarget property of the KeyboardEvent object is changed.

In the following example, the application, the my_vgroup container, and the my_textinput control all dispatch keyUp events to the keyHandler() event listener function:

<?xml version="1.0"?> 
<!-- events/KeyboardEventPrecedence.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="initApp();" 
    width="650"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script><![CDATA[ 
        import mx.core.FlexGlobals; 
    
        private function initApp():void { 
            FlexGlobals.topLevelApplication.addEventListener(KeyboardEvent.KEY_UP, keyHandler); 
            my_vgroup.addEventListener(KeyboardEvent.KEY_UP, keyHandler); 
            my_textinput.addEventListener(KeyboardEvent.KEY_UP, keyHandler); 
 
            // Set the focus somewhere inside the application. 
            my_textinput.setFocus(); 
        } 
 
        private function keyHandler(event:KeyboardEvent):void { 
            ta1.text += event.target + "(" + event.currentTarget + "): " + 
                event.keyCode + "/" + event.charCode + "\n"; 
        } 
    ]]></fx:Script> 
    
    <s:VGroup id="my_vgroup"> 
        <s:TextInput id="my_textinput"/> 
    </s:VGroup> 
 
    <s:TextArea id="ta1" height="300" width="550"/> 
 
</s:Application>

When you examine the output, you will notice that the target property of the KeyboardEvent object stays the same because it refers to the original dispatcher of the event (in this case, my_textinput). But the currentTarget property changes depending on what the current node is during the bubbling (in this case, it changes from my_textinput to my_vgroup to the application itself).

The order of calls to the event listener is determined by the object hierarchy and not the order in which the addEventListener() methods were called. Child controls dispatch events before their parents. In this example, for each key pressed, the TextInput control dispatches the event first, the VGroup container next, and finally the application.

When handling a key or key combination that the underlying operating system or browser recognizes, the operating system or browser generally processes the event first. For example, in Microsoft Internet Explorer, pressing Control+w closes the browser window. If you trap that combination in your application, Internet Explorer users never know it, because the browser closes before the ActiveX Flash Player has a chance to react to the event.

The MouseEvent class and all MouseEvent subclasses (such as ChartItemEvent, DragEvent, and LegendMouseEvent) have the following properties that you can use to determine if a specific key was held down when the event occurred:

The following example deletes Button controls, based on whether the user holds down the Shift key while pressing the mouse button:

<?xml version="1.0"?> 
<!-- events/DetectingShiftClicks.mxml --> 
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="initApp();"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script><![CDATA[ 
        import spark.components.Button; 
 
        private function initApp():void { 
            var b1:Button = new Button(); 
            b1.label = "Button 1"; 
 
            var b2:Button = new Button(); 
            b2.label = "Button 2";        
            b1.addEventListener(MouseEvent.CLICK, removeButtons); 
            b2.addEventListener(MouseEvent.CLICK, removeButtons); 
 
            vg1.addElement(b1); 
            vg1.addElement(b2); 
        } 
 
        private function removeButtons(event:MouseEvent):void { 
            if (event.shiftKey) { 
                vg1.removeElement(Button(event.currentTarget)); 
            } else { 
                event.currentTarget.toolTip = "Shift+click to remove this button.";  
            } 
        } 
    ]]></fx:Script> 
 
    <s:VGroup id="vg1"/> 
    
    <s:Button id="resetButton" label="Reset" click="initApp();"/> 
 
</s:Application>