.section Widgets
.topic widget.timer
.title Timer
.toc 0 Non-Visual Widgets
.toc 0 Timer
.index Timer
.index wgtTimer
.index wgtTimerStart
.index wgtTimerStop
.index wgtTimerSetInterval
.index wgtTimerIsRunning
.index wgtUpdateTimers

.h2 Timer

A non-visual widget that fires its onClick callback at a regular interval. Useful for animations, polling, and periodic updates. Must be explicitly started after creation.

Header: widgets/widgetTimer.h

.h3 Creation

.code
WidgetT *tmr = wgtTimer(parent, 1000, true);  // 1 second, repeating
tmr->onClick = onTimerTick;
wgtTimerStart(tmr);
.endcode

.h3 Macros

.table
  Macro                                          Description
  -----                                          -----------
  wgtTimer(parent, intervalMs, repeat)           Create a timer. intervalMs is the interval in milliseconds. repeat: true for repeating, false for one-shot.
  wgtTimerStart(w)                               Start the timer.
  wgtTimerStop(w)                                Stop the timer.
  wgtTimerSetInterval(w, intervalMs)             Change the timer interval.
  wgtTimerIsRunning(w)                           Returns true if the timer is currently running.
  wgtUpdateTimers()                              Global tick function. Called by the event loop to advance all active timers.
.endtable

.h3 Events

.table
  Callback     Description
  --------     -----------
  onClick      Fires each time the timer elapses.
.endtable

.h3 Properties (BASIC Interface)

.table
  Property     Type       Access       Description
  --------     ----       ------       -----------
  Enabled      Boolean    Read/Write   Whether the timer is running. Reading returns the running state; writing starts or stops it.
  Interval     Integer    Write-only   Timer interval in milliseconds.
.endtable

.h3 Methods (BASIC Interface)

.table
  Method       Description
  ------       -----------
  Start        Start the timer.
  Stop         Stop the timer.
.endtable

.h3 Extra Events (BASIC Interface)

.table
  Event        Description
  -----        -----------
  Timer        Fires each time the timer elapses. Default event.
.endtable

.hr