User guide & reference

The Javascript setInterval() function can be used to execute instructions cyclically, at a chosen time interval. It's pretty handy and can prove itself reliable enough for small needs in a web page's behavior. But when handling time patterns properly becomes a little bit more of a central concern in your application, a few limitations can quickly begin to show up, starting with... issues in the time interval's consistency itself over the cycles.

In such case, the clockWise Interval object may help. Like the Timeout enhancement, its basic use is the same as with the native Javascript function, plus some additional possibilities :

→ a stabilized, more accurate time interval
→ pausing and resuming the cycle
→ altering the time interval on the fly
→ setting a maximum amount of iterations to execute
→ synchronizing multiple Interval objects

Basic use


        // Create an Interval object with default settings
// (will act like a "stabilized" native setInterval call)


        var I = clockWise.setInterval(some_function, 1000);

        // or

        var I = clockWise.setInterval(

                            function() {

        // some instructions here

                            } , 1000

                            );
        


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

Interval-related methods

clockWise.setInterval( callback , time_interval [ , settings ] )

Returns an Interval object that will execute the callback function cyclically at a defined time_interval (in milliseconds) once played. By default, the Interval 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 Interval object will not be played immediately.

→ immediate : boolean
Set to false by default. If set to true, the first callback execution will occur immediately when the object is played. If false, one interval will first elapse.

→ max_times : integer
Ignored by default. If set, defines a maximum number of iterations to execute, after which the object is cleared.

→ stabilize : boolean
Set to the global parameter clockWise.stabilize_by_default (defined as true) if not specified. If set to false, the Interval object's stabilization feature will be deactivated.

→ loss_tolerance : integer or string
Set to the global parameter clockWise.default_loss_tolerance (defined as 15) if not specified. Defines the accumulated time loss in milliseconds, that is tolerated before the object stabilizes itself again. If set to 0, no stabilization will occur.

A percentage is accepted too, if passed as a string, like for example : loss_tolerance : "2%".
It will then be calculated from the object's time_interval.

clockWise.playInterval( interval_object [ , settings ] )

Triggers the interval_object if not already active. An object previously played and paused will resume from its last temporal position in its cycle.

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

Accepted properties for settings :

→ from_current_time : boolean
Set to true by default. If set to false, the Interval object will restart by elapsing a full time_interval instead of the time remaining from its last iteration (if previously paused).

→ force_immediate : boolean
Set to false by default. If set to true, a first callback execution will occur immediately as the cycle resumes. (Has no effect if the from_current_time option is set to true).

clockWise.clearInterval( interval_object )

Resets the interval_object. If active, its action is stopped. The object still exists and can be played again. It will then restart from zero.

clockWise.pauseInterval( interval_object )

If the interval_object is active, its action is stopped. When played again, the object will resume from its last temporal position in its cycle.

Objects with a max_times option set will keep track of their iteration count too.

clockWise.alterInterval( interval_object , alteration [ , immediate_if_active ] )

Edits the interval_object's time_interval according to the given alteration argument.

alteration can be :

→ A positive number, which will replace the time_interval.

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

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

This function works on active objects as well. If, according to the recalculated time_interval, a delay remains to be elapsed before the next callback execution, the new value is immediately taken into account. Otherwise (in a theoretical overstep case), the former value is kept until next iteration is launched.

The optional immediate_if_active argument (boolean, false by default), if set to true for an active object, will force an immediate interruption of the cycle, and replay it with its new time_interval.

clockWise.revertInterval( interval_object [ , immediate_if_active ] )

Reverts the interval_object's time_interval to the value given at creation, canceling previous alterInterval() effects.

This function works on active objects as well. Its behaviour regarding immediacy / effect delay is then similar to alterInterval().

clockWise.syncInterval( interval_object , reference_interval_object )

Forces the interval_object's next callback execution to be triggered when the reference_interval_object's next one is.

If both objects run in stabilized mode and share the same time_interval value, they will actually stay synchronized (until one of them is paused or cleared).

interval_object.getElapsed()

Returns the interval_object's elapsed time (in milliseconds) in its current or last (if paused) cycle.

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