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

Name	Type	Example	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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);
}