> For the complete documentation index, see [llms.txt](https://developer.singular.live/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.singular.live/software-development-kits/widget-sdk/reference/time-control-object.md).

# Time control object

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

{% code title="Create time control object" %}

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

{% endcode %}

#### Return

`object`: Time control object

{% code overflow="wrap" %}

```bash
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
```

{% endcode %}

## Properties

<table><thead><tr><th width="212">Name</th><th width="108">Type</th><th>Example</th><th width="257">Description</th></tr></thead><tbody><tr><td>allowBackwardsJump</td><td>Boolean</td><td><code>false</code> (default)</td><td>Allows the timer to jump backward due to network latency when restarting or continue playing a paused timer.</td></tr><tr><td>intervalID</td><td>Integer</td><td></td><td>The interval ID (internal).</td></tr><tr><td>intervalTime</td><td>Integer</td><td>10, 100, 1000</td><td>Interval time in [ms].</td></tr><tr><td>offsetToServerTime</td><td>Integer</td><td></td><td>The time offset of a local browser to Singular server time.</td></tr><tr><td>roundToInterval</td><td>Boolean</td><td><code>true</code> (default)</td><td>Rounds time to the next interval.</td></tr><tr><td>tc</td><td>Object</td><td><code>{</code><br>  <code>"UTC": 0,</code><br>  <code>"isRunning": false,</code><br>  <code>"value": 0</code><br><code>}</code></td><td>The time control object.<br>  UTC: UTC start time [ms];<br>  isRunning: boolean;<br>  value: offset in [ms]</td></tr><tr><td>timeoutID</td><td>Integer</td><td></td><td>The timeout ID (internal).</td></tr><tr><td>updateCallback</td><td>Function</td><td></td><td>A callback function triggered  at every interval.</td></tr></tbody></table>

## Methods

### getCurrentTime()

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

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

#### Return

&#x20;`integer`: time in \[ms]

```bash
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

<table><thead><tr><th width="217">Name</th><th width="116.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>allowBackwardsJump</td><td>Boolean</td><td><code>false</code>: (default) don't allow backwards jump<br><code>true</code>: allow backwards jump</td></tr></tbody></table>

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

#### &#x20;Return

`none`

### setIntervalTime()

Sets the interval frequency for the timer.

#### Parameter

<table><thead><tr><th width="113.33333333333331">Name</th><th width="127">Type</th><th>Description</th></tr></thead><tbody><tr><td>tInterval</td><td>Number</td><td>The interval duration in [ms].</td></tr></tbody></table>

```javascript
// 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

<table><thead><tr><th width="108.33333333333331">Name</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>tOffset</td><td>Number</td><td>Offset from the local browser time to the Singular server time.</td></tr></tbody></table>

```javascript
// 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

<table><thead><tr><th width="153.33333333333331">Name</th><th width="125">Type</th><th>Description</th></tr></thead><tbody><tr><td>doRounding</td><td>Boolean</td><td><code>true</code>: (default) round time to interval frequency<br><code>false</code>: do not round time</td></tr></tbody></table>

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

#### Return

`none`

### setTimeControl()

The time control object defines the current timer state.

```javascript
// 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

<table><thead><tr><th width="153.33333333333331">Name</th><th width="162">Type</th><th>Description</th></tr></thead><tbody><tr><td>tc</td><td>object</td><td>The time control object.</td></tr></tbody></table>

```javascript
// 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

<table><thead><tr><th width="155.33333333333331">Name</th><th width="128">Type</th><th>Description</th></tr></thead><tbody><tr><td>cb</td><td>function</td><td>The callback function.</td></tr></tbody></table>

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

#### Return

`none`

```javascript
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);
}

```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.singular.live/software-development-kits/widget-sdk/reference/time-control-object.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.