Time control object

The createTimeControl() function returns a time control object to manage clocks, timers, and countdowns.

Create time control object
// This code prints the time control object to the console
const timeControl = SingularWidget.createTimeControl();
console.log(timeControl);

Return

object: Time control object

timeControl: {tc: {…}, allowBackwardsJump: false, roundToInterval: true, intervalID: null, timeoutID: null, …}
> allowBackwardsJump: false
> getCurrentTime: ƒ ()
> intervalID: null
> intervalTime: 1000
> offsetToServerTime: 0
> oldRunningTime: 0
> roundToInterval: true
> setAllowBackwardsJump: ƒ (v)
> setIntervalTime: ƒ (time)
> setOffsetToServerTime: ƒ (time)
> setRoundToInterval: ƒ (v)
> setTimeControl: ƒ (tc)
> setUpdateCallback: ƒ (callback)
> tc: {UTC: 0, isrunning: false, value: 0}
> timeoutID: null
> updateCallback: null

Properties

NameTypeExampleDescription

allowBackwardsJump

Boolean

false (default)

Allows the timer to jump backward due to network latency when restarting or continue playing a paused timer.

intervalID

Integer

The interval ID (internal).

intervalTime

Integer

10, 100, 1000

Interval time in [ms].

offsetToServerTime

Integer

The time offset of a local browser to Singular server time.

roundToInterval

Boolean

true (default)

Rounds time to the next interval.

tc

Object

{ "UTC": 0, "isRunning": false, "value": 0 }

The time control object. UTC: UTC start time [ms]; isRunning: boolean; value: offset in [ms]

timeoutID

Integer

The timeout ID (internal).

updateCallback

Function

A callback function triggered at every interval.

Methods

getCurrentTime()

Returns the current running time of the timer in [ms].

// This code prints the current running time to the console
const currTime = timeControl.getCurrentTime();
console.log("currTime =", currTime);

Return

integer: time in [ms]

currTime = 1234

setAllowBackwardsJump()

Due to a slow internet connection and/or network latency, clocks can jump backwards when starting, pausing, or restarting. Use the setAllowBackwardsJump() call to set this behavior.

Parameter

NameTypeDescription

allowBackwardsJump

Boolean

false: (default) don't allow backwards jump true: allow backwards jump

// This code avoids backwards jumps
timeControl.allowBackwardsJump(false);

Return

none

setIntervalTime()

Sets the interval frequency for the timer.

Parameter

NameTypeDescription

tInterval

Number

The interval duration in [ms].

// This code sets the interval frequency to 1000 [ms]
const tInterval = 1000;
timeControl.setIntervalTime(tInterval );

Return

none

setOffsetToServerTime()

Sets the offset from the local browser to the Singular server time.

Parameter

NameTypeDescription

tOffset

Number

Offset from the local browser time to the Singular server time.

// This code sets the offset to the Singular server time in [ms]
const tOffset = 876;
timeControl.setOffsetToServerTime(tOffset);

Return

none

setRoundToInterval()

Rounds the time to the interval frequency.

Parameter

NameTypeDescription

doRounding

Boolean

true: (default) round time to interval frequency false: do not round time

// This code sets the round-to-interval flag
timeControl.setRoundToInterval(true);

Return

none

setTimeControl()

The time control object defines the current timer state.

// This code shows examples of the time control object
const tStart = Date.now();
const tcStart = {
  "UTC": tStart,     // set start time to current UTC time in [ms]
  "isRunning": true, // start timer
  "value": 0         // offset is 0
};

// .... later
const tPause = Date.now();
const tcPause = {
  "UTC": tPause,             // set start time to current UTC time in [ms]
  "isRunning": false,        // start false
  "value": tcPause - tcStart // offset is 0
};

// .... even later
const tcContinue = {
  "UTC": Date.now(),         // set start time to current UTC time in [ms]
  "isRunning": true,         // start false
  "value": tcPause - tcStart // offset is 0
};

Parameter

NameTypeDescription

tc

object

The time control object.

// This code starts the timer
timeControl.setTimeControl(tcStart)(;

Return

none

setUpdateCallback()

Sets the time control callback function. This function is called at every interval.

Parameter

NameTypeDescription

cb

function

The callback function.

// The code below updates the timer callback function
timeControl.setUpdateCallback(() => {
  console.log("elapsed time = %d[ms]", timeControl.getCurrentTime());
  // add your code here ...
});

Return

none

let tControl = {
    UTC: 0,
    isRunning: false,
    value: value
};

// The code below creates a timecontrol object
const timeControl = SingularWidget.createTimeControl();
// set update callback function
timeControl.setUpdateCallback(updateCallback);
// this will stop the clock from jumping backwards when it is stopped. A jump
// backwards can happen due to network latency
timeControl.setAllowBackwardsJump(false);
// round the time to the interval frequency
timeControl.setRoundToInterval(true);
// tell the timer control object how often to update the callback
timeControl.setIntervalTime(100); //milliseconds

timeControl.setTimeControl(tControl); // todo...

const updateCallback = () => {
  // get current timer value
  let currentTime = timeControl.getCurrentTime();
  console.log("currentTime = %d[ms]", currentTime);
}

Last updated