API | Timers

These functions control the system timers.

 

PS.timerStart ( ticks, exec, ... )

PS.timerStart() establishes a function that executes continuously after a specified time delay.

Parameters:

  1. ticks : integer or PS.DEFAULT
  2. exec : function

Returns: string or PS.ERROR

The required ticks parameter specifies the time delay, expressed in 60ths of a second. It must be an integer greater than or equal to one (1). Non-integral values are floored.

If ticks is PS.DEFAULT, the default delay value (60, one second) is applied.

The required exec parameter must be a valid function reference.

Any parameters supplied to PS.timerStart() after the exec parameter are passed as arguments to the exec function every time it is called.

Usage notes

1. Timer functions must be kept as short and fast as possible. If you try to execute too much code inside a timer function, or run too many timer functions simultaneously, serious performance and synchronization issues are likely to occur.

2. If you intend to stop a timer function you have started, you must save the unique identifier PS.timerStart() returns inside a variable that will be in scope when PS.timerStop() is subsequently called.

3. Any values returned by timer functions are generally ignored. However, if a timer function returns the value PS.ERROR, PS.timerStop() is immediately called on that timer.

Return value

PS.timerStart() returns a string uniquely identifying the newly created timer, or PS.ERROR if an error occurs.

An example of how to use the timer is shown in the documentation for PS.timerStop() below.

 

PS.timerStop ( timer )

PS.timerStop() stops a timer previously started by PS.timerStart().

Parameters:

  1. timer : string or PS.DEFAULT

Returns: string or PS.ERROR

The required timer parameter should be unique timer identifier of the type returned by PS.timerStart().

An error occurs if timer is not a valid timer identifier.

Once a timer is stopped with a call to PS.timerStop(), the identifier of the stopped timer becomes invalid, and should not be used again.

Return value

PS.timerStop() returns timer, or PS.ERROR if an error occurs.

// EXAMPLE
// Display a countdown in the status line

// Global variable for timer ID

var myTimerID;

// Global variable for countdown

var myCounter = 5;

// This is the timer function

function myTimer() {
 if ( myCounter > 0 ) {
 PS.statusText( "T-minus " + myCounter );
 myCounter -= 1; // decrement counter
 }
 else {
 PS.statusText( "Lift off!" );
 PS.timerStop( myTimerID ); // stop timer
 }
};

PS.init = function( system, options ) {
 PS.gridSize( 8, 8 );

 // Timer runs once every second
 // Save ID so timer can be stopped later

 myTimerID = PS.timerStart( 60, myTimer );
};