If a user clicks on Child1 Node , Flash Player dispatches an event object into the event flow.
As the following image shows, the object’s journey starts at Stage , moves down to Parent
Node , then moves to Child1 Node, and then “bubbles” back up to Stage , moving through
Parent Node again on its journey back to Stage .
Stage
Capture
Phase
Parent Node
Bubbling
Phase
Child1 Node Child2 Node
Target Phase
In this example, the capture phase comprises Stage and Parent Node during the initial downward journey. The target phase comprises the time spent at Child1 Node . The bubbling phase comprises Parent Node and Stage as they are encountered during the upward journey back to the root node.
The event flow contributes to a more powerful event handling system than that previously available to ActionScript programmers. In previous versions of ActionScript, the event flow does not exist, which means that event listeners can be added only to the object that generates the event. In ActionScript 3.0, you can add event listeners not only to a target node, but also to any node along the event flow.
The ability to add event listeners along the event flow is useful when a user interface component comprises more than one object. For example, a button object often contains a text object that serves as the button’s label. Without the ability to add a listener to the event flow, you would have to add a listener to both the button object and the text object to ensure that you receive notification about click events that occur anywhere on the button. The existence of the event flow, however, allows you to place a single event listener on the button object that handles click events that occur either on the text object or on the areas of the button object that are not obscured by the text object.
Not every event object, however, participates in all three phases of the event flow. Some types of events, such as the enterFrame and init event types, are dispatched directly to the target node and participate in neither the capture phase nor the bubbling phase. Other events may target objects that are not on the display list, such as events dispatched to an instance of the
Socket class. These event objects will also flow directly to the target object, without participating in the capture and bubbling phases.
The event flow 351
To find out how a particular event type behaves, you can either check the API documentation or examine the event object's properties. Examining the event object’s properties is described in the following section.
Event objects
Event objects serve two main purposes in the new event handling system. First, event objects represent actual events by storing information about specific events in a set of properties.
Second, event objects contain a set of methods that allow you to manipulate event objects and affect the behavior of the event handling system.
To facilitate access to these properties and methods, the Flash Player API defines an Event class that serves as the base class for all event objects. The Event class defines a fundamental set of properties and methods that are common to all event objects.
This section begins with a discussion of the Event class properties, continues with a description of the Event class methods, and concludes with an explanation of why subclasses of the Event class exist.
Understanding Event class properties
The Event class defines a number of read-only properties and constants that provide important information about an event object.The following are especially important:
■
■
■
Event object types are represented by constants and stored in the Event.type
property.
Whether an event’s default behavior can be prevented is represented by a Boolean value and stored in the Event.cancelable
property.
Event flow information is contained in the remaining properties.
Event object types
Every event object has an associated event type. Event types are stored in the Event.type
property as string values. It is useful to know the type of an event object so that your code can distinguish objects of different types from one another. For example, the following code specifies that the clickHandler() listener function should respond to any mouse click event objects that are passed to myDisplayObject : myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);
352 Handling Events
Some two dozen event types are associated with the Event class itself and are represented by
Event class constants, some of which are shown in the following excerpt from the Event class definition: package flash.events
{ public class Event
{
// class constants public static const ACTIVATE:String = "activate"; public static const ADDED:String = "added";
// remaining constants omitted for brevity
}
}
These constants provide an easy way to refer to specific event types. You should use these constants instead of the strings they represent. If you misspell a constant name in your code, the compiler will catch the mistake, but if you instead use strings, a typographical error may not manifest at compile time and could lead to unexpected behavior that could be difficult to debug. For example, when adding an event listener, use the following code: myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler); rather than: myDisplayObject.addEventListener("click", clickHandler);
Default behavior information
Your code can check whether the default behavior for any given event object can be prevented by accessing the cancelable property. The cancelable property holds a Boolean value that indicates whether or not a default behavior can be prevented. You can prevent, or cancel, the default behavior associated with a small number of events using the preventDefault() method. For more information, see “Cancelling default event behavior” on page 356 .
Event flow information
The remaining Event class properties contain important information about an event object and its relationship to the event flow, as described in the following list:
■
■
■
■
The bubbles property contains information about the parts of the event flow in which the event object participates.
The eventPhase property indicates the current phase in the event flow.
The target property stores a reference to the event target.
The currentTarget property stores a reference to the display list object that is currently processing the event object.
Event objects 353
The bubbles property
An event is said to bubble if its event object participates in the bubbling phase of the event flow, which means that the event object is passed from the target node back through its ancestors until it reaches the Stage. The Event.bubbles
property stores a Boolean value that indicates whether the event object participates in the bubbling phase. Because all events that bubble also participate in the capture and target phases, any event that bubbles participates in all three of the event flow phases. If the value is true , the event object participates in all three phases. If the value is false , the event object does not participate in the bubbling phase.
The eventPhase property
You can determine the event phase for any event object by investigating its eventPhase property. The eventPhase property contains an unsigned integer value that represents one of the three phases of the event flow. The Flash Player API defines a separate EventPhase class that contains three constants that correspond to the three unsigned integer values, as shown in the following code excerpt: package flash.events
{
public final class EventPhase
{
public static const CAPTURING_PHASE:uint = 1;
public static const AT_TARGET:uint = 2;
public static const BUBBLING_PHASE:uint = 3;
}
}
These constants correspond to the three valid values of the eventPhase property. You can use these constants to make your code more readable. For example, if you want to ensure that a function named myFunc() is called only if the event target is in the target stage, you can use the following code to test for this condition: if (e.eventPhase == EventPhase.AT_TARGET)
{ myFunc();
}
The target property
The target property holds a reference to the object that is the target of the event. In some cases, this is straightforward, such as when a microphone becomes active, the target of the event object is the Microphone object. If the target is on the display list, however, the display list hierarchy must be taken into account. For example, if a user inputs a mouse click on a point that includes overlapping display list objects, Flash Player always chooses the object that is farthest away from the Stage as the event target.
354 Handling Events
For complex SWF files, especially those in which buttons are routinely decorated with smaller child objects, the target property may not be used frequently because it will often point to a button’s child object instead of the button. In these situations, the common practice is to add event listeners to the button and use the currentTarget property because it points to the button, whereas the target property may point to a child of the button.
The currentTarget property
The currentTarget property contains a reference to the object that is currently processing the event object. Although it may seem odd not to know which node is currently processing the event object that you are examining, keep in mind that you can add a listener function to any display object in that event object's event flow, and the listener function can be placed in any location. Moreover, the same listener function can be added to different display objects.
As a project increases in size and complexity, the currentTarget property becomes more and more useful.
Understanding Event class methods
There are three categories of Event class methods:
■
■
■
Utility methods, which can create copies of an event object or convert it to a string
Event flow methods, which remove event objects from the event flow
Default behavior methods, which prevent default behavior or check whether it has been prevented
Event class utility methods
There are two utility methods in the Event class. The clone() method allows you to create copies of an event object. The toString() method allows you to generate a string representation of the properties of an event object along with their values. Both of these methods are used internally by the event model system, but are exposed to developers for general use.
For advanced developers creating subclasses of the Event class, you must override and implement versions of both utility methods to ensure that the event subclass will work properly.
Event objects 355
