From d2e5694f9c531c84ab35646ae8d4c5bc4a1fb371 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 28 Nov 2019 18:49:38 -0500 Subject: [PATCH] background: Add some property signals and update the doc. It had no signals for the properties. That's non standard and has been fixed. The documentation tags were also upgraded to the latest standards. --- lib/wibox/container/background.lua | 60 ++++++++++++++++++++++-------- 1 file changed, 45 insertions(+), 15 deletions(-) diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index de0cb2ef..bd33f895 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A container capable of changing the background color, foreground color +-- A container capable of changing the background color, foreground color and -- widget shape. -- --@DOC_wibox_container_defaults_background_EXAMPLE@ @@ -216,7 +216,8 @@ end --- The widget displayed in the background widget. -- @property widget -- @tparam widget widget The widget to be disaplayed inside of the background --- area +-- area. +-- @interface container background.set_widget = base.set_widget_common @@ -233,10 +234,13 @@ function background:set_children(children) end --- The background color/pattern/gradient to use. +-- --@DOC_wibox_container_background_bg_EXAMPLE@ +-- -- @property bg --- @param bg A color string, pattern or gradient +-- @tparam color bg A color string, pattern or gradient -- @see gears.color +-- @propemits true false function background:set_bg(bg) if bg then @@ -245,6 +249,7 @@ function background:set_bg(bg) self._private.background = nil end self:emit_signal("widget::redraw_needed") + self:emit_signal("property::bg", bg) end function background:get_bg() @@ -252,9 +257,12 @@ function background:get_bg() end --- The foreground (text) color/pattern/gradient to use. +-- --@DOC_wibox_container_background_fg_EXAMPLE@ +-- -- @property fg --- @param fg A color string, pattern or gradient +-- @tparam color fg A color string, pattern or gradient +-- @propemits true false -- @see gears.color function background:set_fg(fg) @@ -264,6 +272,7 @@ function background:set_fg(fg) self._private.foreground = nil end self:emit_signal("widget::redraw_needed") + self:emit_signal("property::fg", fg) end function background:get_fg() @@ -275,16 +284,19 @@ end -- Use `set_shape` to set additional shape paramaters. -- --@DOC_wibox_container_background_shape_EXAMPLE@ +-- -- @property shape --- @param shape A function taking a context, width and height as arguments +-- @tparam gears.shape|function shape A function taking a context, width and height as arguments -- @see gears.shape -- @see set_shape --- Set the background shape. -- --- Any other arguments will be passed to the shape function +-- Any other arguments will be passed to the shape function. +-- -- @method set_shape --- @param shape A function taking a context, width and height as arguments +-- @tparam gears.shape|function shape A function taking a context, width and height as arguments +-- @propemits true false -- @see gears.shape -- @see shape function background:set_shape(shape, ...) @@ -295,6 +307,7 @@ function background:set_shape(shape, ...) self._private.shape = shape self._private.shape_args = {...} self:emit_signal("widget::redraw_needed") + self:emit_signal("property::shape", shape) end function background:get_shape() @@ -304,8 +317,10 @@ end --- When a `shape` is set, also draw a border. -- -- See `wibox.container.background.shape` for an usage example. +-- -- @deprecatedproperty shape_border_width -- @tparam number width The border width +-- @renamedin 4.4 border_width -- @see border_width --- Add a border of a specific width. @@ -315,6 +330,8 @@ end -- See `wibox.container.background.shape` for an usage example. -- @property border_width -- @tparam[opt=0] number width The border width. +-- @propemits true false +-- @introducedin 4.4 -- @see border_color function background:set_border_width(width) @@ -322,6 +339,7 @@ function background:set_border_width(width) self._private.shape_border_width = width self:emit_signal("widget::redraw_needed") + self:emit_signal("property::border_width", width) end function background:get_border_width() @@ -345,8 +363,11 @@ end --- When a `shape` is set, also draw a border. -- -- See `wibox.container.background.shape` for an usage example. +-- -- @deprecatedproperty shape_border_color --- @param[opt=self._private.foreground] fg The border color, pattern or gradient +-- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. +-- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @renamedin 4.4 border_color -- @see gears.color -- @see border_color @@ -354,7 +375,10 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_color --- @param[opt=self._private.foreground] fg The border color, pattern or gradient +-- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @propemits true false +-- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. +-- @introducedin 4.4 -- @see gears.color -- @see border_width @@ -363,6 +387,7 @@ function background:set_border_color(fg) self._private.shape_border_color = fg self:emit_signal("widget::redraw_needed") + self:emit_signal("property::border_color", fg) end function background:get_border_color() @@ -403,24 +428,28 @@ end -- * *inner*: Squeeze the size of the content by the border width. -- -- @property border_strategy --- @param[opt="none"] string +-- @tparam[opt="none"] string border_strategy function background:set_border_strategy(value) self._private.border_strategy = value self:emit_signal("widget::layout_changed") + self:emit_signal("property::border_strategy", value) end ---- The background image to use +--- The background image to use. +-- -- If `image` is a function, it will be called with `(context, cr, width, height)` -- as arguments. Any other arguments passed to this method will be appended. +-- -- @property bgimage --- @param image A background image or a function +-- @tparam string|surface|function image A background image or a function -- @see gears.surface function background:set_bgimage(image, ...) self._private.bgimage = type(image) == "function" and image or surface.load(image) self._private.bgimage_args = {...} self:emit_signal("widget::redraw_needed") + self:emit_signal("property::bgimage", image) end function background:get_bgimage() @@ -431,9 +460,10 @@ end -- -- A background container applies a background and foreground color -- to another widget. --- @param[opt] widget The widget to display. --- @param[opt] bg The background to use for that widget. --- @param[opt] shape A `gears.shape` compatible shape function +-- +-- @tparam[opt] widget widget The widget to display. +-- @tparam[opt] color bg The background to use for that widget. +-- @tparam[opt] gears.shape|function shape A `gears.shape` compatible shape function -- @constructorfct wibox.container.background local function new(widget, bg, shape) local ret = base.make_widget(nil, nil, {