Module: `gears.connection`

Object oriented way to connect objects.

All AwesomeWM objects have a emit_signal method. They allow to attach business logic to a property value change or random types of events.

The default way to attach business logic to signals is to use connect_signal. It allows to call a function when the signal is emitted. This remains the most common way to perform a connection. However, it is very verbose to use that construct alongside the declarative widget system. gears.connection is much easier to integrate in such constructs:

Usage example

wibox.widget {
    {
        {
            id        = "my_graph",
            max_value = 30,
            widget    = wibox.widget.graph
        },
        {
            id     = "my_label",
            align  = "center",
            valign = "center",
            widget = wibox.widget.textbox,
        },
        layout = wibox.layout.stack
    },
    id            = "my_progress",
    max_value     = 30,
    min_value     = 0,
    widget        = wibox.container.radialprogressbar,

    -- Set the value of all 3 widgets.
    gears.connection {
        source          = my_source_object,
        source_property = "value",
        callback        = function(_, _, value)
            my_graph:add_value(value)
            my_label.text = value .. "mB/s"
            my_progress.value = value
        end
    },
}

Limitations

When used directly as a value to a declarative object (text = gears.connection{...}), it is necessary to manually disconnect the connectio if you want it to stop being auto-updated.

Info:

Copyright: 2019-2020 Emmanuel Lepage-Vallee
Originally authored by: Emmanuel Lepage-Vallee <elv1313@gmail.com>
(Full contributors list available on our github project)

Constructors

gears.connection {[args]}

Create a new gears.connection object.

Object properties

initiate	boolean	If the property should be set when the target object is defined.
enabled	boolean	Turn this connection on or off.
signals	table	A list of source object signals.
signal	string	The (source) signal to monitor.
target	gears.object	The object for the right side object of the connection.
target_property	string	The target object property to set when the source property changes.
target_method	string	Rather than use a property, call a method.
source_class	class or string	Use a whole class rather than an object as source.
source	gears.object	The source object (connection left hand side).
source_property	string	The source object(s)/class property.
sources	gears.object	A list of source objects (connection left hand side).
callback	function	A function called when the source changes.

Object methods

:append_source_object (obj)	Add a source object.
:remove_source_object (obj)	Remove a source object.
:has_source_object (obj)	Return true when `obj` is already a source object.
:disconnect ()	Disconnect this object.
:reconnect ()	Reconnect this object.
: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

Constructors

gears.connection {[args]}

Create a new gears.connection object.

Parameters:

args
- initiate boolean If the property should be set when the target object is defined.
- enabled boolean Turn this connection on or off.
- signals boolean A list of source object signals.
- signal string The (source) signal to monitor.
- target gears.object The object for the right side object of the connection.
- target_property string The target object property to set when the source property changes.
- target_method string Rather than use a property, call a method.
- source_class class or string Use a whole class rather than an object as source.
- source gears.object The source object (connection left hand side).
- source_property string The source object(s)/class property.
- sources gears.object A list of source objects (connection left hand side).
- callback function A function called when the source changes.

Object properties

initiate boolean · 1 signal

If the property should be set when the target object is defined.

It is enabled by default for convinience.

Usage example

Type constraints:

string boolean initiate (default true)

Usage:

-- When source changes, target is updated.
my_source_object.foo = 42

gears.connection {
    source          = my_source_object,
    source_property = "foo",
    target          = my_target_object1,
    target_property = "bar"
}

gears.connection {
    source          = my_source_object,
    source_property = "foo",
    initiate        = false,
    target          = my_target_object2,
    target_property = "bar"
}

-- my_target_object1 should be initialized, but not my_target_object2.
assert(my_target_object1.bar == 42)
assert(my_target_object2.bar == nil)

Click to display more

Emit signals:

property::gears.connection.initiate When the gears.connection.initiate value changes.

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

enabled boolean · 1 signal

Turn this connection on or off.

Usage example

Usage:

-- When source changes, target is updated.
my_source_object.foo = 42

local conn1 = gears.connection {
    source          = my_source_object,
    source_property = "foo",
    target          = my_target_object1,
    target_property = "bar"
}

local conn2 = gears.connection {
    source          = my_source_object,
    source_property = "foo",
    target          = my_target_object2,
    target_property = "bar"
}

conn1.enabled = true
conn2.enabled = false

-- conn1 should be enabled, but not conn2.
assert(my_target_object1.bar == 42)
assert(my_target_object2.bar == nil)

Click to display more

Emit signals:

property::gears.connection.enabled When the gears.connection.enabled value changes.

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

signals table · 1 signal

A list of source object signals.

Emit signals:

property::gears.connection.signals When the gears.connection.signals value changes.

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

signal string · 1 signal

The (source) signal to monitor.

Note that signals and source_property are also provided to simplify common use cases.

Emit signals:

property::gears.connection.signal When the gears.connection.signal value changes.

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

target gears.object · 1 signal

The object for the right side object of the connection.

When used in a widget declarative tree, this is implicit and is the parent object.

Usage example

Usage:

-- When source changes, target is updated.
my_source_object.foo = 42

local conn = gears.connection {
    source          = my_source_object,
    source_property = "foo",
    target          = my_target_object,
    target_property = "bar"
}

-- This works because initiate is true by default.
assert(my_target_object.bar == 42)

-- This works because the source object foo is connected to
-- the target object bar property.
my_source_object.foo = 1337
assert(my_target_object.bar == 1337)

Click to display more

Emit signals:

property::gears.connection.target When the gears.connection.target value changes.

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

target_property string · 1 signal

The target object property to set when the source property changes.

Emit signals:

property::gears.connection.target_property When the gears.connection.target_property value changes.

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

target_method string · 1 signal

Rather than use a property, call a method.

Usage example

Usage:

-- When source changes, target is updated.
-- Declare a method.
function my_target_object:my_method()
    -- do something
end

local conn = gears.connection {
    source          = my_source_object,
    source_property = "foo",
    target          = my_target_object,
    target_method   = "my_method"
}

Click to display more

Emit signals:

property::gears.connection.target_method When the gears.connection.target_method value changes.

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

source_class class or string · 1 signal

Use a whole class rather than an object as source.

Many classes, like client, tag, screen and naughty.notification provide class level signals. When any instance of those classes emit a signal, it is forwarded to the class level signals.

Usage example

Usage:

local conn = gears.connection {
    source_class = client,
    signals      = {"focused", "property::name"},
    initiate     = false,
    callback     = function()
        -- do something
    end
}

-- This emit the focused signal.
screen[1].clients[1]:activate{}

-- Changing the name emits property::name.
screen[1].clients[1].name = "bar"

Click to display more

Emit signals:

property::gears.connection.source_class When the gears.connection.source_class value changes.

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

source gears.object · 1 signal

The source object (connection left hand side).

Emit signals:

property::gears.connection.source When the gears.connection.source value changes.

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

source_property string · 1 signal

The source object(s)/class property.
Click to display more

Emit signals:

property::gears.connection.source_property When the gears.connection.source_property value changes.

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

sources gears.object · 1 signal

A list of source objects (connection left hand side).

If many objects have the same signal, it's not necessary to make multiple gears.connection. They can share the same.

Emit signals:

property::gears.connection.sources When the gears.connection.sources value changes.

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

callback function · 1 signal

A function called when the source changes.

local w = wibox.widget {
    -- Get the current cliently focused name.
    text = gears.connection {
        source_class = client,
        signals      = {"focused", "property::name"},
        initiate     = false,
        callback     = function(source, target, sig_arg1, ...) --luacheck: no unused args
            -- Since the class signal first arg is the source, this works!
            assert(source == sig_arg1)

            -- All widgets with IDs are visible from this callback!
            assert(target == my_textbox)

            -- get_children_by_id can also be used!
            assert(get_children_by_id("my_textbox")[1] == target)

            if not source then return "Nothing!" end

            return "Name: " .. source.name .. "!"
        end
    },
    id = "my_textbox",
    widget = wibox.widget.textbox
}

The callback arguments are:

 callback = function(source, target, sig_arg1, ...)
                      /\     /\        /\     /\
                       |      |         |      |
          The  client -|      |         |      |
       It will be the widget -|         |      |
     Signal first argument, the client -|      |
                   All other signal arguments -|

Click to display more

Emit signals:

property::gears.connection.callback When the gears.connection.callback value changes.

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

Object methods

:append_source_object (obj)

Add a source object.

Usage example

Parameters:

obj gears.object The object.

Usage:

-- When source changes, target is updated.
local conn = gears.connection {
    source = my_source_object1,
    target = my_target_object1,
}

conn:append_source_object(my_source_object1)

assert(conn:has_source_object(my_source_object1))

conn:append_source_object(my_source_object2)
conn:remove_source_object(my_source_object1)

:remove_source_object (obj)

Remove a source object.

Parameters:

obj gears.object The object.

Parameters:

obj gears.object The object.

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.

awesome

Contents

Classes

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Documentation

Module: gears.connection

Limitations

Info:

Constructors

Object properties

Object methods

Constructors

Parameters:

Object properties

Type constraints:

Usage:

Emit signals:

See also:

Usage:

Emit signals:

See also:

Emit signals:

See also:

Emit signals:

See also:

Usage:

Emit signals:

See also:

Emit signals:

See also:

Usage:

Emit signals:

See also:

Usage:

Emit signals:

See also:

Emit signals:

Emit signals:

See also:

Emit signals:

Emit signals:

Object methods

Parameters:

See also:

Usage:

Parameters:

See also:

Parameters:

See also:

See also:

See also:

Parameters:

Parameters:

Parameters:

Module: `gears.connection`