as3signals 0.7.0

data/src/org/osflash/signals/DeluxeSignal.as

@@ -0,0 +1,260 @@
+package org.osflash.signals
+{
+	import flash.errors.IllegalOperationError;
+	
+	import org.osflash.signals.events.IBubbleEventHandler;
+	import org.osflash.signals.events.IEvent;
+
+	/**
+	 * Signal dispatches events to multiple listeners.
+	 * It is inspired by C# events and delegates, and by
+	 * <a target="_top" href="http://en.wikipedia.org/wiki/Signals_and_slots">signals and slots</a>
+	 * in Qt.
+	 * A Signal adds event dispatching functionality through composition and interfaces,
+	 * rather than inheriting from a dispatcher.
+	 * <br/><br/>
+	 * Project home: <a target="_top" href="http://github.com/robertpenner/as3-signals/">http://github.com/robertpenner/as3-signals/</a>
+	 */
+	public class DeluxeSignal implements IDeluxeSignal, ISignalOwner, IDispatcher
+	{
+		protected var _target:Object;
+		protected var _valueClasses:Array;
+		protected var listenerBoxes:Array;
+		protected var listenersNeedCloning:Boolean = false;
+		
+		/**
+		 * Creates a DeluxeSignal instance to dispatch events on behalf of a target object.
+		 * @param	target The object the signal is dispatching events on behalf of.
+		 * @param	valueClasses Any number of class references that enable type checks in dispatch().
+		 * For example, new DeluxeSignal(this, String, uint)
+		 * would allow: signal.dispatch("the Answer", 42)
+		 * but not: signal.dispatch(true, 42.5)
+		 * nor: signal.dispatch()
+		 *
+		 * NOTE: Subclasses cannot call super.apply(null, valueClasses),
+		 * but this constructor has logic to support super(valueClasses).
+		 */
+		public function DeluxeSignal(target:Object, ...valueClasses)
+		{
+			_target = target;
+			listenerBoxes = [];
+			// Cannot use super.apply(null, valueClasses), so allow the subclass to call super(valueClasses).
+			if (valueClasses.length == 1 && valueClasses[0] is Array)
+				valueClasses = valueClasses[0];
+			setValueClasses(valueClasses);
+		}
+		
+		/** @inheritDoc */
+		public function get valueClasses():Array { return _valueClasses; }
+		
+		/** @inheritDoc */
+		public function get numListeners():uint { return listenerBoxes.length; }
+		
+		/** @inheritDoc */
+		public function get target():Object { return _target; }
+		
+		/** @inheritDoc */
+		public function set target(value:Object):void
+		{
+			if (value == _target) return;
+			removeAll();
+			_target = value;
+		}
+		
+		/** @inheritDoc */
+		//TODO: @throws
+		public function add(listener:Function):Function
+		{
+			return addWithPriority(listener)
+		}
+		
+		public function addWithPriority(listener:Function, priority:int = 0):Function
+		{
+			registerListener(listener, false, priority);
+			return listener;
+		}
+		
+		public function addOnce(listener:Function):Function
+		{
+			return addOnceWithPriority(listener)
+		}
+		
+		/** @inheritDoc */
+		public function addOnceWithPriority(listener:Function, priority:int = 0):Function
+		{
+			registerListener(listener, true, priority);
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		public function remove(listener:Function):Function
+		{
+			if (indexOfListener(listener) == -1) return listener;
+			if (listenersNeedCloning)
+			{
+				listenerBoxes = listenerBoxes.slice();
+				listenersNeedCloning = false;
+			}
+			listenerBoxes.splice(indexOfListener(listener), 1);
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		public function removeAll():void
+		{
+			// Looping backwards is more efficient when removing array items.
+			for (var i:uint = listenerBoxes.length; i--; )
+			{
+				remove(listenerBoxes[i].listener as Function);
+			}
+		}
+		
+		/** @inheritDoc */
+		public function dispatch(...valueObjects):void
+		{
+			// Validate value objects against pre-defined value classes.
+			var valueObject:Object;
+			var valueClass:Class;
+			var len:int = _valueClasses.length;
+			for (var i:int = 0; i < len; i++)
+			{
+				// null is allowed to pass through.
+				if ( (valueObject = valueObjects[i]) === null
+					|| valueObject is (valueClass = _valueClasses[i]) )
+					continue;
+					
+				throw new ArgumentError('Value object <' + valueObject
+					+ '> is not an instance of <' + valueClass + '>.');
+			}
+
+			var event:IEvent = valueObjects[0] as IEvent;
+			if (event)
+			{
+				// clone re-dispatched event
+				if (event.target)
+				{
+					valueObjects[0] = event = event.clone();
+				}
+				event.target = this.target;
+				event.currentTarget = this.target;
+				event.signal = this;
+			}
+			
+			// During a dispatch, add() and remove() should clone listeners array instead of modifying it.
+			listenersNeedCloning = true;
+			//// Call listeners.
+			var listener:Function;
+			if (listenerBoxes.length)
+			{
+				//TODO: investigate performance of various approaches
+				
+				for each (var listenerBox:Object in listenerBoxes)
+				{
+					listener = listenerBox.listener;
+					if (listenerBox.once) remove(listener);
+					listener.apply(null, valueObjects);
+				}
+			}
+			
+			listenersNeedCloning = false;
+			
+			if (!event || !event.bubbles) return;
+
+			//// Bubble the event as far as possible.
+			var currentTarget:Object = this.target;
+			while ( currentTarget && currentTarget.hasOwnProperty("parent")
+					&& (currentTarget = currentTarget.parent) )
+			{
+				if (currentTarget is IBubbleEventHandler)
+				{
+					// onEventBubbled() can stop the bubbling by returning false.
+					if (!IBubbleEventHandler(event.currentTarget = currentTarget).onEventBubbled(event))
+						break;
+				}
+			}
+		}
+		
+		protected function indexOfListener(listener:Function):int
+		{
+			for (var i:int = listenerBoxes.length; i--; )
+			{
+				if (listenerBoxes[i].listener == listener) return i;
+			}
+			return -1;
+		}
+				
+		protected function setValueClasses(valueClasses:Array):void
+		{
+			_valueClasses = valueClasses || [];
+			
+			for (var i:int = _valueClasses.length; i--; )
+			{
+				if (!(_valueClasses[i] is Class))
+				{
+					throw new ArgumentError('Invalid valueClasses argument: item at index ' + i
+						+ ' should be a Class but was:<' + _valueClasses[i] + '>.');
+				}
+			}
+		}
+		
+		protected function registerListener(listener:Function, once:Boolean = false, priority:int = 0):void
+		{
+			// function.length is the number of arguments.
+			if (listener.length < _valueClasses.length)
+			{
+				var argumentString:String = (listener.length == 1) ? 'argument' : 'arguments';
+				throw new ArgumentError('Listener has '+listener.length+' '+argumentString+' but it needs at least '+_valueClasses.length+' to match the given value classes.');
+			}
+			
+			var listenerBox:Object = { listener:listener, once:once, priority:priority };
+			// Process the first listener as quickly as possible.
+			if (!listenerBoxes.length)
+			{
+				listenerBoxes[0] = listenerBox;
+				return;
+			}
+			
+			var prevListenerIndex:int = indexOfListener(listener);
+			if (prevListenerIndex >= 0)
+			{
+				// If the listener was previously added, definitely don't add it again.
+				// But throw an exception in some cases, as the error messages explain.
+				var prevListenerBox:Object = listenerBoxes[prevListenerIndex];
+				if (prevListenerBox.once && !once)
+				{
+					throw new IllegalOperationError('You cannot addOnce() then add() the same listener without removing the relationship first.');
+				}
+				else if (!prevListenerBox.once && once)
+				{
+					throw new IllegalOperationError('You cannot add() then addOnce() the same listener without removing the relationship first.');
+				}
+				// Listener was already added, so do nothing.
+				return;
+			}
+			
+			if (listenersNeedCloning)
+			{
+				listenerBoxes = listenerBoxes.slice();
+				listenersNeedCloning = false;
+			}
+		
+			// Assume the listeners are already sorted by priority
+			// and insert in the right spot. For listeners with the same priority,
+			// we must preserve the order in which they were added.
+			var len:int = listenerBoxes.length;
+			for (var i:int = 0; i < len; i++)
+			{
+				// As soon as a lower-priority listener is found, go in front of it.
+				if (priority > listenerBoxes[i].priority)
+				{
+					listenerBoxes.splice(i, 0, listenerBox);
+					return;
+				}
+			}
+			
+			// If we made it this far, the new listener has lowest priority, so put it last.
+			listenerBoxes[listenerBoxes.length] = listenerBox;
+		}
+		
+	}
+}

data/src/org/osflash/signals/IDeluxeSignal.as

@@ -0,0 +1,34 @@
+package org.osflash.signals
+{
+	/**
+	 *
+	 */
+	public interface IDeluxeSignal extends ISignal
+	{
+		/**
+		 * Subscribes a listener for the signal.
+		 * After you successfully register an event listener,
+		 * you cannot change its priority through additional calls to add().
+		 * To change a listener's priority, you must first call remove().
+		 * Then you can register the listener again with the new priority level.
+		 * @param	listener A function with an argument
+		 * that matches the type of event dispatched by the signal.
+		 * If eventClass is not specified, the listener and dispatch() can be called without an argument.
+		 */
+		function addWithPriority(listener:Function, priority:int = 0):Function
+		
+		/**
+		 * Subscribes a one-time listener for this signal.
+		 * The signal will remove the listener automatically the first time it is called,
+		 * after the dispatch to all listeners is complete.
+		 * @param	listener A function with an argument
+		 * that matches the type of event dispatched by the signal.
+		 * If eventClass is not specified, the listener and dispatch() can be called without an argument.
+		 * @param	priority The priority level of the event listener.
+		 * The priority is designated by a signed 32-bit integer.
+		 * The higher the number, the higher the priority.
+		 * All listeners with priority n are processed before listeners of priority n-1.
+		 */
+		function addOnceWithPriority(listener:Function, priority:int = 0):Function
+	}
+}

data/src/org/osflash/signals/IDispatcher.as

@@ -0,0 +1,15 @@
+package org.osflash.signals
+{
+	/**
+	 *
+	 */
+	public interface IDispatcher
+	{
+		/**
+		 * Dispatches an object to listeners.
+		 * @param	valueObjects	Any number of parameters to send to listeners. Will be type-checked against valueClasses.
+		 * @throws	ArgumentError	<code>ArgumentError</code>:	valueObjects are not compatible with valueClasses.
+		 */
+		function dispatch(...valueObjects):void;
+	}
+}

data/src/org/osflash/signals/ISignal.as

@@ -0,0 +1,44 @@
+package org.osflash.signals
+{
+	/**
+	 *
+	 */
+	public interface ISignal
+	{
+		/**
+		 * An optional array of classes defining the types of parameters sent to listeners.
+		 */
+		function get valueClasses():Array;
+		
+		/** The current number of listeners for the signal. */
+		function get numListeners():uint;
+		
+		/**
+		 * Subscribes a listener for the signal.
+		 * @param	listener A function with arguments
+		 * that matches the value classes dispatched by the signal.
+		 * If value classes are not specified (e.g. via Signal constructor), dispatch() can be called without arguments.
+		 * @return the listener Function passed as the parameter
+		 */
+		function add(listener:Function):Function;
+		
+		/**
+		 * Subscribes a one-time listener for this signal.
+		 * The signal will remove the listener automatically the first time it is called,
+		 * after the dispatch to all listeners is complete.
+		 * @param	listener A function with arguments
+		 * that matches the value classes dispatched by the signal.
+		 * If value classes are not specified (e.g. via Signal constructor), dispatch() can be called without arguments.
+		 * @return the listener Function passed as the parameter
+		 */
+		function addOnce(listener:Function):Function;
+		
+		/**
+		 * Unsubscribes a listener from the signal.
+		 * @param	listener
+		 * @return the listener Function passed as the parameter
+		 */
+		function remove(listener:Function):Function;
+		
+	}
+}

data/src/org/osflash/signals/ISignalOwner.as

@@ -0,0 +1,13 @@
+package org.osflash.signals
+{
+	/**
+	 * ISignalOwner gives access to the powerful function, removeAll. This should only be called by trusted classes.
+	 */
+	public interface ISignalOwner extends ISignal
+	{
+		/**
+		 * Unsubscribes all listeners from the signal.
+		 */
+		function removeAll():void
+	}
+}

data/src/org/osflash/signals/Signal.as

@@ -0,0 +1,206 @@
+package org.osflash.signals
+{
+	import flash.errors.IllegalOperationError;
+	import flash.utils.Dictionary;
+
+	/**
+	 * Signal dispatches events to multiple listeners.
+	 * It is inspired by C# events and delegates, and by
+	 * <a target="_top" href="http://en.wikipedia.org/wiki/Signals_and_slots">signals and slots</a>
+	 * in Qt.
+	 * A Signal adds event dispatching functionality through composition and interfaces,
+	 * rather than inheriting from a dispatcher.
+	 * <br/><br/>
+	 * Project home: <a target="_top" href="http://github.com/robertpenner/as3-signals/">http://github.com/robertpenner/as3-signals/</a>
+	 */
+	public class Signal implements ISignalOwner, IDispatcher
+	{
+		protected var _valueClasses:Array;		// of Class
+		protected var listeners:Array;			// of Function
+		protected var onceListeners:Dictionary;	// of Function
+		protected var listenersNeedCloning:Boolean = false;
+		
+		/**
+		 * Creates a Signal instance to dispatch value objects.
+		 * @param	valueClasses Any number of class references that enable type checks in dispatch().
+		 * For example, new Signal(String, uint)
+		 * would allow: signal.dispatch("the Answer", 42)
+		 * but not: signal.dispatch(true, 42.5)
+		 * nor: signal.dispatch()
+		 *
+		 * NOTE: Subclasses cannot call super.apply(null, valueClasses),
+		 * but this constructor has logic to support super(valueClasses).
+		 */
+		public function Signal(...valueClasses)
+		{
+			listeners = [];
+			onceListeners = new Dictionary();
+			// Cannot use super.apply(null, valueClasses), so allow the subclass to call super(valueClasses).
+			if (valueClasses.length == 1 && valueClasses[0] is Array)
+				valueClasses = valueClasses[0];
+			setValueClasses(valueClasses);
+		}
+		
+		/** @inheritDoc */
+		public function get valueClasses():Array { return _valueClasses; }
+		
+		/** @inheritDoc */
+		public function get numListeners():uint { return listeners.length; }
+		
+		/** @inheritDoc */
+		//TODO: @throws
+		public function add(listener:Function):Function
+		{
+			registerListener(listener);
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		public function addOnce(listener:Function):Function
+		{
+			registerListener(listener, true);
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		public function remove(listener:Function):Function
+		{
+			var index:int = listeners.indexOf(listener);
+			if (index == -1) return listener;
+			if (listenersNeedCloning)
+			{
+				listeners = listeners.slice();
+				listenersNeedCloning = false;
+			}
+			listeners.splice(index, 1);
+			delete onceListeners[listener];
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		public function removeAll():void
+		{
+			// Looping backwards is more efficient when removing array items.
+			for (var i:uint = listeners.length; i--; )
+			{
+				remove(listeners[i] as Function);
+			}
+		}
+		
+		/** @inheritDoc */
+		public function dispatch(...valueObjects):void
+		{
+			// Validate value objects against pre-defined value classes.
+			var valueObject:Object;
+			var valueClass:Class;
+			var numValueClasses:int = _valueClasses.length;
+			if (valueObjects.length < numValueClasses)
+			{
+				throw new ArgumentError('Incorrect number of arguments. Expected at least ' + numValueClasses + ' but received ' + valueObjects.length + '.');
+			}
+			
+			for (var i:int = 0; i < numValueClasses; i++)
+			{
+				// null is allowed to pass through.
+				if ( (valueObject = valueObjects[i]) === null
+					|| valueObject is (valueClass = _valueClasses[i]) )
+					continue;
+					
+				throw new ArgumentError('Value object <' + valueObject
+					+ '> is not an instance of <' + valueClass + '>.');
+			}
+
+			if (!listeners.length) return;
+			
+			//// Call listeners.
+			
+			// During a dispatch, add() and remove() should clone listeners array instead of modifying it.
+			listenersNeedCloning = true;
+			var listener:Function;
+			switch (valueObjects.length)
+			{
+				case 0:
+					for each (listener in listeners)
+					{
+						if (onceListeners[listener]) remove(listener);
+						listener();
+					}
+					break;
+					
+				case 1:
+					for each (listener in listeners)
+					{
+						if (onceListeners[listener]) remove(listener);
+						listener(valueObjects[0]);
+					}
+					break;
+					
+				default:
+					for each (listener in listeners)
+					{
+						if (onceListeners[listener]) remove(listener);
+						listener.apply(null, valueObjects);
+					}
+			}
+			listenersNeedCloning = false;
+		}
+		
+		protected function setValueClasses(valueClasses:Array):void
+		{
+			_valueClasses = valueClasses || [];
+			
+			for (var i:int = _valueClasses.length; i--; )
+			{
+				if (!(_valueClasses[i] is Class))
+				{
+					throw new ArgumentError('Invalid valueClasses argument: item at index ' + i
+						+ ' should be a Class but was:<' + _valueClasses[i] + '>.');
+				}
+			}
+		}
+		
+		protected function registerListener(listener:Function, once:Boolean = false):void
+		{
+			// function.length is the number of arguments.
+			if (listener.length < _valueClasses.length)
+			{
+				var argumentString:String = (listener.length == 1) ? 'argument' : 'arguments';
+				throw new ArgumentError('Listener has '+listener.length+' '+argumentString+' but it needs at least '+_valueClasses.length+' to match the given value classes.');
+			}
+			
+			// If there are no previous listeners, add the first one as quickly as possible.
+			if (!listeners.length)
+			{
+				listeners[0] = listener;
+				if (once) onceListeners[listener] = true;
+				return;
+			}
+						
+			if (listeners.indexOf(listener) >= 0)
+			{
+				// If the listener was previously added, definitely don't add it again.
+				// But throw an exception in some cases, as the error messages explain.
+				if (onceListeners[listener] && !once)
+				{
+					throw new IllegalOperationError('You cannot addOnce() then add() the same listener without removing the relationship first.');
+				}
+				else if (!onceListeners[listener] && once)
+				{
+					throw new IllegalOperationError('You cannot add() then addOnce() the same listener without removing the relationship first.');
+				}
+				// Listener was already added, so do nothing.
+				return;
+			}
+			
+			if (listenersNeedCloning)
+			{
+				listeners = listeners.slice();
+				listenersNeedCloning = false;
+			}
+				
+			// Faster than push().
+			listeners[listeners.length] = listener;
+			if (once) onceListeners[listener] = true;
+		}
+	}
+}

data/src/org/osflash/signals/events/GenericEvent.as

@@ -0,0 +1,44 @@
+package org.osflash.signals.events
+{
+	import org.osflash.signals.IDeluxeSignal;
+
+	/**
+	 *
+	 * @see org.osflash.signals.events.IEvent
+	 * Documentation for the event interface being maintained in IEvent to avoid duplication for now.
+	 */
+	public class GenericEvent implements IEvent
+	{
+		protected var _bubbles:Boolean;
+		protected var _target:Object;
+		protected var _currentTarget:Object;
+		protected var _signal:IDeluxeSignal;
+		
+		public function GenericEvent(bubbles:Boolean = false)
+		{
+			_bubbles = bubbles;
+		}
+		
+		/** @inheritDoc */
+		public function get signal():IDeluxeSignal { return _signal; }
+		public function set signal(value:IDeluxeSignal):void { _signal = value; }
+		
+		/** @inheritDoc */
+		public function get target():Object { return _target; }
+		public function set target(value:Object):void { _target = value; }
+		
+		/** @inheritDoc */
+		public function get currentTarget():Object { return _currentTarget; }
+		public function set currentTarget(value:Object):void { _currentTarget = value; }
+		
+		/** @inheritDoc */
+		public function get bubbles():Boolean { return _bubbles; }
+		public function set bubbles(value:Boolean):void	{ _bubbles = value;	}
+		
+		/** @inheritDoc */
+		public function clone():IEvent
+		{
+			return new GenericEvent(_bubbles);
+		}
+	}
+}

data/src/org/osflash/signals/events/IBubbleEventHandler.as

@@ -0,0 +1,14 @@
+package org.osflash.signals.events
+{
+
+	public interface IBubbleEventHandler
+	{
+		/**
+		 * Handler for event bubbling.
+		 * It's left to the IBubbleEventHandler to decide what to do with the event.
+		 * @param	event The event that bubbled up.
+		 * @return whether to continue bubbling this event
+		 */
+		function onEventBubbled(event:IEvent):Boolean; 
+	}
+}

data/src/org/osflash/signals/events/IEvent.as

@@ -0,0 +1,27 @@
+package org.osflash.signals.events
+{
+	import org.osflash.signals.IDeluxeSignal;
+
+	public interface IEvent
+	{
+		/** The object that originally dispatched the event.
+		 *  When dispatched from an signal, the target is the object containing the signal. */
+		function get target():Object;
+		function set target(value:Object):void;
+		
+		/** The object that added the listener for the event. */
+		function get currentTarget():Object;
+		function set currentTarget(value:Object):void;
+		
+		/** The signal that dispatched the event. */
+		function get signal():IDeluxeSignal;
+		function set signal(value:IDeluxeSignal):void;
+		
+		/** Indicates whether the event is a bubbling event. */
+		function get bubbles():Boolean;
+		function set bubbles(value:Boolean):void;
+		
+		/** Returns a new copy of the instance. */
+		function clone():IEvent;
+	}
+}

data/src/org/osflash/signals/natives/INativeDispatcher.as

@@ -0,0 +1,34 @@
+package org.osflash.signals.natives
+{
+	import flash.events.Event;
+	import flash.events.IEventDispatcher;
+
+	/**
+	 * Similar to IDispatcher but using strong types specific to Flash's native event system.
+	 */
+	public interface INativeDispatcher
+	{
+		/**
+		 * The type of event permitted to be dispatched. Corresponds to flash.events.Event.type.
+		 */
+		function get eventType():String;
+		
+		/**
+		 * The class of event permitted to be dispatched. Will be flash.events.Event or a subclass.
+		 */
+		function get eventClass():Class;
+		
+		/**
+		 * The object considered the source of the dispatched events.
+		 */
+		function get target():IEventDispatcher;
+
+		/**
+		 * Dispatches an event to listeners.
+		 * @param	event			An instance of a class that is or extends flash.events.Event.
+		 * @throws	ArgumentError	<code>ArgumentError</code>:	Event object [event] is not an instance of [eventClass].
+		 * @throws	ArgumentError	<code>ArgumentError</code>:	Event object has incorrect type. Expected [eventType] but was [event.type].
+		 */
+		function dispatch(event:Event):Boolean;
+	}
+}