as3signals 0.7.0

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

@@ -0,0 +1,230 @@
+package org.osflash.signals.natives
+{
+	import flash.events.Event;
+	import flash.events.IEventDispatcher;
+
+	/**
+	 * <p>
+	 * The NativeMappedSignal class is used to map/transform a native Event, 
+	 * relayed from an IEventDispatcher, into other forms of data, 
+	 * which are dispatched to all listeners.
+	 * </p>
+	 * <p>This can be used to form a border where native flash Events do not cross.</p>
+	 */
+	public class NativeMappedSignal extends NativeRelaySignal
+	{
+		/**
+		 * @default is initialized to flash.events.Event in constructor if omitted as parameter
+		 */
+		protected var _eventClass:Class;
+		
+		public function get eventClass ():Class 
+		{
+			return _eventClass;
+		}
+		
+		/**
+		 * @default is null, no mapping will occur 
+		 */		
+		private var _mappingFunction:Function = null;
+		
+		/*open for extension but closed for modifications*/
+		protected function get mappingFunction ():Function 
+		{
+			return _mappingFunction;
+		}
+		
+		/**
+		 * Creates a new NativeMappedSignal instance to map/transform a native Event, 
+	 	 * relayed from an IEventDispatcher, into other forms of data, 
+	 	 * which are dispatched to all listeners.
+		 * 
+		 * @param	target	An object that implements the flash.events.IEventDispatcher interface.
+		 * @param	eventType The event string name that would normally be passed to IEventDispatcher.addEventListener().
+		 * @param 	eventClass An optional class reference that enables an event type check in dispatch().
+		 * @param	mappedTypes an optional list of types that enables the checking of the types mapped from an Event. 
+		 */
+		public function NativeMappedSignal(target:IEventDispatcher, eventType:String, eventClass:Class=null, ... mappedTypes)
+		{
+			_eventClass = eventClass || Event;
+			super(target, eventType);
+			setValueClasses(mappedTypes);
+		}
+		
+		/**
+		 * Sets the mapping function or literal object list.
+		 * If the argument is a list of object literals then this list is dispatched to listeners.
+		 * 
+		 * <listing version="3.0">
+		 *  signal = new NativeMappedSignal(button, MouseEvent.CLICK, MouseEvent, String).mapTo("ping")
+		 *  signal.add(function(arg:String):void { trace(arg) }) // prints "ping"
+		 * </listing>
+		 * 
+		 * And an example passing a list of literals:
+		 * 
+		 * <listing version="3.0">
+		 *  signal = new NativeMappedSignal(button, MouseEvent.CLICK, MouseEvent, String, int, Number).mapTo("ping", 3, 3.1415)
+		 *  signal.add(function(arg1:String, arg2:int, arg3:Number):void { trace(arg1, arg2, arg3) }) // prints "ping", 3, 3.1415
+		 * </listing>
+		 * 
+		 * If the argument is a function then it is called when the event this NativeMappedSignal is listeneing for is dispatched.
+		 * The function should return an Array or a single object. The data returned from the function is passed along as arguemnts in the Signal dispatch.
+		 * Lets look at some examples of mapping functions and the function that is called back:
+		 * 
+		 * <listing version="3.0">
+		 *  signal = new NativeMappedSignal(button, MouseEvent.CLICK, MouseEvent, String).mapTo(function():void { 
+		 *    return "ping"
+		 *  })
+		 *  signal.add(function(arg:String):void { trace(arg) }) // prints "ping"
+		 * </listing>
+		 * 
+		 * and here's an example using a list of arguments:
+		 * 
+		 * <listing version="3.0">
+		 *  signal = new NativeMappedSignal(button, MouseEvent.CLICK, MouseEvent, String, int, Number).mapTo(function():void { 
+		 *    return ["ping", 3, 3.1415] 
+		 *  })
+		 * 	signal.add(function(arg1:String, arg2:int, arg3:Number):void { trace(arg1, arg2, arg3) }) // prints "ping", 3, 3.1415
+		 * </listing>
+		 * 
+		 * You can also state your wish to receive the native Event in th mapping function by simply including an argument of type Event:
+		 * 
+		 * <listing version="3.0">
+		 *  signal = new NativeMappedSignal(button, MouseEvent.CLICK, MouseEvent, Point).mapTo(function(event:MouseEvent):void { 
+		 *    return new Point(event.localX, event.localY)
+		 *  })
+		 *  signal.add(function(arg:Point):void { trace(arg) }) // prints "(x=128, y=256)"
+		 * </listing> 
+		 * 
+		 * @param objectListOrFunction This can either be a list of object literals or a function that returns list of objects. 
+		 * @return The NativeMappedSignal object this method was called on. This allows the Signal to be defined and mapped in one statement.
+		 */		
+		public function mapTo(...objectListOrFunction):NativeMappedSignal
+		{
+			if (isArgumentListAFunction(objectListOrFunction))
+			{
+				_mappingFunction = objectListOrFunction[0] as Function;
+				
+				if (hasFunctionMoreThanOneArgument(_mappingFunction))
+				{	
+					throw new ArgumentError('Mapping function has ' + _mappingFunction.length 
+						+ ' arguments but it needs zero or one of type Event');
+				}
+			}
+			else
+			{
+				_mappingFunction = function ():Object { return objectListOrFunction; };
+			}
+			
+			return this;
+		}
+		
+		private function isArgumentListAFunction(argList:Array):Boolean
+		{
+			return argList.length == 1 && argList[0] is Function;
+		}
+		
+		private function hasFunctionMoreThanOneArgument(f:Function):Boolean
+		{
+			return f.length > 1;
+		}
+		
+		/**
+		 * This is used as eventHandler for target or can be called directly with the parameters specified by valueClasses.
+		 * <p>If used as eventHandler the data mapping system is used to supply the super.dispatch with alternative data to dispatch.</p>
+		 *
+		 * @see #mapEvent()
+		 * @see #mapTo()
+		 * @see org.osflash.signals.NativeRelaySignal#dispatch()
+		 */
+		override public function dispatch (... valueObjects):void 
+		{
+			if (areValueObjectValidForMapping(valueObjects)) 
+			{
+				var mappedData:Object = mapEvent(valueObjects[0] as Event);
+				dispatchMappedData(mappedData);
+			} 
+			else 
+			{
+				super.dispatch.apply(null, valueObjects);
+			}
+		}
+
+		private function areValueObjectValidForMapping(valueObjects:Array):Boolean
+		{
+			return valueObjects.length == 1 && valueObjects[0] is _eventClass;
+		}
+		
+		private function dispatchMappedData(mappedData:Object):void
+		{
+			if (mappedData is Array)
+			{
+				if (shouldArrayBePassedWithoutUnrolling)
+				{
+					super.dispatch.call(null, mappedData);
+				}
+				else
+				{
+					super.dispatch.apply(null, mappedData);
+				}
+			}
+			else
+			{
+				super.dispatch.call(null, mappedData);
+			}
+		}
+		
+		private function get shouldArrayBePassedWithoutUnrolling():Boolean
+		{
+			return _valueClasses.length == 1 && _valueClasses[0] == Array;
+		}
+		
+		protected function get mappingFunctionWantsEvent():Boolean
+		{
+			return _mappingFunction.length == 1;
+		}
+		
+		protected function get mappingFunctionExists():Boolean
+		{
+			return _mappingFunction != null;
+		}
+		
+		/**
+		 * For usage without extension, instances of <code>NativeMappedSignal</code> that are dispatching any values ( <code>valueClasses.length > 0</code> ),
+		 * needs to be provided with a either a mapping function or a list of object literals.
+		 * See <code>mapTo</code> for more info.
+		 * 
+		 * Subcclasses could override this one instead of letting the environment set the mapTo,
+		 * MAKE SURE to also override <code>mapTo(...)</code> if it should not be allowed.
+		 *
+		 * @parameter eventFromTarget the event that was dispatched from target.
+		 * @return An object or Array of objects mapped from an Event. The mapping of Event to data will be performed by the mapping function
+		 * if it is set. A list of object literals can also be supplied in place of the mapping function.
+		 * If no mapping function or object literals are supplied then an empty Array is returned or
+		 * if <code>valueClasses.length > 0</code> an ArgumentError is thrown.
+		 *
+		 * @see #mapTo()
+		 */
+		protected function mapEvent (eventFromTarget:Event):Object 
+		{
+			if (mappingFunctionExists) 
+			{
+				if (mappingFunctionWantsEvent)
+				{
+					return _mappingFunction(eventFromTarget);
+				}
+				else
+				{
+					return _mappingFunction();
+				}
+			} 
+			else if (valueClasses.length == 0) 
+			{
+				return [];
+			}
+			
+			throw new ArgumentError("There are valueClasses set to be dispatched <" + valueClasses 
+				+ "> but mappingFunction is null.");
+		}
+	}
+}

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

@@ -0,0 +1,71 @@
+package org.osflash.signals.natives
+{
+	import org.osflash.signals.DeluxeSignal;
+
+	import flash.events.Event;
+	import flash.events.IEventDispatcher;
+
+	/**
+	 * The NativeRelaySignal class is used to relay events from an IEventDispatcher
+	 * to listeners.
+	 * The difference as compared to NativeSignal is that
+	 * NativeRelaySignal has its own dispatching code,
+	 * whereas NativeSignal uses the IEventDispatcher to dispatch.
+	 */
+	public class NativeRelaySignal extends DeluxeSignal
+	{
+		protected var _eventType:String;
+
+		/**
+		 * Creates a new NativeRelaySignal instance to relay events from an IEventDispatcher.
+		 * @param	target	An object that implements the flash.events.IEventDispatcher interface.
+		 * @param	name	The event string name that would normally be passed to IEventDispatcher.addEventListener().
+		 * @param	eventClass An optional class reference that enables an event type check in dispatch().
+		 * Because the target is an IEventDispatcher,
+		 * eventClass needs to be flash.events.Event or a subclass of it.
+		 */
+		public function NativeRelaySignal(target:IEventDispatcher, eventType:String, eventClass:Class = null)
+		{
+			super(target, eventClass || Event);
+			_eventType = eventType;
+		}
+		
+		/** @inheritDoc */
+		override public function addWithPriority(listener:Function, priority:int = 0):Function
+		{
+			var prevListenerCount:uint = listenerBoxes.length;
+			// Try to add first because it may throw an exception.
+			super.addWithPriority(listener);
+			// Account for cases where the same listener is added twice.
+			if (prevListenerCount == 0 && listenerBoxes.length == 1)
+				IEventDispatcher(_target).addEventListener(_eventType, dispatch, false, priority);
+			
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		override public function addOnceWithPriority(listener:Function, priority:int = 0):Function
+		{
+			var prevListenerCount:uint = listenerBoxes.length;
+			// Try to add first because it may throw an exception.
+			super.addOnceWithPriority(listener);
+			// Account for cases where the same listener is added twice.
+			if (prevListenerCount == 0 && listenerBoxes.length == 1)
+				IEventDispatcher(_target).addEventListener(_eventType, dispatch, false, priority);
+			
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		override public function remove(listener:Function):Function
+		{
+			var prevListenerCount:uint = listenerBoxes.length;
+			super.remove(listener);
+			if (prevListenerCount == 1 && listenerBoxes.length == 0)
+				IEventDispatcher(_target).removeEventListener(_eventType, dispatch);
+			
+			return listener;
+		}
+		
+	}
+}

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

@@ -0,0 +1,176 @@
+package org.osflash.signals.natives
+{
+	import org.osflash.signals.IDeluxeSignal;
+
+	import flash.errors.IllegalOperationError;
+	import flash.events.Event;
+	import flash.events.IEventDispatcher;
+
+	/**
+	 * The NativeSignal class provides a strongly-typed facade for an IEventDispatcher.
+	 * A NativeSignal is essentially a mini-dispatcher locked to a specific event type and class.
+	 * It can become part of an interface.
+	 */
+	public class NativeSignal implements IDeluxeSignal, INativeDispatcher
+	{
+		protected var _target:IEventDispatcher;
+		protected var _eventType:String;
+		protected var _eventClass:Class;
+		protected var listenerBoxes:Array;
+				
+		/**
+		 * Creates a NativeSignal instance to dispatch events on behalf of a target object.
+		 * @param	target The object on whose behalf the signal is dispatching events.
+		 * @param	eventType The type of Event permitted to be dispatched from this signal. Corresponds to Event.type.
+		 * @param	eventClass An optional class reference that enables an event type check in dispatch(). Defaults to flash.events.Event if omitted.
+		 */
+		public function NativeSignal(target:IEventDispatcher, eventType:String, eventClass:Class = null)
+		{
+			_target = target;
+			_eventType = eventType;
+			_eventClass = eventClass || Event;
+			listenerBoxes = [];
+		}
+		
+		/** @inheritDoc */
+		public function get eventType():String { return _eventType; }
+		
+		/** @inheritDoc */
+		public function get eventClass():Class { return _eventClass; }
+		
+		/** @inheritDoc */
+		public function get valueClasses():Array { return [_eventClass]; }
+		
+		/** @inheritDoc */
+		public function get numListeners():uint { return listenerBoxes.length; }
+		
+		/** @inheritDoc */
+		public function get target():IEventDispatcher { return _target; }
+		
+		/** @inheritDoc */
+		public function set target(value:IEventDispatcher):void
+		{
+			if (value == _target) return;
+			removeAll();
+			_target = value;
+		}
+		
+		/** @inheritDoc */
+		//TODO: @throws
+		public function add(listener:Function):Function
+		{
+			return addWithPriority(listener)
+		}
+		
+		/** @inheritDoc */
+		//TODO: @throws
+		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
+		{
+			var listenerIndex:int = indexOfListener(listener);
+			if (listenerIndex == -1) return listener;
+			var listenerBox:Object = listenerBoxes.splice(listenerIndex, 1)[0];
+			// For once listeners, execute is a wrapper function around the listener.
+			_target.removeEventListener(_eventType, listenerBox.execute);
+			return listener;
+		}
+		
+		/** @inheritDoc */
+		public function removeAll():void
+		{
+			for (var i:int = listenerBoxes.length; i--; )
+			{
+				remove(listenerBoxes[i].listener as Function);
+			}
+		}
+		
+		/**
+		 * Unlike other signals, NativeSignal does not dispatch null
+		 * because it causes an exception in EventDispatcher.
+		 * @inheritDoc
+		 */
+		public function dispatch(event:Event):Boolean
+		{
+			if (!(event is _eventClass))
+				throw new ArgumentError('Event object '+event+' is not an instance of '+_eventClass+'.');
+				
+			if (event.type != _eventType)
+				throw new ArgumentError('Event object has incorrect type. Expected <'+_eventType+'> but was <'+event.type+'>.');
+
+			return _target.dispatchEvent(event);
+		}
+		
+		protected function registerListener(listener:Function, once:Boolean = false, priority:int = 0):void
+		{
+			// function.length is the number of arguments.
+			if (listener.length != 1)
+				throw new ArgumentError('Listener for native event must declare exactly 1 argument.');
+				
+			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;
+			}
+			
+			var listenerBox:Object = { listener:listener, once:once, execute:listener };
+			
+			if (once)
+			{
+				var signal:NativeSignal = this;
+				// For once listeners, create a wrapper function to automatically remove the listener.
+				listenerBox.execute = function(event:Event):void
+				{
+					signal.remove(listener);
+					listener(event);
+				};
+			}
+			
+			listenerBoxes[listenerBoxes.length] = listenerBox;
+			_target.addEventListener(_eventType, listenerBox.execute, false, priority);
+		}
+		
+		/**
+		 *
+		 * @param	listener	A handler function that may have been added previously.
+		 * @return	The index of the listener in the listenerBoxes array, or -1 if not found.
+		 */
+		protected function indexOfListener(listener:Function):int
+		{
+			for (var i:int = listenerBoxes.length; i--; )
+			{
+				if (listenerBoxes[i].listener == listener) return i;
+			}
+			return -1;
+		}
+	}
+}

data/tests/org/osflash/signals/AllTests.as

@@ -0,0 +1,44 @@
+package org.osflash.signals
+{
+	import org.osflash.signals.natives.AmbiguousRelationshipInNativeSignalTest;
+	import org.osflash.signals.natives.NativeMappedSignalBoundaryUseTest;
+	import org.osflash.signals.natives.NativeMappedSignalDefaultsTest;
+	import org.osflash.signals.natives.NativeMappedSignalFunctionArgTest;
+	import org.osflash.signals.natives.NativeMappedSignalFunctionNoArgsTest;
+	import org.osflash.signals.natives.NativeMappedSignalObjectArgTest;
+	import org.osflash.signals.natives.NativeRelaySignalTest;
+	import org.osflash.signals.natives.NativeSignalTest;
+
+	[Suite]
+	public class AllTests
+	{
+		public var _AmbiguousRelationshipTest:AmbiguousRelationshipTest;
+		public var _AmbiguousRelationshipInNativeSignalTest:AmbiguousRelationshipInNativeSignalTest;
+		public var _GenericEventTest:GenericEventTest;
+		public var _NativeRelaySignalTest:NativeRelaySignalTest;
+		public var _NativeSignalTest:NativeSignalTest;
+		public var _NativeMappedSignalDefaultsTest:NativeMappedSignalDefaultsTest;
+		public var _NativeMappedSignalObjectArgTest:NativeMappedSignalObjectArgTest;
+		public var _NativeMappedSignalFunctionNoArgsTest:NativeMappedSignalFunctionNoArgsTest;
+		public var _NativeMappedSignalFunctionArgTest:NativeMappedSignalFunctionArgTest;
+		public var _NativeMappedSignalBoundaryUseTest:NativeMappedSignalBoundaryUseTest;
+		public var _PriorityListenersTest:PriorityListenersTest;
+		public var _RedispatchedEventTest:RedispatchedEventTest;
+		public var _DeluxeSignalAmbiguousRelationshipTest:DeluxeSignalAmbiguousRelationshipTest;
+		public var _DeluxeSignalTest:DeluxeSignalTest;
+		public var _DeluxeSignalDispatchExtraArgsTest:DeluxeSignalDispatchExtraArgsTest;
+		public var _DeluxeSignalDispatchNoArgsTest:DeluxeSignalDispatchNoArgsTest;
+		public var _DeluxeSignalDispatchNonEventTest:DeluxeSignalDispatchNonEventTest;
+		public var _DeluxeSignalSplitInterfacesTest:DeluxeSignalSplitInterfacesTest;
+		public var _DeluxeSignalWithBubblingEventTest:DeluxeSignalWithBubblingEventTest;
+		public var _DeluxeSignalWithCustomEventTest:DeluxeSignalWithCustomEventTest;
+		public var _DeluxeSignalWithGenericEventTest:DeluxeSignalWithGenericEventTest;
+		
+		public var _SignalDispatchExtraArgsTest:SignalDispatchArgsTest;
+		public var _SignalDispatchNoArgsTest:SignalDispatchNoArgsTest;
+		public var _SignalDispatchNonEventTest:SignalDispatchNonEventTest;
+		public var _SignalSplitInterfacesTest:SignalSplitInterfacesTest;
+		public var _SignalTest:SignalTest;
+		public var _SignalWithCustomEventTest:SignalWithCustomEventTest;
+	}
+}

data/tests/org/osflash/signals/AllTestsRunner.as

@@ -0,0 +1,19 @@
+package org.osflash.signals
+{
+	import asunit.core.TextCore;
+
+	import flash.display.MovieClip;
+
+	[SWF(width='1000', height='800', backgroundColor='#333333', frameRate='31')]
+	public class AllTestsRunner extends MovieClip
+	{
+        private var core:TextCore;
+
+		public function AllTestsRunner()
+		{
+            core = new TextCore();
+			core.start(AllTests, null, this);
+		}
+	}
+}
+

data/tests/org/osflash/signals/AmbiguousRelationshipTest.as

@@ -0,0 +1,60 @@
+package org.osflash.signals
+{
+	import asunit.asserts.*;
+
+	public class AmbiguousRelationshipTest
+	{
+		private var target:Object;
+		
+		private var instance:Signal;
+
+		[Before]
+		public function setUp():void
+		{
+			target = {};
+			instance = new Signal();
+		}
+
+		[After]
+		public function tearDown():void
+		{
+			instance = null;
+		}
+		
+		[Test(expects="flash.errors.IllegalOperationError")]
+		public function add_then_addOnce_throws_error():void
+		{
+			instance.add(failIfCalled);
+			instance.addOnce(failIfCalled);
+		}
+		
+		[Test(expects="flash.errors.IllegalOperationError")]
+		public function addOnce_then_add_should_throw_error():void
+		{
+			instance.addOnce(failIfCalled);
+			instance.add(failIfCalled);
+		}
+		
+		[Test]
+		public function add_then_add_should_not_throw_error():void
+		{
+			instance.add(failIfCalled);
+			instance.add(failIfCalled);
+			assertEquals(1, instance.numListeners);
+		}
+		
+		[Test]
+		public function addOnce_then_addOnce_should_not_throw_error():void
+		{
+			instance.addOnce(failIfCalled);
+			instance.addOnce(failIfCalled);
+			assertEquals(1, instance.numListeners);
+		}
+		
+		private function failIfCalled():void
+		{
+			fail("if this listener is called, something horrible is going on");
+		}
+		
+	}
+}

data/tests/org/osflash/signals/DeluxeSignalAmbiguousRelationshipTest.as

@@ -0,0 +1,60 @@
+package org.osflash.signals
+{
+	import asunit.asserts.*;
+
+	public class DeluxeSignalAmbiguousRelationshipTest
+	{
+		private var target:Object;
+		
+		private var instance:DeluxeSignal;
+
+		[Before]
+		public function setUp():void
+		{
+			target = {};
+			instance = new DeluxeSignal(target);
+		}
+
+		[After]
+		public function tearDown():void
+		{
+			instance = null;
+		}
+		
+		[Test(expects="flash.errors.IllegalOperationError")]
+		public function add_then_addOnce_throws_error():void
+		{
+			instance.add(failIfCalled);
+			instance.addOnce(failIfCalled);
+		}
+		
+		[Test(expects="flash.errors.IllegalOperationError")]
+		public function addOnce_then_add_should_throw_error():void
+		{
+			instance.addOnce(failIfCalled);
+			instance.add(failIfCalled);
+		}
+		
+		[Test]
+		public function add_then_add_should_not_throw_error():void
+		{
+			instance.add(failIfCalled);
+			instance.add(failIfCalled);
+			assertEquals(1, instance.numListeners);
+		}
+		
+		[Test]
+		public function addOnce_then_addOnce_should_not_throw_error():void
+		{
+			instance.addOnce(failIfCalled);
+			instance.addOnce(failIfCalled);
+			assertEquals(1, instance.numListeners);
+		}
+		
+		private function failIfCalled():void
+		{
+			fail("if this listener is called, something horrible is going on");
+		}
+		
+	}
+}