# Module: `naughty.widget.background`

A notification background widget.

This widget holds the boilerplate code associated with the notification background. This includes the color and potentially some other styling elements such as the shape and border.

* Honor the beautiful notification variables. * React to the naughty.notification changes.

Note that this widget is based on the wibox.container.background. This is an implementation detail and may change in the future without prior notice.

### Class Hierarchy

- gears.object
- - wibox.widget.base
  - - wibox.container.background
    - - naughty.widget.background

### Info:

- Copyright: 2019 Emmanuel Lepage Vallee
- Originally authored by: Emmanuel Lepage Vallee <elv1313@gmail.com>
  (Full contributors list available on our github project)

### See also:

wibox.container.background

## Constructors

naughty.container.background {[args]} | Create a new naughty.container.background. |

## Object properties

notification | naughty.notification | The attached notification. |
widget | widget or nil | The widget displayed in the background widget. | Inherited from wibox.container.background
stretch_horizontally | boolean | Stretch the background gradient horizontally. | Inherited from wibox.container.background
stretch_vertically | boolean | Stretch the background gradient vertically. | Inherited from wibox.container.background
bg | color | The background color/pattern/gradient to use. | Inherited from wibox.container.background
fg | color | The foreground (text) color/pattern/gradient to use. | Inherited from wibox.container.background
shape | shape | The background shape. | Inherited from wibox.container.background
border_width | number | Add a border of a specific width. | Inherited from wibox.container.background
border_color | color | Set the color for the border. | Inherited from wibox.container.background
border_strategy | string | How the border width affects the contained widget. | Inherited from wibox.container.background
children | table | Get or set the children elements. | Inherited from wibox.widget.base
all_children | table | Get all direct and indirect children widgets. | Inherited from wibox.widget.base
forced_height | number or nil | Force a widget height. | Inherited from wibox.widget.base
forced_width | number or nil | Force a widget width. | Inherited from wibox.widget.base
opacity | number | The widget opacity (transparency). | Inherited from wibox.widget.base
visible | boolean | The widget visibility. | Inherited from wibox.widget.base
buttons | table | The widget buttons. | Inherited from wibox.widget.base

## Object methods

:emit_signal (name, ...) | Emit a signal. | Inherited from gears.object
:connect_signal (name, func) | Connect to a signal. | Inherited from gears.object
:weak_connect_signal (name, func) | Connect to a signal weakly. | Inherited from gears.object
:set_shape (shape) | Set the background shape. | Inherited from wibox.container.background
:add_button (button) | Add a new awful.button to this widget. | Inherited from wibox.widget.base
:emit_signal_recursive (signal_name, ...) | Emit a signal and ensure all parent widgets in the hierarchies also forward the signal. | Inherited from wibox.widget.base
:index (widget, recursive, ...) -> (number, widget, table) | Get the index of a widget. | Inherited from wibox.widget.base
:disconnect_signal (name, func) | Disconnect from a signal. | Inherited from gears.object

## Deprecated object properties

shape_border_width | number | When a `shape` is set, also draw a border. | Deprecated Inherited from wibox.container.background
shape_border_color | color | When a `shape` is set, also draw a border. | Deprecated Inherited from wibox.container.background
bgimage | string or surface or function | The background image to use. | Deprecated Inherited from wibox.container.background

## Signals

widget::layout_changed | When the layout (size) change. | Inherited from wibox.widget.base
widget::redraw_needed | When the widget content changed. | Inherited from wibox.widget.base
button::press | When a mouse button is pressed over the widget. | Inherited from wibox.widget.base
button::release | When a mouse button is released over the widget. | Inherited from wibox.widget.base
mouse::enter | When the mouse enter a widget. | Inherited from wibox.widget.base
mouse::leave | When the mouse leave a widget. | Inherited from wibox.widget.base

## Constructors

🔗 naughty.container.background {[args]} · 3 theme variables
  Create a new naughty.container.background.

  ### Parameters:

  Note: This constructors uses named parameters calling convention. It means you call it with `{}` and omit the parantheses. For example, calling this will all default argument would be `naughty.container.background{}`. This is a Lua shortcut syntax equivalent to `naughty.container.background({})`. `args` is only a placeholder name for the "lone table argument" used in named parameters calls.

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  args |  | table |
  notification |  | naughty.notification | The notification.

  Click to display more

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  `beautiful.notification_border_width` | Fallback when the `border_width` property isn't set.
  `beautiful.notification_border_color` | Fallback when the `border_color` property isn't set.
  `beautiful.notification_shape` | Fallback when the `shape` property isn't set.

## Object properties

🔗 notification naughty.notification · 1 signal
  The attached notification.

  ### Constraints:

  Default value | : This is usually set in the construtor.

  Click to display more

  ### Emit signals:

  - `property::notification` When the notification value changes.
  - `self` naughty.widget.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` notification The new value affected to the property.
🔗 widget widget or nil · Inherited from wibox.container.background
  The widget displayed in the background widget.

  ### Constraints:

  Default value | : `nil`
  Valid values | : The widget to be disaplayed inside of the background area.

🔗 stretch_horizontally boolean · Inherited from wibox.container.background · 1 signal
  Stretch the background gradient horizontally.

  This only works for linear or radial gradients. It does nothing for solid colors, `bgimage` or raster patterns.

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

  ### See also:

  stretch_vertically | Stretch the background gradient vertically. | object properties
  bg | The background color/pattern/gradient to use. | object properties
  gears.color | This module simplifies the creation of cairo pattern objects. | module

  ### Usage:

      local gradients = {
          gears.color {
              type  = "linear",
              from  = { 0  , 0 },
              to    = { 100, 0 },
              stops = {
                  { 0  , "#0000ff" },
                  { 0.8, "#0000ff" },
                  { 1  , "#ff0000" }
              }
          },
          gears.color {
              type = "radial",
              from  = { 30, 98, 20  },
              to    = { 30, 98, 120 },
              stops = {
                  { 0  , "#ff0000" },
                  { 0.5, "#00ff00" },
                  { 1  , "#0000ff" },
              }
          }
      }

      for k, stretch in ipairs { false, true } do
          for __, grad in ipairs(gradients) do
              for idx, width in ipairs { 50, 100, 150, 200 } do
                  local w = wibox.widget {
                      {
                          {
                              text   = "  Width: " .. width .. "  ",
                              valign = "center",
                              align  = "center",
                              widget = wibox.widget.textbox
                          },
                          bg                   = grad,
                          stretch_horizontally = stretch,
                          forced_width         = width,
                          fg                   = "#ffffff",
                          shape                = gears.shape.rounded_rect,
                          widget               = wibox.container.background
                      },
                      forced_width  = 200,
                      widget        = wibox.container.place
                  }
              end
          end
      end

  Click to display more

  ### Emit signals:

  - `property::stretch_horizontally` When the `stretch_horizontally` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `stretch_horizontally` The new value affected to the property.
🔗 stretch_vertically boolean · Inherited from wibox.container.background · 1 signal
  Stretch the background gradient vertically.

  This only works for linear or radial gradients. It does nothing for solid colors, `bgimage` or raster patterns.

  ### Constraints:

  Default value | : `false`
  Valid values | : `true` or `false`.

  ### See also:

  stretch_horizontally | Stretch the background gradient horizontally. | object properties
  bg | The background color/pattern/gradient to use. | object properties
  gears.color | This module simplifies the creation of cairo pattern objects. | module

  ### Usage:

      local gradients = {
          gears.color {
              type  = "linear",
              from  = { 0, 0   },
              to    = { 0, 100 },
              stops = {
                  { 0  , "#0000ff" },
                  { 0.8, "#0000ff" },
                  { 1  , "#ff0000" }
              }
          },
          gears.color {
              type = "radial",
              from  = { 30, 98, 20  },
              to    = { 30, 98, 120 },
              stops = {
                  { 0  , "#ff0000" },
                  { 0.5, "#00ff00" },
                  { 1  , "#0000ff" },
              }
          }
      }

      for k, stretch in ipairs { false, true } do
          for _, gradient in ipairs(gradients) do
              for idx, height in ipairs { 10, 50, 100, 150 } do
                  local w = wibox.widget {
                      {
                          {
                              text   = "  Height: " .. height .. "  ",
                              valign = "center",
                              align  = "center",
                              widget = wibox.widget.textbox
                          },
                          bg                 = gradient,
                          stretch_vertically = stretch,
                          forced_height      = height,
                          fg                 = "#ffffff",
                          shape              = gears.shape.rounded_rect,
                          widget             = wibox.container.background
                      },
                      forced_height = 150,
                      widget        = wibox.container.place
                  }
              end
          end
      end

  Click to display more

  ### Emit signals:

  - `property::stretch_vertically` When the `stretch_vertically` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `stretch_vertically` The new value affected to the property.
🔗 bg color · Inherited from wibox.container.background · 1 signal
  The background color/pattern/gradient to use.

  ### Constraints:

  Default value | : When unspecified, it will inherit the value from an higher level wibox.container.background or directly from the wibox.bg property.
  Type description:
  string | : An hexadecimal color code, such as `"#ff0000"` for red.
  string | : A color name, such as `"red"`.
  table | : A [gradient table](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#create_png_pattern)

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

  ### Usage:

      local text_widget = {
          text   = "Hello world!",
          widget = wibox.widget.textbox
      }
      parent : setup {
          {
              text_widget,
              bg     = '#ff0000',
              widget = wibox.container.background
          },
          {
              text_widget,
              bg     = '#00ff00',
              widget = wibox.container.background
          },
          {
              text_widget,
              bg     = '#0000ff',
              widget = wibox.container.background
          },
          spacing = 10,
          layout  = wibox.layout.fixed.vertical
      }

  Click to display more

  ### Emit signals:

  - `property::bg` When the `bg` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `bg` The new value affected to the property.
🔗 fg color · Inherited from wibox.container.background · 1 signal
  The foreground (text) color/pattern/gradient to use.

  ### Constraints:

  Default value | : When unspecified, it will inherit the value from an higher level wibox.container.background or directly from the wibox.fg property.
  Type description:
  string | : An hexadecimal color code, such as `"#ff0000"` for red.
  string | : A color name, such as `"red"`.
  table | : A [gradient table](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#create_png_pattern)
  Valid values | : A color string, pattern or gradient

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

  ### Usage:

      local text_widget = {
          text   = "Hello world!",
          widget = wibox.widget.textbox
      }
      parent : setup {
          {
              text_widget,
              fg     = '#ff0000',
              widget = wibox.container.background
          },
          {
              text_widget,
              fg     = '#00ff00',
              widget = wibox.container.background
          },
          {
              text_widget,
              fg     = '#0000ff',
              widget = wibox.container.background
          },
          spacing = 10,
          layout  = wibox.layout.fixed.vertical
      }

  Click to display more

  ### Emit signals:

  - `property::fg` When the `fg` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `fg` The new value affected to the property.
🔗 shape shape · Inherited from wibox.container.background
  The background shape.

  Use `set_shape` to set additional shape paramaters.

  ### Constraints:

  Default value | : `gears.shape.rectangle`
  Type description:
  gears.shape | : Like gears.shape.circle
  function: | : This can be used for custom shapes or to set parameters of existing shapes.
  Function prototype:
  Parameters:
  cr (cairo.context) | : A [Cairo context](https://cairographics.org/manual/cairo-cairo-t.html)
  width (number) | : The area width.
  height (number) | : The area height.
  Return | : The function returns nothing.

  ### See also:

  gears.shape | Module dedicated to gather common shape painters. | module
  set_shape | Set the background shape. | object methods

  ### Usage:

      parent : setup {
          {
              -- Adding a shape without margin may result in cropped output
              {
                  text   = "Hello world!",
                  widget = wibox.widget.textbox
              },
              shape              = gears.shape.hexagon,
              bg                 = beautiful.bg_normal,
              shape_border_color = beautiful.border_color,
              shape_border_width = beautiful.border_width,
              widget             = wibox.container.background
          },
          {
              -- To solve this, use a margin
              {
                  {
                      text   = "Hello world!",
                      widget = wibox.widget.textbox
                  },
                  left   = 10,
                  right  = 10,
                  top    = 3,
                  bottom = 3,
                  widget = wibox.container.margin
              },
              shape        = gears.shape.hexagon,
              bg           = beautiful.bg_normal,
              border_color = beautiful.border_color,
              border_width = beautiful.border_width,
              widget       = wibox.container.background
          },
          spacing = 10,
          layout  = wibox.layout.fixed.vertical
      }

🔗 border_width number · Inherited from wibox.container.background · 1 signal
  Add a border of a specific width.

  If the shape is set, the border will also be shaped.

  ### Constraints:

  Default value | : `0`
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  border_color | Set the color for the border. | object properties

  ### Usage:

      for _, width in ipairs {0, 1, 3, 10 } do
          local w = wibox.widget {
              {
                  {
                      text          = "  Content  ",
                      valign        = "center",
                      align         = "center",
                      widget        = wibox.widget.textbox
                  },
                  margins = 10,
                  widget  = wibox.container.margin
              },
              border_color = beautiful.bg_normal,
              border_width = width,
              shape        = gears.shape.rounded_rect,
              widget       = wibox.container.background
          }
      end

  Click to display more

  ### Emit signals:

  - `property::border_width` When the `border_width` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `border_width` The new value affected to the property.
🔗 border_color color · Inherited from wibox.container.background · 1 signal · 1 theme variable
  Set the color for the border.

  ### Constraints:

  Default value | : wibox.container.background.fg if set, otherwise beautiful.fg_normal.
  Type description:
  string | : An hexadecimal color code, such as `"#ff0000"` for red.
  string | : A color name, such as `"red"`.
  table | : A [gradient table](../theme_related_libraries/gears.color.html).
  cairo.pattern | : Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html).
  cairo.pattern | : A texture build from an image by [gears.color.create\_png\_pattern](../theme_related_libraries/gears.color.html#create_png_pattern)

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module
  border_width | Add a border of a specific width. | object properties

  ### Usage:

      local colors = {
          beautiful.bg_normal,
          "#00ff00",
          gears.color {
              type  = "linear",
              from  = { 0 , 20 },
              to    = { 20, 0  },
              stops = {
                  { 0, "#0000ff" },
                  { 1, "#ff0000" }
              },
          },
      }

      for _, color in ipairs(colors) do
          local w = wibox.widget {
              {
                  {
                      text          = "  Content  ",
                      valign        = "center",
                      align         = "center",
                      widget        = wibox.widget.textbox
                  },
                  margins = 10,
                  widget  = wibox.container.margin
              },
              border_color         = color,
              border_width         = 3,
              stretch_vertically   = true,
              stretch_horizontally = true,
              shape                = gears.shape.rounded_rect,
              widget               = wibox.container.background
          }
      end

      See wibox.container.background.shape for an usage example.

  Click to display more

  ### Emit signals:

  - `property::border_color` When the `border_color` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `border_color` The new value affected to the property.

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.fg_normal | Fallback when 'fg' and `border_color` aren't set.

🔗 border_strategy string · Inherited from wibox.container.background · 1 signal
  How the border width affects the contained widget.

  ### Constraints:

  Default value | : `"none"`
  Valid values:
  `"none"` | : Just apply the border, do not affect the content size (default).
  `"inner"` | : Squeeze the size of the content by the border width.

  ### Usage:

      for k, strategy in ipairs { "none", "inner" } do
          for idx, width in ipairs {0, 1, 3, 10 } do
              local w = wibox.widget {
                  {
                      {
                          text          = "border_width = "..width,
                          valign        = "center",
                          align         = "center",
                          widget        = wibox.widget.textbox
                      },
                      border_color    = beautiful.bg_normal,
                      border_width    = width,
                      border_strategy = strategy,
                      shape           = gears.shape.rounded_rect,
                      widget          = wibox.container.background
                  },
                  widget = wibox.container.place
              }
          end
      end

  Click to display more

  ### Emit signals:

  - `property::border_strategy` When the `border_strategy` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `border_strategy` The new value affected to the property.
🔗 children table · Inherited from wibox.widget.base
  Get or set the children elements.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of wibox.widget.

  ### See also:

  wibox.widget.base.all_children |  |

🔗 all_children table · Inherited from wibox.widget.base
  Get all direct and indirect children widgets. This will scan all containers recursively to find widgets Warning: This method it prone to stack overflow if there is a loop in the widgets hierarchy. A hierarchy loop is when a widget, or any of its children, contain (directly or indirectly) itself.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of wibox.widget.

  ### See also:

  wibox.widget.base.children |  |

🔗 forced_height number or nil · Inherited from wibox.widget.base
  Force a widget height.

  ### Constraints:

  Default value | : `nil`
  Type description:
  nil | : Let the layout decide the height. Usually using the widget native height.
  number | : Enforce a number of pixels.
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  wibox.widget.base.forced_width |  |

🔗 forced_width number or nil · Inherited from wibox.widget.base
  Force a widget width.

  ### Constraints:

  Default value | : `nil`
  Type description:
  nil | : Let the layout decide the width. Usually using the widget native width.
  number | : Enforce a number of pixels.
  Unit | : pixel
  Negative allowed | : false

  ### See also:

  wibox.widget.base.forced_height |  |

🔗 opacity number · Inherited from wibox.widget.base
  The widget opacity (transparency).

  ### Constraints:

  Default value | : `1.0`
  Unit | : A gradient between transparent (`0.0`) and opaque (`1.0`).
  Minimum value | : 0.0
  Maximum value | : 1.0

  ### See also:

  wibox.widget.base.visible |  |

🔗 visible boolean · Inherited from wibox.widget.base
  The widget visibility.

  ### Constraints:

  Default value | : `true`
  Valid values | : `true` or `false`.

  ### See also:

  wibox.widget.base.opacity |  |

🔗 buttons table · Inherited from wibox.widget.base
  The widget buttons.

  The table contains a list of awful.button objects.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of awful.button.

  ### See also:

  awful.button | Create easily new buttons objects ignoring certain modifiers. | module

## Object methods

🔗 :emit_signal (name, ...) · Inherited from gears.object
  Emit a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  ... |  |  | Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

🔗 :connect_signal (name, func) · Inherited from gears.object
  Connect to a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

🔗 :weak_connect_signal (name, func) · Inherited from gears.object
  Connect to a signal weakly.

  This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

  **Warning:** Only use this function if you really, really, really know what you are doing.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback to call when the signal is emitted.

🔗 :set_shape (shape) · Inherited from wibox.container.background · 1 signal
  Set the background shape.

  Any other arguments will be passed to the shape function.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  shape |  | gears.shape or function | A function taking a context, width and height as arguments

  ### See also:

  gears.shape | Module dedicated to gather common shape painters. | module
  shape | The background shape. | object properties

  Click to display more

  ### Emit signals:

  - `property::set_shape` When the `set_shape` value changes.
  - `self` wibox.container.background The object which changed (useful when connecting many object to the same callback).
  - `new_value` `shape` The new value affected to the property.
🔗 :add_button (button) · Inherited from wibox.widget.base
  Add a new awful.button to this widget.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  button |  | awful.button | The button to add.

🔗 :emit_signal_recursive (signal_name, ...) · Inherited from wibox.widget.base
  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.

  Note that this function has some flaws:

  1. The signal is only forwarded once the widget tree has been built. This happens after all currently scheduled functions have been executed. Therefore, it will not start to work right away. 2. In case the widget is present multiple times in a single widget tree, this function will also forward the signal multiple times (once per upward tree path). 3. If the widget is removed from the widget tree, the signal is still forwarded for some time, similar to the first case.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  signal_name |  | string |
  ... |  |  | Other arguments

🔗 :index (widget, recursive, ...) -> (number, widget, table) · Inherited from wibox.widget.base
  Get the index of a widget.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  widget |  | widget | The widget to look for.
  recursive | Optional | boolean | Recursively check accross the sub-widgets hierarchy.
  ... | Optional | widget | Additional widgets to add at the end of the sub-widgets hierarchy "path".

  ### Returns:

  1. number The widget index.
  2. widget The parent widget.
  3. table The hierarchy path between "self" and "widget".
🔗 :disconnect_signal (name, func) · Inherited from gears.object
  Disconnect from a signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal.
  func |  | function | The callback that should be disconnected.

## Deprecated object properties

🔗 shape_border_width number · Inherited from wibox.container.background
  When a `shape` is set, also draw a border.

  See wibox.container.background.shape for an usage example.

  ### Type constraints:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  width |  | number | The border width

  ### See also:

  border_width | Add a border of a specific width. | object properties

🔗 shape_border_color color · Inherited from wibox.container.background · 1 theme variable
  When a `shape` is set, also draw a border.

  See wibox.container.background.shape for an usage example.

  ### Type constraints:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  fg |  | color | The border color, pattern or gradient

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module
  border_color | Set the color for the border. | object properties

  Click to display more

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.fg_normal | Fallback when 'fg' and `border_color` aren't set.

🔗 bgimage string or surface or function · Inherited from wibox.container.background
  The background image to use.

  This property is deprecated. The wibox.container.border provides a much more fine-grained support for background images. It is now out of the wibox.container.background scope. wibox.layout.stack can also be used to overlay a widget on top of a wibox.widget.imagebox. This solution exposes all availible imagebox properties. Finally, if you wish to use the `function` callback support, implement the `before_draw_children` method on any widget. This gives you the same level of control without all the `bgimage` corner cases.

  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.

  ### Type constraints:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  bgimage |  | string, surface or function | A background image or a function.

  ### See also:

  gears.surface | Utilities to integrate and manipulate Cairo drawing surfaces. | module
  wibox.container.border | Place widgets or images on the sides, corner and back of another widget. | module
  wibox.widget.imagebox | A widget to display an image. | module
  wibox.layout.stack | Place multiple widgets on top of each other. | module

## Signals

🔗 widget::layout_changed · Inherited from wibox.widget.base
  When the layout (size) change. This signal is emitted when the previous results of `:layout()` and `:fit()` are no longer valid. Unless this signal is emitted, `:layout()` and `:fit()` must return the same result when called with the same arguments.

  ### See also:

  widget::redraw_needed | When the widget content changed. | signals

🔗 widget::redraw_needed · Inherited from wibox.widget.base
  When the widget content changed. This signal is emitted when the content of the widget changes. The widget will be redrawn, it is not re-layouted. Put differently, it is assumed that `:layout()` and `:fit()` would still return the same results as before.

  ### See also:

  widget::layout_changed | When the layout (size) change. | signals

🔗 button::press · Inherited from wibox.widget.base
  When a mouse button is pressed over the widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  lx |  | number | The horizontal position relative to the (0,0) position in the widget.
  ly |  | number | The vertical position relative to the (0,0) position in the widget.
  button |  | number | The button number.
  mods |  | table | The modifiers (mod4, mod1 (alt), Control, Shift)
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

🔗 button::release · Inherited from wibox.widget.base
  When a mouse button is released over the widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  lx |  | number | The horizontal position relative to the (0,0) position in the widget.
  ly |  | number | The vertical position relative to the (0,0) position in the widget.
  button |  | number | The button number.
  mods |  | table | The modifiers (mod4, mod1 (alt), Control, Shift)
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

🔗 mouse::enter · Inherited from wibox.widget.base
  When the mouse enter a widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

🔗 mouse::leave · Inherited from wibox.widget.base
  When the mouse leave a widget.

  ### Arguments:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  self |  | table | The current object instance itself.
  find_widgets_result |  | table | The entry from the result of wibox:find_widgets for the position that the mouse hit.
  drawable |  | wibox.drawable | The drawable containing the widget.
  widget |  | widget | The widget being displayed.
  hierarchy |  | wibox.hierarchy | The hierarchy managing the widget's geometry.
  x |  | number | An approximation of the X position that the widget is visible at on the surface.
  y |  | number | An approximation of the Y position that the widget is visible at on the surface.
  width |  | number | An approximation of the width that the widget is visible at on the surface.
  height |  | number | An approximation of the height that the widget is visible at on the surface.
  widget_width |  | number | The exact width of the widget in its local coordinate system.
  widget_height |  | number | The exact height of the widget in its local coordinate system.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

generated by LDoc 1.5.0