Developer Portal
Quick StartsComposition scriptingAPIs and SDKsSupport
  • Portal overview
  • Quick start
  • REST API
    • Introduction
    • Rate limits
    • Authorization
    • How-to guides
      • Get a control app's API token
      • Get a composition's sub-composition IDs and names and their payload structures
      • Get a control app's model
      • Get a control app's metadata
      • Update a sub-composition's content
      • Update a sub-composition's animation state
      • Update a sub-composition's content and animation state in one call
      • Update multiple sub-compositions in one call
    • API reference
      • Get control app details
        • Get a control app's metadata
        • Get a control app's model
        • Get a control app's control data
      • Send data to a control app
        • Update a control app's content
        • Update a control app's animation state
      • Take out all of an app's output
  • Data stream API
    • Introduction
    • Rate limits
    • Authorization
    • How-to guides
      • Create a data stream
      • Link a data stream to a composition
      • Send data to an app using the data stream API
    • API reference
  • Composition scripting
    • Introduction
    • Overview
    • Quick start
      • Find sub-compositions and widgets
      • Read and update control nodes
      • Set text widget text properties
      • Read and update widget properties
      • Read control nodes and update widget properties
      • Set image widget URL property
      • Set table widget content property
    • Cheat sheets
      • Fundamentals
      • Interactive overlays
      • Best practices
    • Use cases
      • Read control nodes and generate HTML text
      • Read control nodes, generate HTML text with background
      • Text Ticker - Start ticker on "In" animation
    • Composition script editor reference
  • Software development kits
    • Graphics SDK
      • Getting started
      • Reference
        • SDK functions
        • Composition object
        • Sequencer object
      • Guides and examples
        • Load a composition with its token
        • Load a composition with its URL
        • Get the composition URL of an app instance
        • Sequencer VOD example
        • Control local preview of app
        • Load app instance output
    • Overlay SDK
      • Getting started
      • SDK functions
      • Use case examples
    • Widget SDK
      • Preparing your environment
      • Getting started
      • Reference
        • Widget UI definition
        • Widget callback functions
        • Time control object
        • Composition instance
      • Guides and examples
        • Widget example: CSS patterns
    • App SDK
  • Singular Basics
    • Overview of Singular
    • Managing overlays in the Dashboard
      • How to create a new composition
      • How to open a new app template
      • How to create an app for a composition
      • How to extract a composition from an app
      • How to find an app's shared app token and shared API URL
      • Dashboard reference
    • Building overlays in Composer
      • How to build a composition
      • How to set up layer logic to automate overlay transitions
      • How to set up control nodes to make widget properties available to a control app
      • Animating overlays
        • How to create timeline animations
        • How to create behavior animations
        • How to create update animations
      • How to make overlays interactive
      • How to adapt overlays to various screen sizes
      • Composer reference
    • Controlling overlays in Studio and UNO
      • How to use Studio
      • Studio reference
      • UNO reference
  • Support
    • Singular status
    • Support resources
    • Singular terminology
    • Performance Testing
Powered by GitBook
On this page
  • Properties
  • Methods
  • getCurrentTime()
  • setAllowBackwardsJump()
  • setIntervalTime()
  • setOffsetToServerTime()
  • setRoundToInterval()
  • setTimeControl()
  • setUpdateCallback()

Was this helpful?

  1. Software development kits
  2. Widget SDK
  3. Reference

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);
}
PreviousWidget callback functionsNextComposition instance

Last updated 2 years ago

Was this helpful?