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:
🔗 :stop () · 1 signal
Stop the timer.

Does nothing if the timer isn't running.

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 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