flash propagation_target_phase

The target phase corresponds to the broadcast of the event from the target object. Certain events associated with graphic objects only participate in this phase.

It is the case of the four following events which don’t participate in the capture phase or the bubbling phase:

• Event.ENTER_FRAME
• Event.ACTIVATE
• Event.DEACTIVATE
• Event.RENDER

We will take the previous example but this time we will look at the target phase rather than the capture phase:

In order to listen to the MouseEvent.CLICK event we subscribe a listener to each instance of the Window class:

// number of windows
var lng:int = 12;
// creation of a container
var containerWindows:Sprite = new Sprite();
// add to the display list
addChild ( containerWindows );
var myWindow:Window;
for (var i:int = 0; i< lng; i++ )
{
myWindow = new Window();
// subscription to each instance for the target phase
myWindow.addEventListener ( MouseEvent.CLICK, clickWindow );
myWindow.x = 7 + Math.round ( i % 3 ) * ( myWindow.width + 10 );
myWindow.y = 7 + Math.floor ( i / 3 ) * ( myWindow.height + 10 );
containerWindows.addChild ( myWindow );
}
function clickWindow ( pEvt:MouseEvent ):void
{
// displays : [object Window]
trace( pEvt.target );
}

When clicked, the event starts its propagation then maintains the target object, our clickWindow listener window is triggered.

When we call the addEventListener method without specifying the useCapture parameter, we subscribe the listener to the target phase as well as the bubbling phase.

If we display the content of the target property of the event object, it returns a reference to the target object, in this case our Window.

To delete each instance, we add the instruction removeChild to our listener function by passing the object referenced by the target property of the event object:

function clickWindow ( pEvt:MouseEvent ):void
{
// the instance of the clicked window is deleted from the display
containerWindows.removeChild ( DisplayObject ( pEvt.target ) );
// unsubscription of the function clickWindow to the event
// MouseEvent.CLICK
pEvt.target.removeEventListener ( MouseEvent.CLICK, clickWindow );
}

It is important to note that during the target phase the target object is also the broadcaster of the event.

By testing the following code we see that the target and currentTarget properties of the event object references the same graphic object:

function clickWindow ( pEvt:MouseEvent ):void
{
// displays : true
trace( pEvt.target == pEvt.currentTarget );
// the instance of the clicked window is deleted from the display
containerWindows.removeChild ( DisplayObject ( pEvt.target ) );
// unsubscription of the function clickWindow to the event
// MouseEvent.CLICK
pEvt.target.removeEventListener ( MouseEvent.CLICK, clickWindow );
}

To test if the broadcasted event is resulting from the target phase we can compare the eventPhase property of the event object to the EventPhase.AT_TARGET constant:

function clickWindow ( pEvt:MouseEvent ):void
{
// displays : true
trace( pEvt.target == pEvt.currentTarget );
// displays : TARGET PHASE
if ( pEvt.eventPhase == EventPhase.AT_TARGET )
{
trace("TARGET PHASE");
}
// the instance of the clicked window is deleted from the display
containerWindows.removeChild ( DisplayObject ( pEvt.target ) );
// unsubscription of the function clickWindow to the event
// MouseEvent.CLICK
pEvt.target.removeEventListener ( MouseEvent.CLICK, clickWindow );
}

By using the target phase we have lost flexibility in subscribing the clickWindow listener function to each instance of the Window class and in managing the un-subscription of listeners during the deletion of the display list.

The capture phase should not be and cannot be systematically used. By using the target phase we can save a listener function to a unique button, which is paramount when the associated logic to each button is radically different. Even though it is useful in certain cases, the capture phase intercepts the clicks of each button by executing a single listener function which can prove to be limiting in certain situations.

Each phase should therefore be used when the situation requires it.

Worth remembering

• The target phase corresponds to the broadcast of the event by the target object.
• The graphic objects broadcast events which are able to be propagated.
• The non-graphic objects broadcast events which only take part in the target phase.
• It is worth looking at the stacking of graphic objects in the application and to use the most suitable phase for our needs.

ActionScript 3 also offers the possibility of intervening in the propagation of an event. This functionality can be useful when we want to prevent an event reaching the target object by halting the continuation of its proagation.

In the next article we will now look at how to use this new idea with a concrete example.