widget: Turn `:buttons()` into a normal property.

docs/common/widget.ldoc

@@ -40,9 +40,13 @@
 -- @property visible
 -- @param boolean
 
---- Set/get a widget's buttons.
--- @param _buttons The table of buttons that should bind to the widget.
--- @method buttons
+--- The widget buttons.
+--
+-- The table contains a list of `awful.button` objects.
+--
+-- @property buttons
+-- @param table
+-- @see awful.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

lib/awful/widget/common.lua

@@ -21,17 +21,23 @@ local common = {}
 -- @param object
 -- @treturn table
 function common.create_buttons(buttons, object)
+    local is_formatted = buttons and buttons[1] and (
+        type(buttons[1]) == "button" or buttons[1]._is_capi_button) or false
+
     if buttons then
         local btns = {}
-        for _, b in ipairs(buttons) do
-            -- Create a proxy button object: it will receive the real
-            -- press and release events, and will propagate them to the
-            -- button object the user provided, but with the object as
-            -- argument.
-            local btn = capi.button { modifiers = b.modifiers, button = b.button }
-            btn:connect_signal("press", function () b:emit_signal("press", object) end)
-            btn:connect_signal("release", function () b:emit_signal("release", object) end)
-            btns[#btns + 1] = btn
+        for _, src in ipairs(buttons) do
+            --TODO v6 Remove this legacy overhead
+            for _, b in ipairs(is_formatted and {src} or src) do
+                -- Create a proxy button object: it will receive the real
+                -- press and release events, and will propagate them to the
+                -- button object the user provided, but with the object as
+                -- argument.
+                local btn = capi.button { modifiers = b.modifiers, button = b.button }
+                btn:connect_signal("press", function () b:emit_signal("press", object) end)
+                btn:connect_signal("release", function () b:emit_signal("release", object) end)
+                btns[#btns + 1] = btn
+            end
         end
 
         return btns

lib/wibox/widget/base.lua

@@ -22,15 +22,11 @@ local base = {}
 -- Functions available on all widgets.
 base.widget = {}
 
---- Set/get a widget's buttons.
--- @tab _buttons The table of buttons that is bound to the widget.
--- @method buttons
-function base.widget:buttons(_buttons)
-    if _buttons then
-        self._private.widget_buttons = _buttons
-    end
-    return self._private.widget_buttons
-end
+object.properties._legacy_accessors(base.widget, "buttons", nil, true, function(new_btns)
+    return new_btns[1] and (
+        type(new_btns[1]) == "button" or new_btns[1]._is_capi_button
+    ) or false
+end, true)
 
 --- Set a widget's visibility.
 -- @tparam boolean b Whether the widget is visible.
@@ -368,7 +364,7 @@ function base.handle_button(event, widget, x, y, button, modifiers, geometry)
 
     -- Find all matching button objects.
     local matches = {}
-    for _, v in pairs(widget._private.widget_buttons) do
+    for _, v in pairs(widget._private.buttons_formatted or {}) do
         local match = true
         -- Is it the right button?
         if v.button ~= 0 and v.button ~= button then match = false end
@@ -662,9 +658,6 @@ function base.make_widget(proxy, widget_name, args)
     -- Create a table used to store the widgets internal data.
     rawset(ret, "_private", {})
 
-    -- No buttons yet.
-    ret._private.widget_buttons = {}
-
     -- Widget is visible.
     ret._private.visible = true
 
@@ -719,6 +712,20 @@ function base.make_widget(proxy, widget_name, args)
     mt.__tostring = function()
         return string.format("%s (%s)", ret.widget_name, orig_string)
     end
+
+    -- Even when properties are disabled, buttons is required for backward
+    -- compatibility.
+    --TODO v6 Remove this
+    if not args.enable_properties then
+        mt.__index = function(_, key)
+            if key == "buttons" then
+                return base.widget.get_buttons(ret)
+            end
+
+            return rawget(ret, key)
+        end
+    end
+
     return setmetatable(ret, mt)
 end