Dispatcher

The Dispatcher can be used to dispatch an event from anywhere in your application. It can be used as a tag within your views and can be instantiated in ActionScript classes. Its main advantage is that it allows you to receive direct event responses using the inner ResponseHandler and ServiceResponseHandler tags.

Example:

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

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

Using dispatcher as a 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.

Using dispatcher in ActionScript

When you have a class that is not a visual component, it is not possible to make it dispatch an event unless you extend it from EventDispatcher or make it implement the IEventDispatcher interface.

The dispatcher class allows you to dispatch events in non-visual components or any other ActionScript class.

You only need to instantiate an instance of Dispatcher, create the event and use the instance to dispatch it:

var myDispatcher:Dispatcher = new Dispatcher();

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);

6 responses so far

  1. Is there any way to declare the dispatchers (using tags) in a separate file, not in the same file as the view?
  2. Ricardo,
    Yes, you can. But you'll have to include that other component in your view.
  3. "The properties to set in your event must be public."

    Will these tags that depend on public properties work with private properties and implicit getters, setters?

    The Flex community seems to not care too much for encapsulation. Any comments?
  4. Ankur,
    Public getters or public properties are the same to an external object, so they are interchangeable.
  5. I setup a LocalEventMap and have the LocalEventMap tag inside a VBox component. I defined a custom event with the bubbles property set to true. I then defined a dispatcher tag inside the VBox. When I call generateEvent() I get no event fired on the LocalEventMap. I had to actually set the bubbles property on the dispatcher tag to true in order to get this to work. Is this the way a dispatcher tag has to be defined when using a LocalEventMap that is not defined in a module? None of the documentation eludes to any of that. I stumbled across through sheer tenacity. What made me suspicious is that when I instantiate my custom event and call dispatchEvent it worked. Now I just want to understand why I had to set bubbles to true on the dispatcher tag. Thanks
  6. Is it wise to only declare one dispatcher for every mxml and reuse that one to dispatch different events?
    Then use actionscript to set the properties before generating the event?

    Thanks.

Leave a response

If you need help or want to comment on something not related to this page, please post in the forums. Thanks!

Leave this field empty