tests: Test `gears.connection`.

tests/examples/text/gears/connection/add_remove.lua

@@ -0,0 +1,39 @@
+--DOC_GEN_IMAGE
+
+local gears = {object = require("gears.object"), connection = require("gears.connection")} --DOC_HIDE
+
+-- When `source` changes, `target` is updated.
+local my_source_object1 = gears.object { --DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local my_source_object2 = gears.object {--DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local my_target_object1 = gears.object {--DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local conn = gears.connection {
+    source = my_source_object1,
+    target = my_target_object1,
+}
+
+--DOC_NEWLINE
+
+conn:append_source_object(my_source_object1)
+--DOC_NEWLINE
+assert(conn:has_source_object(my_source_object1))
+--DOC_NEWLINE
+assert(not conn:has_source_object(my_source_object2)) --DOC_HIDE
+conn:append_source_object(my_source_object2)
+assert(conn:has_source_object(my_source_object2)) --DOC_HIDE
+local ret = --DOC_HIDE
+conn:remove_source_object(my_source_object1)
+assert(ret) --DOC_HIDE
+assert(not conn:has_source_object(my_source_object1)) --DOC_HIDE
+assert(not  conn:remove_source_object({})) --DOC_HIDE

tests/examples/text/gears/connection/class.lua

@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE
+
+local gears = {object = require("gears.object"), connection = require("gears.connection")} --DOC_HIDE
+
+client.gen_fake {name = "foo"} --DOC_HIDE
+client.gen_fake {name = "baz"} --DOC_HIDE
+
+local called = 0 --DOC_HIDE
+
+--DOC_NEWLINE
+
+local conn = gears.connection {
+    source_class = client,
+    signals      = {"focused", "property::name"},
+    initiate     = false,
+    callback     = function()
+        called = called + 1 --DOC_HIDE
+        -- do something
+    end
+}
+
+assert(conn) --DOC_HIDE
+assert(conn.signals[1] == "focused") --DOC_HIDE
+assert(conn.signals[2] == "property::name") --DOC_HIDE
+assert(conn.source_class == client) --DOC_HIDE
+assert(conn.callback) --DOC_HIDE
+
+--DOC_NEWLINE
+
+-- This emit the `focused` signal.
+screen[1].clients[1]:activate{}
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(called == 1) --DOC_HIDE
+
+--DOC_NEWLINE
+
+-- Changing the name emits `property::name`.
+screen[1].clients[1].name = "bar"
+client.emit_signal("property::name", screen[1].clients[1]) --DOC_HIDE
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(called == 2) --DOC_HIDE
+

tests/examples/text/gears/connection/enabled.lua

@@ -0,0 +1,53 @@
+--DOC_GEN_IMAGE
+
+local gears = {object = require("gears.object"), connection = require("gears.connection")} --DOC_HIDE
+
+-- When `source` changes, `target` is updated.
+local my_source_object = gears.object { --DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local my_target_object1 = gears.object {--DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local my_target_object2 = gears.object {--DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+
+my_source_object.foo = 42
+
+--DOC_NEWLINE
+
+local conn1 = gears.connection {
+    source          = my_source_object,
+    source_property = "foo",
+    target          = my_target_object1,
+    target_property = "bar"
+}
+
+--DOC_NEWLINE
+
+local conn2 = gears.connection {
+    source          = my_source_object,
+    source_property = "foo",
+    target          = my_target_object2,
+    target_property = "bar"
+}
+
+--DOC_NEWLINE
+
+conn1.enabled = true
+conn2.enabled = false
+
+--DOC_NEWLINE
+
+-- conn1 should be enabled, but not conn2.
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(my_target_object1.bar == 42)
+assert(my_target_object2.bar == nil)
+

tests/examples/text/gears/connection/initiate.lua

@@ -0,0 +1,60 @@
+--DOC_GEN_IMAGE
+
+local gears = {object = require("gears.object"), connection = require("gears.connection")} --DOC_HIDE
+
+-- When `source` changes, `target` is updated.
+local my_source_object = gears.object { --DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local my_target_object1 = gears.object {--DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local my_target_object2 = gears.object {--DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+
+my_source_object.foo = 42
+
+--DOC_NEWLINE
+
+local conn = --DOC_HIDE
+gears.connection {
+    source          = my_source_object,
+    source_property = "foo",
+    target          = my_target_object1,
+    target_property = "bar"
+}
+
+assert(conn.source_property == "foo") --DOC_HIDE
+assert(conn.source == my_source_object) --DOC_HIDE
+assert(conn.target == my_target_object1) --DOC_HIDE
+assert(conn.target_property == "bar") --DOC_HIDE
+assert(conn.initiate) --DOC_HIDE
+
+--DOC_NEWLINE
+
+conn = --DOC_HIDE
+gears.connection {
+    source          = my_source_object,
+    source_property = "foo",
+    initiate        = false,
+    target          = my_target_object2,
+    target_property = "bar"
+}
+
+--DOC_NEWLINE
+
+assert(not conn.initiate) --DOC_HIDE
+
+-- my_target_object1 should be initialized, but not my_target_object2.
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(my_target_object1.bar == 42)
+assert(my_target_object2.bar == nil)
+
+conn.sources = {my_source_object, my_target_object1} --DOC_HIDE

tests/examples/text/gears/connection/method.lua

@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE
+
+local gears = {object = require("gears.object"), connection = require("gears.connection")} --DOC_HIDE
+
+local called = false --DOC_HIDE
+
+-- When `source` changes, `target` is updated.
+local my_source_object = gears.object { --DOC_HIDE
+    enable_properties   = true, --DOC_HIDE
+    enable_auto_signals = true  --DOC_HIDE
+}--DOC_HIDE
+
+local my_target_object = gears.object {--DOC_HIDE
+    enable_properties   = true, --DOC_HIDE
+    enable_auto_signals = true  --DOC_HIDE
+} --DOC_HIDE
+
+-- Declare a method.
+function my_target_object:my_method()
+    called = true --DOC_HIDE
+    -- do something
+end
+
+my_source_object.foo = 42 --DOC_HIDE
+
+--DOC_NEWLINE
+
+local conn = gears.connection {
+    source          = my_source_object,
+    source_property = "foo",
+    target          = my_target_object,
+    target_method   = "my_method"
+}
+
+assert(conn) --DOC_HIDE
+assert(conn.target == my_target_object) --DOC_HIDE
+assert(conn.enabled) --DOC_HIDE
+assert(conn.target_method == "my_method") --DOC_HIDE
+
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(called) --DOC_HIDE
+

tests/examples/text/gears/connection/target.lua

@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE
+
+local gears = {object = require("gears.object"), connection = require("gears.connection")} --DOC_HIDE
+
+-- When `source` changes, `target` is updated.
+local my_source_object = gears.object { --DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+local my_target_object = gears.object {--DOC_HIDE
+    enable_properties   = true,--DOC_HIDE
+    enable_auto_signals = true--DOC_HIDE
+}--DOC_HIDE
+
+my_source_object.foo = 42
+
+--DOC_NEWLINE
+
+local conn = gears.connection {
+    source          = my_source_object,
+    source_property = "foo",
+    target          = my_target_object,
+    target_property = "bar"
+}
+
+assert(conn) --DOC_HIDE
+
+--DOC_NEWLINE
+
+-- This works because `initiate` is `true` by default.
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(my_target_object.bar == 42)
+
+--DOC_NEWLINE
+
+-- This works because the `source` object `foo` is connected to
+-- the `target` object `bar` property.
+my_source_object.foo = 1337
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(my_target_object.bar == 1337)
+

tests/examples/wibox/decl_doc/connection.lua

@@ -0,0 +1,19 @@
+--DOC_GEN_IMAGE --DOC_HIDE --DOC_NO_USAGE --DOC_NO_DASH
+local parent = ... --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+
+    local w = wibox.widget {
+
+        -- Get the current cliently focused name.
+        gears.connection {
+            source_class         = client,
+            signal               = "focused",
+            source_property      = "name",
+            destination_property = "text",
+        },
+
+        widget = wibox.widget.textbox
+    }
+
+parent:add(w) --DOC_HIDE

tests/examples/wibox/decl_doc/connection2.lua

@@ -0,0 +1,49 @@
+--DOC_HIDE --DOC_NO_USAGE
+local gears = require("gears") --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+
+-- luacheck: globals my_textbox get_children_by_id --DOC_HIDE
+
+   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)
+
+               --DOC_NEWLINE
+
+               -- All widgets with IDs are visible from this callback!
+               assert(target and my_textbox) --DOC_HIDE
+               assert(target == my_textbox)
+
+               --DOC_NEWLINE
+
+               -- get_children_by_id can also be used!
+               assert(get_children_by_id("my_textbox")[1] == target)
+
+               --DOC_NEWLINE
+
+               if not source then return "Nothing!" end
+
+               --DOC_NEWLINE
+
+               return "Name: " .. source.name .. "!"
+           end
+       },
+       forced_width  = 100, --DOC_HIDE
+       forced_height = 20, --DOC_HIDE
+       id = "my_textbox",
+       widget = wibox.widget.textbox
+   }
+
+
+--DOC_HIDE 1: delayed connection, 2: delayed layout, 3: delayed draw
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(w.text == "Nothing!") --DOC_HIDE
+

tests/examples/wibox/decl_doc/connection3.lua

@@ -0,0 +1,37 @@
+--DOC_GEN_IMAGE --DOC_HIDE --DOC_NO_USAGE --DOC_NO_DASH
+local parent= ... --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+
+local obj = nil --DOC_HIDE
+
+gears.timer = function()--DOC_HIDE
+    obj = gears.object { --DOC_HIDE
+        enable_properties   = true, --DOC_HIDE
+        enable_auto_signals = true  --DOC_HIDE
+    }--DOC_HIDE
+    return obj --DOC_HIDE
+end--DOC_HIDE
+
+    local w = wibox.widget {
+
+        gears.connection {
+            source   = gears.timer {
+                timeout   = 5,
+                autostart = true,
+            },
+            signal   = "timeout",
+            callback = function(_, parent_widget)
+                parent_widget.text = "this will get called every 5 seconds"
+            end
+        },
+
+        widget = wibox.widget.textbox
+    }
+
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(obj) --DOC_HIDE
+obj:emit_signal("timeout") --DOC_HIDE
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+assert(w.text == "this will get called every 5 seconds") --DOC_HIDE
+parent:add(w) --DOC_HIDE

tests/examples/wibox/decl_doc/connection4.lua

@@ -0,0 +1,68 @@
+--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_HIDE
+local parent    = ... --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local data = { --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+} --DOC_HIDE
+
+local my_source_object = gears.object { --DOC_HIDE
+    enable_properties   = true, --DOC_HIDE
+    enable_auto_signals = true  --DOC_HIDE
+}--DOC_HIDE
+
+my_source_object.value = 0 --DOC_HIDE
+
+-- luacheck: globals my_graph my_label my_progress --DOC_HIDE
+
+local w = --DOC_HIDE
+    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,
+        forced_height = 30, --DOC_HIDE
+        forced_width  = 200, --DOC_HIDE
+        widget        = wibox.container.radialprogressbar,
+
+        --DOC_NEWLINE
+        -- 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
+        },
+    }
+
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+
+for _, v in ipairs(data) do --DOC_HIDE
+    assert(v ~= nil) --DOC_HIDE
+    my_source_object.value = v --DOC_HIDE
+end --DOC_HIDE
+
+parent:add(w) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/decl_doc/connection5.lua

@@ -0,0 +1,68 @@
+--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_HIDE --DOC_NO_DASH
+local parent    = ... --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local data = { --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+    3, 5, 6,4, 11,15,19,29,17,17,14,0,0,3,1,0,0, 22, 17,7, 1,0,0,5, --DOC_HIDE
+} --DOC_HIDE
+
+local my_source_object = gears.object { --DOC_HIDE
+    enable_properties   = true, --DOC_HIDE
+    enable_auto_signals = true  --DOC_HIDE
+}--DOC_HIDE
+
+my_source_object.value = 0 --DOC_HIDE
+
+-- luacheck: globals my_graph my_label my_progress --DOC_HIDE
+
+local w = --DOC_HIDE
+    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,
+        forced_height = 30, --DOC_HIDE
+        forced_width  = 200, --DOC_HIDE
+        widget        = wibox.container.radialprogressbar,
+
+        --DOC_NEWLINE
+        -- 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
+        },
+    }
+
+require("gears.timer").run_delayed_calls_now() --DOC_HIDE
+
+for _, v in ipairs(data) do --DOC_HIDE
+    assert(v ~= nil) --DOC_HIDE
+    my_source_object.value = v --DOC_HIDE
+end --DOC_HIDE
+
+parent:add(w) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80