From 07590962e5be2fb766a5ab43c0194c652d599255 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 22 Oct 2022 21:00:13 -0700 Subject: [PATCH] template: Rename to `wibox.template`. It was previously `wibox.widget.template`, but was in fact a container. Now it is a top level concept. The next few commits will integrate it deeper into AwesomeWM. --- lib/awful/widget/common.lua | 2 +- lib/wibox/init.lua | 1 + lib/wibox/{widget => }/template.lua | 49 ++++++++----- lib/wibox/widget/init.lua | 1 - spec/wibox/widget/template_spec.lua | 4 +- .../sequences/widget/tmpl/bind_property.lua | 2 +- .../wibox/widget/template/basic_textbox.lua | 2 +- .../examples/wibox/widget/template/clone1.lua | 4 +- .../concrete_implementation_module.lua | 4 +- .../template/concrete_implementation_user.lua | 2 +- .../widget/template/set_property_custom.lua | 71 +++++++++---------- .../widget/template/set_property_existing.lua | 2 +- 12 files changed, 77 insertions(+), 67 deletions(-) rename lib/wibox/{widget => }/template.lua (91%) diff --git a/lib/awful/widget/common.lua b/lib/awful/widget/common.lua index ef665229d..58e46ac37 100644 --- a/lib/awful/widget/common.lua +++ b/lib/awful/widget/common.lua @@ -51,7 +51,7 @@ function common.create_buttons(buttons, object) end local function custom_template(args) - local l = base.make_widget_from_value(args.widget_template) + local l = wibox.template.make_from_value(args.widget_template) -- The template system requires being able to get children elements by ids. -- This is not optimal, but for now there is no way around it. diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index 9715a93ee..7cd09c18d 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -31,6 +31,7 @@ wibox.container = require("wibox.container") wibox.widget = require("wibox.widget") wibox.drawable = require("wibox.drawable") wibox.hierarchy = require("wibox.hierarchy") +wibox.template = require("wibox.template") local force_forward = { shape_bounding = true, diff --git a/lib/wibox/widget/template.lua b/lib/wibox/template.lua similarity index 91% rename from lib/wibox/widget/template.lua rename to lib/wibox/template.lua index 81d943fdc..7ee392567 100644 --- a/lib/wibox/widget/template.lua +++ b/lib/wibox/template.lua @@ -1,7 +1,7 @@ --------------------------------------------------------------------------- -- An abstract widget that handles a preset of concrete widget. -- --- The `wibox.widget.template` widget is an abstraction layer that contains a +-- The `wibox.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. -- @@ -23,7 +23,7 @@ -- (this part is to be completed according to awful.widget comming PRs to implement the widget_template usage) -- -- This widget was designed to be used as a standard way to offer customization --- over concrete widget implementation. We use the `wibox.widget.template` as a +-- over concrete widget implementation. We use the `wibox.template` as a -- base to implement widgets from the `awful.widget` library. This way, it is -- easy for the final user to customize the standard widget offered by awesome! -- @@ -31,7 +31,7 @@ -- widget module to offer more customization to the final user. -- -- Here is an example of implementation for a custom widget inheriting from --- `wibox.widget.template` : +-- `wibox.template` : -- -- The module definition should include a default widget and a builder function -- that can build the widget with either, the user values or the default. @@ -46,7 +46,7 @@ -- @author Aire-One -- @copyright 2021 Aire-One -- --- @widgetmod wibox.widget.template +-- @widgetmod wibox.template -- @supermodule wibox.widget.base --------------------------------------------------------------------------- @@ -232,8 +232,10 @@ function template:set_property(property, value, ids) widgets = widgets or {target} for _, widget in ipairs(widgets) do - if widget["set_"..property] then + if rawget(widget, "set_"..property) then widget["set_"..property](widget, value) + else + widget[property] = value end end end @@ -320,6 +322,10 @@ function template:get_widget() return lazy_load_child(self) end +function template:get_children() + return { lazy_load_child(self) } +end + --- Set the update_callback property. -- @tparam function update_callback The new callback function. -- @method set_update_callback @@ -330,6 +336,15 @@ function template:set_update_callback(update_callback) self._private.update_callback = update_callback end +function template:get_update_callback() + return self._private.update_callback +end + +-- Undocumented, for backward compatibility +function template:get_create_callback() + return rawget(lazy_load_child(self), "create_callback") +end + --- Hack to allow automatic update of the widget at construction time. -- This is supposed to be a setter for an `update_now` property. This property -- however doesn't exist. We use this setter in the scope of the widget @@ -347,32 +362,32 @@ function template:set_update_now(update_now) end ---- Create a new `wibox.widget.template` instance using the same template. +--- Create a new `wibox.template` instance using the same template. -- -- This copy will be blank. Note that `set_property`, `bind_property` or -- `update_callback` from `self` will **NOT** be transferred over to the copy. -- -- The following example is a new widget to list a bunch of colors. It uses --- `wibox.widget.template` to let the module user define their own color +-- `wibox.template` to let the module user define their own color -- widget. It does so by cloning the original template into new instances. This -- example doesn't handle removing or updating them to keep the size small. -- --@DOC_wibox_widget_template_clone1_EXAMPLE@ -- -- @method clone --- @treturn wibox.widget.template The copy. +-- @treturn wibox.template The copy. function template:clone() return template(self._private.widget_template) end ---- Create a new `wibox.widget.template` instance. +--- Create a new `wibox.template` instance. -- @tparam[opt] table tmpl -- @tparam[opt] function tmpl.update_callback The callback function to update -- the widget. -- @tparam[opt] boolean tmpl.update_now Update the widget after its -- construction. This will call the `:update()` method with no parameter. --- @treturn wibox.widget.template The new instance. --- @constructorfct wibox.widget.template +-- @treturn wibox.template The new instance. +-- @constructorfct wibox.template function template.new(tmpl) tmpl = tmpl or {} @@ -390,22 +405,22 @@ function template.new(tmpl) return ret end ---- Create a `wibox.widget.template` from a table. +--- Create a `wibox.template` from a table. -- --- @staticfct wibox.widget.template.make_from_value --- @tparam[opt=nil] table|wibox.widget.template|nil value A template declaration. --- @treturn wibox.widget.template The template object. +-- @staticfct wibox.template.make_from_value +-- @tparam[opt=nil] table|wibox.template|nil value A template declaration. +-- @treturn wibox.template The template object. function template.make_from_value(value) if not value then return nil end + if rawget(value, "_is_template") then return value:clone() end + assert( not rawget(value, "is_widget"), "This property requires a widget template, not a widget object.\n".. "Use `wibox.template` instead of `wibox.widget`" ) - if rawget(value, "_is_template") then return value:clone() end - return template.new(value) end diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index ed766622d..b96caac7f 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -25,7 +25,6 @@ local widget = { slider = require("wibox.widget.slider"); calendar = require("wibox.widget.calendar"); separator = require("wibox.widget.separator"); - template = require("wibox.widget.template"); } setmetatable(widget, { diff --git a/spec/wibox/widget/template_spec.lua b/spec/wibox/widget/template_spec.lua index 1a603fa86..6444fd435 100644 --- a/spec/wibox/widget/template_spec.lua +++ b/spec/wibox/widget/template_spec.lua @@ -6,9 +6,9 @@ _G.awesome.connect_signal = function() end local gtimer = require("gears.timer") -local template = require("wibox.widget.template") +local template = require("wibox.template") -describe("wibox.widget.template", function() +describe("wibox.template", function() local widget before_each(function() diff --git a/tests/examples/sequences/widget/tmpl/bind_property.lua b/tests/examples/sequences/widget/tmpl/bind_property.lua index cec436bdc..0573da590 100644 --- a/tests/examples/sequences/widget/tmpl/bind_property.lua +++ b/tests/examples/sequences/widget/tmpl/bind_property.lua @@ -12,7 +12,7 @@ client.focus = client.gen_fake{ --DOC_HIDE_END - local my_template_widget = wibox.widget.template { + local my_template_widget = wibox.template { { { set_icon = function(self, icon) diff --git a/tests/examples/wibox/widget/template/basic_textbox.lua b/tests/examples/wibox/widget/template/basic_textbox.lua index 0be653662..fe4ebca41 100644 --- a/tests/examples/wibox/widget/template/basic_textbox.lua +++ b/tests/examples/wibox/widget/template/basic_textbox.lua @@ -5,7 +5,7 @@ local parent = ... local wibox = require("wibox") --DOC_HIDE_END - local my_template_widget = wibox.widget.template { + local my_template_widget = wibox.template { widget = wibox.widget.textbox, update_callback = function(template_widget, args) local text = args.text or "???" diff --git a/tests/examples/wibox/widget/template/clone1.lua b/tests/examples/wibox/widget/template/clone1.lua index 4a8690031..32adfc780 100644 --- a/tests/examples/wibox/widget/template/clone1.lua +++ b/tests/examples/wibox/widget/template/clone1.lua @@ -22,7 +22,7 @@ client.focus = client.gen_fake{ local module = {} --DOC_NEWLINE - local default_template = wibox.widget.template { + local default_template = wibox.template { { { { @@ -59,7 +59,7 @@ client.focus = client.gen_fake{ -- @property widget_template -- @tparam[opt=nil] wibox.template|nil function module:set_widget_template(t) - self._private.widget_template = wibox.widget.template.make_from_value(t) + self._private.widget_template = wibox.template.make_from_value(t) end --DOC_NEWLINE diff --git a/tests/examples/wibox/widget/template/concrete_implementation_module.lua b/tests/examples/wibox/widget/template/concrete_implementation_module.lua index 8c4f0e6d2..d6bcc426c 100644 --- a/tests/examples/wibox/widget/template/concrete_implementation_module.lua +++ b/tests/examples/wibox/widget/template/concrete_implementation_module.lua @@ -25,9 +25,7 @@ local wibox = require("wibox") --DOC_NEWLINE -- Build an instance of the template widget with either, the -- user provided parameters or the default - local ret = wibox.widget.template { - template = args.widget_template or default_widget - } + local ret = wibox.template(args.widget_template or default_widget) --DOC_NEWLINE -- Patch the methods and fields the widget instance should have diff --git a/tests/examples/wibox/widget/template/concrete_implementation_user.lua b/tests/examples/wibox/widget/template/concrete_implementation_user.lua index b6b3182dc..3af55021d 100644 --- a/tests/examples/wibox/widget/template/concrete_implementation_user.lua +++ b/tests/examples/wibox/widget/template/concrete_implementation_user.lua @@ -6,7 +6,7 @@ local parent = ... local wibox = require("wibox") local function concrete_widget_template_builder(args) - return wibox.widget.template(args) + return wibox.template(args) end --DOC_HIDE_END diff --git a/tests/examples/wibox/widget/template/set_property_custom.lua b/tests/examples/wibox/widget/template/set_property_custom.lua index 5123baf3b..e481f0d98 100644 --- a/tests/examples/wibox/widget/template/set_property_custom.lua +++ b/tests/examples/wibox/widget/template/set_property_custom.lua @@ -14,44 +14,42 @@ client.focus = client.gen_fake{ --DOC_HIDE_END - local my_template_widget = wibox.widget.template { - template = { + local my_template_widget = wibox.template { + { { - { - id = "client_role", - set_client = function(self, c) - self.image = gears.surface(c.icon) - end, - widget = wibox.widget.imagebox - }, - { - id = "client_role", - set_client = function(self, c) - -- If the value can change, don't forget to connect - -- some signals: - local function update() - local txt = "Name: "..c.name - if c.minimized then - txt = txt .. " (minimized)" - end - self.markup = txt - end - - update() - c:connect_signal("property::name", update) - c:connect_signal("property::minimized", update) - end, - widget = wibox.widget.textbox - }, - widget = wibox.layout.fixed.horizontal, + id = "client_role", + set_client = function(self, c) + self.image = gears.surface(c.icon) + end, + widget = wibox.widget.imagebox }, - bg = "#0000ff", - fg = "#ffffff", - shape = gears.share.rounded_rect, - widget = wibox.container.background, - forced_width = 200, --DOC_HIDE - forced_height = 24, --DOC_HIDE - } + { + id = "client_role", + set_client = function(self, c) + -- If the value can change, don't forget to connect + -- some signals: + local function update() + local txt = "Name: "..c.name + if c.minimized then + txt = txt .. " (minimized)" + end + self.markup = txt + end + + update() + c:connect_signal("property::name", update) + c:connect_signal("property::minimized", update) + end, + widget = wibox.widget.textbox + }, + widget = wibox.layout.fixed.horizontal, + }, + bg = "#0000ff", + fg = "#ffffff", + shape = gears.share.rounded_rect, + widget = wibox.container.background, + forced_width = 200, --DOC_HIDE + forced_height = 24, --DOC_HIDE } --DOC_NEWLINE @@ -63,5 +61,4 @@ client.focus = client.gen_fake{ --DOC_HIDE_START parent:add(my_template_widget) - -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/widget/template/set_property_existing.lua b/tests/examples/wibox/widget/template/set_property_existing.lua index 08771623c..485b2117a 100644 --- a/tests/examples/wibox/widget/template/set_property_existing.lua +++ b/tests/examples/wibox/widget/template/set_property_existing.lua @@ -14,7 +14,7 @@ client.focus = client.gen_fake{ --DOC_HIDE_END - local my_template_widget = wibox.widget.template { + local my_template_widget = wibox.template { { { id = "icon_role",