SASAPI

     1  /**
     2   * com.sekati.events.Dispatcher
     3   * @version 1.1.5
     4   * @author jason m horwitz | sekati.com
     5   * Copyright (C) 2007  jason m horwitz, Sekat LLC. All Rights Reserved.
     6   * Released under the MIT License: http://www.opensource.org/licenses/mit-license.php
     7   */
     8  
     9  import com.sekati.core.CoreObject;
    10  import com.sekati.events.Event;
    11  import com.sekati.events.IDispatchable;
    12  import mx.events.EventDispatcher;
    13  
    14  /**
    15   * A centralized EventDispatcher to decouple event listeners & dispatchers from direct addressing.
    16   * {@code Usage:
    17   * var receiveObj:Object = {_name:"receiveObj"};
    18   * // define a generic method for the reciever object to use
    19   * function onEventReceived (event:Object):Void {
    20   * var str:String = (this._name + " received Event = { type:" + event.type + ", target:" + event.target + ", data: {");
    21   * for (var i in event.data) { str += " " + i + ":" + event.data[i] + ","; }
    22   * trace (str+" }};");
    23   * }
    24   * // add the method to our reciever object as 'testEvent'
    25   * receiveObj.testEvent = onEventReceived;
    26   * // add reciever object as an event listener for "testEvent"
    27   * Dispatcher.getInstance().addEventListener ("testEvent",receiveObj);
    28   * // define sender and data objects (optional)
    29   * var senderObj:Object = this;
    30   * var dataObj:Object = {message:"hello", someNumber:42};
    31   * // Dispatch the event to all 'testEvent' EventListeners
    32   * Dispatcher.getInstance().dispatchEvent (new Event ("testEvent", senderObj, dataObj));
    33   * }
    34   * Some excellent explanations of the AS2/3 event models and broadcasters vs dispatchers
    35   * @see <a href="http://www.communitymx.com/content/article.cfm?page=1&cid=76FDB">http://www.communitymx.com/content/article.cfm?page=1&cid=76FDB</a>
    36   * @see <a href="http://www.kirupa.com/developer/actionscript/eventdispatcher.htm">http://www.kirupa.com/developer/actionscript/eventdispatcher.htm</a>
    37   * @see {@link com.sekati.events.Broadcaster}
    38   */
    39  class com.sekati.events.Dispatcher extends CoreObject implements IDispatchable {
    40  
    41  	private static var _instance:Dispatcher;
    42  	private var _manager:Object;
    43  
    44  	/**
    45  	 * Singleton Private Constructor: initializes centralized management of mx.events.EventDispatcher
    46  	 */
    47  	private function Dispatcher() {
    48  		super( );
    49  		_manager = new Object( );
    50  		EventDispatcher.initialize( _manager );
    51  	}
    52  
    53  	/**
    54  	 * Singleton Accessor
    55  	 * @return Dispatcher
    56  	 */
    57  	public static function getInstance():Dispatcher {
    58  		if (!_instance) _instance = new Dispatcher( );
    59  		return _instance;
    60  	}
    61  
    62  	/**
    63  	 * shorthand singleton accessor getter
    64  	 */
    65  	public static function get $():Dispatcher {
    66  		return Dispatcher.getInstance( );	
    67  	}
    68  
    69  	/**
    70  	 * Add the event listener to the centralized event manager
    71  	 * @param event (String) the name of the event ("click", "change", etc)
    72  	 * @param handler (Object) the function or object that should be called
    73  	 * @return Void
    74  	 */
    75  	public function addEventListener(event:String, handler:Object):Void {
    76  		_manager.addEventListener( event, handler );
    77  	}
    78  
    79  	/**
    80  	 * Remove the event listener from the centralized event manager
    81  	 * @param event (String) the name of the event ("click", "change", etc)
    82  	 * @param handler (Object) the function or object that should be called
    83  	 * @return Void
    84  	 */
    85  	public function removeEventListener(event:String, handler:Object):Void {
    86  		_manager.removeEventListener( event, handler );
    87  	}
    88  
    89  	/**
    90  	 * Dispatch the event to all listeners via the centralized event manager
    91  	 * @param e (Event) an Event or one of its subclasses describing the event
    92  	 * @return Void
    93  	 * {@code Usage:
    94  	 * Dispatcher.getInstance().dispatchEvent(new Event("myEvent", this, {foo:true, bar:false}));
    95  	 * }
    96  	 */
    97  	public function dispatchEvent(e:Event):Void {
    98  		_manager.dispatchEvent( e );
    99  	}
   100  
   101  	/**
   102  	 * Bubbles event up the chain. The target property is added on the route
   103  	 * and then replaced by the new target.
   104  	 * @param e (Event)
   105  	 * @return Void
   106  	 */
   107  	public function bubbleEvent(e:Event):Void {
   108  		e.bubble( this );
   109  		dispatchEvent( e );
   110  	}
   111  
   112  	/**
   113  	 * Wrapper to dispatchEvent: creates an Event object and dispatchs it to all event listeners
   114  	 * {@code Usage:
   115  	 * Dispatcher.getInstance().broadcastEvent("myEvent",targetObject, {param0:value0, param1:value1, paramn:valuen});
   116  	 * }
   117  	 * @param _type (String) type of event
   118  	 * @param _target (Object) he object that dispatched this event. There is a known bug with this property: It always returns as '/'. This may be a flaw in EventDispatcher; if you need to pass the event source use {@link dispatchEvent}.
   119  	 * @param _data (Object) a transport object for any needed data
   120  	 * @return Void
   121  	 */
   122  	public function broadcastEvent(_type:String, _target:Object, _data:Object):Void {
   123  		var event:Event = new Event( _type, _target, _data );
   124  		_manager.dispatchEvent( event );
   125  	}
   126  
   127  	/**
   128  	 * Destroy singleton instance.
   129  	 * @return Void
   130  	 */
   131  	public function destroy():Void {
   132  		delete _manager;
   133  		delete _instance;
   134  		super.destroy( );
   135  	}	
   136  }