User Guide

354 Handling Events
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.