Timers

Timers track the passage of time for components with repeating actions, such as Animations and Canvases.

Overview

Timers are used to determine when to perform a repeated action such as scrolling a Section or redrawing an Animation. There are two components to a Timer: the last_run_time and the interval. The last_run_time stores the last time that the Timer executed, and the interval is the amount of time that must pass from the last_run_time before the Timer runs again. When the Timer does run, it sets a flag that its parent component watches for. The Timer then changes its last_run_time to the current time, and the process starts over.

Timers are designed to repeat - that is, if the interval is set to 1000 milliseconds, the Timer will fire every 1000 ms.

Creating a Timer

To create a Timer, pass in the amount of time (in milliseconds) before the Timer goes off. Update the Timer in a loop using Timer::update(), passing in the program’s current runtime. As long as the interval has not passed, update() returns true. Once the interval passes, the Timer runs and its update() method returns true. Immediately after this, the Timer returns false until the next interval.

The following Arduino example creates a Timer that performs an action every 5000ms:

// ...
Timer timer(5000);
// ...
void loop()
  if (timer.update(millis())) {
    // Perform some action
  }

You mostly likely won’t need to interact with Timers directly. Any PixelMaestro component that uses a Timer will wrap its Timer in a set_timer() method. The functionality is the same, but it saves you the effort of having to create and run your own Timer objects.

Changing the Interval

To change the update interval on an existing Timer, use Timer::set_interval() and pass in your new update interval.

// Changes the interval to 10 seconds
timer.set_interval(10000);

You can also change the Timer’s last update time by using Timer::set_last_time(). This is useful when synchronizing multiple Timers.

Starting and Stopping a Timer

Timers include a start() and stop() method for starting and stopping the Timer, respectively. If a Timer is stopped, running Timer::update() will always return false and the last time will not update.