Skip to Main Content

Class: ForegroundTimer

QuickNav

Fields

Methods

apex.util.ForegroundTimer

A controllable low resolution interval timer that runs only when the page is in the active or passive state (foreground). The interval, in seconds, is configurable. The timer can be stopped, started and paused. A callback function is called each interval and when the timer state changes. The timer will pause if the page is hidden. No matter how the timer is started, paused, restarted, stopped, etc. it will not call the interval callback in less than interval seconds.

The interval should be much larger than the time the callback spends processing. If the callback makes requests to a server make sure to set the interval so that the server is not overwhelmed, taking into consideration server resources and number of clients.

Constructor

new apex.util.ForegroundTimer(pCallback, pOptionsopt)

Create an apex.util.ForegroundTimer instance.
Parameters:
Name Type Attributes Description
pCallback function A callback function that is called each time interval and when the timer changes state.

Function signature: {void|boolean|Promise} callback( {string} reason );

The function receives a single string argument that indicates the reason for the call. It is one of "start", "interval", "pause", "restart", "stop". The return value of the function is ignored except for when the reason is "interval". When the reason is "interval" the return value can be:

  • A boolean. If the return value is false then the timer will stop as if ForegroundTimer#stop was called.
  • A promise. The promise resolves with a boolean value and if it is false the timer will stop as if ForegroundTimer#stop was called. Otherwise, the timer interval callback will not be called again until after the promise resolves. A jQuery promise will also work.

When the reason is "interval" and the callback throws an exception the timer will stop as if ForegroundTimer#stop was called.

While the timer is running, if the page enters the hidden state (for example when another browser tab is activated) the callback is called with reason = "pause" and the timer is paused until the page is no longer hidden.
pOptions object <optional>
 An options object
Properties
Name Type Attributes Description
interval number <optional>
 Initial value for the ForegroundTimer#interval property.
autoStart boolean <optional>
 Value for the ForegroundTimer#autoStart property. If true the timer will start running as soon as the ForegroundTimer instance is created. If false then the ForegroundTimer#start method needs to be called to start the timer running. The default is false.
minInterval number <optional>
 Value for the ForegroundTimer#minInterval property. The minimum value that the interval property can be set to. Must be greater than or equal to 1. The default is 2.
Examples

Create a timer that runs every 60 seconds

const t1 = new apex.util.ForegroundTimer( ( reason ) => {
        if ( reason === "interval" ) {
            console.log( "timer interval", new Date() );
            // do some processing
            // return false if something goes wrong and the timer needs to stop
        } else {
            console.log( "timer status change", reason );
        }
    }, {
        interval: 60,
        autoStart: true
    } );

Create a timer that runs every 30 seconds. In this case the processing is asynchronous and the timer does not auto start.

const t1 = new apex.util.ForegroundTimer( ( reason ) => {
        if ( reason === "interval" ) {
            return new Promise( resolve => {
                // do some processing. This is simulating an async process.
                setTimeout( () => {
                    console.log( "timer interval", new Date() );
                    resolve( true ); // resolve with false if something goes wrong and the timer must stop
                }, 2000 );
            } );
        } else {
            console.log( "timer status change", reason );
        }
    }, {
        interval: 30
    } );
// when ready call start
t1.start();

Fields

autoStart :boolean

Determine if timer will start running as soon as it is created. Set when the timer is created and can't be changed. If true the timer will start running as soon as the ForegroundTimer instance is created. If false then the ForegroundTimer#start method needs to be called to start the timer running.
Type:
  • boolean
Default Value:
  • {false}

interval :number

The number of seconds between calls to the callback function with reason = "interval". This can be set while the timer is running.

A value of 0 will disable the timer. Other values less than ForegroundTimer#minInterval will be coerced to ForegroundTimer#minInterval.

Type:
  • number
Default Value:
  • 5 seconds

minInterval :number

The minimum number of seconds that ForegroundTimer#interval can be. Set when the timer is created and can't be changed. Must be greater than or equal to 1.
Type:
  • number
Default Value:
  • 2

Methods

destroy()

This method must be called when the timer will no longer be used to free up resources.

getState() → {string}

Returns the current state of the timer.

Returns:
Timer state. One of "stopped", "paused", or "running".
Type
string

pause()

Call to pause the running timer.

The difference between pause and stop is that calling start after pause will call the callback with reason "interval" sooner because it takes the last time the interval ran into consideration. Calling start after stop will wait the full interval seconds before calling it.

Example

Pause the timer t1.

t1.pause();
// the callback provided when the timer was created is called with the reason = "pause"
// and it is not called again until the timer is started.

start()

Call to start the timer running. While the timer is running the callback is called with reason = "interval" every interval seconds.

Example

Start the timer t1.

t1.start();
// now the callback provided when the timer was created is called first with the reason = "start"
// (or if the timer was previously paused the reason = "restart")
// and then every interval seconds after that with reason = "interval" until the timer is stopped or paused.

stop()

Call to stop the running timer.
Example

Stop the timer t1.

t1.stop();
// the callback provided when the timer was created is called with the reason = "stop"
// and it is not called again until the timer is started.