Mate Flex Framework

(This tag must be placed inside an <EventHandlers> tag or a <MessageHandlers> tag)

Handlers inside an EventHandlers block run all listeners in order. The StopHandlers tag lets you stop execution of the handlers before it reaches the end of the list. The list can be stopped based on whether the "lastReturn" is equal to some value, or based on an external function that tells whether or not the sequence must be stopped.

<StopHandlers lastReturnEquals="someValue" />

or

<StopHandlers stopFunction="myStopSequenceFuntion" />

Attributes

lastReturnEquals

either lastReturnEquals or stopFunction must be provided

If there exists a MethodInvoker right before the StopHandlers tag, and the execution of the function called by the MethodInvoker returned a value ("lastReturn"), you can compare it to some other value and stop the subsequent handlers execution if it is equal.

<StopHandlers lastReturnEquals="someValue" />

Though other tags return values, generally speaking, only MethodInvokers return values you can use. Normally, that value is nullified after other tags are executed. See Using lastReturn.

stopFunction

either lastReturnEquals or stopFunction must be provided

A more flexible approach than using lastReturnEquals is to use the stopFunction attribute and handle the logic externally. The function that you implement needs to return true if the list execution must stop or false if not.

<StopHandlers stopFunction="myStopSequenceFuntion" />

Then you implement your evaluation function:

private function myStopHandlersFunction(scope:IScope):Boolean {

                  ... here you do some evaluation to determine

                                    whether to stop the sequence or not...

                  return false; //or return true;

}

eventPropagation

String

Possible values are: noStop, stopPropagation, stopImmediatePropagation (default: stopImmediatePropagation)

This attribute lets you stop the event that triggered the execution of the handlers list (EventHandlers). If there are any listeners for this event other than this list of handlers, they will not be notified if the propagation of the event is stopped. See Flex documentation regarding the difference between stop propagation and stop immediate propagation.

The default of this attribute is to immediate stop propagation of the event ("stopImmediatePropagation").

Using the scope parameter in the stopFunction

The stopFunction function you implement must receive one argument of type IScope. You can use the values in the EventHandlers' scope to determine whether or not the execution must be stopped.

Implementors of the interface IScope contain these properties and functions:

event: the event that triggered the list execution. Although it is of type flash.events.Event, you can cast it to a custom event.

data: the data object. It is used to store custom information while the list is running.

lastReturn: the returned value from the last handler that run.

isRunning(): a function that returns whether the list execution is currently running.

dispatcher: an event dispatcher that can be use to dispatch events.

currentEvent: the event that triggered the handlers list or inner handlers list, such as resultHandlers or faultHandlers (ResultEvent and FaultEvent respectively) to run .

Depending on the type of handlers list the StopHandlers tag is in, this scope can be of one the Scope subtypes:

1. MessageScope
   This type exists when the StopHandlers tag is inside a <MessageHandlers> block as opposed to an <EventHandlers>. It contains properties specific to a "message received" event:

   message: the message received (type mx.messaging.messages.IMessage)

   messageEvent: the original MessageEvent (type mx.messaging.events.MessageEvent)

   fault: if the consumer subscription generated a fault, it will be available in this property

2. ServiceScope

   This sequence type exists when the StopHandlers  tag is inside a <resultHandlers> or <faultHandlers> block that generated from a Service call (either by using WebServiceInvoker, HTTPServiceInvoker or RemoteObjectInvoker tags). It contains data returned by the server.

   result: the result object returned by the server when the server did not generated a fault.

   fault: the fault (if any) generated by the service call.

   resultEvent: the result event generated by the service call. This property is of type mx.rpc.events.ResultEvent

   faultEvent: the fault event generated by the service call. This property is of type mx.rpc.events.FaultEvent

Handlers can also be stopped inside a function called by MethodInvoker that either implements the IScopeReceiver interface (see Implementing the IScopeReceiver interface) or by passing the scope as an argument in the function call.