Merge branch 'release-0.5'

CHANGELOG.markdown

@@ -2,6 +2,41 @@
 
 
 
+## v0.5 (2010/12/03) ##
+
+### API changes ###
+
+ - Added:
+   - `SignalBinding.prototype.getListener()` (issue #3)
+   - `Signal.dispose()` (issue #6)
+   - `signals.VERSION`
+   - `signals.isDef()`
+
+ - Removed:
+  - `SignalBinding.listener` (issue #3)
+
+ - Renamed:
+  - `SignalBinding.listenerScope` -> `SignalBinding.context` (issue #4)
+
+### Fixes ###
+
+ - Removed unnecessary function names (issue #5)
+ - Improved `remove()`, `removeAll()` to dispose binding (issue #10)
+
+### Test Changes ###
+
+ - Added different HTML files to test dev/dist/min files. 
+ - Updated test cases to match new API.
+
+### Other ###
+
+ - Improved source code comments and documentation.
+ - Small refactoring for better organization and DRY. 
+ - Added error messages for required params.
+ - Removed unnecessary info from `SignalBinding.toString()`.
+
+
+
 ## v0.4 (2010/11/27) ##
 
 ### API changes ###
@@ -45,7 +80,7 @@
 
 ### Other ###
 
-Added inline documentation to source codeand included an HTML version of the documentation together with distribution files.
+Added inline documentation to source code and included an HTML version of the documentation together with distribution files.
 
 
 

build.xml

@@ -33,6 +33,7 @@
 		<concat destfile="${dist.dir}/${dist.name}" fixlastline="yes" eol="unix">
 			<filelist dir="${src.dir}">
 				<file name="intro.js" />
+				<file name="signals.js" />
 				<file name="Signal.js" />
 				<file name="SignalBinding.js" />
 				<file name="outro.js" />
@@ -59,6 +60,7 @@
 		    <arg path="${yuicompressor.jar}" />
 		    <arg value="--charset" />
 		    <arg value="ANSI" />
+		    <arg value="-v" />
 		    <arg value="-o" />
 		    <targetfile />
 		    <mapper type="glob" from="${dist.name}" to="${dist.min.name}" />

dev/build/build.number

@@ -1,3 +1,3 @@
 #Build Number for ANT. Do not edit!
-#Sat Nov 27 16:19:16 EST 2010
-build.number=65
+#Fri Dec 03 17:27:32 EST 2010
+build.number=101

dev/build/build.properties

@@ -6,6 +6,6 @@ docs.dir = ${dist.dir}/docs
 jsdoc-toolkit.dir = ${build.dir}/jsdoc-toolkit
 yuicompressor.jar = ${build.dir}/yuicompressor/yuicompressor-2.4.2.jar
 product.name = js-signals
-version.number = 0.4
+version.number = 0.5
 dist.name = ${product.name}.js
 dist.min.name = ${product.name}.min.js

dev/src/Signal.js

@@ -1,12 +1,13 @@
 
 	/**
-	 * Signal - custom event broadcaster inpired by Robert Penner's AS3Signals <https://github.com/robertpenner/as3-signals/>
+	 * Signal - custom event broadcaster
+	 * <br />- inspired by Robert Penner's AS3 Signals.
 	 * @author Miller Medeiros
 	 * @constructor
 	 */
 	signals.Signal = function(){
 		/**
-		 * @type Array.<SignalBinding>
+		 * @type Array.<signals.SignalBinding>
 		 * @private
 		 */
 		this._bindings = [];
@@ -30,18 +31,21 @@
 		/**
 		 * @param {Function} listener
 		 * @param {boolean} isOnce
-		 * @param {Object} scope
+		 * @param {Object} [scope]
 		 * @return {signals.SignalBinding}
 		 * @private
 		 */
-		_registerListener : function _registerListener(listener, isOnce, scope){
+		_registerListener : function(listener, isOnce, scope){
+
+			if(!signals.isDef(listener)) throw new Error('listener is a required param of add() and addOnce().');
+
 			var prevIndex = this._indexOfListener(listener),
 				binding;
 
 			if(prevIndex !== -1){ //avoid creating a new Binding for same listener if already added to list
 				binding = this._bindings[prevIndex];
 				if(binding.isOnce() !== isOnce){
-					throw new Error('You cannot '+ (isOnce? 'add()' : 'addOnce()') +' then '+ (!isOnce? 'add()' : 'addOnce()') +' the same listener without removing the relationship first.');
+					throw new Error('You cannot add'+ (isOnce? '' : 'Once') +'() then add'+ (!isOnce? '' : 'Once') +'() the same listener without removing the relationship first.');
 				}
 			} else {
 				binding = new signals.SignalBinding(listener, isOnce, scope, this);
@@ -55,7 +59,7 @@
 		 * @param {signals.SignalBinding} binding
 		 * @private
 		 */
-		_addBinding : function _addBinding(binding){
+		_addBinding : function(binding){
 			this._bindings.push(binding);
 		},
 
@@ -64,97 +68,108 @@
 		 * @return {int}
 		 * @private
 		 */
-		_indexOfListener : function _indexOfListener(listener){
+		_indexOfListener : function(listener){
 			var n = this._bindings.length;
 			while(n--){
-				if(this._bindings[n].listener === listener) return n;
+				if(this._bindings[n]._listener === listener) return n;
 			}
 			return -1;
 		},
 
 		/**
 		 * Add a listener to the signal.
 		 * @param {Function} listener	Signal handler function.
-		 * @param {Object} scope	Context on which listener will be executed (object that should represent the `this` variable inside listener function).
+		 * @param {Object} [scope]	Context on which listener will be executed (object that should represent the `this` variable inside listener function).
 		 * @return {signals.SignalBinding} An Object representing the binding between the Signal and listener.
 		 */
-		add : function add(listener, scope){
+		add : function(listener, scope){
 			return this._registerListener(listener, false, scope);
 		},
 
 		/**
 		 * Add listener to the signal that should be removed after first execution (will be executed only once).
 		 * @param {Function} listener	Signal handler function.
-		 * @param {Object} scope	Context on which listener will be executed (object that should represent the `this` variable inside listener function).
+		 * @param {Object} [scope]	Context on which listener will be executed (object that should represent the `this` variable inside listener function).
 		 * @return {signals.SignalBinding} An Object representing the binding between the Signal and listener.
 		 */
-		addOnce : function addOnce(listener, scope){
+		addOnce : function(listener, scope){
 			return this._registerListener(listener, true, scope);
 		},
 
+		/**
+		 * @private
+		 */
+		_removeByIndex : function(i){
+			this._bindings[i]._destroy(); //no reason to a SignalBinding exist if it isn't attached to a signal
+			this._bindings.splice(i, 1);
+		},
+
 		/**
 		 * Remove a single listener from the dispatch queue.
 		 * @param {Function} listener	Handler function that should be removed.
 		 * @return {Function} Listener handler function.
 		 */
-		remove : function remove(listener){
+		remove : function(listener){
+			if(!signals.isDef(listener)) throw new Error('listener is a required param of remove().');
+
 			var i = this._indexOfListener(listener);
-			if(i !== -1){
-				this._bindings.splice(i, 1);
-			}
+			if(i !== -1) this._removeByIndex(i);
 			return listener;
 		},
 
 		/**
 		 * Remove all listeners from the Signal.
 		 */
-		removeAll : function removeAll(){
-			this._bindings.length = 0;
+		removeAll : function(){
+			var n = this._bindings.length;
+			while(n--){
+				this._removeByIndex(n);
+			}
 		},
 
 		/**
 		 * @return {uint} Number of listeners attached to the Signal.
 		 */
-		getNumListeners : function getNumListeners(){
+		getNumListeners : function(){
 			return this._bindings.length;
 		},
 
 		/**
 		 * Disable Signal, will block dispatch to listeners until `enable()` is called.
 		 * @see signals.Signal.prototype.enable
 		 */
-		disable : function disable(){
+		disable : function(){
 			this._isEnabled = false;
 		},
 
 		/**
 		 * Enable broadcast to listeners.
 		 * @see signals.Signal.prototype.disable
 		 */
-		enable : function enable(){
+		enable : function(){
 			this._isEnabled = true;
 		}, 
 
 		/**
 		 * @return {boolean} If Signal is currently enabled and will broadcast message to listeners.
 		 */
-		isEnabled : function isEnabled(){
+		isEnabled : function(){
 			return this._isEnabled;
 		},
 
 		/**
 		 * Stop propagation of the event, blocking the dispatch to next listeners on the queue.
 		 * - should be called only during signal dispatch, calling it before/after dispatch won't affect signal broadcast. 
 		 */
-		halt : function halt(){
+		halt : function(){
 			this._shouldPropagate = false;
 		},
 
 		/**
 		 * Dispatch/Broadcast Signal to all listeners added to the queue. 
-		 * @param {...*} params	Parameters that should be passed to each handler.
+		 * @param {...*} [params]	Parameters that should be passed to each handler.
 		 */
-		dispatch : function dispatch(params){
+		dispatch : function(params){
 			if(! this._isEnabled) return;
 
 			var paramsArr = Array.prototype.slice.call(arguments),
@@ -169,10 +184,19 @@
 			}
 		},
 
+		/**
+		 * Remove binding from signal and destroy any reference to external Objects (destroy Signal object).
+		 * <br /> - calling methods on the signal instance after calling dispose will throw errors.
+		 */
+		dispose : function(){
+			this.removeAll();
+			delete this._bindings;
+		},
+
 		/**
 		 * @return {string} String representation of the object.
 		 */
-		toString : function toString(){
+		toString : function(){
 			return '[Signal isEnabled: '+ this._isEnabled +' numListeners: '+ this.getNumListeners() +']';
 		}