In my own projects, I've often needed to tell various components of my applications that something importatnt has happened, without breaking the general compositional rules of inheritance and encapsulation in AS3.  A typical scenario: you've got a class that handles loading xml files, and an xml manager that uses this loading class to load a bunch of xml files sequentially.  Outside of your xml manager, you've got a higher level class waiting on all the xml files to finish loading.  An AS2 mindset would tell us to set up a callback in the xml manager that calls a function of its owner to say 'hey, i'm done!', breaking the encapsulation of the the xml manager, as it then becomes dependent on the coupling of it with its owner.  To avoid this, it's best to introduce the EventDispatcher and the possibilities of writing your own custom events in flash.

Before covering custom events, let's first familiarize ourself with the EventDispatcher class and the process of firing off events outside of the general scope of flash's native methods.

To successfully do this, you will need two classes: one to listen for the Event that will be dispatched, and one to dispatch the event.

// 1. Listener class

package
{
    import flash.events.Event;
    import DispatcherClass;
    
    public class ListenerClass
    {
        private var _dispatcher:DispatcherClass;
    
        public function ListenerClass():void
        {
            _dispatcher = new DispatcherClass();
            // add event listener first
            _dispatcher.addEventListener( Event.COMPLETE, handleComplete );
            // call function in dispatcher that will dispatch event
            // of course, you could dispatch the event from the dispatch class whereever you want.
            _dispacher.dispatchMyEvent();
        };
    
        private function handleComplete( evt:Event ):void
        {
            trace( "ListenerClass.handleComplete()" );
        };
    }
}

Great. A parent class is set up and it listens for an Event.COMPLETE from its child. This seems typical..but..

// 2. Dispatcher class

package
{
    import flash.events.Event;
    import flash.events.EventDispatcher;
    
    public class DispatcherClass
    {
    
        public function DispatcherClass():void
        {

        };

        public function dispatchMyEvent():void
        {
            dispatchEvent( new Event( Event.COMPLETE ) );
        };

    }

}

Ok, notice the dispatcher class has a method that dispatches a new Event.  Any class that is listening to the DispatcherClass for an Event.COMPLETE will pick up on the dispatchEvent call and execute its corresponding function.  Simple Right?

Let's take this a step further -
Custom Events!

To set up a custom event, you will need:

1. a class file for the custom event that extends the Event class.

2. a Listener class that listens for custom events.

3. a dispatcher class to broadcast the custom event.


1. Let's create our custom event.

package
{
    import flash.events.Event;

    public class CustomEvent extends Event
    {
        public static const CUSTOM:String = "CLICK_CUSTOM";
       
        private var customData:*;
       
        public function CustomEvent (type:String):void
        {
            super (type);
        };

        public function addData (customData:*):void
        {
            this.customData = customData;
        };

        public function get data ():*
        {
            return customData;
        };

        public function demo ():void
        {
            trace( "CustomEvent.demo()" );
        }
    }

}


2. Set up our listener class

package
{
    import CustomEvent;
    import DispatcherClass;
    
    public class ListenerClass
    {
        private var _dispatcher:DispatcherClass;
    
        public function ListenerClass():void
        {
            _dispatcher = new DispatcherClass();
            // add event listener first
            _dispatcher.addEventListener( CustomEvent.CUSTOM, handleClickCustom );
            _dispacher.dispatchMyEvent();
        };
    
        private function handleClickCustom( evt:ClickEvent ):void
        {
            // the custom event was fired and caught here!
            trace( "ListenerClass.handleComplete()" );
            // we now have access to the event class that was dispatched (and all its unique public properties and methods)
            trace( evt.data );
            trace( evt.data.name );
            trace( evt.data.demo() );
        };
    }
}


3. Set up the class that the listener class will be looking to for any CustomEvent that is fired.

package
{
    import flash.events.CustomEvent;
    import flash.events.EventDispatcher;
    
    public class DispatcherClass
    {
        public var name:String = "Dispatcher!";

        public function DispatcherClass():void
        {

        };

        public function dispatchMyEvent():void
        {
            // instantiate custom event class
            var customEvent:CustomEvent = new CustomEvent( CustomEvent.CUSTOM);
            
            // pass in this as a parameter to demonstrate its flexibility.
            customEvent.addData(this);
            
            dispatchEvent( customEvent );
        };
    }
}

That's basically the gist of it.  Once you realize the Event class is really just a class like any other that just gets passed between other classes (listeners and broadcasters), custom tailoring events is a breezy.  There are many circumstances where dispatching both regular and custom events can come in handy, so I hope this was some help.