Messaging and event management in Potomac is managed by two primary pieces. First, is the global PotomacDispatcher class. The second is the [Handles] tag.

PotomacDispatcher

The PotomacDispatcher is a global class that can be used to dispatch events throughout a Potomac application. Any class may get an instance of the PotomacDispatcher via injection (add [Inject] on a var of type PotomacDispatcher) or more easily via the PotomacDispatcher#getInstance() method.

The PotomacDispatcher provides two approach to message passing. First is the standard Flash/Flex event dispatching. PotomacDispatcher extends flash.events.EventDispatcher and provides the normal expected methods like dispatchEvent, addEventListener and removeEventListener. The second approach is a bit simpler and alleviates the need to declare event classes. This approach is made available via the dispatch, addListener and removeListener methods (notice no ‘Event’ in the names). The dispatch method simply takes the name of the event followed by any number of arguments or data for that event. Listener methods are expected to have a method signature that matches the arguments passed to dispatch. Here’s an example:

Code dispatching event

PotomacDispatcher.getInstance().dispatch("myEvent","string",100,"string2");

Code listening to event

[Handles(event="myEvent",global="true")]
public function myListener(string1:String,int1:int,string2:String):void
{
   ...
}

This approach can be much simpler but is also a bit more brittle. Alternatively, adding and removing properties of a standard Event class will not necessarily break the listening methods. Adding or removing arguments using this approach always requires the listening methods to update their function signature.

[Handles] – Listening for Events

[Handles] is a rather simple extension point but it plays a large role in typical development with Potomac.

The handles tag allows you to associate functions with events without the need to use addEventListener.

Handles tags must be declared on public methods.

[Handles] can be used to listen to standard events dispatched by any IEventDispatcher. Adding a [Handles] tag on a method simply wires that method as an event listener of the specified event on the current class (or the source component if that is specified).

[Handles] can also be used to listen to global events dispatched on the PotomacDispatcher. Setting global=”true” will cause the method to be added as a listener to the global PotomacDispatcher.