ActionScript Article

Introduction to event handling in ActionScript 3.0

Event propagation and phases

Although you might not have realized it in the previous example, the event that took place as a result of the box being clicked actually affects many different objects, not just the object being clicked. The big, new feature in ActionScript 3.0 event handling is the support for event propagation—the transference of a single event applying to multiple objects. Each of those objects receives the event, instead of just the object in which the event originated.

With ActionScript 2.0, there was no such thing as event propagation. In fact, you couldn't even have objects with certain event handlers associated with them inside another object that had its own event handler. For example, in ActionScript 2.0, if you were to assign an onPress event handler to a window object that had a button within it, any onPress (or similar) event handlers assigned to the button would not function and receive events. With ActionScript 3.0, you no longer have that issue. Instead, you have events that propagate through instances and their parents.

With event propagation you're dealing with three "phases" of an event (see Figure 2). Each phase represents a path or the location of an event as it works itself through the display objects in Flash that relate to that event. The three phases of an event are capturing, at target, and bubbling:

• Capturing phase: This represents the parent objects of the target object from which the event originated. Any propagated event starts with the topmost parent (stage) and works down the display object hierarchy until reaching the original target.
• At target phase: The target phase is the phase where the event is at the target object or the object from which the event originated. Unlike the capturing and bubbling phases, this phase always relates to only one object, the target object.
• Bubbling phase: When an event "bubbles" it follows the reverse path of the capturing phase and works its way back up the parent hierarchy of the target object until reaching the top-most parent or stage.

Not all propagated events (and not all events propagate) go through each phase, however. If the Stage object, for example, receives an event, there will only be an at target phase since there are no objects beyond the stage for the capturing or bubbling phases to take place.

Figure 2. Diagram of three event phases that occur when clicking the box

Note: The hierarchy in Flex is a little different because it contains the Application instance between root and the box Canvas instance (not shown).

As the event makes its way though each phase and each object within those phases, it calls all of the listener functions that were added for that event. This means that clicking on the box doesn't limit the event to the box; the stage also receives the event. The stage receives the event twice, once in the capturing phase and once in the bubbling phase (see Figure 3).

Figure 3. Event path that occurs when clicking the box

You can see how this all works more clearly by adding more listeners to our example.

Example 2: One box, many listeners

To see how a single mouse click propagates through many objects within the display list hierarchy, you can add additional listeners to receive the event for each of those objects it affects. For this example, however, we'll want to have listeners for all phases of the event. For this we need to make use of the third parameter in addEventListener, the useCapture parameter.

The useCapture parameter in addEventListener lets you specify whether or not a listener should be listening in the capture phase. If not, it will be listening for the event in the at target or bubbling phases. The default value of false sets a listener to listen to the at target and bubbling phases. By passing in a true value, you can listen to events in the capture phase. If you want an event to listen for an event in all phases, you simply use addEventListener twice, once with useCapture set to false (or omitted) and once with useCapture set to true.

In this example (see Figure 4) we will add listeners for stage, root, and box. For stage and root we will be adding event listeners that alternately use and don't use the useCapture parameter.

Figure 4. Clicking the box propagates the events throughout all specified listeners for all phases

Using Flash CS3 Professional

1. Open Example 1.

2. Replace the timeline script in Frame 1 with the following:

   function boxClick(event:MouseEvent):void {
      trace("box click");
   }
   function rootClick(event:MouseEvent):void {
      trace("root click");
   }
   function stageClick(event:MouseEvent):void {
      trace("stage click");
   }
   
   box.addEventListener(MouseEvent.CLICK, boxClick);
   root.addEventListener(MouseEvent.CLICK, rootClick);
   root.addEventListener(MouseEvent.CLICK, rootClick, true);
   stage.addEventListener(MouseEvent.CLICK, stageClick);
   stage.addEventListener(MouseEvent.CLICK, stageClick, true);
   

Using Flex 3

1. Create a new Flex MXML document (or edit Example 1).

2. Use the following MXML:

   <?xml version="1.0" encoding="utf-8"?>
   <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
               applicationComplete="initApp()">
      <mx:Script>
         <![CDATA[
            public function boxClick(event:MouseEvent):void {
               trace("box click");
            }
            public function rootClick(event:MouseEvent):void {
               trace("root click");
            }
            public function stageClick(event:MouseEvent):void {
               trace("stage click");
            }
   
            public function initApp():void {
               box.addEventListener(MouseEvent.CLICK, boxClick);
               root.addEventListener(MouseEvent.CLICK, rootClick);
               root.addEventListener(MouseEvent.CLICK, rootClick, true);
               stage.addEventListener(MouseEvent.CLICK, stageClick);
               stage.addEventListener(MouseEvent.CLICK, stageClick, true);
            }
         ]]>
      </mx:Script>
      
      <mx:Canvas id="box" width="200" height="200" backgroundColor="#800000">
      </mx:Canvas>
      
   </mx:Application>
   

Note: Be sure to use the applicationComplete event in Flex to assure access to stage and root within the Application script. The stage and root will not be accessible in the creationComplete event.

Test this movie and click around to see the results. Clicking on the box should give you the following output:

stage click
root click
box click
root click
stage click

The output shows how both the stage and root objects received the event twice—one time each in the capturing and bubbling phases of the event. In contrast, the target of the event, the box, received the event only once in the at target phase. Try clicking anywhere off of the box (on the stage) and, if you are using Flash, you get an output of:

stage click

Because the stage is at the top of the hierarchy in the Flash movie, the only phase of a stage-based event is at target.

In Flex, when clicking the stage, you will get an output that looks more like this:

stage click
root click
root click
stage click

This is a result of the intermediate application instance (Application.application) containing the gradient background encompassing the entire area of the stage. By clicking the stage you're actually clicking this instance—which has no listeners—instead of the stage itself. If the intermediate application instance is not present, only the stage listener will be called.

Though event propagation is most prevalent in mouse events, it also occurs in other events such as keyboard events. Event propagation is also used in the added and removed events in DisplayObjectContainer instances, where child objects are added or removed from their display lists.

Page 3 of 8

Previous Page

Next Page