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. | |
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 | Emitted when the timer is started. | |
stop | Emitted when the timer is stopped. | |
timeout | Emitted when timeout seconds have elapsed. |
Tables
timer | Timer objects. |
Constructors
- gears.timer {[args]}
-
Create a new timer object.
call_now
only takes effect when acallback
is provided.single_shot
, on the other hand, also stops signals connected to the timeout signal.Specifying a function
func
asargs.callback
is equivalent to calling:connect_signal(func)
on the 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. (optional)
- single_shot
boolean
Run only once then stop.
(default
false
)
- timeout
number
Timeout in seconds (e.g.
Returns:
- args Arguments.
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 callcallback
every timeout seconds. It is stopped whencallback
returnsfalse
, whencallback
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
The new timer object.
See also:
- 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:
- timeout number Timeout in seconds (e.g. 1.5).
- callback function Function to start.
Returns:
-
timer
The new timer object.
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 GLib event 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.
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 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
- 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 totrue
for the timer.
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
before dropping the last reference to prevent leaking the object.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.
- timeout
number
Interval in seconds to emit the timeout signal.
Can be any value, including floating point ones (e.g.