EventHandlers

(This tag must be placed inside an <EventMap> tag)

The list of event handlers defined by the EventHandlers tag that is defined in the EventMap will run whenever an event of the type specified in the "type" argument is dispatched. Note that in order for the list to be able to listen for the given event, this event must have its bubbling setting as true and be dispatched from an object that has Application as its root ancestor, or the event must be dispatched by a Mate Dispatcher (such is the case when dispatching events from a PopUp window).

<EventHandlers type="myEventType">
   ... here what you want to happen when this event is dispatched...
</EventHandlers>

Attributes

type

String

required

The event type that, when dispatched, should trigger the list of handlers to run. It should match the type specified in the event when created. All events extending from flash.events.Event have a "type" property.

While this attribute is a string, a constant is most commonly used:

<EventHandlers type="{MyEvent.MY_EVENT_TYPE}">
   ... here what you want to happen when this event is dispatched...
</EventHandlers>

Any bubbling up event or an event dispatched by a Mate Dispatcher can be used, including Flex built-in events such as FlexEvent.APPLICATION_COMPLETE.

priority

Number

If you expect to have several listeners for the same events (the Event Map, several views, etc), you can assign each listener a different priority to manage the order at which those listeners will be notified. By default, the listeners are notified by the order at which they were registered (when they have the same priority). The listeners will be called from highest priority (highest number) to lowest. Default value is 0.

Note that as Flex documentation states, although the listeners will be called in that order, there is no guarantee that one listener will finish execution before the others are called.

debug

Boolean

Whether to show debugging information for this event handlers block. If true, Console output will show debugging information as this list runs.

start

Event handler

In the start attribute you can supply an event handler for the event of type ActionListEvent.START. This event is dispatched right before the handlers are called, when the list starts execution.

Example:

<EventHandlers type="{MyEvent.MY_EVENT_TYPE}" start="trace('Execution of handlers list started!')">
   ...
</EventHandlers>

end

Event handler

In the end attribute you can supply an event handler for the event of type ActionListEvent.END. This event is dispatched right after all the handlers have been called, when the list ends execution (although this event might be dispatched before asynchronous calls have returned).

Example:

<EventHandlers type="{MyEvent.MY_EVENT_TYPE}" end="trace('Execution of handlers list ended!')">
   ...
</EventHandlers>

Inner tags

Allowed inner tags:

Order of the inner tags is important

The order in which the inner tags ("handlers") are placed is important because it determines the order in which each action will be taken.

For example, say you have defined the following sequence:

<EventHandlers type="myEventType">

   <!-- Step 1 -->
   <MethodInvoker generator="WorkerOne" method="doSomeWork" />

   <!-- Step 2 -->
   <EventAnnouncer type="myEventTypeTwo" generator="EventClassNameToInstantiate" />

   <!-- Step 3 -->
   <MethodInvoker generator="WorkerTwo" method="doSomethingElse" />
   
</EventHandlers>

In this scenario, when an event of type "myEventType" is dispatched, the following will happen:

  1. An instance of WorkerOne will be created and the method doSomeWork() will be called
  2. A new event of type "myEventTypeTwo" will be dispatched.
  3. An instance of WorkerTwo will be created and the method doSomethingElse() will be called

For more information about the list order when using asynchronous services, refer to "Handling a service result or fault".

15 responses so far

  1. Looks like event routing is done solely on the event type without consideration of the event class. There is no guarantee that event types provided by Adobe or component creators are unique. Perhaps another attribute should be provided, which specifies the event class. For some small applications event routing could be done solely by event type; for other applications event type might be sufficient; the application I am working on requires an additional event property in order to route events.
  2. Sorry, my previous posting was messed up.

    Looks like event routing is done solely on the event type without consideration of the event class. There is no guarantee that event types provided by Adobe or component creators are unique. Perhaps another attribute should be provided, which specifies the event class. For some small applications event routing could be done solely by event type; for other applications event class might be sufficient; the application I am working on requires both event class and type, plus an additional event property in order to route events.
  3. Hi Mike,
    We use events in the same way that Flex does (ie: when you add an event listener, you only specify the event type). You need to use unique types to make sure that your Handlers do not conflict. While there is no guarantee that component events are unique, those typically do not bubble up and the parent of the component explicitly registers to them.
    We have a section in the best practices that talks about that: Events best practices
  4. Isn't InlineInvoker missing in the list of allowed inner tags here?
  5. franz,
    Yes, it was missing.
  6. I notice that the EventHandlers tag has an "actions" attribute. What is that for?

    Thanks
  7. Todd,
    actions is the default property that allows you to add all other tags inside the EventHandlers and other handlers.
  8. It would be a nice feature if the xml generated by the debugging were proper xml.
  9. Jacob,
    You can add it to user voice :)
    http://mate.uservoice.com/

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