Working with events

The following sections describe the standardized event handling model in ActionScript 3.0.

All events are handled the same way

Events have evolved in ActionScript 3.0. The event handling metaphor common to ActionScript 2.0 components has become part of all display objects in ActionScript 3.0. The big picture is that all objects in ActionScript now share a common event model. Along with standardization in ActionScript 3.0 comes a few changes to how event handler functions work. In the new model, the addEventListener method expects a function reference for the listener instead of an object or a function reference. In ActionScript 2.0 it was common to use an object as a container for a number of event handler functions, but in ActionScript 3.0 listeners appear as functions per event or as functions containing switch statements to handle multiple events.

The following code illustrates how a mouse event handler is assigned to a button:

import flash.events.MouseEvent;
 
function clickHandler(event:MouseEvent):void
{
   // Handle event here...
}
my_btn.addEventListener(MouseEvent.CLICK, clickHandler);

The code above first imports the MouseEvent class for data typing. The clickHandler function is the event handler that responds to the event notification. The addEventListener method registers the event handler with the object broadcasting the event.

Some events flow through the display list

Events for visual objects residing on the display list flow through the display list on the way to the target object. There are three phases to event propagation, and these phases allow objects other than the target object to receive the event. For example, consider a button in a movie clip on the main Timeline. If you click that button, the CLICK event travels from the Stage through the movie clip to the button, and then back up through the movie clip to the Stage. This structure allows you to place the listener on the button (in which case you'll just receive an event from the button) or on the movie clip container (which would allow you to receive the event from any number of buttons within the container). You could also place the listener on the Stage and receive CLICK events from anywhere in the movie. Being able to listen for events in this way opens up many possibilities for handling the event flow.

When setting up initialization code that requires access to the display list, you can use the ADDED_TO_STAGE event to perform the initialization at the correct time. For example:

import flash.event.Event;
 
function adddedToStageHandler(event:Event):void
{
   // Initialization code goes here...
}
addEventListener(Event.ADDED_TO_STAGE, addedToStageHandler);

Remember you might not always add the object to the display list immediately after instantiating it. Using the code above will allow you to initialize using the Stage without causing timing errors.

Using the currentTarget event property and target event property

The event handler function receives an event object with information about the event. In the ActionScript 2.0 component event structure you could always count on the target property as being a reference back to the object which broadcast the event. In ActionScript 3.0, the target property of the event object may not reference that object.

I found that assigning my listener directly to the target object and using the currentTarget event property is the most reliable way to work with the structures I'm building; for example:

import flash.events.MouseEvent;
 
function clickHandler(event:MouseEvent):void
{
   // Do something on click...
   switch(event.currentTarget)
   {
   case my_btn1:
      // do something...
      Break;
   case my_btn2:
      // do something...
      Break;
   case my_btn3:
      // do something...
      Break;
   }
}
my_btn1.addEventListener(MouseEvent.CLICK, clickHandler);
my_btn2.addEventListener(MouseEvent.CLICK, clickHandler);
my_btn3.addEventListener(MouseEvent.CLICK, clickHandler);

If you want to use the target property instead of currentTarget, be sure to notice the extra parameters associated with the addEventListener method. I discovered with ActionScript 3.0 that the target property was sometimes empty because the event system was deleting the reference to the target before it was sent to my event handler. To resolve this issue I changed the garbage-collection settings by adjusting the optional parameters that appear at the end of the addEventListener method. For example:

import flash.events.MouseEvent;
 
function clickHandler(event:MouseEvent):void
{
   // Do something on click...
   switch(event.target)
   {
   case my_btn1:
      // do something...
      Break;
   case my_btn2:
      // do something...
      Break;
   case my_btn3:
      // do something...
      Break;
   }
}
addEventListener(MouseEvent.CLICK,clickHandler,false,0,true);

The last parameter is useWeakReference, and in the code above it is set to true. A strong reference prevents the listener from being garbage-collected. Therefore, setting this parameter to false causes the event system to not garbage-collect the reference to the event's target.

Page 3 of 6

Previous Page

Next Page