widget: Add an `:add_button()` method.

This is done now because a lot of code in `lib/` add buttons by manually
extracting buttons from awful.button. Instead of adding ugly code to
prevent using the legacy API, do this.

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/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