Programming Flex 3

Handling Events

ActionScript 3.0 and the Flex framework use events to notify and receive notification when things occur. Events occur in response to the user (e.g., the user clicks on something), time (timer events), and asynchronous messaging (such as remote procedure calls). Regardless of the cause of an event, nearly all ActionScript events use the same event model.

In Chapter 3, you saw how to use event handler attributes. In ActionScript, you can handle events by registering listeners. A listener is a function or method that should receive notifications when an event is dispatched. For example, you can register a method to receive a notification when the user clicks a button.

You need at least two elements to register a listener: an object that dispatches events, and a function that listens for events. Objects capable of dispatching events either extend the flash.events.EventDispatcher class or implement the flash.events.IEventDispatcher interface. When an object can dispatch events, it has a public addEventListener() method that requires at least two parameters: the name of the event for which you want to listen and the function/method that should listen for the event.

object.addEventListener("eventName", listenerFunction);

In most cases, the event names are stored in constants of the corresponding event type class. For example, the click event name is stored in the MouseEvent.CLICK constant.

The listener function must expect one parameter of type mx.events.Event or the relevant subclass of Event. For example, if the object dispatches an event of type MouseEvent, the listener should accept a MouseEvent parameter. The event parameter contains information about the event that occurred, including a reference to the object dispatching the event (the target property of the event object) and the object that most recently bubbled (relayed) the event (the currentTarget property). (In many cases, the target and currentTarget properties reference the same object.) The following example adds an event listener using ActionScript, and when the user clicks the button, the listener displays the event object in an alert dialog box:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
initialize="initializeHandler(event)">
  <mx:Script>
    <![CDATA[

      import mx.controls.Alert;

      private function initializeHandler(event:Event):void {
        button.addEventListener(MouseEvent.CLICK, clickHandler);
      }

      private function clickHandler(event:MouseEvent):void {
        Alert.show("Event: " + event.type + " with target: " + event.target);
      }

    ]]>
  </mx:Script>

  <mx:Button id="button" />

</mx:Application>

Note

In the preceding example, you may notice that clickHandler() is defined such that it expects a MouseEvent parameter. When you register an event handler method using the addEventListener() method, the event handler method will always be passed an Event parameter (or a subclass of Event, as in this example).

You can also unregister an event listener using the removeEventListener() method. This method requires the same parameters as addEventListener(). The method unregisters the specified listener function as a listener for the specified event.

Note

It is extremely important that you remove event listeners when they are no longer necessary. This includes all cases where you want to remove from memory the object listening for the events. Flash Player will not garbage-collect an object if there are any references to it still in memory. That means that even if an object is no longer used anywhere in the application, except for a reference held by an event dispatcher, it will not be garbage-collected.

The following example removes the event listener added in the previous example:

button.removeEventListener(MouseEvent.CLICK, onClick);