Working with Time: Delays and Counting

Time Delays

timer.performWithDelay() is Corona’s function for performing specific actions after a set period of time. The function name is actually very descriptive, so it’s likely you already knew what it did as soon as you saw it.

Here’s an overview of the syntax:


timer.performWithDelay( delay, listener [, iterations] )


When you call the function, you specify how long you want the delay to last in milliseconds (delay), and then you specify the function (listener) you want to be called once the delay time has lapsed. Optionally, you can specify the number of iterations you want the delay to be repeated (the default is 1 iteration).

Next I’ll show you how you can use both functions and anonymous functions as listeners when using timer.performWithDelay().

Using a function

In the example below, we are calling a function called hello_world() after 1 second (1000 milliseconds) only one time (1 iteration):


local function hello_world()
print( "Hello world!" )
end

timer.performWithDelay( 1000, hello_world, 1 )


Using anonymous functions

Since the second argument of timer.performWithDelay() simply has to be of type “function”, you can also use an anonymous function (one without a name; not assigned to a variable). The below example does exactly the same thing as the previous example:


timer.performWithDelay( 1000, function()
print( "Hello world!" )
end, 1 )


Of course, I could have put everything on one line, but I decided to make it “look” like a function definition for easier readability.

Also keep in mind that with anonymous functions, we’re actually defining the whole function (from “function()” … all the way to … “end”) entirely between the commas that separate the function arguments. Therefore, timer.performWithDelay() actually takes it as a valid argument (we’re not calling a function, we’re defining it—which serves the same purpose as a reference to a function).

You can get more information on using closures as function callbacks in Eric Wing’s tutorial that he published over a year ago.

Passing Arguments to the Listener

One of the most common questions in regards to using timer.performWithDelay() is, “Since I’m passing only a reference to an external function, what if that function takes arguments?”

The answer is, use a combination of the two examples from above. That is, use an anonymous function and an external function:


local function hello_world( arg1, arg2 )
print( "Hello world!", arg1, arg2 )
end

timer.performWithDelay( 1000, function()
hello_world( "first", "second" )
end, 1 )


Do you see how I did that? Since hello_world, our listener function, takes two arguments (arg1 and arg2), we use an anonymous function as the listener which in-turn calls the hello_world() function with the arguments we need to pass in (“first” and “second”).

It might take a while to soak in, but once you work with timer.performWithDelay() enough, things begin to make sense pretty quickly. In fact, using this function regularly and taking the time to fully understand how it works can actually work wonders in helping you understand some of Lua’s extremely important but somewhat confusing features.

Other functions

It’s worth noting that timer.performWithDelay() actually returns a timerId that can be stored into a variable and used with other functions in Corona’s timer library. These functions include timer.pause(), timer.cancel(), and timer.resume() which are beyond the scope of this tutorial. Thankfully, they are fairly self-explanatory once you’ve mastered the use of timer.performWithDelay(). Visit the timer API reference page for more information.

Counting Time

As I mentioned earlier, there are countless reasons why you might want to keep track of time in your app. For the sake of this tutorial, let’s assume you want to begin counting time at the start of a round and stop once the player has reached a “game over” state.

So, at the start of the round:


local markTime = os.time()


Once the player has reached the “game over” state (at the end of the round), here’s how we would get the total amount of time passed since we first marked the time and stored it in markTime:


local timePassed = os.time() - markTime


In the above example, timePassed actually gives you the time in seconds. You can convert the time into minutes by dividing the value by 60, or multiply it by 1000 to get milliseconds. A faster way to get milliseconds right off the bat is to substitute os.time() with system.getTimer() in both code snippets above.

Time’s up!

So by now, you should be a pro at using Corona’s timer.performWithDelay() function, and also have a good understanding of how you can track/count time in your app. All in all, that should cover most use-cases having to do with time.

But in case you want to get daring, some other time-related functions you may want to check out include: os.clock(), os.date(), os.difftime(), and system.getTimer().