# Module: `gears.timer`

Class to execute code at specific intervals.

### Usage:

    -- Create a widget and update its content using the output of a shell
    -- command every 10 seconds:
    local mybatterybar = wibox.widget {
        {
            min_value    = 0,
            max_value    = 100,
            value        = 0,
            paddings     = 1,
            border_width = 1,
            forced_width = 50,
            border_color = "#0000ff",
            id           = "mypb",
            widget       = wibox.widget.progressbar,
        },
        {
            id           = "mytb",
            text         = "100%",
            widget       = wibox.widget.textbox,
        },
        layout      = wibox.layout.stack,
        set_battery = function(self, val)
            self.mytb.text  = tonumber(val).."%"
            self.mypb.value = tonumber(val)
        end,
    }

    gears.timer {
        timeout   = 10,
        call_now  = true,
        autostart = true,
        callback  = function()
            -- You should read it from `/sys/class/power_supply/` (on Linux)
            -- instead of spawning a shell. This is only an example.
            awful.spawn.easy_async(
                {"sh", "-c", "acpi | sed -n 's/^.*, \([0-9]*\)%/\1/p'"},
                function(out)
                    mybatterybar.battery = out
                end
            )
        end
    }

### Info:

- Copyright: 2014 Uli Schlachter
- Originally authored by: Uli Schlachter
  (Full contributors list available on our github project)

## Constructors

gears.timer {[args]} | Create a new timer object. |

## Static module functions

gears.timer.start_new (timeout, callback) -> timer | Create a simple timer for calling the `callback` function continuously. |
gears.timer.weak_start_new (timeout, callback) -> timer | Create a simple timer for calling the `callback` function continuously. |
gears.timer.run_delayed_calls_now () | Run all pending delayed calls now. |
gears.timer.delayed_call (callback, ...) | Call the given function at the end of the current GLib event loop iteration. |

## Object properties

started | boolean | The timer is started. |
timeout | number | The timer timeout value in seconds. |

## Object methods

:start () | Start the timer. |
:stop () | Stop the timer. |
:again () | Restart the timer. |
:emit_signal (name, ...) | Emit a signal. | Inherited from gears.object
:connect_signal (name, func) | Connect to a signal. | Inherited from gears.object
:weak_connect_signal (name, func) | Connect to a signal weakly. | Inherited from gears.object

## Signals

start | Emitted when the timer is started. |
stop | Emitted when the timer is stopped. |
timeout | Emitted when timeout seconds have elapsed. |

## Tables

gears.timer.timer | Timer objects. |

## Constructors

🔗 gears.timer {[args]}
  Create a new timer object.

  `call_now` only takes effect when a `callback` is provided. `single_shot`, on the other hand, also stops signals connected to the timeout signal.

  Specifying a function `func` as `args.callback` is equivalent to calling `:connect_signal(func)` on the timer object.

  ### Parameters:

  Note: This constructors uses named parameters calling convention. It means you call it with `{}` and omit the parantheses. For example, calling this will all default argument would be `gears.timer{}`. This is a Lua shortcut syntax equivalent to `gears.timer({})`. `args` is only a placeholder name for the "lone table argument" used in named parameters calls.

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  args |  | table | Arguments. | Not applicable
  timeout |  | number | Timeout in seconds (e.g. `1.5`). | Not applicable
  autostart | Optional | boolean | Immediately start the timer countdown. | `false`
  call_now | Optional | boolean | Immediately call the callback function. | `false`
  callback | Optional | function | Callback function to connect to the "timeout" signal. | Undefined
  single_shot | Optional | boolean | Run only once then stop. | `false`

  ### Returns:

  timer

## Static module functions

🔗 gears.timer.start_new (timeout, callback) -> timer
  Create a simple timer for calling the `callback` function continuously.

  This is a small wrapper around gears.timer, that creates a timer based on `callback`. The timer will run continuously and call `callback` every timeout seconds. It is stopped when `callback` returns `false`, when `callback` throws an error or when the `:stop()` method is called on the return value.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  timeout |  | number | Timeout in seconds (e.g. 1.5).
  callback |  | function | Function to run.

  ### Returns:

  timer The new timer object.

  ### See also:

  gears.timer.weak_start_new | Create a simple timer for calling the `callback` function continuously. | static module functions

🔗 gears.timer.weak_start_new (timeout, callback) -> timer
  Create a simple timer for calling the `callback` function continuously.

  This function is almost identical to gears.timer.start_new. The only difference is that this does not prevent the callback function from being garbage collected. In addition to the conditions in gears.timer.start_new, this timer will also stop if `callback` was garbage collected since the previous run.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  timeout |  | number | Timeout in seconds (e.g. 1.5).
  callback |  | function | Function to start.

  ### Returns:

  timer The new timer object.

  ### See also:

  gears.timer.start_new | Create a simple timer for calling the `callback` function continuously. | static module functions

🔗 gears.timer.run_delayed_calls_now ()
  Run all pending delayed calls now. This function should best not be used at all, because it means that less batching happens and the delayed calls run prematurely.
🔗 gears.timer.delayed_call (callback, ...)
  Call the given function at the end of the current GLib event loop iteration.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  callback |  | function | The function that should be called
  ... |  |  | Arguments to the callback function

## Object properties

🔗 started boolean
  The timer is started.

  For this to be `true` by default, pass `autostart` to the constructor.

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

  ### See also:

  start | Emitted when the timer is started. | signals
  stop | Emitted when the timer is stopped. | signals

🔗 timeout number · 1 signal
  The timer timeout value in seconds.

  ### Constraints:

  Default value | : `0`
  Unit | : second
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::timeout` When the timeout value changes.
  - `self` gears.timer The object which changed (useful when connecting many object to the same callback).
  - `new_value` timeout The new value affected to the property.

## Object methods

🔗 :start () · 1 signal
  Start the timer.
  Click to display more

  ### Emit signals:

  - start
🔗 :stop () · 1 signal
  Stop the timer.

  Does nothing if the timer isn't running.

  Click to display more

  ### Emit signals:

  - stop
🔗 :again () · 2 signals
  Restart the timer. This is equivalent to stopping the timer if it is running and then starting it.
  Click to display more

  ### Emit signals:

  - start
  - stop
🔗 :emit_signal (name, ...) · Inherited from gears.object
  Emit a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  ... |  |  | Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

🔗 :connect_signal (name, func) · Inherited from gears.object
  Connect to a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

🔗 :weak_connect_signal (name, func) · Inherited from gears.object
  Connect to a signal weakly.

  This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

  **Warning:** Only use this function if you really, really, really know what you are doing.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

## Signals

🔗 start
  Emitted when the timer is started.
🔗 stop
  Emitted when the timer is stopped.
🔗 timeout
  Emitted when timeout seconds have elapsed.

  This will be emitted repeatedly, unless `single_shot` has been set to `true` for the timer.

## Tables

🔗 gears.timer.timer
  Timer objects. This type of object is useful when triggering events repeatedly.

  The timer will emit the "timeout" signal every N seconds, N being the timeout value. Note that a started timer will not be garbage collected. Call `:stop` before dropping the last reference to prevent leaking the object.

  ### Fields:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  timeout |  | number | Interval in seconds to emit the timeout signal. Can be any value, including floating point ones (e.g. `1.5` seconds).
  started |  | boolean | Read-only boolean field indicating if the timer has been started.

generated by LDoc 1.5.0