19. Table timer

The table timer calls a function (callback) in a specific interval of time.

19.1. timer callback signature

The following signature must be implemented to be used in a timer callback:

function onTimeOut(self)
    -- self is the timer table
end

19.2. timer methods

19.2.1. timer new

new(function callback_timer, number time)

Create a new instance of a timer passing the function callback and the interval of time to be called.

Parameters

  • string – callback_timer to the real function in lua.

  • number – interval in seconds to call the callback.

Returns

timer table.

Example:

--important the function be defined before register the callback
function on2Seconds(self)
  print('2 seconds has been passed...')
end

tTimer = timer:new(on2Seconds,2)

Also the function might be anonymous:

tTimer = timer:new(function (self)
            print('2 seconds has been passed...')
        end, 2 )
new(string callback_timer, number time)

Create a new instance of a timer passing the function callback as string and the interval of time to be called.

Parameters

  • string – callback_timer string to real function in lua.

  • number – interval in seconds to call the callback.

Returns

timer table.

Example:

--important the function be defined before register the callback
function on2Seconds(self)
  print('2 seconds has been passed...')
end

tTimer = timer:new('on2Seconds',2)

19.2.2. timer start

start

Start the timer.

If the timer was stopped using stop function, the timer will begin from zero.

If the timer was paused using pause function, the timer will take account the time passed before.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed...') end, 2 )
tTimer:start()
stop

Start the timer.

Stop the timer callback and the internal timer.

Example:

tTimer = timer:new(function (self) print('I will be never called...') end, 2 )
tTimer:stop()
pause

Pause the timer.

Pause the timer callback. This method does not zero the internal timer. Next time the timer start, it will take account the time elapsed.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )
tTimer:pause()
restart

Restart the timer.

If it was paused or stopped it will start again.

The internal timer will be set to zero.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )
tTimer:restart()
isRunning

Check if the timer is running or not.

Returns

boolean running - true is is running, false if is not.

If it was paused or stopped it will return false.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )
print('Timer is running:', tTimer:isRunning())
set(number interval)

Change the interval of timer callback

Parameters

number – internal of callback timer.

Example:

tTimer = timer:new(function (self) print('3 seconds has been passed..') end, 2 )
tTimer:set(3)
get

Retrieve the interval of the timer callback

Returns

number interval - the interval of timer callback.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )
print('Timer to callback:', tTimer:get())
elapsed

Retrieve the time elapsed since the last callback.

Returns

number elapsed - the elapsed timer.

Example:

tTimer = timer:new(
    function (self)
        print('Timer elapsed:', tTimer:elapsed()) --always 0
    end, 2 )

function loop(delta)
    print('Timer elapsed:', tTimer:elapsed()) -- here is possible to the timer elapsed
end
times

Retrieve how much times the callback has been called since the last start.

Returns

number times - how much times the callback has been called.

Example:

tTimer = timer:new(
    function (self)
        print('Time number :', tTimer:times())
    end, 2 )
setCallBack(string callback_function_name)

Change the callback of timer passing the callback as string.

Parameters

string – name of new callback timer.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )

function onTimer(self)
    print('New callback in action')
end

tTimer:setCallBack('onTimer')
setCallBack(function callback_function)

Change the callback of timer passing as argument.

Parameters

function – callback of new callback timer.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )

function onTimer(self)
    print('New callback in action')
end

tTimer:setCallBack(onTimer)

-- or as anonymous

tTimer:setCallBack(
    function(self)
        print('New anonymous callback in action')
    end)
destroy

Destroy a timer.

Example:

tTimer = timer:new(function (self) print('I will never be called') end, 2 )

tTimer:destroy()
tTimer = nil

19.3. timer attributes

There is no attribute for timer table. So it is possible to add any tipe of attribute like number, boolean, string, table or function.

Example:

tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )
tTimer.x = 100
tTimer.y = 200

print(tTimer.x,tTimer.y) -- 100 200

19.4. User data acknowledgment

This table uses the first index to store the userdata C++ class internally, however, for timer, is allowed to write / read to / from index.

Error

It is important to understand that as all tables used in this engine, this table uses the first index to store the userdata pointing to the C++ class internally.

There is no mechanism to prevent to access the first index from timer. If you overload the userdata, probably the program will crash.

Listing 19.1 Do not do this:
1 tTimer = timer:new(function (self) print('2 seconds has been passed..') end, 2 )
2 tTimer.x = 0
3 
4 print(tTimer[1]) -- read, okay will print userdata: 0x44958588a6a8 for example
5 
6 tTimer[1] = 5 -- Error, not allowed for this table. program will crash!