lua_api_timer.dox

/**
\page lua_api_timer Timers

Timers allow you to call a function in the future with a specified delay.

Examples of use:

\verbatim
-- Play sound "secret" in one second.
sol.timer.start(1000, play_secret_sound)

function play_secret_sound()
  sol.audio.play_sound("secret")
end
\endverbatim

\verbatim
-- Equivalent code using an anonymous function.
sol.timer.start(1000, function()
  sol.audio.play_sound("secret")
end)
\endverbatim

\section Contents

- \ref lua_api_timer_functions
- \ref lua_api_timer_methods

<hr>

\section lua_api_timer_functions Functions of sol.timer

<hr>

\subsection lua_api_timer_start sol.timer.start([context], delay, callback)

Sets a function to be called after a delay.

If the delay is set to zero, the function is called immediately.
- \c context (table, game, map or enemy; optional): Determines the lifetime of
  the timer. This parameter is optional: its default value is adapted to some
  usual situations.<br>
  The context is where the timer belongs.
  If the context is destroyed before the timer is finished, then
  the timer is canceled. More precisely, the following rules are applied.
  - If the context is a game, the timer is canceled when the game is closed.
  - If the context is a map, the timer is canceled when the player goes to
    another map.
  - If the context is an enemy, the timer is canceled when the enemy is
    killed or removed.
  - If the context is the table of a \ref lua_api_menu "menu", the timer is
    canceled when the menu is closed.
  - If the context is the \ref lua_api_main "sol.main" table, the timer is
    canceled when Lua is closed. Thus, it will be a global timer.
  - If the context is not set, then a default context is chosen
    (the current map during a game, and the current menu otherwise).
- \c delay (number): Delay before calling the function in milliseconds.
- \c callback (function): The function to be called when the timer finishes.
- Return value (timer): The timer created (or \c nil if \c delay is \c 0).
  There is no problem if the timer returned is garbage-collected: the timer
  persists until its completion or the destruction of its context.
  Usually, you will store the return value only if you need to stop the timer
  explicitely later.

<hr>

\section lua_api_timer_methods Methods of the type timer

<hr>

\subsection lua_api_timer_stop timer:stop()

Cancels this timer.

If the timer was already finished or canceled, nothing happens.

<hr>

\subsection lua_api_timer_is_with_sound timer:is_with_sound()

Returns whether a clock sound is played repeatedly during this timer.
- Return value (boolean): \c true if a clock sound is played with this timer.

<hr>

\subsection lua_api_timer_set_with_sound timer:set_with_sound(with_sound)

Sets whether a clock sound is played repeatedly during this timer.

Before you call this function, no sound is played.
- \c with_sound (boolean, optional): \c true to play a clock sound
  repeatedly (default is \c true).

<hr>

*/