User guide & reference

What we call a Timeout object here is basically the same as the result of a native Javascript setTimeout() call. It allows to set a function or bit of code to be executed after a chosen delay. However, the clockWise version offers a few more features, such as :

→ pausing and resuming the delay
→ altering its duration on the fly
→ keeping track of elapsed time
→ forcing immediate execution when needed




Basic use

// Create a Timeout object with default settings
// (will act exactly like a native setTimeout call)

var T = clockWise.setTimeout(some_function, 1000);
// or
var T = clockWise.setTimeout(
function() {
// some instructions here
} , 1000
);

// The resulting object can then be controlled
// using clockWise methods described below.


Timeout-related methods
clockWise.setTimeout( callback , delay [ , settings ] )
Returns a Timeout object that will execute the callback function after a defined delay (in milliseconds) when played. By default, the Timeout object will be played immediately.

The settings argument is optional. If given, it has to be a { property:value } list.

Accepted properties for settings :

→ auto_start : boolean
Set to true by default. If set to false, the Timeout object will not be played immediately.
clockWise.playTimeout( timeout_object )
Triggers the timeout_object if not already active. An object previously played and paused will not restart from zero, only what remains of its delay will be elapsed before the callback execution.
clockWise.clearTimeout( timeout_object )
Resets the timeout_object. If active, its action is stopped and its callback function's execution is prevented.

The object still exists and can be played again. It will then restart from zero, letting its whole delay elapse before the callback execution.
clockWise.pauseTimeout( timeout_object )
If the timeout_object is active, its action is stopped and its callback function's execution is prevented.

When played again, the object will not restart from zero, only what remains of its delay will be elapsed before the callback execution.
clockWise.forceTimeout( timeout_object )
Clears the timeout_object and immediately executes its callback function.
clockWise.alterTimeout( timeout_object , alteration [ , save ] )
Edits the timeout_object's delay according to the given alteration argument.

alteration can be :

→ A positive number, which will replace the delay.

→ A simple operation as a string, to execute on the delay.
+, -, * and / are accepted operators.

Examples : "+ 500" / "- 250" / "* 1.5" / "/ 10"

This function works on active objects as well, and will immediately alter them. If the object's elapsed time in its current action is already larger than the new delay (a theoretical overstep case), its callback execution will be immediately forced.

The optional save argument (boolean, true by default) defines whether the alteration has to be kept or not for next plays. Must be left to true for the function to take effect on an inactive object.
clockWise.revertTimeout( timeout_object [ , immediate_if_active ] )
Reverts the timeout_object's delay to the value given at creation, canceling previous alterTimeout() effects.

The optional immediate_if_active argument (boolean, true by default) defines whether the operation has to take effect immediately or after the object's current action (if active).
clockWise.syncTimeout( timeout_object , reference_timeout_object )
Forces the timeout_object's next callback execution to be triggered when the reference_timeout_object's next one is. Cancels the timeout_object's possible current action.
timeout_object.getElapsed()
Returns the timeout_object's elapsed time (in milliseconds) in its current or last (paused) action.

An object's elapsed time is reset to 0 when cleared, as well as every time its callback is executed.