Sequencr.for & Sequencr.do

Sequencr.for(startInclusive, endExclusive, callback, timeout, onCompleted)

Description

Calls a function (callback) as if it was the body of a for loop, and adds a timeout (defined by the timeout argument) between each iteration. A timeout will occur before the first iteration. If JavaScript had a sleep function, Sequencr.for might look something like this:

for(var i = startInclusive; i < endExclusive; i++)
{
    sleep(timeout);
    if(callback(i) === false){
        break;
    }
}

if(onCompleted)
{
    onCompleted();
}

Arguments

startInclusive: The initial value of the iterator in the for loop (inclusive). See the above example.

endExclusive: The final value of the iterator in the for loop (exclusive). See the above example.

callback: The function to call each iteration. The function should accept one parameter for the value of the iterator.

timeout: Optional (default=1). The timeout in ms between iterations. This can be an integer, or a function that returns an integer. If timeout is a function, Sequencr.js will provide a parameter for i - the current value being iterated.

onComplete: Optional. A function to call when the for loop has completed. There will not be any delay between the final call of callback and the call of onComplete, so if a delay is required, build it into onComplete. onComplete is passed a single parameter that will be true if the for loop completed without breaking (by returning false in the callback function).

Examples

Basic Usage

Sequencr.for(0, 10, function(i)
{
    console.log("Currently at iteration #" + i);
}, 1000, function()
{
    console.log("Done!");
});

Breaking (new)

To break out of the loop early, return false in callback. This will immediately result in the onCompleted function being called. Any other return value will be ignored.

The above code counts to 10 in the console with one-second timeouts between each iteration. Try it here (don't forget to open your JavaScript console)!

Passing Different Parameters

To pass parameters (for instance, myfunction(a, b, c)), use anonymous functions.

Sequencr.for(0, 10, function(i)
{
    myfunction(a, b, c); //i won't be offended if you don't use it.
}, 10);

Preserving Scope

To preserve scope use JavaScript's built-in apply function. Otherwise this will refer to Sequencr itself.

Sequencr.for.apply(this, [0, 10, myfunction, 10, completeCallback]);

Using the onComplete Callback

Just declare the function anywhere and pass the name in. If you need to pass parameters in, use the technique illustrated above.

function completeCallback()
{
    console.log("Sequencr.for is done!");
}

Sequencr.for(0, 10, myfunction, 10, completeCallback);

If you do use JavaScript's apply or call to modify the scope, make sure completeCallback is in the correct scope (or else any references to this will be messed up). Scope can always be set inside the onComplete by using an anonymous function:

function MyThing()
{
    this.x = 100;
    this.completeCallback = function()
    {
        console.log("Sequencr.for is done! By the way, this.x = " + this.x);
    }
}

var that = new MyThing();

Sequencr.for.apply(this, [
    0, 
    3, 
    function(i)
    {
        console.log(i);
    }, 
    1000, 
    function()
    {
        that.completeCallback.call(that);
}]);

Sequencr.do(callback, timeout)

Description

A simplified version of Sequencr.for that runs infinitely and does not have an onCompleted callback. It's possible to break out of the loop by returning false in the callback. Great for game update loops.

Arguments

callback: The function to call each iteration. The function should accept one parameter for the value of the iterator.

timeout: The timeout in ms between iterations. This can be an integer, or a function that returns an integer.

Examples

Basic Usage

var i = 0;
Sequencr.do(function()
{
    console.log("Iteration #" + i);
    i++;
    if(i == 10)
    {
        return false;
    }
}, 1000);