Friday, April 29, 2011

Remove Event Listeners

Flex adds event listeners either inline (inside mx tags) or in functions inside script block.
The ways we remove added listeners for the event is same as the way we have added it.
i.e first, we need to call the removeEventListener on that component/container by passing all the parameters
which we passed while calling the addEventListener for the same component/container.
this may be just 2 required parameters as shown below:

comp_id.removeEventListener(eventType:EVENT_TYPE,removeHandlerFunction)

and then finally, we need to define the removeHandlerFunction which expects the same event type that we passed
as EVENT_TYPE in the above method and perform the logic there:

private function removeHandlerFunction(eventType:EVENT_TYPE):void {
....
}

But there is 1 difference in how the event listeners are removed.
If we have added any event listener inline (i.e. inside <mx:> tag for the component or container),
then even calling removeEventListener won't remove it.

However, all the events which are added through addEventListeners (inside script block) can be removed
using the removeEventListener

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="createHandler(event)">
<mx:Script>
<![CDATA[
import mx.controls.Alert;

private function createHandler(event:Event):void {
b1.addEventListener(MouseEvent.CLICK,myClickHandler);
}

private function removeMyHandlers(event:Event):void {
Alert.show("Removing listener for Button 1");
/* Remove listener for b1's click event because it was added with the addEventListener() method */
b1.removeEventListener(MouseEvent.CLICK,myClickHandler);

/* Does NOT remove the listener for b2's click event because it was added inline i.e in MXML tag */
b2.removeEventListener(MouseEvent.CLICK,myClickHandler);
}

private function myClickHandler(event:Event):void {
Alert.show("The button was clicked");
}
]]>
</mx:Script>

<mx:Button id="b1" label="Click Me (Button 1)" />
<mx:Button id="b2" label="Click Me (Button 2)" click="myClickHandler(event)"/>
<mx:Button id="b3" label="Remove Event Listeners" click="removeMyHandlers(event)"/>
</mx:Application>


In the above example, first try to click button b1. You will see and Alert box saying "The button was clicked". Then, try same for Button b2. You will again see the same output.
Then, try to click the 'Remove Event Listeners' button. This button removes the event listener for b1
since it was added using the addEventListener. But for b2, it does not removes the event listener even though we called the b2.removeEventListener too.

After clicking on the third button, again try to click b1. The alert won't be displayed as it has already removed the listener for this button's click event and hence, it does not call myClickHandler.
However, b2 is still having its listener active and hence its click handler function myClickHandler executes and alert gets displayed on click on b2.

stopPropagation and stopImmediatePropagation

Generally, flex navigates its compelte display list, either upwards towards Application, in Bubbling or Target Phase
or downwards towards the immediate ancestor of the component/container which triggered the event in Capturing Phase.
However, we can stop this navigation or propagation using the following 2 methods of event:

1. stopPropagation: This is used to prevent the Event object from moving onto the next node, but allows the other event listeners (EVENT of same type, example another CLICK) on the current node to execute.
2. stopImmediatePropagation: This is used to prevent the Event object not only to move to next node, but it also does not allow the other event listeners (ONLY OF SAME TYPE, example another CLICK) on the current node to execute

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
click="clickHandler(event)" name="Application" initialize="initApp()">
<mx:Script>
<![CDATA[
import mx.controls.Alert;

private function initApp():void {
myBtn1.addEventListener(MouseEvent.CLICK,anotherClickHandlerForBtn1);
myBtn1.addEventListener(MouseEvent.CLICK,clickHandler);
myBtn1.addEventListener(MouseEvent.ROLL_OUT,rollOutHandler);
myBtn2.addEventListener(MouseEvent.CLICK,anotherClickHandlerForBtn2);
myBtn2.addEventListener(MouseEvent.CLICK,clickHandler);
myBtn2.addEventListener(MouseEvent.ROLL_OUT,rollOutHandler);
}

/*
This will always execute for the buttons
irrespective of stopPropagation or stopImmediatePropagation
as this is a ROLL_OUT event (Event other then CLICK type for which
we are calling the stopPropagation or stopImmediatePropagation)
*/

private function rollOutHandler(event:MouseEvent):void {
Alert.show("Roll Out event for target("+event.target.name+")&"+
" currentTarget("+event.currentTarget.name+")");
}


/*
In this function, we are calling stopPropagation.
So, Flex tries to see if there are any other event other than CLICK on this object or CLICK event itself on parent container. And if there are, it does not execute them
However, if there are more than 1 CLICK handlers for this button itself, it executes all of them. And do not move to the next node in event flow.
*/

private function anotherClickHandlerForBtn1(event:MouseEvent):void {
Alert.show("This is first click handler and would also allow all the other" +
" click handlers of this 'Button 1' to execute (event.stopPropagation)" +
" and stop propagating to other nodes ",event.type);
event.stopPropagation();
}

/*
In this function, we are calling stopImmediatePropagation
So, As soon as this CLICK handler gets executed, Flex stops the event there itself and
no other events gets called (even if there is another CLICK handler, it won't execute)
And also, it does not moves on to the next node in event flow.
*/

private function anotherClickHandlerForBtn2(event:MouseEvent):void {
Alert.show("This will just allow the click handler of this 'Button 2' to execute" +
" and then would stop propagating the event to other click handlers on same node" +
" as well as other nodes (event.stopPropagation)",event.type);
event.stopImmediatePropagation()
}

private function clickHandler(event:MouseEvent):void {
Alert.show("Target object: "+event.target.name
+"\n"+
"Phase: "+getPhaseName(event.eventPhase)
+"\n"+
"Current Target object: "+event.currentTarget.name);
}

private function getPhaseName(phase:uint):String {
switch(phase) {
case 1:
return "CAPTURING PHASE";
case 2:
return "TARGET PHASE";
case 3:
return "BUBBLING PHASE";
}
return "";
}
]]>
</mx:Script>
<mx:Panel borderThickness="250" name="Panel" click="clickHandler(event)" width="700" height="300">
<mx:VBox backgroundColor="#EEEEEE" click="clickHandler(event)" name="VBox" height="200" width="600"
horizontalAlign="center" verticalAlign="middle">
<mx:Label text="Stops propagation to next node but does not stops other events on the same node to execute" />
<mx:Button id="myBtn1" name="Button 1" label="Button 1" />
<mx:Label text="Stops propagation to next node as well as stops other CLICK events on the same node to execute" />
<mx:Button id="myBtn2" name="Button 2" label="Button 2" />
</mx:VBox>
</mx:Panel>
</mx:Application>

Capturing Phase Event

In Flex, we need to know what are the 'target' and 'currentTarget' properties of the Event object and also the
3 stages of Event processing. Let us go through them.

1. target and currentTarget properties: 'target' always refers to the component that has dispatched the event in
first place (example: Button component dispatching click event) and the 'currentTarget' refers to the container
which is currently handling the event (Example, VBOX container in which the above Button is placed and VBOX has
registered for listening to the Button's click event).

In Flex, there are 3 stages of Event processing:
1. Capturing Phase
2. Target Phase
3. Bubbling Phase

Consider the below example which has Application, inside which we have a Panel, inside which we have a VBOox and
then a Button Control.
So, the structure looks like this:

Application
Panel
VBox
Button

Say now, we have clicked on the button. This calls the 'click' event on button. Here, the 'target' object would
always be the same 'button'.

In Capturing Phase: Flex examies the Button's ancestors from the Application right down to the immediate ancestor
of the button (i.e. VBox in this case). This is hardly used. So, in this, the following steps occur during the
capturing phase in same order"
1. Check the Application container for click event listeners (target: Button, currentTarget: Application)
2. Check the Panel container for click event listeners (target: Button, currentTarget: Panel)
3. Check the VBox container for click event listeners (target: Button, currentTarget: VBox)

In Target Phase: Flex reaches the Button for seeing the listeners and here the 'target' and 'currentTarget' refers
to the same component i.e (target:Button, currentTarget: Button)

In Bubbling Phase: Flex examines the Button's ancestors for listeenrs. But here, it starts with the dispatcher's
(button's) immediate ancestor (VBox) and moves all up the display list to the root ancestor (i.e Application). This
is the reverse of the Capturing phase and most often used. The following steps occur in same order:
1. Check the VBox container for click event listeners (target: Button, currentTarget: VBox)
2. Check the Panel container for click event listeners (target: Button, currentTarget: Panel)
3. Check the Application container for click event listeners (target: Button, currentTarget: Application)


<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
initialize="addCapturingPhaseEvent(event)" name="Application">
<mx:Script>
<![CDATA[
import mx.controls.Alert;

private function addCapturingPhaseEvent(event:Event):void {
/* to use capturing phase, we need to pass the "useCapture" parameter as true once
and false another time as the third parameter to the addEventListener method.
Passing "false" as the third parameter (Which is by default, but gets overridden if
we have passed as "true" once, will call the Bubbling as well as the Target phase
*/


Application.application.addEventListener(MouseEvent.CLICK,clickHandler,true);

// The below line if commented, will not call the bubbling and the target phase
// as we have set useCapture = true in the previous statement


Application.application.addEventListener(MouseEvent.CLICK,clickHandler,false);
myPanel.addEventListener(MouseEvent.CLICK,clickHandler,true);
myPanel.addEventListener(MouseEvent.CLICK,clickHandler,false);
myBtn.addEventListener(MouseEvent.CLICK,clickHandler,true);
myBtn.addEventListener(MouseEvent.CLICK,clickHandler,false);
myVBox.addEventListener(MouseEvent.CLICK,clickHandler,true);
myVBox.addEventListener(MouseEvent.CLICK,clickHandler,false);
}
private function clickHandler(event:MouseEvent):void {
Alert.show("Target object: "+event.target.name
+"\n"+
"Phase: "+getPhaseName(event.eventPhase)
+"\n"+
"Current Target object: "+event.currentTarget.name);
}

private function getPhaseName(phase:uint):String {
switch(phase) {
case 1:
return "CAPTURING PHASE";
case 2:
return "TARGET PHASE";
case 3:
return "BUBBLING PHASE";
}
return "";
}
]]>
</mx:Script>


<mx:Panel borderThickness="250" name="Panel" id="myPanel" width="500" height="300">
<mx:VBox backgroundColor="#EEEEEE" id="myVBox" name="VBox" height="200" width="300"
horizontalAlign="center" verticalAlign="middle">
<mx:Button name="Button" label="Click Me" id="myBtn" />
</mx:VBox>
</mx:Panel>
</mx:Application>

Bubbling And Target Event Phase

In Flex, we need to know what are the 'target' and 'currentTarget' properties of the Event object and also the
3 stages of Event processing. Let us go through them.

1. target and currentTarget properties: 'target' always refers to the component that has dispatched the event in
first place (example: Button component dispatching click event) and the 'currentTarget' refers to the container
which is currently handling the event (Example, VBOX container in which the above Button is placed and VBOX has
registered for listening to the Button's click event).

In Flex, there are 3 stages of Event processing:
1. Capturing Phase
2. Target Phase
3. Bubbling Phase

Consider the below example which has Application, inside which we have a Panel, inside which we have a VBOox and
then a Button Control.
So, the structure looks like this:

Application
Panel
VBox
Button

Say now, we have clicked on the button. This calls the 'click' event on button. Here, the 'target' object would
always be the same 'button'.

In Capturing Phase: Flex examies the Button's ancestors from the Application right down to the immediate ancestor
of the button (i.e. VBox in this case). This is hardly used. So, in this, the following steps occur during the
capturing phase in same order"
1. Check the Application container for click event listeners (target: Button, currentTarget: Application)
2. Check the Panel container for click event listeners (target: Button, currentTarget: Panel)
3. Check the VBox container for click event listeners (target: Button, currentTarget: VBox)

In Target Phase: Flex reaches the Button for seeing the listeners and here the 'target' and 'currentTarget' refers
to the same component i.e (target:Button, currentTarget: Button)

In Bubbling Phase: Flex examines the Button's ancestors for listeenrs. But here, it starts with the dispatcher's
(button's) immediate ancestor (VBox) and moves all up the display list to the root ancestor (i.e Application). This
is the reverse of the Capturing phase and most often used. The following steps occur in same order:
1. Check the VBox container for click event listeners (target: Button, currentTarget: VBox)
2. Check the Panel container for click event listeners (target: Button, currentTarget: Panel)
3. Check the Application container for click event listeners (target: Button, currentTarget: Application)

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
click="clickHandler(event)" name="Application">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
private function clickHandler(event:MouseEvent):void {
Alert.show("Target object: "+event.target.name
+"\n"+
"Phase: "+getPhaseName(event.eventPhase)
+"\n"+
"Current Target object: "+event.currentTarget.name);
}

private function getPhaseName(phase:uint):String {
switch(phase) {
case 1:
return "CAPTURING PHASE";
case 2:
return "TARGET PHASE";
case 3:
return "BUBBLING PHASE";
}
return "";
}
]]>
</mx:Script>
<mx:Panel borderThickness="250" name="Panel" click="clickHandler(event)" width="500" height="300">
<mx:VBox backgroundColor="#EEEEEE" click="clickHandler(event)" name="VBox" height="200" width="300"
horizontalAlign="center" verticalAlign="middle">
<mx:Button name="Button" label="Click Me" click="clickHandler(event)" />
</mx:VBox>
</mx:Panel>
</mx:Application>




In the above example, we have placed the click event handler on the containers (i.e Application, Panel, VBox) as well as the Button component
However, if you try to remove the click="clickHandler(event)" from any 1 container, say VBox, then on click of the VBox, you would find
that the Alert for the Bubbling phase with the currentTarget of Panel and Application gets displayed as they are checked in the bubbling
phase for the click event and since they have the handler for the click event, it gets called.
However, the Target phase of the VBox won't be called in this case as VBox does not handles the click event itself.