Mate Flex Framework

A fundamental part of Mate are the events, since all communication between the different parts of the application is made via events.

The EventHandlers in the EventMap subscribe to listen to events of particular types. The type specified is very important because it will determine whether or not a sequence must be run. This type is a string and that string must be unique throughout your whole application.

We define this type as a constant in the event itself. Suppose you have an event called CustomerEvent:

import flash.events.Event;

public class CustomerEvent extends Event {

                  public function CustomerEvent(type:String, bubbles:Boolean=true, cancelable:Boolean=true) {

                  super(type, bubbles, cancelable);

                  }

}

We add a constant for the event type:

public static const ADD:String = "addCustomerEvent";

In our event map, then, we can use this constant as the event type. This helps us not making mistakes when typing the event type.

<EventHandlers type="{CustomerEvent.ADD}">
   .....
</EventHandlers>

You can use the same in your view Listeners:

<mate:Listener type="{CustomerEvent.ADD}" ..../>

And in your dispatchers:

<mate:Dispatcher generator="{CustomerEvent}" type="{CustomerEvent.ADD}" ...>

Creating a unique type

Since the event type must be unique, you can append the name of your event class so that it will be less likely to conflict with other events:

"add" + "CustomerEvent"= "addCustomerEvent"

public static const ADD:String = "addCustomerEvent";

If you want to ensure there are no conflicts, you can also use the full package name as part of the event type:

public static const ADD:String = "com.mydomain.events.CustomerEvent.ADD";

The above approach is not recommended if this event is a view event declared by the Event metatag in the view, as it will make the type too large and unreadable in parent views that wish to add event handlers for that event.

Having several types in the same event

You can have more than one type in the same event. As long as all those types defined use and need the same properties, they can be put together. For example, adding, updating and removing a customer all need a customer property and it makes sense to create only one event for all those types (assume you have a class Customer):

public class CustomerEvent extends Event {

                  public static const ADD:String = "addCustomerEvent";

                  public static const UPDATE:String = "updateCustomerEvent";

                  public static const DELETE:String = "deleteCustomerEvent";

                  public var customer:Customer;

                  public function CustomerEvent(type:String, bubbles:Boolean=false, cancelable:Boolean=true) {

                  super(type, bubbles, cancelable);

                  }

}

Bubbling property

When an event has it "bubbles" property set to false, only listeners added explicitly to the object that dispatched the event will be notified when the event is dispatched.

If you use the <Dispatcher> tag in your views or the Mate Dispatcher class in your other classes and PopUps, whether you set the event to bubble up or not will not make much difference, since the EventMap and other views registered will still be notified of the event.

However, if you use the view's dispatchEvent() function (every Display Object is a Dispatcher) and dispatch the event as you would normally do:

var myEvent:CustomerEvent = new CustomerEvent(CustomerEvent.ADD);
dispatchEvent(myEvent);

the aforementioned rules will apply and other views and the event map will not be notified unless you set the event property bubbles to true. Just so that you don't have to remember this every time you create an event:

new CustomerEvent(CustomerEvent.ADD, true)

you can set this property as true by default in your constructor:

public function CustomerEvent(type:String, bubbles:Boolean=true, cancelable:Boolean=true)

and then this code will work fine:

var myEvent:CustomerEvent = new CustomerEvent(CustomerEvent.ADD);
dispatchEvent(myEvent);

Built-in Events

An EventHandlers block can listen to any event that bubbles up or that has been dispatched by using the Mate Dispatcher. Any Flex built-in event can also be used as long as it bubbles up. For example, an EventHandlers block can listen to FlexEvent.APPLICATION_COMPLETE event.

dispatchEvent() vs Dispatcher tag

If you only need to dispatch an event, in most cases, you can simply use dispatchEvent() function that is available in every display object (ie: views). In those cases, you would simply instantiate an event, and then dispatch it using the dispatchEvent(myEvent) function. For example:

var myEvent:CustomerEvent = new CustomerEvent(CustomerEvent.ADD);
dispatchEvent(myEvent);

If you need additional functionality, particularly when you need to receive responses after you dispatched the event, you will need to use the Dispatcher tag. See ResponseHandler, ServiceResponseHandler, ResponseAnnouncer, and ServiceResponseAnnouncer.

Unless you need that additional functionality provided by the Dispatcher tag, it is recommended to use dispatchEvent() as a way of decoupling your application from Mate.