Mate Flex Framework

The Dispatcher can be used to dispatch an event from anywhere in your application. Its main advantage is that it allows you to receive direct event responses using the inner ResponseHandler and ServiceResponseHandler tags. Since those tags have been deprecated, the Dispatcher has been deprecated as well. See ResponseHandler and ServiceResponseHandler for replacement information.

Example:

<mate:Dispatcher generator="MyEventClass" type="myEventType">

   <mate:eventProperties>
      <mate:EventProperties myProperty="myValue" />
   </mate:eventProperties>
   
</mate:Dispatcher>

Using the tag

Using the dispatcher tag allows you to dispatch an event from any MXML component. You can use the dispatcher attributes to make the dispatcher create the event for you or you can create an event and use the dispatcher only to dispatch the already created event.

It also allows you to receive direct responses such that only the object that dispatched the event receives this response.

Attributes

generator

The generator attributes specifies what class of event should be instantiated and dispatched.

Suppose you have a custom event called "MyEvent" in the package com.yourdomain.events.  You can specify a complete path to com.yourdomain.events.MyEvent:

<mate:Dispatcher

                  generator="com.yourdomain.events.MyEvent"

                  type="myEventType" />

Generally, you may want to use a binding to specify the class name. Assuming you  have an import statement like this in your Event Map:

import com.yourdomain.events.MyEvent;

or simply:

import com.yourdomain.events.*;

You can then declare your event class using bindings:

<mate:Dispatcher 

                  generator="{MyEvent}"

                  type="myEventType" />

type

String

The type attribute specifies the event type you want to dispatch. Suppose you have an event class definition as follows:

public class MyEvent extends Event {

                  public static const MY_EVENT_TYPE:String = "myEventType";

                  public var myProperty:String;

                  public var myProperty2:uint;

}

You can then specify the type attribute with the event type literal string:

<mate:Dispatcher

                  generator="{MyEvent}"

                  type="myEventType" />

Or you can use the binding syntax again:

<mate:Dispatcher

                  generator="{MyEvent}"

                  type="{MyEvent.MY_EVENT_TYPE}" />

This will allow the compiler to check that the type you specified exists.

Inner tags

eventProperties

You can add properties to your event by using the EventProperties tag inside the eventProperties inner tag. The properties to set in your event must be public.

As attributes of the EventProperties tag, you can specify the names of your properties and set the values of those properties by setting the value of those attributes.

Suppose you are creating an event of the class shown previously (MyEvent) and assigning values for its two properties (myProperty and myProperty2):

<mate:Dispatcher

                  generator="{MyEvent}"

                  type="{MyEvent.MY_EVENT_TYPE}">

                  <mate:eventProperties>

                                    <mate:EventProperties

                                                      myProperty="myValue"

                                                      myProperty2="100" />

                  </mate:eventProperties>

</mate:Dispatcher>

ResponseHandler

The ResponseHandler tag can be used to receive a response from an event that was dispatched from this dispatcher instance.

See Receiving a response to a dispatched event.

ServiceResponseHandler

The ServiceResponseHandler tag can be used to receive a service response from an event that was dispatched from this dispatcher instance.

See Receiving a response to a dispatched event.

Receiving a response to a dispatched event

After dispatching an event using the Dispatcher tag, the view that dispatched this event can receive a response. Those responses are sent from the EventMap within the EventHandlers block that was listening for the event dispatched by the Dispatcher.

It's important to note that this response will be received only by the view instance that dispatched the event, even if there are other instances of the same view or other views dispatch the same event.

Using the ResponseHandler tag

<mate:ResponseHandler type="searchCustomerResult" response="onSearchResultReceived(event.result)" />

Using the ServiceResponseHandler tag

A simple way to receive a response generated by a service call. It contains result and fault handlers you can use as you would when receiving a normal service (ie: RemoteObject) result or fault. It also contains a response handler that can be used for any situation.

<mate:ServiceResponseHandler
   result="trace(event.result)"
   fault="trace(event.fault.faultString)"
   response="trace(event.data)" />

This tag listens for responses sent by ServiceReponse tags created in the EventHandlers block that was listening for the event dispatched by the Dispatcher. The use of this tag has no effect if its matching counterpart is not included in the EventMap. ServiceResponseAnnouncer tags must be included in a resultHandlers and in a faultHandlers.

Different ways of dispatching an event

Suppose you want to create and dispatch a MyEvent event of type  MyEvent.MY_EVENT_TYPE with properties myProperty="myValue" and myProperty2=100

Creating the event and using the Dispatcher tag to dispatch it

In this scenario, you have a simple Dispatcher tag:

<mate:Dispatcher id="myDispatcher" />

And you create the event as usual:

var myEvent:MyEvent = new MyEvent(MyEvent.MY_EVENT_TYPE);
myEvent.myProperty = "myValue";
myEvent.myProperty2 = 100;

Then you use the dispatcher to dispatch it:

myDispatcher.dispatchEvent(myEvent);

Using the default event type and class and setting properties at dispatch time

You can set the event type that you will be dispatching and the class to instantiate as your event in the Dispatcher tag:

<mate:Dispatcher

                  generator="{MyEvent}"

                  type="{MyEvent.MY_EVENT_TYPE}">

The Dispatcher will create an event of the given class and type, so it is not necessary to manually create it. In order to dispatch it, you use the dispatcher's generateEvent() function:

myDispatcher.generateEvent();

If you need to add properties to the event, as in the original example, you can add those properties at the moment of dispatching the event in the form of an object:

myDispatcher.generateEvent({myProperty: "myValue", myProperty2: 100});

Creating an event with properties set in the Dispatcher tag

The dispatcher tag allows you to define all properties of an event within the Dispatcher tag itself. You can assign the event type, the event class to instantiate and the properties that the event will contain:

<mate:Dispatcher

                  id="myDispatcher"

                  generator="{MyEvent}"

                  type="{MyEvent.MY_EVENT_TYPE}">

                  <mate:eventProperties>

                                    <mate:EventProperties

                                                      myProperty="myValue"

                                                      myProperty2="100" />

                  </mate:eventProperties>

</mate:Dispatcher>

You then dispatch the event at any time, for example, when the user clicks on a button:

<mx:Button click="myDispatcher.generateEvent()" />

On the button click, the event with the properties set in the Dispatcher tag will be dispatched.