Merge pull request #2508 from Elv13/xmas_2k18_2

New round of API standardization (for v4.4)

awesomerc.lua

@@ -104,7 +104,7 @@ mytextclock = wibox.widget.textclock()
 
 -- Create a wibox for each screen and add it
 -- @TAGLIST_BUTTON@
-local taglist_buttons = gears.table.join(
+local taglist_buttons = {
     awful.button({ }, 1, function(t) t:view_only() end),
     awful.button({ modkey }, 1, function(t)
                                 if client.focus then
@@ -118,11 +118,11 @@ local taglist_buttons = gears.table.join(
                                 end
                             end),
     awful.button({ }, 4, function(t) awful.tag.viewnext(t.screen) end),
-                    awful.button({ }, 5, function(t) awful.tag.viewprev(t.screen) end)
-                )
+    awful.button({ }, 5, function(t) awful.tag.viewprev(t.screen) end),
+}
 
 -- @TASKLIST_BUTTON@
-local tasklist_buttons = gears.table.join(
+local tasklist_buttons = {
     awful.button({ }, 1, function (c)
                             if c == client.focus then
                                 c.minimized = true
@@ -142,7 +142,8 @@ local tasklist_buttons = gears.table.join(
                         end),
     awful.button({ }, 5, function ()
                             awful.client.focus.byidx(-1)
-                                          end))
+                        end),
+}
 
 -- @DOC_WALLPAPER@
 screen.connect_signal("request::wallpaper", function(s)
@@ -166,12 +167,16 @@ screen.connect_signal("request::desktop_decoration", function(s)
     s.mypromptbox = awful.widget.prompt()
     -- Create an imagebox widget which will contain an icon indicating which layout we're using.
     -- We need one layoutbox per screen.
-    s.mylayoutbox = awful.widget.layoutbox(s)
-    s.mylayoutbox:buttons(gears.table.join(
+    s.mylayoutbox = awful.widget.layoutbox {
+        screen  = s,
+        buttons = {
             awful.button({ }, 1, function () awful.layout.inc( 1) end),
             awful.button({ }, 3, function () awful.layout.inc(-1) end),
             awful.button({ }, 4, function () awful.layout.inc( 1) end),
-                           awful.button({ }, 5, function () awful.layout.inc(-1) end)))
+            awful.button({ }, 5, function () awful.layout.inc(-1) end),
+        }
+    }
+
     -- Create a taglist widget
     s.mytaglist = awful.widget.taglist {
         screen  = s,
@@ -192,7 +197,7 @@ screen.connect_signal("request::desktop_decoration", function(s)
 
     -- @DOC_SETUP_WIDGETS@
     -- Add widgets to the wibox
-    s.mywibox:setup {
+    s.mywibox.widget = {
         layout = wibox.layout.align.horizontal,
         { -- Left widgets
             layout = wibox.layout.fixed.horizontal,
@@ -214,16 +219,16 @@ end)
 
 -- {{{ Mouse bindings
 -- @DOC_ROOT_BUTTONS@
-root.buttons(gears.table.join(
+root.buttons = {
     awful.button({ }, 3, function () mymainmenu:toggle() end),
     awful.button({ }, 4, awful.tag.viewnext),
-    awful.button({ }, 5, awful.tag.viewprev)
-))
+    awful.button({ }, 5, awful.tag.viewprev),
+}
 -- }}}
 
 -- {{{ Key bindings
 -- @DOC_GLOBAL_KEYBINDINGS@
-globalkeys = gears.table.join(
+globalkeys = {
     awful.key({ modkey,           }, "s",      hotkeys_popup.show_help,
               {description="show help", group="awesome"}),
     awful.key({ modkey,           }, "Left",   awful.tag.viewprev,
@@ -321,11 +326,11 @@ globalkeys = gears.table.join(
               {description = "lua execute prompt", group = "awesome"}),
     -- Menubar
     awful.key({ modkey }, "p", function() menubar.show() end,
-              {description = "show the menubar", group = "launcher"})
-)
+              {description = "show the menubar", group = "launcher"}),
+}
 
 -- @DOC_CLIENT_KEYBINDINGS@
-clientkeys = gears.table.join(
+clientkeys = {
     awful.key({ modkey,           }, "f",
         function (c)
             c.fullscreen = not c.fullscreen
@@ -366,17 +371,16 @@ clientkeys = gears.table.join(
             c.maximized_horizontal = not c.maximized_horizontal
             c:raise()
         end ,
-        {description = "(un)maximize horizontally", group = "client"})
-)
+        {description = "(un)maximize horizontally", group = "client"}),
+}
 
 -- @DOC_NUMBER_KEYBINDINGS@
 -- Bind all key numbers to tags.
 -- Be careful: we use keycodes to make it work on any keyboard layout.
 -- This should map on the top row of your keyboard, usually 1 to 9.
 for i = 1, 9 do
-    globalkeys = gears.table.join(globalkeys,
     -- View tag only.
-        awful.key({ modkey }, "#" .. i + 9,
+    table.insert(globalkeys, awful.key({ modkey }, "#" .. i + 9,
         function ()
             local screen = awful.screen.focused()
             local tag = screen.tags[i]
@@ -384,9 +388,11 @@ for i = 1, 9 do
                 tag:view_only()
             end
         end,
-                  {description = "view tag #"..i, group = "tag"}),
+        {description = "view tag #"..i, group = "tag"})
+    )
+
     -- Toggle tag display.
-        awful.key({ modkey, "Control" }, "#" .. i + 9,
+    table.insert(globalkeys, awful.key({ modkey, "Control" }, "#" .. i + 9,
         function ()
             local screen = awful.screen.focused()
             local tag = screen.tags[i]
@@ -394,9 +400,11 @@ for i = 1, 9 do
                 awful.tag.viewtoggle(tag)
             end
         end,
-                  {description = "toggle tag #" .. i, group = "tag"}),
+        {description = "toggle tag #" .. i, group = "tag"})
+    )
+
     -- Move client to tag.
-        awful.key({ modkey, "Shift" }, "#" .. i + 9,
+    table.insert(globalkeys, awful.key({ modkey, "Shift" }, "#" .. i + 9,
         function ()
             if client.focus then
                 local tag = client.focus.screen.tags[i]
@@ -405,9 +413,11 @@ for i = 1, 9 do
                 end
             end
         end,
-                  {description = "move focused client to tag #"..i, group = "tag"}),
+        {description = "move focused client to tag #"..i, group = "tag"})
+    )
+
     -- Toggle tag on focused client.
-        awful.key({ modkey, "Control", "Shift" }, "#" .. i + 9,
+    table.insert(globalkeys, awful.key({ modkey, "Control", "Shift" }, "#" .. i + 9,
         function ()
             if client.focus then
                 local tag = client.focus.screen.tags[i]
@@ -421,7 +431,7 @@ for i = 1, 9 do
 end
 
 -- @DOC_CLIENT_BUTTONS@
-clientbuttons = gears.table.join(
+clientbuttons = {
     awful.button({ }, 1, function (c)
         c:emit_signal("request::activate", "mouse_click", {raise = true})
     end),
@@ -432,11 +442,11 @@ clientbuttons = gears.table.join(
     awful.button({ modkey }, 3, function (c)
         c:emit_signal("request::activate", "mouse_click", {raise = true})
         awful.mouse.client.resize(c)
-    end)
-)
+    end),
+}
 
 -- Set keys
-root.keys(globalkeys)
+root.keys = globalkeys
 -- }}}
 
 -- {{{ Rules
@@ -522,7 +532,7 @@ end)
 -- Add a titlebar if titlebars_enabled is set to true in the rules.
 client.connect_signal("request::titlebars", function(c)
     -- buttons for the titlebar
-    local buttons = gears.table.join(
+    local buttons = {
         awful.button({ }, 1, function()
             c:emit_signal("request::activate", "titlebar", {raise = true})
             awful.mouse.client.move(c)
@@ -530,10 +540,10 @@ client.connect_signal("request::titlebars", function(c)
         awful.button({ }, 3, function()
             c:emit_signal("request::activate", "titlebar", {raise = true})
             awful.mouse.client.resize(c)
-        end)
-    )
+        end),
+    }
 
-    awful.titlebar(c) : setup {
+    awful.titlebar(c).widget = {
         { -- Left
             awful.titlebar.widget.iconwidget(c),
             buttons = buttons,

docs/common/widget.ldoc

@@ -48,6 +48,10 @@
 -- @param table
 -- @see awful.button
 
+--- Add a new `awful.button` to this widget.
+-- @tparam awful.button button The button to add.
+-- @function add_button
+
 --- Emit a signal and ensure all parent widgets in the hierarchies also
 -- forward the signal. This is useful to track signals when there is a dynamic
 -- set of containers and layouts wrapping the widget.

lib/awful/hotkeys_popup/widget.lua

@@ -458,10 +458,11 @@ function widget.new(args)
             height = height,
         })
         mywibox:set_widget(pages[1])
-        mywibox:buttons(gtable.join(
+
+        mywibox.buttons = {
             awful.button({ }, 1, function () widget_obj:hide() end),
             awful.button({ }, 3, function () widget_obj:hide() end)
-        ))
+        }
 
         function widget_obj.page_next(_self)
             if _self.current_page == #pages then return end

lib/awful/menu.lua

@@ -446,13 +446,14 @@ function menu:add(args, index)
 
 
     -- Create bindings
-    item._background:buttons(gtable.join(
+    item._background.buttons = {
         button({}, 3, function () self:hide() end),
         button({}, 1, function ()
             local num = gtable.hasitem(self.items, item)
             self:item_enter(num, { mouse = true })
             self:exec(num, { exec = true, mouse = true })
-        end )))
+        end)
+    }
 
 
     item._mouse = function ()

lib/awful/titlebar.lua

@@ -492,6 +492,18 @@ local function load_titlebars(c, hide_all, keep)
     return true
 end
 
+local function get_children_by_id(self, name)
+    --TODO v5: Move the ID management to the hierarchy.
+    if self._drawable._widget
+      and self._drawable._widget._private
+      and self._drawable._widget._private.by_id then
+          return self._drawable.widget._private.by_id[name]
+    end
+
+    return {}
+end
+
+
 --- Get a client's titlebar.
 -- @tparam client c The client for which a titlebar is wanted.
 -- @tparam[opt={}] table args A table with extra arguments for the titlebar.
@@ -556,6 +568,7 @@ local function new(c, args)
 
     -- Handle declarative/recursive widget container
     ret.setup = base.widget.setup
+    ret.get_children_by_id = get_children_by_id
 
     c._private = c._private or {}
     c._private.titlebars = bars
@@ -717,16 +730,20 @@ function titlebar.widget.button(c, name, selector, action)
     end
     ret.state = ""
     if action then
-        ret:buttons(abutton({ }, 1, nil, function()
+        ret.buttons = {
+            abutton({ }, 1, nil, function()
                 ret.state = ""
                 update()
                 action(c, selector(c))
-        end))
+            end)
+        }
     else
-        ret:buttons(abutton({ }, 1, nil, function()
+        ret.buttons = {
+            abutton({ }, 1, nil, function()
                 ret.state = ""
                 update()
-        end))
+            end)
+        }
     end
     ret:connect_signal("mouse::enter", function()
         ret.state = "hover"

lib/awful/tooltip.lua

@@ -212,7 +212,9 @@ function tooltip:get_wibox()
 
     -- Close the tooltip when clicking it.  This gets done on release, to not
     -- emit the release event on an underlying object, e.g. the titlebar icon.
-    wb:buttons(a_button({}, 1, nil, self.hide))
+    wb.buttons = {
+        a_button({}, 1, nil, self.hide)
+    }
 
     self._private.wibox = wb
 

lib/awful/widget/button.lua

@@ -1,12 +1,12 @@
 ---------------------------------------------------------------------------
 -- A simple button widget.
--- @usage local button = awful.widget.button()
--- button:buttons(gears.table.join(
---     button:buttons(),
+--
+--    button.buttons = {
 --        awful.button({}, 1, nil, function ()
 --            print("Mouse was clicked")
 --        end)
--- ))
+--    }
+--
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @widgetmod awful.widget.button
@@ -46,8 +46,11 @@ function button.new(args)
         orig_set_image(self, img_release)
     end
     w:set_image(args.image)
-    w:buttons(abutton({}, 1, function () orig_set_image(w, img_press) end,
-                             function () orig_set_image(w, img_release) end))
+
+    w.buttons = {
+        abutton({}, 1, function () orig_set_image(w, img_press) end,
+                       function () orig_set_image(w, img_release) end)
+    }
 
     w:connect_signal("mouse::leave", function(self) orig_set_image(self, img_release) end)
 

lib/awful/widget/calendar_popup.lua

@@ -254,7 +254,8 @@ function calendar_popup:attach(widget, position, args)
     position = position or "tr"
     args = args or {}
     if args.on_hover == nil then args.on_hover=true end
-    widget:buttons(gears.table.join(
+
+    widget.buttons = {
         abutton({ }, 1, function ()
                               if not self.visible or self._calendar_clicked_on then
                                   self:call_calendar(0, position)
@@ -264,7 +265,8 @@ function calendar_popup:attach(widget, position, args)
                         end),
         abutton({ }, 4, function () self:call_calendar(-1) end),
         abutton({ }, 5, function () self:call_calendar( 1) end)
-    ))
+    }
+
     if args.on_hover then
         widget:connect_signal("mouse::enter", function ()
             if not self._calendar_clicked_on then
@@ -330,7 +332,7 @@ local function get_cal_wibox(caltype, args)
     }
     ret:set_widget(widget)
 
-    ret:buttons(gears.table.join(
+    ret.buttons = {
         abutton({ }, 1, function ()
             ret.visible=false
             ret._calendar_clicked_on=false
@@ -341,7 +343,8 @@ local function get_cal_wibox(caltype, args)
         end),
         abutton({ }, 4, function () ret:call_calendar(-1) end),
         abutton({ }, 5, function () ret:call_calendar( 1) end)
-    ))
+    }
+
     return ret
 end
 

lib/awful/widget/common.lua

@@ -129,7 +129,7 @@ function common.list_update(w, buttons, label, data, objects, args)
             cache = (args and args.widget_template) and
                 custom_template(args) or default_template()
 
-            cache.primary:buttons(common.create_buttons(buttons, o))
+            cache.primary.buttons = {common.create_buttons(buttons, o)}
 
             if cache.create_callback then
                 cache.create_callback(cache.primary, o, i, objects)

lib/awful/widget/keyboardlayout.lua

@@ -8,7 +8,6 @@ local capi = {awesome = awesome}
 local setmetatable = setmetatable
 local textbox = require("wibox.widget.textbox")
 local button = require("awful.button")
-local gtable = require("gears.table")
 local widget_base = require("wibox.widget.base")
 local gdebug = require("gears.debug")
 
@@ -295,9 +294,9 @@ function keyboardlayout.new()
                                 function () update_status(self) end);
 
     -- Mouse bindings
-    self:buttons(
-        gtable.join(button({ }, 1, self.next_layout))
-    )
+    self.buttons = {
+        button({ }, 1, self.next_layout)
+    }
 
     return self
 end

lib/awful/widget/launcher.lua

@@ -5,7 +5,6 @@
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
-local gtable = require("gears.table")
 local spawn = require("awful.spawn")
 local wbutton = require("awful.widget.button")
 local button = require("awful.button")
@@ -22,14 +21,12 @@ function launcher.new(args)
     local w = wbutton(args)
     if not w then return end
 
-    local b
     if args.command then
-       b = gtable.join(w:buttons(), button({}, 1, nil, function () spawn(args.command) end))
+        w:add_button(button({}, 1, nil, function () spawn(args.command) end))
     elseif args.menu then
-       b = gtable.join(w:buttons(), button({}, 1, nil, function () args.menu:toggle() end))
+        w:add_button(button({}, 1, nil, function () args.menu:toggle() end))
     end
 
-    w:buttons(b)
     return w
 end
 

lib/awful/widget/layoutbox.lua

@@ -14,7 +14,7 @@ local tooltip = require("awful.tooltip")
 local beautiful = require("beautiful")
 local wibox = require("wibox")
 local surface = require("gears.surface")
--- local gdebug = require("gears.debug")
+local gdebug = require("gears.debug")
 local gtable = require("gears.table")
 
 local function get_screen(s)
@@ -55,11 +55,11 @@ function layoutbox.new(args)
 
     if type(args) == "number" or type(args) == "screen" or args.fake_remove then
         screen, args = args, {}
---TODO uncomment
---         gdebug.deprecate(
---             "Use awful.widget.layoutbox{screen=s} instead of awful.widget.layoutbox(screen)",
---             {deprecated_in=5}
---         )
+
+        gdebug.deprecate(
+            "Use awful.widget.layoutbox{screen=s} instead of awful.widget.layoutbox(screen)",
+            {deprecated_in=5}
+        )
     end
 
     assert(type(args) == "table")

lib/awful/widget/only_on_screen.lua

@@ -51,13 +51,7 @@ end
 -- @property widget
 -- @tparam widget widget The widget
 
-function only_on_screen:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+only_on_screen.set_widget = base.set_widget_common
 
 function only_on_screen:get_widget()
     return self._private.widget

lib/naughty/layout/legacy.lua

@@ -31,7 +31,6 @@ local screen    = require("awful.screen")
 local button    = require("awful.button")
 local beautiful = require("beautiful")
 local surface   = require("gears.surface")
-local gtable    = require("gears.table")
 local wibox     = require("wibox")
 local gfs       = require("gears.filesystem")
 local timer     = require("gears.timer")
@@ -446,14 +445,11 @@ function naughty.default_notification_handler(notification, args)
             local action_height = h + 2 * margin
             local action_width = w + 2 * margin
 
-            actionmarginbox:buttons(gtable.join(
-                button({ }, 1, function()
-                    action:invoke(notification)
-                end),
-                button({ }, 3, function()
-                    action:invoke(notification)
-                end)
-            ))
+            actionmarginbox.buttons = {
+                button({ }, 1, function() action:invoke(notification) end),
+                button({ }, 3, function() action:invoke(notification) end),
+            }
+
             actionslayout:add(actionmarginbox)
 
             actions_total_height = actions_total_height + action_height
@@ -584,10 +580,12 @@ function naughty.default_notification_handler(notification, args)
     notification.box:set_widget(completelayout)
 
     -- Setup the mouse events
-    layout:buttons(gtable.join(button({}, 1, nil, run),
+    layout.buttons = {
+        button({}, 1, nil, run),
         button({}, 3, nil, function()
             die(naughty.notification_closed_reason.dismissed_by_user)
-                                    end)))
+        end),
+    }
 
     -- insert the notification to the table
     table.insert(current_notifications[s][notification.position], notification)

lib/wibox/container/arcchart.lua

@@ -192,13 +192,7 @@ end
 -- @property widget
 -- @tparam widget widget The widget
 
-function arcchart:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+arcchart.set_widget = base.set_widget_common
 
 function arcchart:get_children()
     return {self._private.widget}

lib/wibox/container/background.lua

@@ -218,13 +218,7 @@ end
 -- @tparam widget widget The widget to be disaplayed inside of the background
 --  area
 
-function background:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+background.set_widget = base.set_widget_common
 
 function background:get_widget()
     return self._private.widget

lib/wibox/container/constraint.lua

@@ -42,10 +42,7 @@ end
 -- @property widget
 -- @tparam widget widget The widget
 
-function constraint:set_widget(widget)
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+constraint.set_widget = base.set_widget_common
 
 function constraint:get_widget()
     return self._private.widget

lib/wibox/container/margin.lua

@@ -73,13 +73,7 @@ end
 -- @property widget
 -- @tparam widget widget The widget
 
-function margin:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+margin.set_widget = base.set_widget_common
 
 function margin:get_widget()
     return self._private.widget

lib/wibox/container/mirror.lua

@@ -49,13 +49,7 @@ end
 -- @property widget
 -- @tparam widget widget The widget
 
-function mirror:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+mirror.set_widget = base.set_widget_common
 
 function mirror:get_widget()
     return self._private.widget

lib/wibox/container/place.lua

@@ -61,13 +61,11 @@ function place:fit(context, width, height)
         and height or h
 end
 
-function place:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+--- The widget to be placed.
+-- @property widget
+-- @tparam widget widget The widget
+
+place.set_widget = base.set_widget_common
 
 function place:get_widget()
     return self._private.widget

lib/wibox/container/radialprogressbar.lua

@@ -129,13 +129,7 @@ end
 -- @property widget
 -- @tparam widget widget The widget
 
-function radialprogressbar:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+radialprogressbar.set_widget = base.set_widget_common
 
 function radialprogressbar:get_children()
     return {self._private.widget}

lib/wibox/container/rotate.lua

@@ -62,13 +62,7 @@ end
 -- @property widget
 -- @tparam widget widget The widget
 
-function rotate:set_widget(widget)
-    if widget then
-        base.check_widget(widget)
-    end
-    self._private.widget = widget
-    self:emit_signal("widget::layout_changed")
-end
+rotate.set_widget = base.set_widget_common
 
 function rotate:get_widget()
     return self._private.widget

lib/wibox/container/scroll.lua

@@ -277,10 +277,14 @@ function scroll:set_widget(widget)
     if widget == self._private.widget then
         return
     end
-    if widget then
-        base.check_widget(widget)
+
+    local w = base.make_widget_from_value(widget)
+
+    if w then
+        base.check_widget(w)
     end
-    self._private.widget = widget
+
+    self._private.widget = w
     self:emit_signal("widget::layout_changed")
     self:emit_signal("widget::redraw_needed")
 end

lib/wibox/drawable.lua

@@ -13,6 +13,7 @@ local capi = {
     screen = screen
 }
 local beautiful = require("beautiful")
+local base = require("wibox.widget.base")
 local cairo = require("lgi").cairo
 local color = require("gears.color")
 local object = require("gears.object")
@@ -77,11 +78,11 @@ local function do_redraw(self)
     -- Relayout
     if self._need_relayout or self._need_complete_repaint then
         self._need_relayout = false
-        if self._widget_hierarchy and self.widget then
+        if self._widget_hierarchy and self._widget then
             local had_systray = systray_widget and self._widget_hierarchy:get_count(systray_widget) > 0
 
             self._widget_hierarchy:update(context,
-                self.widget, width, height, self._dirty_area)
+                self._widget, width, height, self._dirty_area)
 
             local has_systray = systray_widget and self._widget_hierarchy:get_count(systray_widget) > 0
             if had_systray and not has_systray then
@@ -89,9 +90,9 @@ local function do_redraw(self)
             end
         else
             self._need_complete_repaint = true
-            if self.widget then
+            if self._widget then
                 self._widget_hierarchy_callback_arg = {}
-                self._widget_hierarchy = hierarchy.new(context, self.widget, width, height,
+                self._widget_hierarchy = hierarchy.new(context, self._widget, width, height,
                         self._redraw_callback, self._layout_callback, self._widget_hierarchy_callback_arg)
             else
                 self._widget_hierarchy = nil
@@ -226,13 +227,17 @@ end
 
 --- Set the widget that the drawable displays
 function drawable:set_widget(widget)
-    self.widget = widget
+    self._widget = base.make_widget_from_value(widget)
 
     -- Make sure the widget gets drawn
     self._need_relayout = true
     self.draw()
 end
 
+function drawable:get_widget()
+    return rawget(self, "_widget")
+end
+
 --- Set the background of the drawable
 -- @param c The background to use. This must either be a cairo pattern object,
 --   nil or a string that gears.color() understands.
@@ -480,7 +485,22 @@ function drawable.new(d, widget_context_skeleton, drawable_name)
     -- Make sure the drawable is drawn at least once
     ret._do_complete_repaint()
 
-    return ret
+    return setmetatable(ret, {
+        __index = function(self, k)
+            if rawget(self, "get_"..k) then
+                return rawget(self, "get_"..k)(self)
+            else
+                return rawget(ret, k)
+            end
+        end,
+        __newindex = function(self, k,v)
+            if rawget(self, "set_"..k) then
+                rawget(self, "set_"..k)(self, v)
+            else
+                rawset(self, k, v)
+            end
+        end
+    })
 end
 
 -- Redraw all drawables when the wallpaper changes

lib/wibox/init.lua

@@ -39,7 +39,8 @@ local force_forward = {
 --@DOC_wibox_COMMON@
 
 function wibox:set_widget(widget)
-    self._drawable:set_widget(widget)
+    local w = base.make_widget_from_value(widget)
+    self._drawable:set_widget(w)
 end
 
 function wibox:get_widget()
@@ -202,6 +203,7 @@ end
 function wibox:get_children_by_id(name)
     --TODO v5: Move the ID management to the hierarchy.
     if rawget(self, "_by_id") then
+        --TODO v5: Remove this, it's `if` nearly dead code, keep the `elseif`
         return rawget(self, "_by_id")[name]
     elseif self._drawable.widget
       and self._drawable.widget._private

lib/wibox/layout/fixed.lua

@@ -70,8 +70,9 @@ function fixed:add(...)
     local args = { n=select('#', ...), ... }
     assert(args.n > 0, "need at least one widget to add")
     for i=1, args.n do
-        base.check_widget(args[i])
-        table.insert(self._private.widgets, args[i])
+        local w = base.make_widget_from_value(args[i])
+        base.check_widget(w)
+        table.insert(self._private.widgets, w)
     end
     self:emit_signal("widget::layout_changed")
 end

lib/wibox/layout/grid.lua

@@ -293,10 +293,9 @@ function grid:add(...)
     assert(args.n > 0, "need at least one widget to add")
     local row, column
     for i=1, args.n do
-        local w = args[i]
         -- Get the next empty coordinate to insert the widget
         row, column = self:get_next_empty(row, column)
-        self:add_widget_at(w, row, column, 1, 1)
+        self:add_widget_at(args[i], row, column, 1, 1)
     end
 end
 
@@ -317,6 +316,7 @@ function grid:add_widget_at(child, row, col, row_span, col_span)
     col_span = (col_span and col_span > 0) and col_span or 1
 
     -- check if the object is a widget
+    child = base.make_widget_from_value(child)
     base.check_widget(child)
 
     -- test if the new widget superpose with existing ones

lib/wibox/layout/manual.lua

@@ -102,9 +102,16 @@ function manual_layout:layout(context, width, height)
 end
 
 function manual_layout:add(...)
-    local wdgs = {...}
+    local wdgs = {}
     local old_count = #self._private.widgets
-    gtable.merge(self._private.widgets, {...})
+
+    for _, v in ipairs {...} do
+        local w = base.make_widget_from_value(v)
+        base.check_widget(w)
+        table.insert(wdgs, w)
+    end
+
+    gtable.merge(self._private.widgets, wdgs)
 
     -- Add the points
     for k, v in ipairs(wdgs) do
@@ -166,7 +173,7 @@ function manual_layout:add_at(widget, point)
     end
 
     self._private.pos[#self._private.widgets+1] = point
-    self:add(widget)
+    self:add(base.make_widget_from_value(widget))
 end
 
 --- Move a widget (by index).

lib/wibox/layout/ratio.lua

@@ -355,8 +355,9 @@ function ratio:add(...)
     local args = { n=select('#', ...), ... }
     assert(args.n > 0, "need at least one widget to add")
     for i=1, args.n do
-        base.check_widget(args[i])
-        table.insert(self._private.widgets, args[i])
+        local w = base.make_widget_from_value(args[i])
+        base.check_widget(w)
+        table.insert(self._private.widgets, w)
     end
 
     normalize(self)

lib/wibox/widget/base.lua

@@ -40,6 +40,29 @@ function base.widget:set_visible(b)
     end
 end
 
+--- Add a new `awful.button` to this widget.
+-- @tparam awful.button button The button to add.
+function base.widget:add_button(button)
+    if not button then return end
+
+    -- Simple case
+    if not self._private.buttons then
+        self:set_buttons({button})
+        return
+    end
+
+    -- This could happen if something accidentally uses rawset
+    assert(self._private.buttons_formatted)
+
+    -- an `awful.button` is a tupple of `capi.button`
+    self._private.buttons_formatted = gtable.join(
+        self._private.buttons_formatted,
+        button
+    )
+
+    table.insert(self._private.buttons, button)
+end
+
 --- Is the widget visible?
 -- @treturn boolean
 -- @method get_visible
@@ -155,6 +178,24 @@ function base.widget:get_all_children()
     return ret
 end
 
+--- Common implementation of the `:set_widget()` method exposed by many
+-- other widgets.
+--
+-- Use this if your widget has no custom logic when setting the widget.
+--
+-- @usage
+--   rawset(my_custom_widget, "set_widget", wibox.widget.base.set_widget_common)
+function base.set_widget_common(self, widget)
+    local w = widget and base.make_widget_from_value(widget)
+
+    if w then
+        base.check_widget(w)
+    end
+
+    self._private.widget = w
+    self:emit_signal("widget::layout_changed")
+end
+
 --- Emit a signal and ensure all parent widgets in the hierarchies also
 -- forward the signal. This is useful to track signals when there is a dynamic
 -- set of containers and layouts wrapping the widget.

tests/_wibox_helper.lua

@@ -18,7 +18,7 @@ return { create_wibox = function()
     local right_layout = wibox.layout.fixed.horizontal()
     local textclock = wibox.widget.textclock()
     right_layout:add(textclock)
-    right_layout:add(awful.widget.layoutbox(1))
+    right_layout:add(awful.widget.layoutbox{screen=1})
 
     -- Now bring it all together (with the tasklist in the middle)
     local layout = wibox.layout.align.horizontal()

tests/test-awful-widget-button.lua

@@ -2,7 +2,7 @@ local runner    = require( "_runner"   )
 local wibox     = require( "wibox"     )
 local awful     = require( "awful"     )
 local beautiful = require( "beautiful" )
-local gtable    = require("gears.table")
+local gdebug    = require("gears.debug")
 
 local steps = {}
 
@@ -64,12 +64,20 @@ table.insert(steps, function()
     layout = w.widget
     assert(layout)
 
-    button:buttons(gtable.join(
-        button:buttons(),
+    -- Test both legacy and new APIs
+    gdebug.deprecate = function() end
+
+    assert(#button:buttons() == 4)
+    assert(#button.buttons   == 1)
+
+    button:add_button(
         awful.button({}, 1, nil, function ()
             button:emit_signal_recursive("test::recursive")
         end)
-    ))
+    )
+
+    assert(#button:buttons() == 8)
+    assert(#button.buttons   == 2)
 
     layout:connect_signal("test::recursive", function()
         got_called = true

tests/test-leak-client.lua

@@ -7,7 +7,7 @@ local gtable = require("gears.table")
 -- Create a titlebar and return a table with references to its member widgets.
 local function create_titlebar(c)
     local parts = {}
-    local buttons = gtable.join(
+    local buttons = {
         awful.button({ }, 1, function()
             client.focus = c
             c:raise()
@@ -18,18 +18,18 @@ local function create_titlebar(c)
             c:raise()
             awful.mouse.client.resize(c)
         end)
-    )
+    }
 
     -- Widgets that are aligned to the left
     parts.icon = awful.titlebar.widget.iconwidget(c)
     local left_layout = wibox.layout.fixed.horizontal(parts.icon)
-    left_layout:buttons(buttons)
+    left_layout.buttons = buttons
 
     -- The title goes in the middle
     parts.title = awful.titlebar.widget.titlewidget(c)
     parts.title:set_align("center")
     local middle_layout = wibox.layout.flex.horizontal(parts.title)
-    middle_layout:buttons(buttons)
+    middle_layout.buttons = buttons
 
     parts.floating_button  = awful.titlebar.widget.floatingbutton(c)
     parts.maximized_button = awful.titlebar.widget.maximizedbutton(c)

tests/test-leaks.lua

@@ -41,7 +41,7 @@ end
 
 -- Use the layoutbox for testing delayed tooltips
 local function tooltip_delayed()
-    local l = awful.widget.layoutbox(1)
+    local l = awful.widget.layoutbox{screen = 1}
     local t = l._layoutbox_tooltip
     assert(t)
     return l, t
@@ -63,7 +63,7 @@ collectable(wibox.layout.align.horizontal())
 collectable(awful.widget.launcher({ image = cairo.ImageSurface(cairo.Format.ARGB32, 20, 20), command = "bash" }))
 collectable(awful.widget.prompt())
 collectable(wibox.widget.textclock())
-collectable(awful.widget.layoutbox(1))
+collectable(awful.widget.layoutbox{screen=1})
 
 -- Some widgets do things via timer.delayed_call
 prepare_for_collect = run_delayed_calls