Timer

Overview

The Timer API is used to set repeating timers. It is fundamental for creating many types of Intelligent Modules that use polling to update the UI and perform repeating actions. Every time the timer completes, an EventHandler function will be called. This is typically used to poll and update aspects of the UI and/or perform some repeating operations at a regular interval.

Timer.

Timer.New

User Timer.New() to create a new named Timer Object.

MyTimer = Timer.New()         --Creates a new Timer called MyTimer

TimerName

The following methods and properties are available for a Timer object with name TimerName.

TimerName.ID

Get the ID index for a timer.

MyTimer = Timer.New()
MyTimerID = MyTimer.ID                    -- MyTimerID = 1

TimerName:Start(period)

This method starts the named timer with a period given in seconds.

MyTimer:Start(1)        --Starts the timer with a period of 1 second

TimerName:Stop

This method stops the named timer. It can be restarted

MyTimer:Stop            --Stops the timer

TimerName.EventHandler(TimerName)

Assign the callback function for the named timer that will be called whenever the timer reaches its set time.

This can be done in two ways. With a dedicated function:

function TimerClick ()
      --Do lots of stuff every time
end

MyTimer.EventHandler = TimerClick

MyTimer.EventHandler = function ()
--Do lots of stuff every time
end

You can optionally pass the Timer object as an argument in the callback function. This allows access to the Timer.ID, which allows you to use the same callback function for multiple timers.

function TimerClick (TimerName)
      if TimerName.ID == MyTimerID then
            --Do stuff for the first timer
      else
            --Do different stuff for every other timer
      end
end

MyTimer.EventHandler = TimerClick
MyTimerID = MyTimer.ID
MyOtherTimer.EventHandler = TimerClick

Usage Examples

The following examples illustrate how these can be used:

Example 1 – Putting it all together

This example shows how Timers are used to update the UI and/or perform some repeating actions at a regular interval.

function TimerClick ()
      --Do lots of stuff every time
end

MyTimer = Timer.New()
MyTimer.EventHandler = TimerClick
MyTimer:Start(.25)

First define the function to be called every time the timer completes. Then create the Timer and set the function as the EventHandler for the timer. Finally, start the timer.

Example 2 – What goes in the Event Handler?

One of the more common things you will put within your TimerClick () function is to get the input value of named components in your user interface, and then do something with them.

function TimerClick ()
      currentFaderValue = NamedControl.getValue("MyFader")
      if currentFaderValue > .5 then
            NamedControl.setValue("MyLED", 1)
      end
end

Normally, you will never stop this type of Timer. It will simply go forever, checking the status of the UI and updating it. But you will often want to check if each UI element has actually changed, and only perform the processing if it has.

Example 3 - Stop it Now!

If you want the actions to only be performed a single time when the timer completes, simply add a Timer.Stop() to the end of your TimerClick() function:

function TimerClick ()
      --Do lots of stuff one time after 10 seconds
      MyTimer:Stop() --Stop the Timer.
end

MyTimer = Timer.New()
MyTimer.EventHandler = TimerClick
MyTimer:Start(10)

Example 4 - Multiple Timers - But you probably don’t want to do this

If you need multiple timers at different rates, you can simply create more than one timer.

function FastTimerClick ()
      --Do stuff that needs to be done very often
end

function SlowTimerClick ()
      --Do other stuff that can happen less regularly
end

FastTimer = Timer.New()
FastTimer.EventHandler = FastTimerClick
FastTimer:Start(.25)                -- Calls EventHandler every .25s

SlowtTimer = Timer.New()
SlowTimer.EventHandler = SlowTimerClick
SlowTimer:Start(10)                 -- Calls EventHandler every 10s

This can alternately be handled with a single event handler.

function TimerClick (ID)
      if ID == 1 then
            --Do stuff for the fast timer
      elseif ID == 2 then
            --Do different stuff for the slow timer
      end
end

FastTimer = Timer.New()
FastTimer.EventHandler = TimerClick
FastTimer:Start(.25)                -- Calls EventHandler ever .25s

SlowtTimer = Timer.New()
SlowTimer.EventHandler = TimerClick
SlowTimer:Start(10)                 -- Calls EventHandler ever 10s

This is useful for updating some internal control processing at a fast rate, while polling and updating the UI at a slower rate.

But this isn’t the most efficient way to handle this need in most cases; instead, see the next example.

Example 5 - Multiple Timers - The Better Way!

A better way to handle the need for multiple timers than described in the example above, is to have a single fast timer with a multiplier counter limiting some of the work in the callback to occur less frequently.

timerMultiplier = 10
timerCounter = 0

function TimerClick ()
      -- Do stuff every timer the timer occur

      timerCounter = timerCounter + 1

      if timerCounter >= timerMultiplier then
            --Do other stuff that can happen less regularly
            timerCounter = 0              --Reset the timerCounter
      end
end

MyTimer = Timer.New()
MyTimer.EventHandler = TimerClick
MyTimer:Start(.25)

This is more efficient using less processing and can be used as long as the slow timer is a multiple of the fast timer.