Merge branch 'release-0.5.3'

CHANGELOG.markdown

@@ -2,6 +2,18 @@
 
 
 
+## v0.5.3 (2011/02/21) ##
+
+### API changes ###
+
+ - added priority parameter to `add` and `addOnce`.
+
+### Other ###
+
+ - improved code structure.
+
+
+
 ## v0.5.2 (2011/02/18) ##
 
 ### Other ###

README.markdown

@@ -1,7 +1,9 @@
 
 # JS-Signals #
 
-Custom event/messaging system for JavaScript inspired by [AS3-Signals](https://github.com/robertpenner/as3-signals). For a more in-depth introduction read the [JS-Signals Project Page](http://millermedeiros.github.com/js-signals/) and visit the links below.
+Custom event/messaging system for JavaScript inspired by [AS3-Signals](https://github.com/robertpenner/as3-signals).
+
+For a more in-depth introduction read the [JS-Signals Project Page](http://millermedeiros.github.com/js-signals/) and visit the links below.
 
 
 ## Links ##
@@ -21,16 +23,27 @@ Custom event/messaging system for JavaScript inspired by [AS3-Signals](https://g
 
 ### Folder Structure ###
 
-    .\dev       ->  development files
-    ...\build       ->  files used on the build process
-    ...\src         ->  source files
-    ...\tests       ->  unit tests
-    .\dist      ->  distribution files
-    ...\docs        ->  documentation
+    dev       ->  development files
+    |- build       ->  files used on the build process
+    |- src         ->  source files
+    |- tests       ->  unit tests
+    dist      ->  distribution files
+    |- docs        ->  documentation
 
 ### Branches ###
 
     master      ->  always contain code from the latest stable version
     release-**  ->  code canditate for the next stable version (alpha/beta)
     develop     ->  main development branch (nightly)
     **other**   ->  features/hotfixes/experimental, probably non-stable code
+
+
+## Building your own ##
+
+This project uses [Apache Ant](http://ant.apache.org/) for the build process. If for some reason you need to build a custom version of JS-Signals install Ant and run:
+
+    ant build
+
+This will delete all JS files inside the `dist` folder, merge/update/compress source files (`dev/src`), validate generated code using [JSLint](http://www.jslint.com/) and copy the output to the `dist` folder.
+
+**IMPORTANT:** `dist` folder always contain the latest version, regular users should **not** need to run build task.

dev/build/build.number

@@ -1,3 +1,3 @@
 #Build Number for ANT. Do not edit!
-#Fri Feb 18 19:22:48 EST 2011
-build.number=139
+#Mon Feb 21 19:18:50 EST 2011
+build.number=144

dev/build/build.properties

@@ -11,7 +11,7 @@ jslint.jar = ${build.dir}/jslint4java/jslint4java-1.4.6.jar
 yuitest-coverage.jar = ${build.dir}/yuitest-coverage/yuitest-coverage-0.5.5.jar
 yuitest-coverage-report.jar = ${build.dir}/yuitest-coverage/yuitest-coverage-report-0.5.5.jar
 product.name = js-signals
-version.number = 0.5.2
+version.number = 0.5.3
 dist.name = ${product.name}.js
 dist.min.name = ${product.name}.min.js
 dist.inst.name = ${product.name}.inst.js

dev/src/Signal.js

@@ -1,3 +1,4 @@
+/*global signals:true, SignalBinding:true*/
 
 	// Signal --------------------------------------------------------
 	//================================================================
@@ -34,10 +35,11 @@
 		 * @param {Function} listener
 		 * @param {boolean} isOnce
 		 * @param {Object} [scope]
+		 * @param {Number} [priority]
 		 * @return {SignalBinding}
 		 * @private
 		 */
-		_registerListener : function(listener, isOnce, scope){
+		_registerListener : function(listener, isOnce, scope, priority){
 
 			if(typeof listener !== 'function'){
 				throw new Error('listener is a required param of add() and addOnce() and should be a Function.');
@@ -52,13 +54,24 @@
 					throw new Error('You cannot add'+ (isOnce? '' : 'Once') +'() then add'+ (!isOnce? '' : 'Once') +'() the same listener without removing the relationship first.');
 				}
 			} else {
-				binding = new SignalBinding(this, listener, isOnce, scope);
-				this._bindings.push(binding);
+				binding = new SignalBinding(this, listener, isOnce, scope, priority);
+				this._addBinding(binding);
 			}
 
 			return binding;
 		},
 
+		/**
+		 * @param {Function} binding
+		 * @private
+		 */
+		_addBinding : function(binding){
+			//simplified insertion sort
+			var n = this._bindings.length;
+			do { --n; } while (this._bindings[n] && binding._priority <= this._bindings[n]._priority);
+			this._bindings.splice(n+1, 0, binding);
+		},
+
 		/**
 		 * @param {Function} listener
 		 * @return {number}
@@ -78,20 +91,22 @@
 		 * 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 {Number} [priority]	The priority level of the event listener. Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added. (default = 0)
 		 * @return {SignalBinding} An Object representing the binding between the Signal and listener.
 		 */
-		add : function(listener, scope){
-			return this._registerListener(listener, false, scope);
+		add : function(listener, scope, priority){
+			return this._registerListener(listener, false, scope, priority);
 		},
 
 		/**
 		 * 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 {Number} [priority]	The priority level of the event listener. Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added. (default = 0)
 		 * @return {SignalBinding} An Object representing the binding between the Signal and listener.
 		 */
-		addOnce : function(listener, scope){
-			return this._registerListener(listener, true, scope);
+		addOnce : function(listener, scope, priority){
+			return this._registerListener(listener, true, scope, priority);
 		},
 
 		/**
@@ -175,17 +190,13 @@
 
 			var paramsArr = Array.prototype.slice.call(arguments),
 				bindings = this._bindings.slice(), //clone array in case add/remove items during dispatch
-				i,
 				n = this._bindings.length;
 
 			this._shouldPropagate = true; //in case `halt` was called before dispatch or during the previous dispatch.
-
-			for(i=0; i<n; i++){
-				//execute all callbacks until end of the list or until a callback returns `false` or stops propagation
-				if(bindings[i].execute(paramsArr) === false || !this._shouldPropagate){
-					break;
-				}
-			}
+
+			//execute all callbacks until end of the list or until a callback returns `false` or stops propagation
+			//reverse loop since listeners with higher priority will be added at the end of the list
+			do { n--; } while (bindings[n] && this._shouldPropagate && bindings[n].execute(paramsArr) !== false);
 		},
 
 		/**

dev/src/SignalBinding.js

@@ -1,20 +1,21 @@
-
 	// SignalBinding -------------------------------------------------
 	//================================================================
 
 	/**
 	 * Object that represents a binding between a Signal and a listener function.
-	 * <br />- <strong>This is an internall constructor and shouldn't be called by regular user.</strong>
+	 * <br />- <strong>This is an internal constructor and shouldn't be called by regular users.</strong>
 	 * <br />- inspired by Joa Ebert AS3 SignalBinding and Robert Penner's Slot classes.
 	 * @author Miller Medeiros
 	 * @constructor
+	 * @internal
 	 * @name signals.SignalBinding
 	 * @param {signals.Signal} signal	Reference to Signal object that listener is currently bound to.
 	 * @param {Function} listener	Handler function bound to the signal.
 	 * @param {boolean} isOnce	If binding should be executed just once.
 	 * @param {Object} [listenerContext]	Context on which listener will be executed (object that should represent the `this` variable inside listener function).
+	 * @param {Number} [priority]	The priority level of the event listener. (default = 0).
 	 */
-	 function SignalBinding(signal, listener, isOnce, listenerContext){
+	 function SignalBinding(signal, listener, isOnce, listenerContext, priority){
 
 		/**
 		 * Handler function bound to the signal.
@@ -44,6 +45,13 @@
 		 * @private
 		 */
 		this._signal = signal;
+
+		/**
+		 * Listener priority
+		 * @type Number
+		 * @private
+		 */
+		this._priority = priority || 0;
 	}
 
 	SignalBinding.prototype = /** @lends signals.SignalBinding.prototype */ {
@@ -68,7 +76,7 @@
 					this.detach();
 				}
 			}
-			return r; //avoid warnings on some editors
+			return r;
 		},
 
 		/**

dev/src/signals.js

@@ -7,22 +7,23 @@
  * @version ::VERSION_NUMBER::
  * @build ::BUILD_NUMBER:: (::BUILD_DATE::)
  */
-var signals = (function(){
-
-	/**
-	 * @namespace Signals Namespace - Custom event/messaging system based on AS3 Signals
-	 * @name signals
-	 */
-	var signals = {};
 
-	/**
-	 * Signals Version Number
-	 * @type string
-	 * @const
-	 */
-	signals.VERSION = '::VERSION_NUMBER::';
+/**
+ * @namespace Signals Namespace - Custom event/messaging system based on AS3 Signals
+ */
+var signals = (function(){
+
+	var signals = /** @lends signals */{
+		/**
+		 * Signals Version Number
+		 * @type string
+		 * @const
+		 */
+		VERSION : '::VERSION_NUMBER::'
+	};
 
 //::SIGNAL_BINDING_JS:://
+
 //::SIGNAL_JS:://
 
 	return signals;