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
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.
wake_up	boolean	Emit "timeout" if the timer is past due when resuming.
timeout	number	The timer timeout value.
randomized	boolean	Randomize the length of the first iteration.
start_at	table	When the timer starts.
stop_at	table	When the timer stops.
elapsed	number	Nunber of seconds since the timer started.
remaining	number	Number of seconds until the next timeout.
initial_delay	number	Number of seconds before the normal timeout cycle begins.
count	number	The number of timeouts since the timer started.
iterations	number	Number of timeouts before auto-stopping.
single_shot	boolean	Trigger this timer a single time then stop.

Object methods

:start ()	Start the timer.
:stop ()	Stop the timer.
:again ()	Restart the timer.
:realign ()	Re-align the timer.
:snooze (delay)	Snooze (mute) the timer for a number of seconds.
:delay (delay)	Add a delay before the next timeout.
: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.
finished	When the number of timeout reaches the value of iterations.

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)
- wake_up boolean Track system sleep. (default false)
- callback function Callback function to connect to the "timeout" signal. (default nil)
- single_shot boolean Run only once then stop. (default false)
- initial_delay number The number of seconds before auto-starting the timer. Note that autostart also needs to be set for the timer to actually start. (default 0)
- randomized boolean Randomize the length of the first iteration (from zero to the value of timeout). (default false)
- iterations number The number of timeout before stopping the timer. (default nil)
- start_at table Wait until this time to "really" start. (default nil)
- stop_at table Stop the timer at this time. (default nil)

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:

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

Returns:

timer

Parameters:

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

Returns:

timer

Parameters:

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

Object properties

started boolean

The timer is started.

wake_up boolean · 1 signal

Emit "timeout" if the timer is past due when resuming.

If the computer goes to sleep, temporarely freezes or hibernates, it is possible one or many timeout signals wont be sent. If this is detected and this property is set to true, the timeout signal will be emitted. Please note that AwesomeWM down not actively track when the system goes to sleep for portability and resource usage reasons. This property is implemented in a best-effort way.

Click to display more

Emit signals:

property::wake_up When the wake_up value changes.

self gears.timer The object which changed (useful when connecting many object to the same callback).
new_value wake_up The new value affected to the property.

timeout number · 1 signal

The timer timeout value.

The value can be a number (in seconds). It can also be a table with the following:

second: Number from 0 to 59.
minute: Number from 0 to 59.
hour: Number from 0 to 23.
day: Number from 1 to 31.
month: Number between 1 and 12.
year: Full year number (eg. 2021) starting with the current year.
multiplier: Floating point number to divide/multiply the number of seconds between 2 timeouts.

If the multiplier is lesser than one, then it will make the timeout happen more often. For example, for {second = 0, multiplier = 1/3}, the timeout will occur at :00, :20, :40 of every minute.

If the multiplier of greater than 1, then it will happen less often. For example, for { minute = 0, multiplier = 2}, the timeout will happen every 2 hours.

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.

randomized boolean · 1 signal

Randomize the length of the first iteration.

The delay will be between zero and timeout.

This option is useful to distribute the events across time. For example, if there is 2 timers at 5 seconds and one at 10 seconds, then 3 timeout will occur virtually at the same time. If they trigger a lot of code, then it might create visible latency.

Please also note that the opposite can also be resirable. Bundling multiple events at the same time can improve energy usage on laptops by letting them be idle for longer.

Using randomized = true is thus desirable for low latency and randomized = false is better for energy efficiency.

Click to display more

Emit signals:

property::randomized When the randomized value changes.

self gears.timer The object which changed (useful when connecting many object to the same callback).
new_value boolean The new value affected to the property.

start_at table · 1 signal

When the timer starts.

Note that using this property still requires something to either call :start() or set autostart in the constructor. This tells when timer when to start, not if it is started.

Note that setting this property will reset initial_delay as they are both mutually exclusive.

Emit signals:

property::start_at When the start_at value changes.

self gears.timer The object which changed (useful when connecting many object to the same callback).
new_value start_at The new value affected to the property.

stop_at table · 1 signal · 1 signal

When the timer stops.

Emit signals:

finished When the timer stops.

Emit signals:

property::stop_at When the stop_at value changes.

self gears.timer The object which changed (useful when connecting many object to the same callback).
new_value start_at The new value affected to the property.

elapsed number

Nunber of seconds since the timer started.

This property is read-only.

remaining number

Number of seconds until the next timeout.

initial_delay number · 1 signal

Number of seconds before the normal timeout cycle begins.

The value is in seconds.

Please note that setting this value does not start the timer. :start() still needs to be called. Also note that setting this property will reset the start_at property as they are mutually exclusive.

Click to display more

Emit signals:

property::initial_delay When the initial_delay value changes.

self gears.timer The object which changed (useful when connecting many object to the same callback).
new_value initial_delay The new value affected to the property.

count number

The number of timeouts since the timer started.

Note that this property is reset each timer the timer is (re)started.

iterations number · 1 signal · 1 signal

Number of timeouts before auto-stopping.

Emit signals:

finished After the timer timeouts the iterations time.

Emit signals:

property::iterations When the iterations value changes.

self gears.timer The object which changed (useful when connecting many object to the same callback).
new_value iterations The new value affected to the property.

single_shot boolean · 1 signal · 1 signal

Trigger this timer a single time then stop.

Emit signals:

finished After the timer timeout once.

Emit signals:

property::single_shot When the single_shot value changes.

self gears.timer The object which changed (useful when connecting many object to the same callback).
new_value single_shot The new value affected to the property.

Object methods

:start () · 1 signal

Start the timer.

If there is an initial_delay or start_at, the start signal will be emitted later.

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

:realign ()

Re-align the timer.

When the timeout property is a date/time rather than a number of milliseconds, it is possible the time will shift. This method will reset the timer delay.

:snooze (delay)

Snooze (mute) the timer for a number of seconds.

This will not emit timeout before the delay.

Parameters:

delay number The delay (in seconds).

Parameters:

delay number The delay (in seconds).

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.

finished

When the number of timeout reaches the value of iterations.

awesome

Contents

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

Documentation

Module: gears.timer

Usage:

Info:

Constructors

Static module functions

Object properties

Object methods

Signals

Constructors

Parameters:

Returns:

Static module functions

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Object properties

Emit signals:

Emit signals:

Emit signals:

See also:

Emit signals:

See also:

Emit signals:

Emit signals:

Emit signals:

See also:

Emit signals:

Emit signals:

See also:

Emit signals:

Emit signals:

Object methods

Emit signals:

Emit signals:

Emit signals:

Parameters:

See also:

Parameters:

See also:

Parameters:

Parameters:

Parameters:

Signals

See also:

Module: `gears.timer`