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>
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.
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);