Flex Event Tips

Event Reference： http://www.w3.org/TR/DOM-Level-3-Events/events.html

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.

addEventListener() useCapture parameter -- If useCapture  is set to true  , the listener processes the event only during the capture phase and not in the target or bubbling phase. If useCapture  is false  , the listener processes the event only during the target or bubbling phase.  To listen for the event in all three phases, call addEventListener  twice, once with useCapture  set to true  , then again with useCapture  set to false  .

You can remove only event listeners that you added with the addEventListener() method in an ActionScript block. You cannot remove an event listener that was defined in the MXML tag, even if it was registered using a call to the addEventListener() method that was made inside a tag attribute.

During each of these phases, the nodes have a chance to react to the event. For example, assume the user clicks a Button control that is inside a VBox container. During the capturing phase, Flex checks the Application object and the VBox for listeners to handle the event. Flex then triggers the Button's listeners in the target phase. In the bubbling phase, the VBox and then the Application are again given a chance to handle the event but now in the reverse order from the order in which they were checked in the capturing phase.

Detecting the event phase
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)
    
Capturing phase
In the capturing phase, Flex examines an event'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.
    
Targeting phase

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.

Bubbling phase

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.

   
The following example displays the current phase and current target's ID:
<?xml version="1.0"?>
<!-- events/DisplayCurrentTargetInfo.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script><![CDATA[
        import mx.controls.Alert;

        private function showInfo(e:MouseEvent):void {
            Alert.show("Phase: " + e.eventPhase + "/n" +
                "Current Target: " + e.currentTarget.id);
        }
    ]]></mx:Script>

    <mx:Button id="b1"
        label="Click Me"
        click="showInfo(event)"
    />

</mx:Application>

Stopping propagation
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()
    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.
    
Event priorities
<?xml version="1.0"?>
<!-- events/ShowEventPriorities.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initApp()">
    <mx:Script><![CDATA[
        private function returnResult(e:Event):void {
            ta1.text += "returnResult() method called last (priority 1)/n";  
        }
        private function verifyInputData(e:Event):void {
            ta1.text += "verifyInputData() method called first (priority 3)/n";  
        }
        private function saveInputData(e:Event):void {
            ta1.text += "saveInputData() method called second (priority 2)/n";  
        }
        private function initApp():void {
            b1.addEventListener(MouseEvent.CLICK, returnResult, false, 1);
            b1.addEventListener(MouseEvent.CLICK, saveInputData, false, 2);
            b1.addEventListener(MouseEvent.CLICK, verifyInputData, false, 3);
        }
    ]]></mx:Script>
    <mx:Button id="b1" label="Click Me"/>   
    <mx:TextArea id="ta1" height="200" width="300"/>   
</mx:Application>
You can set the event priority to any valid integer, positive or negative. The default value is 0. If multiple listeners have the same priority, Flex calls them in the order in which they were registered.
If you want to change the priority of an event listener once the event listener has already been defined, you must remove the listener by calling the removeEventListener() method. You add the event again with the new priority.

The useWeakReference parameter allows you to specify whether the reference to the listener function is weak or normal. Setting this parameter to true allows you to avoid situations in which listener functions persist in memory even though they are no longer needed. Flash Player and AIR use a technique called garbage collection to clear objects from memory that are no longer in use. An object is considered no longer in use if no references to it exist. The garbage collector disregards weak references, which means that a listener function that has only a weak reference pointing to it is eligible for garbage collection.

One important consequence of this parameter involves working with display objects' events. Normally, you might expect a display object to be removed from memory when it is removed from the display list. However, if other objects have subscribed as listeners to that display object, with the useWeakReference parameter set to false (the default), the display object will continue to exist in Flash Player's or AIR's memory even though it no longer appears on the screen. To work around this issue, either have all the listeners subscribe to the display object with the useWeakReference parameter set to true, or else remove all the event listeners from the display object using the removeEventListener() method.