harglerode

I’ve had some people asking questions about custom AS3 events, so I figured I would post a small example here.

Now, there are two types of custom events in AS3. The first is simply a standard event object with a unique string name. Below is the syntax.

dispatchEvent( new Event( "MyCustomEvent" ) );

This is handy when all you need to to do is track when something occurs. But, what happens when I need to pass along event specific data like positions, time, etc. Well, this is when you create a custom event object. Basically you just extend the flash event object and fill in your own data. It’s not quite that simple though. There are a few other things you need to do as well. I’ll show you how.

First, let’s create our custom event object. Be sure to inherit from the flash event object.

package
{
    import flash.events.Event;

    public class MyCustomEvent extends Event
    {

    }
}

Now, we need to add the properties that we wish to pass along with this event and include the constructor. The constructor is what will accept the values for these properties. For the sake of our example, let’s imagine that we want two properties, time and position.

package
{
    import flash.events.Event;

    public class MyCustomEvent extends Event
    {
        public var time:Number;
        public var position:uint;

        public function MyCustomEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false, time:Number, position:uint)
        {
            super(type, bubbles, cancelable);
            this.time = time;
            this.position = position;
        }
    }
}

What we’ve done is create public variables for each property we wish to track. We make them public because when we access this object in the event handler, we want these properties available to us. We’ve also created the custom event constructor. This constructor takes 5 parameters, the first 3 are the standard three parameters for a basic event and the last 2 are our specific values. In the constructor we call super and pass along the first 3 parameters, that way the core flash event properties are still handled properly. Next, we set our two properties.

Next, we have to define the types of events we expect this event object to handle. Since our two values are time and position, lets imagine that the two events are for time changing and position changing. We need to add those as public static variables to our event object. It’s good practice for an event to store its own event type strings.

package
{
    import flash.events.Event;

    public class MyCustomEvent extends Event
    {
        public var time:Number;
        public var position:uint;

        public static const TIME_CHANGED:String = "CustomEventTimeChanged";
        public static const POSITION_CHANGED:String = "CustomEventPositionChanged";

        public function MyCustomEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false, time:Number, position:uint)
        {
            super(type, bubbles, cancelable);
            this.time = time;
            this.position = position;
        }
    }
}

You always want these event type string to be as unique as possible. I will typically include the event name for good measure. Almost there.

Finally, we have to override a few function from the flash event to make sure our event works properly. The two functions to override are clone() and toString().

package
{
    import flash.events.Event;

    public class MyCustomEvent extends Event
    {
        public var time:Number;
        public var position:uint;

        public static const TIME_CHANGED:String = "CustomEventTimeChanged";
        public static const POSITION_CHANGED:String = "CustomEventPositionChanged";

        public function MyCustomEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false, time:Number, position:uint)
        {
            super(type, bubbles, cancelable);
            this.time = time;
            this.position = position;
        }

        override public function clone():Event
        {
            return new MyCustomEvent(type, bubbles, cancelable, time, position);
        }

        override public function toString():String
        {
            return formatToString("MyCustomEvent", "type", "bubbles", "cancelable", "time", "position");
        }
    }
}

These two function are utility functions that get used occasionally. You don’t need to know specifics, just know that you will have to override both of these functions and include your event data.

That’s it, your custom event is now complete. Now you just need to dispatch the event from your application and provide the two properties at the time of the event. Make sure you also define the event type using the static strings in the event class.

dispatchEvent( new MyCustomEvent( MyCustomEvent.TIME_CHANGED, false, false, nTime, nPosition ) );

Those properties will then be available from the event object in your event handler. Below is an example.

myClip.addEventListener(MyCustomEvent.TIME_CHANGED, myHandler);

private function myHandler(e:MyCustomEvent):void
{
    // e.time and e.position are now available
}

Cheers!