Module: gears.timer

Timer objects and functions.

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
  • Author: Uli Schlachter

Constructors

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

Static module functions

gears.timer.start_new (timeout, callback) Create a timeout for calling some callback function.
gears.timer.weak_start_new (timeout, callback) Create a timeout for calling some callback function.
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 main loop iteration

Object properties

started boolean The timer is started.
timeout number The timer timeout value.

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 When the timer is started.
stop When the timer is stopped.
timeout When the timer had a timeout event.

Tables

timer Timer objects.


Constructors

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

Parameters:

  • args Arguments.
    • timeout number Timeout in seconds (e.g. 1.5).
    • autostart boolean Automatically start the timer. (default false)
    • call_now boolean Call the callback at timer creation. (default false)
    • callback function Callback function to connect to the “timeout” signal. (default nil)
    • single_shot boolean Run only once then stop. (default false)

Returns:

    timer

Static module functions

gears.timer.start_new (timeout, callback)
Create a timeout for calling some callback function. When the callback function returns true, it will be called again after the same timeout. If false is returned, no more calls will be done. If the callback function causes an error, no more calls are done.

Parameters:

  • timeout number Timeout in seconds (e.g. 1.5).
  • callback function Function to run.

Returns:

    timer The timer object that was set up.

See also:

gears.timer.weak_start_new (timeout, callback)
Create a timeout for calling some callback function. 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. After the callback function was collected, the timer returned will automatically be stopped.

Parameters:

  • timeout number Timeout in seconds (e.g. 1.5).
  • callback function Function to start.

Returns:

    timer The timer object that was set up.

See also:

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 main loop iteration

Parameters:

  • callback function The function that should be called
  • ... Arguments to the callback function

Object properties

started (boolean)
The timer is started.
timeout (number) · 1 signal
The timer timeout value. Signal: property::timeout
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 number The new value affected to the property.

Object methods

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

Emit signals:
:stop () · 1 signal
Stop the timer.
Click to display more

Emit signals:
: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:
:emit_signal (name, ...) · Inherited from gears.object
Emit a signal.

Parameters:

  • 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 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 string The name of the signal.
  • func function The callback to call when the signal is emitted.

Signals

start
When the timer is started.
stop
When the timer is stopped.
timeout
When the timer had a timeout event.

Tables

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 to enable garbage collection.

Fields:

  • 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.4.6 Last updated 2030-01-01 00:00:00