Event priorities

You can register any number of event listeners with a single event. Flex registers event listeners in the order in which the addEventListener() methods are called. Flex then typically calls the listener functions when the event occurs in the order in which they were registered. However, if you register some event listeners inline and some with the addEventListener() method, the order in which the listeners are called for a single event can be unpredictable.

You can change the order in which Flex calls event listeners by using the priority parameter of the addEventListener() method. It is the fourth argument of the addEventListener() method.

Flex calls event listeners in priority order, from highest to lowest. The highest priority event is called first. In the following example, Flex calls the verifyInputData() method before the saveInputData() function. The verifyInputData() method has the highest priority. The last method to be called is returnResult() because the value of its priority parameter is lowest.

<?xml version="1.0"?>
<!-- events/ShowEventPriorities.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[
        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);
        }
        ]]>
    </fx:Script>

    <s:Button id="b1" label="Click Me"/>
    
    <s:TextArea id="ta1" height="200" width="300"/>
    
</s:Application>

The executing SWF file for the previous example is shown below:

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 typically calls them in the order in which they were registered, although the order is not guaranteed.

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 priority parameter of the addEventListener() method is not an official part of the DOM Level 3 events model. ActionScript 3.0 provides it so that programmers can be more flexible when organizing their event listeners.

If your listeners rely on a specific order of execution, you can call one listener function from within another, or dispatch a new event from within the first event listener. For more information on manually dispatching events, see Manually dispatching events.