PureMVC SignalNotifierMap

puremvc-SignalNotifierMap.as

package uk.co.jonnyreeves.puremvc.util
{
	import flash.utils.Dictionary;
	
	import org.osflash.signals.ISignal;
	import org.puremvc.as3.multicore.interfaces.INotifier;

	/**
	 * Convenience class which allows you to create bindings between as3-signals and PureMVC notifications - when the
	 * Signal gets dispatched, the mapped Notification is created with the Signal's payload supplied as the
	 * Notification Body.
	 * 
	 * @example Creating mappings for a viewComponent's signals in a Mediator.
	 * <listing version="3.0">
	 * override public function onRegister() : void {
	 *     // Create a new SignalNotifierMap which will work with this Mediator
	 *     const signalMap : SignalNotifierMap = new SignalNotifierMap(this);
	 * 
	 *     // Create a mapping so that whenever the View Component's onButtonClicked Signal is dispatched, the
	 *     // BUTTON_CLICKED notification gets broadcast.
	 *     signalMap.add(viewComponent.onButtonClicked, Notifications.BUTTON_CLICKED);
	 * }
	 * </listing> 
	 * 
	 * @author Jonny Reeves
	 */
	public class SignalNotifierMap
	{
		private var _notifier : INotifier;
		private var _callbacksBySignalMap : Dictionary = new Dictionary();

		/**
		 * Creates a new SignalNotifierMap which will work for the supplied INotifier instance; in such that when 
		 * mapped signals are dispatched, the notifier will send the notification via it's sendNotification() method.
		 * 
		 * @param notifier the client which will broadcast notifications
		 */ 
		public function SignalNotifierMap(notifier : INotifier)
		{
			_notifier = notifier
		}

		/**
		 * Creates a mapping between the supplied Signal and notificationName.  When the supplied Signal is dispatched,
		 * a notification containing the Signal's payload as the Notificaiton Body will be sent.
		 * 
		 * @param signal to listen on
		 * @param notificaitonName to send when the Signal is dispatched
		 * @param addOnce automatically remove the mapping once the Signal dispatches.
		 * @return a reference to this instance for method chaining
		 */
		public function add(signal : ISignal, notificationName : String, addOnce : Boolean = false) : SignalNotifierMap
		{
			const callback : Function = function(...args) : void {
				if (addOnce) {
					delete _callbacksBySignalMap[signal][callback];
					signal.remove(callback);
				}
				_notifier.sendNotification(notificationName, args);
			}
			
			const signalCallbackSet : Dictionary = _callbacksBySignalMap[signal] ||= new Dictionary();
			signalCallbackSet[callback] = true;

			signal.add(callback);
			return this;
		}
	
		/**
		 * Removes all the mappings; typically called in your Mediator's onRemove() method.
		 */
		public function removeAll() : void
		{
			for (var signal : * in _callbacksBySignalMap) {
				removeAllOf(signal as ISignal);
			}
		}
		
		/**
		 * Removes all the mappings for the supplied Signal.  If the supplied Signal dispatches after a call to
		 * removeAllOf() is made, no Notification will be sent.
		 * 
		 * @param signal to remove all mappings for
		 */
		public function removeAllOf(signal : ISignal) : void
		{
			var signalCallbackSet : Dictionary = _callbacksBySignalMap[signal];
			if (signalCallbackSet != null)
			{
				for (var callback : * in signalCallbackSet) {
					(signal as ISignal).remove(callback);
				}
				delete _callbacksBySignalMap[signal];
			}
		}
	}
}