Stopping an Event Dispatch

At any point during the event flow, every event listener can put a stop on the entire event dispatch.
To stop an event dispatch, we invoke the Event class’s instance method stopImmediatePropagation() or stopPropagation().

For example, suppose we have a Sprite, container that contains a TextField, child:

var container:Sprite = new Sprite();
var child:TextField = new TextField();
child.text = "click here";
child.autoSize = TextFieldAutoSize.LEFT;
container.addChild(child);

Further suppose we have three event listener functions: containerClickListenerOne(), containerClickListenerTwo() and childClickListener().

container.addEventListener(MouseEvent.CLICK, containerClickListenerOne, true)
container.addEventListener(MouseEvent.CLICK, containerClickListenerTwo, true)
child.addEventListener(MouseEvent.CLICK, childClickListener, false);

Under normal circumstances, when the user clicks child, all three events listeners are triggered – two during the capture phase, and one during the target phase. If, however, containerClickListenerOne() consumes the event using stopImmediatePropagation(), then neither containerClickListenerTwo() nor childClickListener() is triggered.

public function containerClickListenerOne(e:MouseEvent) : void {
e.stopImmediatePropagation();
}

On the other hand, if containerClickListenerOne() consumes the event using stopPropagation(), then container’s remaining MouseEvent.CLICK event listeners are triggered before the event dispatch stops. Hance, containerClickListenerTwo() receives the event, but childClickListener() does not.

public function containerClickListenerOne(e:MouseEvent) : void {
e.stopPropagation();
}

Note that the preceding examples relies on containerClickListenerOne() being registered before containerClickListenerTwo().

Events are typically consumed in order to stop or override a program’s normal response to an event. For example, suppose a Sprite subclass, ToolPanel, contains a group of interface controls, each of which accepts user input. The ToolPanel class has two operational states: enabled and disabled. When a ToolPanel object is disabled, the user should not be able to interact with any of its nested interface controls.