Sequence.js

define([
	"dojo/_base/kernel",
	"dojo/_base/array",
	"dojo/_base/declare",
	"dojo/_base/lang",
	"./_base"
], function(dojo){
	dojo.experimental("dojox.timing.Sequence");

	return dojo.declare("dojox.timing.Sequence", null, {
		// summary:
		//	This class provides functionality to really sequentialize
		//	function calls. You need to provide a list of functions and
		//	some parameters for each (like: pauseBefore) and they will
		//	be run one after another. This can be very useful for slideshows
		//	or alike things.
		//
		// description:
		//	This array will contain the sequence defines resolved, so that
		// 	ie. repeat:10 will result in 10 elements in the sequence, so
		// 	the repeat handling is easier and we don't need to handle that
		// 	many extra cases. Also the doneFunction, if given is added at the
		// 	end of the resolved-sequences.

	/*=====
		// _defsResolved: Array
		// 	The resolved sequence, for easier handling.
		_defsResolved: [],
	=====*/

		// This is the time to wait before goOn() calls _go(), which
		// mostly results from a pauseAfter for a function that returned
		// false and is later continued by the external goOn() call.
		// The time to wait needs to be waited in goOn() where the
		// sequence is continued.

		// _goOnPause: Integer
		//	The pause to wait before really going on.
		_goOnPause: 0,

		_running: false,

		constructor: function(){
			this._defsResolved = [];
		},

		go: function(/* Array */defs, /* Function|Array? */doneFunction){
			// summary:
			//		Run the passed sequence definition
			// defs: Array
			//		The sequence of actions
			// doneFunction: Function|Array?
			//		The function to call when done
			this._running = true;
			dojo.forEach(defs, function(cur){
				if(cur.repeat > 1){
					var repeat = cur.repeat;
					for(var j = 0; j < repeat; j++){
						cur.repeat = 1;
						this._defsResolved.push(cur);
					}
				}else{
					this._defsResolved.push(cur);
				}
			}, this);
			var last = defs[defs.length - 1];
			if(doneFunction){
				this._defsResolved.push({ func: doneFunction });
			}
			// stop the sequence, this actually just sets this._running to false
			this._defsResolved.push({ func: [this.stop, this] });
			this._curId = 0;
			this._go();
		},

		_go: function(){
			// summary:
			//		Execute one task of this._defsResolved.

			// if _running was set to false stop the sequence, this is the
			// case when i.e. stop() was called.
			if(!this._running){
				return;
			}
			var cur = this._defsResolved[this._curId];
			this._curId += 1;
			// create the function to call, the func property might be an array, which means
			// [function, context, parameter1, parameter2, ...]
			function resolveAndCallFunc(func) {
				var ret = null;
				if(dojo.isArray(func)){
					// Two elements might only be given when the function+context
					// is given, this is nice for using this, ie: [this.func, this]
					if(func.length>2){
						ret = func[0].apply(func[1], func.slice(2));
					}else{
						ret = func[0].apply(func[1]);
					}
				}else{
					ret = func();
				}
				return ret;
			}

			if(this._curId >= this._defsResolved.length){
				resolveAndCallFunc(cur.func); // call the last function, since it is the doneFunction we dont need to handle pause stuff
				// don't go on and call this._go() again, we are done
				return;
			}

			if(cur.pauseAfter){
				if(resolveAndCallFunc(cur.func) !== false){
					setTimeout(dojo.hitch(this, "_go"), cur.pauseAfter);
				}else{
					this._goOnPause = cur.pauseAfter;
				}
			}else if(cur.pauseBefore){
				var x = dojo.hitch(this,function(){
					if(resolveAndCallFunc(cur.func) !== false){
						this._go()
					}
				});
				setTimeout(x, cur.pauseBefore);
			}else{
				if(resolveAndCallFunc(cur.func) !== false){
					this._go();
				}
			}
		},

		goOn: function(){
			// summary:
			//		This method just provides a hook from the outside, so that
			//		an interrupted sequence can be continued.
			if(this._goOnPause){
				setTimeout(dojo.hitch(this, "_go"), this._goOnPause);
				this._goOnPause = 0; // reset it, so if the next one doesnt set it we dont use the old pause
			}else{ this._go(); }
		},

		stop: function(){
			// summary:
			//		Stop the currently running sequence.
			// description:
			//		This can only interrupt the sequence not the last function that
			//		had been started. If the last function was i.e. a slideshow
			//		that is handled inside a function that you have given as
			//		one sequence item it cant be stopped, since it is not controlled
			//		by this object here. In this case it would be smarter to
			//		run the slideshow using a sequence object so you can also stop
			//		it using this method.
			this._running = false;
		}

	});
});