Handy ActionScript Toolset

Event handling is something that no large project can get away without. Without an event handling mechanism of some sort the code would get too unweildy and no abstraction can take place making different modules very tightly bound. Flash AS2 doesn't have anything of the sort built in and the only some objects allow you to add listener objects. All HATObjects come with the ability to send events out and have event handlers added to intercept them.

Here's an example of adding a handler to handle an event:

hatObj.handle( "Click", this, onHATClick );

function onHATClick( event : HATEvent )
{
     traceI( "HATClick handled" );
}

HATEvent, that's inside the com.kirillam.handy.events package, is the most basic event class and all other events are its subclasses. It tells what the event name is, what the object that sent the event is and any data associated with the event that is being made available by the event sender.

The full signature of the handle method is:

handle( eventName : String, target : Object, method : Function, useStrongReference : Boolean, ... );

The eventName is the event identifier for an event sent out by the object. Target is the handler object and the method is the reference to the function to call on the target. The 4th parameter is a bit interesting. It tells whether to use a strong reference to the handler object or not. While using a strong reference the handler is kept in memory even if there's no other reference to it anywhere in the application. With a weak reference, which is the default if you don't pass anything in, the object will get garbage collected if there's no other reference to it. This is good for preventing memory leaks with objects that were added as handlers, never removed afterwards, and no longer being used in the application. With a strong reference they would remain in memory until removed as handlers. But you might still need to use a strong reference if maybe you're passing in a dummy object that is basically a wrapper or a proxy to another object, since you wouldn't want it to be garbage collected. Everything you pass in after the 4th parameter is passed in as arguments to the handler function after the event object.

To remove a handler call:

 ignore( event: String, target : Object );

Or:

ignoreAll( target : Object );

There are also two house keeping methods that tell you if an even is handled by a particular handler and if an even is handled by anybody:

hasHandler( event: String, target : Object ) : Boolean
isHandled( event : String ) : Boolean

If you're subclassing HATObject your class can send events of it's own by calling:

sendEvent( event : HATEvent );

You have to instanciate a new event object that you pass as an argument to the method. It's target property is then set and the even is sent out to any handlers. HATEvent class has a list of static constants for some of the more typical events. You are not limited by these, though.