Previous part of AS3 Event Handling series was about creating custom event class. In this part we will look at the one of the mostly unused parameters in addEventListener method handler.
addEventListener is the method used to add an listener to an object for a specified event. Hence we usually pass two parameters ( first one is the event name and second event handler name) and everything works perfectly. But if you need more control over the event flow you may be interested in the other parameters available. The other three parameters are useCapture, priority & useWeakReference. We will discuss about the first one in this part.
useCapture
This parameter tells about processing of event object in the phases of the event propagation. The default value is false, means event object can provide information about the target phase and the bubbling phase and not about the capture phase.
To understand the exact behaviour let’s create one small flash file and write some code. Open an AS3 flash document and create one big rectanglular movieclip and name is as “parent_mc” and a smaller rectangular movieclip inside it and name is as “child_mc“. Now select first frame and write the code. Download the file to see what the trace statements say about mouse down event.
-
parent_mc.addEventListener(MouseEvent.MOUSE_DOWN, truePhase, true);
-
parent_mc.addEventListener(MouseEvent.MOUSE_DOWN, falsePhase, false);
-
-
function truePhase(evt:MouseEvent):void{
-
trace("=====================use capture true===================================");
-
switch(evt.eventPhase){
-
case EventPhase.BUBBLING_PHASE:
-
trace("BUBBLING_PHASE");
-
break;
-
case EventPhase.CAPTURING_PHASE:
-
evt.stopImmediatePropagation();
-
trace("CAPTURING_PHASE");
-
break;
-
case EventPhase.AT_TARGET:
-
trace("AT_TARGET");
-
break;
-
}
-
-
trace("currenttarget: " +evt.currentTarget.name);
-
trace("target: "+evt.target.name);
-
}
-
-
function falsePhase(evt:MouseEvent):void{
-
trace("=====================use capture false===================================");
-
switch(evt.eventPhase){
-
case EventPhase.BUBBLING_PHASE:
-
trace("BUBBLING_PHASE");
-
break;
-
case EventPhase.CAPTURING_PHASE:
-
trace("CAPTURING_PHASE");
-
break;
-
case EventPhase.AT_TARGET:
-
trace("AT_TARGET");
-
break;
-
}
-
-
trace("currenttarget: " +evt.currentTarget.name);
-
trace("target: "+evt.target.name);
-
}
There are two event handlers that handle the mouse down event, it’s because if we set useCapture true then we wont be able to catch the target & bubbling phase. So in two event handlers will handle the event with useCapture true and false respectively. When you down your mouse on the bigger rectangle, you can only see the target as parent_mc and in target phase of propagation. This is because there is no child element under the mouse pointer. Notice that I have added evt.stopImmediatePropagation(); in the first event handler in second switch statement, this blocks further propagation of event and do not let the second event handler get execute. The event object stops navigation. You can see the results when you click the inner child_mc in this example. You can only be able to see
=====================use capture true===================================
CAPTURING_PHASE
currenttarget: parent_mc
target: child_mc
If you uncomment that line then you will be able to see the events fired in bubbling phase also. So uncomment it and look at the results. You will see:
=====================use capture true===================================
CAPTURING_PHASE
currenttarget: parent_mc
target: child_mc
=====================use capture false===================================
BUBBLING_PHASE
currenttarget: parent_mc
target: child_mc
This tells us one good logic to control our events when we have to control the event flow while working with nested display objects.
Click here to download the example file.