[RFC] Implement wibox.widget.template: An abstract widget that handles a preset of concrete widget.

lib/wibox/widget/init.lua

@@ -25,6 +25,7 @@ local widget = {
     slider = require("wibox.widget.slider");
     calendar = require("wibox.widget.calendar");
     separator = require("wibox.widget.separator");
+    template = require("wibox.widget.template");
 }
 
 setmetatable(widget, {

lib/wibox/widget/template.lua

@@ -0,0 +1,129 @@
+---------------------------------------------------------------------------
+-- An abstract widget that handles a preset of concrete widget.
+--
+-- The `wibox.widget.template` widget is an abstraction layer that contains a
+-- concrete widget definition. The template widget can be used to build widgets
+-- that the user can customize at their will, thanks to the template mechanism.
+--
+-- @author Aire-One
+-- @copyright 2021 Aire-One <aireone@aireone.xyz>
+--
+-- @classmod wibox.widget.template
+-- @supermodule wibox.widget.base
+---------------------------------------------------------------------------
+
+local wbase = require("wibox.widget.base")
+local gtable = require("gears.table")
+local gtimer = require("gears.timer")
+
+local template = {
+    mt = {},
+    queued_updates = {},
+}
+
+function template:fit(...)
+    return self._private.widget:fit(...)
+end
+
+function template:draw(...)
+    return self._private.widget:draw(...)
+end
+
+function template:_do_update_now()
+    if type(self._private.update_callback) == "function" then
+        self._private.update_callback(self, self._private.update_args)
+    end
+
+    self._private.update_args = nil
+    template.queued_updates[self] = false
+end
+
+--- Update the widget.
+-- This function will call the `update_callback` function at the end of the
+-- current GLib event loop. Updates are batched by event loop, it means that the
+-- widget can only be update once by event loop. If the `template:update` method
+-- is called multiple times during the same GLib event loop, only the first call
+-- will be run.
+-- All arguments are passed to the queued `update_callback` call.
+function template:update(args)
+    if type(args) == "table" then
+        self._private.update_args = gtable.crush(
+            gtable.clone(self._private.update_args or {}, false),
+            args
+        )
+    end
+
+    if not template.queued_updates[self] then
+        gtimer.delayed_call(function()
+            self:_do_update_now()
+        end)
+        template.queued_updates[self] = true
+    end
+end
+
+function template:set_template(widget_template)
+    local widget = type(widget_template) == "function" and widget_template()
+        or widget_template
+        or wbase.empty_widget()
+
+    self._private.template = widget
+    self._private.widget = wbase.make_widget_from_value(widget)
+
+    -- We need to connect to these signals to actually redraw the template
+    -- widget when its child needs to.
+    local signals = {
+        "widget::redraw_needed",
+        "widget::layout_changed",
+    }
+    for _, signal in pairs(signals) do
+        self._private.widget:connect_signal(signal, function(...)
+            self:emit_signal(signal, ...)
+        end)
+    end
+
+    self:emit_signal("widget::redraw_needed")
+end
+
+function template:get_widget()
+    return self._private.widget
+end
+
+function template:set_update_callback(update_callback)
+    assert(type(update_callback) == "function" or update_callback == nil)
+
+    self._private.update_callback = update_callback
+end
+
+-- @hidden
+function template:set_update_now(update_now)
+    if update_now then
+        self:update()
+    end
+end
+
+--- Create a new `wibox.widget.template` instance.
+-- @tparam[opt] table args
+-- @tparam[opt] table|widget|function args.template The widget template to use.
+-- @tparam[opt] function args.update_callback The callback function to update the widget.
+-- @treturn wibox.widget.template The new instance.
+function template.new(args)
+    args = args or {}
+
+    local ret = wbase.make_widget(nil, nil, { enable_properties = true })
+
+    gtable.crush(ret, template, true)
+
+    ret:set_template(args.template)
+    ret:set_update_callback(args.update_callback)
+    ret:set_update_now(args.update_now)
+
+    return ret
+end
+
+function template.mt:__call(...)
+    return template.new(...)
+end
+
+return setmetatable(template, template.mt)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

spec/preload.lua

@@ -5,8 +5,8 @@ require "lgi"
 
 -- Always show deprecated messages
 _G.awesome = {
-   version = "v9999",
-   api_level = 9999,
+    version = "v9999",
+    api_level = 9999,
 }
 
 -- "fix" some intentional beautiful breakage done by .travis.yml

spec/wibox/widget/template_spec.lua

@@ -0,0 +1,73 @@
+---------------------------------------------------------------------------
+-- @author Aire-One
+-- @copyright 2021 Aire-One
+---------------------------------------------------------------------------
+
+_G.awesome.connect_signal = function() end
+
+local template = require("wibox.widget.template")
+local gtimer = require("gears.timer")
+
+describe("wibox.widget.template", function()
+    local widget
+
+    before_each(function()
+        widget = template()
+    end)
+
+    describe("widget:update()", function()
+        it("batch calls", function()
+            local spied_update_callback = spy.new(function() end)
+
+            widget.update_callback = function(...) spied_update_callback(...) end
+
+            -- Multiple calls to update
+            widget:update()
+            widget:update()
+            widget:update()
+
+            -- update_callback shouldn't be called before the end of the event loop
+            assert.spy(spied_update_callback).was.called(0)
+
+            gtimer.run_delayed_calls_now()
+
+            -- updates are batched, so only 1 call should have been performed
+            assert.spy(spied_update_callback).was.called(1)
+        end)
+
+        it("update parameters", function()
+            local spied_update_callback = spy.new(function() end)
+            local args = { foo = "string" }
+
+            widget.update_callback = function(...) spied_update_callback(...) end
+
+            widget:update(args)
+
+            gtimer.run_delayed_calls_now()
+
+            assert.spy(spied_update_callback).was.called_with(
+                match.is_ref(widget),
+                match.is_same(args)
+            )
+        end)
+
+        it("crush update parameters", function()
+            local spied_update_callback = spy.new(function() end)
+
+            widget.update_callback = function(...) spied_update_callback(...) end
+
+            widget:update { foo = "bar" }
+            widget:update { bar = 10 }
+
+            gtimer.run_delayed_calls_now()
+
+            assert.spy(spied_update_callback).was.called_with(
+                match.is_ref(widget),
+                match.is_same { foo = "bar", bar = 10 }
+            )
+        end)
+
+    end)
+end)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80