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

docs/89-NEWS.md

@@ -88,6 +88,9 @@ This document was last updated at commit v4.3-197-g9085ed631.
  * Pango 1.44 is now the oldest recommended Pango version. Older versions are
    still supported, but will lack the ability to use some textbox properties,
    mainly `wibox.widget.textbox.line_spacing_factor`.
+ * Passing a widget to any `widget_template` property now prints an error. It
+   wasn't working before, but wasn't printing an error. Replace `wibox.widget`
+   with `wibox.template` in your widget definition.
 
 <a name="v43"></a>
 # Awesome window manager framework version 4.3 changes

docs/config.ld

@@ -126,7 +126,7 @@ local type_fallback_description = {
         "string An [XFT string](https://wiki.archlinux.org/title/X_Logical_Font_Description), such as `\"-*-dejavu sans mono-medium-r-normal--*-80-*-*-*-*-iso10646-1\"`.",
 
     },
-    template = {
+    ["wibox.template"] = {
         "table A table containing a widget tree definition. WARNING: This is really a table"..
         " and **NOT** a widget object. Use the `widget = come.class.here` to define the "..
         " topmost class rather than construct an instance."
@@ -165,6 +165,7 @@ local type_name_linting = {
     ["double"]          = "number",
     ["float"]           = "number",
     ["bool"]            = "boolean",
+    ["template"]        = "wibox.template",
 }
 
 local metadata_tags = {

lib/awful/widget/common.lua

@@ -17,7 +17,6 @@ local capi = { button = button }
 local wibox = require("wibox")
 local gdebug = require("gears.debug")
 local dpi = require("beautiful").xresources.apply_dpi
-local base = require("wibox.widget.base")
 
 --- Common utilities for awful widgets
 local common = {}
@@ -51,7 +50,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.
@@ -72,7 +71,7 @@ end
 
 local function default_template()
     return custom_template {
-        widget_template = {
+        widget_template = wibox.template {
             id = 'background_role',
             border_strategy = 'inner',
             widget = wibox.container.background,

lib/awful/widget/layoutlist.lua

@@ -190,7 +190,7 @@ local layoutlist = {}
 --- The delegate widget template.
 --
 -- @property widget_template
--- @tparam[opt=nil] template|nil widget_template
+-- @tparam[opt=nil] wibox.template|nil widget_template
 -- @propemits true false
 
 --- The layoutlist screen.
@@ -362,7 +362,7 @@ function layoutlist:get_count()
 end
 
 function layoutlist:set_widget_template(widget_template)
-    self._private.widget_template = widget_template
+    self._private.widget_template = wibox.template.make_from_value(widget_template)
 
     -- Remove the existing instances
     self._private.data = setmetatable({}, { __mode = 'k' })

lib/awful/widget/taglist.lua

@@ -56,6 +56,7 @@ local gstring = require("gears.string")
 local gdebug = require("gears.debug")
 local base = require("wibox.widget.base")
 local gtable = require("gears.table")
+local wtemplate = require("wibox.template")
 
 local function get_screen(s)
     return s and capi.screen[s]
@@ -525,7 +526,7 @@ end
 --- A templete used to genetate the individual tag widgets.
 --
 -- @property widget_template
--- @tparam[opt=nil] template|nil widget_template
+-- @tparam[opt=nil] wibox.template|nil widget_template
 
 for _, prop in ipairs { "filter", "update_function", "widget_template", "source", "screen" } do
     taglist["set_"..prop] = function(self, value)
@@ -545,6 +546,16 @@ for _, prop in ipairs { "filter", "update_function", "widget_template", "source"
     end
 end
 
+function taglist:set_widget_template(widget_template)
+    self._private.widget_template = wtemplate.make_from_value(widget_template)
+
+    self._do_taglist_update()
+
+    self:emit_signal("widget::layout_changed")
+    self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::widget_template", self._private.widget_template)
+end
+
 --- Create a new taglist widget. The last two arguments (update_function
 -- and layout) serve to customize the layout of the taglist (eg. to
 -- make it vertical). For that, you will need to copy the
@@ -561,7 +572,7 @@ end
 --   is wibox.layout.fixed.horizontal().
 -- @tparam[opt=awful.widget.taglist.source.for_screen] function args.source The
 --  function used to generate the list of tag.
--- @tparam[opt] table args.widget_template A custom widget to be used for each tag
+-- @tparam[opt] wibox.template args.widget_template A custom widget to be used for each tag
 -- @tparam[opt={}] table args.style The style overrides default theme.
 -- @tparam[opt=beautiful.taglist_fg_focus] string|pattern args.style.fg_focus
 -- @tparam[opt=beautiful.taglist_bg_focus] string|pattern args.style.bg_focus
@@ -658,7 +669,7 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget)
         buttons         = args.buttons,
         filter          = args.filter,
         update_function = args.update_function,
-        widget_template = args.widget_template,
+        widget_template = wtemplate.make_from_value(args.widget_template),
         source          = args.source,
         screen          = screen
     })

lib/awful/widget/tasklist.lua

@@ -95,6 +95,7 @@ local wmargin = require("wibox.container.margin")
 local wtextbox = require("wibox.widget.textbox")
 local clienticon = require("awful.widget.clienticon")
 local wbackground = require("wibox.container.background")
+local wtemplate = require("wibox.template")
 local gtable = require("gears.table")
 
 local function get_screen(s)
@@ -391,7 +392,7 @@ local function default_template(self)
         or self._private.style.tasklist_disable_icon
         or beautiful.tasklist_disable_icon
 
-    return {
+    return wtemplate {
         {
             (not has_no_icon) and {
                 clienticon,
@@ -678,7 +679,7 @@ end
 -- @DOC_sequences_client_tasklist_widget_template1_EXAMPLE@
 --
 -- @property widget_template
--- @tparam[opt=nil] template|nil widget_template
+-- @tparam[opt=nil] wibox.template|nil widget_template
 -- @propemits true false
 
 --- A function to gather the clients to display.
@@ -794,7 +795,7 @@ function tasklist:set_screen(value)
 end
 
 function tasklist:set_widget_template(widget_template)
-    self._private.widget_template = widget_template
+    self._private.widget_template = wtemplate.make_from_value(widget_template)
 
     -- Remove the existing instances
     self._private.data = setmetatable({}, { __mode = 'k' })
@@ -803,7 +804,7 @@ function tasklist:set_widget_template(widget_template)
 
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::redraw_needed")
-    self:emit_signal("property::widget_template", widget_template)
+    self:emit_signal("property::widget_template", self._private.widget_template)
 end
 
 --- Create a new tasklist widget.
@@ -824,7 +825,7 @@ end
 --   is `wibox.layout.flex.horizontal`.
 -- @tparam[opt=awful.widget.tasklist.source.all_clients] function args.source The
 --  function used to generate the list of client.
--- @tparam[opt] table args.widget_template A custom widget to be used for each client
+-- @tparam[opt] wibox.template args.widget_template A custom widget to be used for each client
 -- @tparam[opt={}] table args.style The style overrides default theme.
 -- @tparam[opt=beautiful.tasklist_fg_normal] string|pattern args.style.fg_normal
 -- @tparam[opt=beautiful.tasklist_bg_normal] string|pattern args.style.bg_normal
@@ -922,7 +923,7 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget
         buttons           = args.buttons,
         style             = args.style or {},
         screen            = screen,
-        widget_template   = args.widget_template,
+        widget_template   = wtemplate.make_from_value(args.widget_template),
         source            = args.source,
         data              = setmetatable({}, { __mode = 'k' })
     })

lib/gears/shape.lua

@@ -778,6 +778,7 @@ end
 -- @tparam number height The shape height
 -- @tparam[opt=5] number x_offset The shadow area horizontal offset.
 -- @tparam[opt=5] number y_offset The shadow area vertical offset.
+-- @noreturn
 function module.solid_rectangle_shadow(cr, w, h, x_offset, y_offset)
     x_offset, y_offset = x_offset or 5, y_offset or 5
     w, h = w - math.abs(x_offset), h - math.abs(y_offset)

lib/naughty/layout/box.lua

@@ -176,7 +176,7 @@ end)
 --
 -- The default template is (less or more):
 --
---    {
+--    wibox.template {
 --        {
 --            {
 --                {
@@ -209,7 +209,7 @@ end)
 --    }
 --
 -- @property widget_template
--- @tparam[opt=nil] template|nil widget_template
+-- @tparam[opt=nil] wibox.template|nil widget_template
 -- @usebeautiful beautiful.notification_max_width The maximum width for the
 --  resulting widget.
 
@@ -324,7 +324,7 @@ end
 --
 -- @constructorfct naughty.layout.box
 -- @tparam[opt=nil] table args
--- @tparam table args.widget_template A widget definition template which will
+-- @tparam wibox.template args.widget_template A widget definition template which will
 --  be instantiated for each box.
 -- @tparam naughty.notification args.notification The notification object.
 -- @tparam string args.position The position. See `naughty.notification.position`.
@@ -364,7 +364,9 @@ local function new(args)
 
     local ret = popup(new_args)
     ret._private.notification = {}
-    ret._private.widget_template = args.widget_template
+    ret._private.widget_template = wibox.template.make_from_value(
+        args.widget_template
+    )
     ret._private.position = args.position
 
     gtable.crush(ret, box, true)

lib/naughty/list/actions.lua

@@ -203,7 +203,7 @@ local actionlist = {}
 
 --- The actionlist parent notification.
 -- @property widget_template
--- @tparam[opt=nil] template|nil widget_template
+-- @tparam[opt=nil] wibox.template|nil widget_template
 -- @propemits true false
 
 --- A table with values to override each `beautiful.notification_action` values.
@@ -271,7 +271,7 @@ function actionlist:set_base_layout(layout)
 end
 
 function actionlist:set_widget_template(widget_template)
-    self._private.widget_template = widget_template
+    self._private.widget_template = wibox.template.make_from_value(widget_template)
 
     -- Remove the existing instances
     self._private.data = {}
@@ -280,7 +280,7 @@ function actionlist:set_widget_template(widget_template)
 
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::redraw_needed")
-    self:emit_signal("property::widget_template", widget_template)
+    self:emit_signal("property::widget_template", self._private.widget_template)
 end
 
 function actionlist:set_style(style)

lib/naughty/list/notifications.lua

@@ -182,7 +182,7 @@ local notificationlist = {}
 
 --- The notificationlist parent notification.
 -- @property widget_template
--- @tparam[opt=nil] template|nil widget_template
+-- @tparam[opt=nil] wibox.template|nil widget_template
 -- @propertydefault The default template displays the icon, title, message and
 --  actions.
 -- @propemits true false
@@ -208,7 +208,7 @@ local notificationlist = {}
 -- @usebeautiful beautiful.notification_bgimage_selected Fallback.
 
 function notificationlist:set_widget_template(widget_template)
-    self._private.widget_template = widget_template
+    self._private.widget_template = wibox.template.make_from_value(widget_template)
 
     -- Remove the existing instances
     self._private.data = {}
@@ -217,7 +217,7 @@ function notificationlist:set_widget_template(widget_template)
 
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::redraw_needed")
-    self:emit_signal("property::widget_template", widget_template)
+    self:emit_signal("property::widget_template", self._private.widget_template)
 end
 
 function notificationlist:set_style(style)
@@ -289,7 +289,7 @@ end
 -- @tparam gears.color|string args.style.fg_selected
 -- @tparam gears.surface|string args.style.bgimage_normal
 -- @tparam gears.surface|string args.style.bgimage_selected
--- @tparam[opt] table args.widget_template A custom widget to be used for each
+-- @tparam[opt] wibox.template args.widget_template A custom widget to be used for each
 --  notifications.
 -- @treturn widget The notification list widget.
 -- @constructorfct naughty.list.notifications

lib/naughty/notification.lua

@@ -15,15 +15,16 @@
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @coreclassmod naughty.notification
 ---------------------------------------------------------------------------
-local capi     = { screen = screen }
-local gobject  = require("gears.object")
-local gtable   = require("gears.table")
-local timer    = require("gears.timer")
-local gfs      = require("gears.filesystem")
-local cst      = require("naughty.constants")
-local naughty  = require("naughty.core")
-local gdebug   = require("gears.debug")
-local pcommon = require("awful.permissions._common")
+local capi      = { screen = screen }
+local gobject   = require("gears.object")
+local gtable    = require("gears.table")
+local timer     = require("gears.timer")
+local gfs       = require("gears.filesystem")
+local cst       = require("naughty.constants")
+local naughty   = require("naughty.core")
+local gdebug    = require("gears.debug")
+local pcommon   = require("awful.permissions._common")
+local wtemplate = require("wibox.template")
 
 local notification = {}
 
@@ -514,7 +515,7 @@ local notification = {}
 -- off with a specialized notification widget.
 --
 -- @property widget_template
--- @tparam[opt=nil] template|nil widget_template
+-- @tparam[opt=nil] wibox.template|nil widget_template
 -- @propertydefault The default template as the icon, title, message and actions.
 -- @propemits true false
 
@@ -857,6 +858,21 @@ function notification:append_actions(new_actions)
 
 end
 
+function notification:set_widget_template(value)
+    self._private.widget_template = wtemplate.make_from_value(value)
+    self:emit_signal("property::widget_template", value)
+
+    -- When a notification is updated over dbus or by setting a property,
+    -- it is usually convenient to reset the timeout.
+    local reset = ((not self.suspended) or self._private.ignore_suspend)
+        and self.auto_reset_timeout ~= false
+        and naughty.auto_reset_timeout
+
+    if reset then
+        self:reset_timeout()
+    end
+end
+
 function notification:set_screen(s)
     assert(not self._private.screen)
 

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,