# Module: `wibox.container.border`

Place widgets or images on the sides, corner and back of another widget.

This widget main use case is to surround another widget with an uniform border. It can also be used to create soft shadows. It support CSS style image slicing or widgets within the border. The `awful.layout.align` layout an also be used to achieve border, but make it very hard to make them symmetric on both axis.

Note that because of legacy reasons, wibox.container.background also has good support for borders. If you only need simple shaped strokes, the `background` container is a much better choice. This module is better suited for background images and border widgets.

Advanced usage ==============

In this first example, 2 `wibox.container.borders` are combined in a wibox.layout.stack. The bottom one is the "real" border and the top layer is used to place some widgets. This is useful to built titlebars.

local w = wibox.widget { -- This is the background border. { paddings = { left = 5, top = 3, right = 10, bottom = 10, }, borders = 20, border_image = image_path, honor_borders = false, widget = wibox.container.border }, -- This border container is used top place widgets. { { text = "Center widget", valign = "center", align = "center", widget = wibox.widget.textbox }, border_widgets = { top_left = generic_widget(""), top = generic_widget("top"), top_right = generic_widget(""), right = generic_widget("right"), bottom_right = generic_widget(""), bottom = generic_widget("bottom"), bottom_left = generic_widget(""), left = generic_widget("left"), }, widget = wibox.container.border }, layout = wibox.layout.stack }

This example demonstrates how to use this module to create a client border with a top titlebar and borders. It does so by embedding a wibox.container.border into another wibox.container.border. The outer container acts as the border around the central area while the inner one spans the top area and contains the titlebar itself. The outer border widgets area can be used to implement border resize.

local w = wibox.widget { { { text = "Content", align = "center", valign = "center", widget = wibox.widget.textbox }, border_widgets = { top = { { { { stylesheet = "#bg1 {stop-color:#ca2b2b;} #bg2 {stop-color:#f8b9b9;}", image = btn, widget = wibox.widget.imagebox }, { stylesheet = "#bg1 {stop-color:#ec9527;} #bg2 {stop-color:#ffff9c;}", image = btn, widget = wibox.widget.imagebox }, { stylesheet = "#bg1 {stop-color:#75b525;} #bg2 {stop-color:#e0fda9;}", image = btn, widget = wibox.widget.imagebox }, spacing = 3, layout = wibox.layout.fixed.horizontal }, { align = "center", text = "Shameless macOS ripoff", widget = wibox.widget.textbox }, layout = wibox.layout.align.horizontal }, paddings = 6, borders = 14, border_image = bg, honor_borders = false, fill = true, widget = wibox.container.border }, right = generic_widget(""), bottom_right = generic_widget(""), bottom = generic_widget(""), bottom_left = generic_widget(""), left = generic_widget(""), }, borders = { top = 28, left = 22, right = 22, bottom = 22, }, border_merging = { top = true }, widget = wibox.container.border }, bg = "#d9d9d9", shape = gears.shape.rounded_rect, widget = wibox.container.background }

This container is like every other widgets. It is possible to override the Cairo drawing functions. This is very useful here to create custom borders using cairo while still re-using the internal geometry handling code.

local w = wibox.widget { { text = "Center widget", valign = "center", align = "center", widget = wibox.widget.textbox }, after_draw_children = function(_, _, cr, width, height) cr:set_source_rgba(1,0,0,1) cr:set_dash({1,1},1) cr:rectangle(1, 1, width-2, height-2) cr:rectangle(5, 5, width-10, height-10) cr:stroke() end, borders = 20, honor_borders = false, widget = wibox.container.border }

### Class Hierarchy

- gears.object
- - wibox.widget.base
  - - wibox.container.border

### Info:

- Copyright: 2021 Emmanuel Lepage-Vallee
- Originally authored by: Emmanuel Lepage-Vallee
  (Full contributors list available on our github project)

## Object properties

widget | widget or nil | The widget to display inside of the border. |
border_image | string or image or nil | A single border image for the border. |
slice | boolean | Sice the border_image to fit the content. |
border_image_stylesheet | string | Set a stylesheet for the slice surface. |
image_scaling_quality | string | How the border_image(s) are scaled. |
border_images | table or image or nil | Use images for each of the side/corner/filling sections. |
borders | table or number | The size of the border on each side. |
sides_fit_policy | string | How the sliced image is resized for the border sides. |
filling_fit_policy | string | How the sliced image is resized for the border filling. |
corners_fit_policy | string | How the sliced image is resized for the border corners. |
honor_borders | boolean | Stretch the child widget over the entire area. |
ontop | boolean | Draw the child widget below or on top of the border. |
fill | boolean | Use the center portion of the border_image as a background. |
paddings | number or table | Add some space between the border and the inner widget. |
border_widgets | table or nil | Use individual widgets as a border. |
border_merging | table or nil | Merge the corners widgets into the side widgets. |
expand_corners | boolean | When border_widgets is used, allow the border to grow due to corner widgets. |
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

:reset () | Reset this layout. |
: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
: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
:disconnect_signal (name, func) | Disconnect from a signal. | Inherited from gears.object
:emit_signal (name, ...) | Emit a signal. | Inherited from gears.object

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

## Object properties

🔗 widget widget or nil
  The widget to display inside of the border.

  ### Constraints:

  Default value | : `nil`

🔗 border_image string or image or nil
  A single border image for the border.

  When using this property, the borders also **needs** to be specified.

  ### Constraints:

  Default value | : `nil`
  Type description:
  string | : Interpreted as a path to an image file.
  string | : A valid SVG content.
  cairo | : A cairo image surface: Directly used as-is.
  librsvg | : A librsvg handle object: Directly used as-is.
  nil | : Unset the image.

  ### See also:

  borders | The size of the border on each side. | object properties
  border_images | Use images for each of the side/corner/filling sections. | object properties

🔗 slice boolean · 1 signal
  Sice the border_image to fit the content.

  This applies a CSS-like modifier to the image. It will use the values of the borders property to split the original image into multiple smaller images and use the value of filling_fit_policy, sides_fit_policy and corners_fit_policy to resize the content.

  ### Constraints:

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

  ### Usage:

      local w = wibox.widget {
          {
              text          = "Central widget",
              valign        = "center",
              align         = "center",
              forced_height = 30,
              forced_width  = 30,
              widget        = wibox.widget.textbox
          },
          fill         = true,
          borders      = 10,
          border_image = image_path,
          slice        = i,
          widget       = wibox.container.border
      }

  Click to display more

  ### Emit signals:

  - `property::slice` When the slice value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` slice The new value affected to the property.
🔗 border_image_stylesheet string
  Set a stylesheet for the slice surface.

  This only affect `.svg` based assets. It does nothing for `.png`/`.jpg` and already loaded `gears.surfaces` based assets.

  ### Constraints:

  Default value | : `""`
  Valid values | : CSS data or file path.

  ### See also:

  wibox.widget.imagebox.stylesheet | Set the SVG CSS stylesheet. (wibox.widget.imagebox) | object properties

  ### Usage:

      local image_path = '<?xml version="1.0"?>'..
          '<svg xmlns:xlink="http://www.w3.org/1999/xlink" width="30" height="30" viewBox="0 0 7.937 7.937">'..
          '  <defs>'..
          '    <linearGradient id="a">'..
          '      <stop style="stop-opacity:1" offset="0" id="first"/>'..
          '      <stop offset=".5" style="stop-opacity:1" id="second"/>'..
          '      <stop style="stop-opacity:1" offset="1" id="third"/>'..
          '    </linearGradient>' ..
          '    <linearGradient xlink:href="#a" id="b" gradientUnits="userSpaceOnUse" x1="28.726" y1="64.923" x2="182.185" y2="201.75" gradientTransform="matrix(.04726 0 0 .053 83.075 141.528)"/>'..
          '  </defs>'..
          '  <path d="M84.732 144.627c-.372 0-.642.329-.642.679v6.58c0 .35.27.678.642.678h6.653c.372 0 .642-.328.642-.679v-6.579c0-.35-.27-.68-.642-.68zm.043.685h6.567v6.568h-6.567z" style="fill:url(#b);" transform="translate(-84.09 -144.627)"/>'..
          '</svg>'

      local style = ""..
          "#first  {stop-color: magenta;}" ..
          "#second {stop-color: cyan;}" ..
          "#third  {stop-color: yellow;}"

      local w = wibox.widget {
          {
              text   = "Center widget",
              valign = "center",
              align  = "center",
              widget = wibox.widget.textbox
          },
          borders                 = 50,
          border_image_stylesheet = style,
          border_image            = image_path,
          honor_borders           = false,
          widget                  = wibox.container.border
      }

🔗 image_scaling_quality string
  How the border_image(s) are scaled.

  Note that `nearest` and `best` are the most sensible choices. Other modes may introduce anti-aliasing artifacts at the junction of the various images.

  Value | Description
  --- | ---
  fast | A high-performance filter
  good | A reasonable-performance filter
  best | The highest-quality available
  nearest | Nearest-neighbor filtering (blocky)
  bilinear | Linear interpolation in two dimensions

  ### Constraints:

  Default value | : `"nearest"`
  Valid values:
  `"fast"` | : A high-performance filter.
  `"good"` | : A reasonable-performance filter.
  `"best"` | : The highest-quality available.
  `"nearest"` | : Nearest-neighbor filtering (blocky).
  `"bilinear"` | : Linear interpolation in two dimensions.

🔗 border_images table or image or nil · 1 signal
  Use images for each of the side/corner/filling sections.

  This property is for using different images for each component of the border. If you want to use a single image, use border_image.

  Please note that this is mutually exclusive for each corner or side with border_widgets. It has priority over border_image.

  ### Constraints:

  Default value | : `nil`
  Type description:
  string | : Interpreted as a path to an image file.
  string | : A valid SVG content.
  cairo | : A cairo image surface: Directly used as-is.
  librsvg | : A librsvg handle object: Directly used as-is.
  nil | : Unset the image.
  Table keys:
  top_left (string|image|nil)
  top (string|image|nil)
  top_right (string|image|nil)
  right (string|image|nil)
  bottom_right (string|image|nil)
  bottom (string|image|nil)
  bottom_left (string|image|nil)
  left (string|image|nil)

  ### See also:

  border_image | A single border image for the border. | object properties

  ### Usage:

      local w1 = wibox.widget {
          {
              text          = "Single image",
              valign        = "center",
              align         = "center",
              widget        = wibox.widget.textbox
          },
          borders          = 20,
          sides_fit_policy = "repeat",
          border_images    = blue_logo,
          widget           = wibox.container.border
      }

      local w2 = wibox.widget {
          {
              text          = "Multiple images",
              valign        = "center",
              align         = "center",
              widget        = wibox.widget.textbox
          },
          sides_fit_policy = "repeat",
          border_images    = {
              top_left     = red_logo,
              top          = green_logo,
              top_right    = blue_logo,
              right        = yellow_logo,
              bottom_right = orange_logo,
              bottom       = purple_logo,
              bottom_left  = cyan_logo,
              left         = black_logo,
          },
          widget = wibox.container.border
      }

  Click to display more

  ### Emit signals:

  - `property::border_images` When the border_images value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` border_images The new value affected to the property.
🔗 borders table or number
  The size of the border on each side.

  Ideally, the value should be smaller than half of the original surface size. For example, if the source is 48x48, then the maximum size should be 23 pixels. If the value exceed this, it will be lowered to the maximum value.

  ### Constraints:

  Default value | : `0`
  Table keys:
  top (number)
  left (number)
  right (number)
  bottom (number)
  Negative allowed | : false

  ### Usage:

      for k, borders in ipairs {0, 10, 30, 64} do
          for idx, image in ipairs {svg_image_path, png_image_path} do
              local w = wibox.widget {
                  {
                      text          = "Central widget",
                      valign        = "center",
                      align         = "center",
                      forced_height = 30,
                      forced_width  = 30,
                      widget        = wibox.widget.textbox
                  },
                  fill               = false,
                  borders            = borders,
                  border_image       = image,
                  forced_height      = 100,
                  widget             = wibox.container.border
              }
              l:add_widget_at(w, r+1, idx, 1, 1)
          end
      end

🔗 sides_fit_policy string · 1 signal
  How the sliced image is resized for the border sides.

  In the following example, the gradient based border works will with `fit` and `pad`. The repeated dot works well with `repeat` and `reflect`. The soft shadow one works regardless of the mode because the borders are identical.

  ### Constraints:

  Default value | : `"fit"`
  Valid values:
  `"fit"` | : (default)
  `"repeat"`
  `"reflect"`
  `"pad"`

  ### See also:

  wibox.widget.imagebox.vertical_fit_policy | Set the vertical fit policy. (wibox.widget.imagebox) | object properties
  wibox.widget.imagebox.horizontal_fit_policy | Set the horizontal fit policy. (wibox.widget.imagebox) | object properties

  ### Usage:

      local images = {
          {
              path     = image_path1,
              borders = 10,
          },
          {
              path    = image_path2,
              borders = 30,
          },
          {
              path    = image_path3,
              borders = {
                  top    = 20,
                  left   = 20,
                  bottom = 20,
                  right  = 20,
              },
          },
      }

      for k, mode in ipairs {"fit", "repeat", "reflect", "pad"} do
          for idx, image in ipairs(images) do
              local w = wibox.widget {
                  {
                      text          = "Central widget",
                      valign        = "center",
                      align         = "center",
                      widget        = wibox.widget.textbox
                  },
                  fill               = false,
                  borders            = image.borders,
                  border_image       = image.path,
                  sides_fit_policy   = mode,
                  widget             = wibox.container.border
              }
          end
      end

  Click to display more

  ### Emit signals:

  - `property::sides_fit_policy` When the sides_fit_policy value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` sides_fit_policy The new value affected to the property.
🔗 filling_fit_policy string · 1 signal
  How the sliced image is resized for the border filling.

  Also note that if slice is set to `false`, this will be used for the entire background.

  ### Constraints:

  Default value | : `"fit"`
  Valid values:
  `"fit"` | : (default)
  `"repeat"`
  `"reflect"`
  `"pad"`

  ### See also:

  fill | Use the center portion of the border_image as a background. | object properties
  wibox.widget.imagebox.vertical_fit_policy | Set the vertical fit policy. (wibox.widget.imagebox) | object properties
  wibox.widget.imagebox.horizontal_fit_policy | Set the horizontal fit policy. (wibox.widget.imagebox) | object properties

  ### Usage:

      for k, mode in ipairs {"fit", "repeat", "reflect", "pad"} do
          for idx, image in ipairs { image_path1, image_path2 } do
              local w = wibox.widget {
                  {
                      text          = "Central widget",
                      valign        = "center",
                      align         = "center",
                      widget        = wibox.widget.textbox
                  },
                  fill               = true,
                  borders            = idx == 1 and 10 or 30,
                  border_image       = image,
                  filling_fit_policy = mode,
                  widget             = wibox.container.border
              }
          end
      end

  Click to display more

  ### Emit signals:

  - `property::filling_fit_policy` When the filling_fit_policy value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` filling_fit_policy The new value affected to the property.
🔗 corners_fit_policy string · 1 signal
  How the sliced image is resized for the border corners.

  ### Constraints:

  Default value | : `"fit"`
  Valid values:
  `"fit"` | : (default)
  `"repeat"`
  `"reflect"`
  `"pad"`

  ### See also:

  wibox.widget.imagebox.vertical_fit_policy | Set the vertical fit policy. (wibox.widget.imagebox) | object properties
  wibox.widget.imagebox.horizontal_fit_policy | Set the horizontal fit policy. (wibox.widget.imagebox) | object properties

  ### Usage:

      for k, mode in ipairs {"fit", "repeat", "reflect", "pad"} do
          for idx, image in ipairs { image_path1, image_path2 } do
              local w = wibox.widget {
                  {
                      text          = "Central widget",
                      valign        = "center",
                      align         = "center",
                      widget        = wibox.widget.textbox
                  },
                  fill               = false,
                  borders            = {
                      left   = 10,
                      right  = 50,
                      top    = 10,
                      bottom = 50,
                  },
                  border_image       = image,
                  corners_fit_policy = mode,
                  widget             = wibox.container.border
              }
          end
      end

  Click to display more

  ### Emit signals:

  - `property::corners_fit_policy` When the corners_fit_policy value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` corners_fit_policy The new value affected to the property.
🔗 honor_borders boolean · 1 signal
  Stretch the child widget over the entire area.

  By default, the widget honors the borders.

  ### Constraints:

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

  ### See also:

  ontop | Draw the child widget below or on top of the border. | object properties

  ### Usage:

      local w = wibox.widget {
          {
              {
                  markup        = "<b>Central widget</b>",
                  valign        = "center",
                  align         = "center",
                  forced_height = 30,
                  forced_width  = 30,
                  widget        = wibox.widget.textbox
              },
              bg     = stripe_pattern,
              widget = wibox.container.background
          },
          borders       = 10,
          border_image  = image_path,
          honor_borders = honor,
          widget        = wibox.container.border
      }

  Click to display more

  ### Emit signals:

  - `property::honor_borders` When the honor_borders value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` honor_borders The new value affected to the property.
🔗 ontop boolean · 1 signal
  Draw the child widget below or on top of the border.

  wibox.container.background supports border clips because it knows the shape of the border. wibox.container.border doesn't have this luxury because the border is defined in an image and the "inner limit" could be any pixel.

  This proporty helps mitigate that by allowing the border to be drawn on top of the child widget when honor_borders is set to false. When honor_borders is `true`, it does nothing. In the example below, some paddings are also necessary to look decent.

  ### Constraints:

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

  ### See also:

  honor_borders | Stretch the child widget over the entire area. | object properties
  paddings | Add some space between the border and the inner widget. | object properties

  ### Usage:

      local w = wibox.widget {
          {
              {
                  markup        = "<b>Central widget</b>",
                  valign        = "center",
                  align         = "center",
                  forced_height = 30,
                  forced_width  = 30,
                  widget        = wibox.widget.textbox
              },
              bg     = stripe_pattern,
              widget = wibox.container.background
          },
          paddings      = {
              left   = 5,
              top    = 3,
              right  = 10,
              bottom = 10,
          },
          borders       = 20,
          border_image  = image_path,
          ontop         = ontop,
          honor_borders = false,
          widget        = wibox.container.border
      }

  Click to display more

  ### Emit signals:

  - `property::ontop` When the ontop value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` ontop The new value affected to the property.
🔗 fill boolean · 1 signal
  Use the center portion of the border_image as a background.

  ### Constraints:

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

  ### See also:

  filling_fit_policy | How the sliced image is resized for the border filling. | object properties

  ### Usage:

      local w = wibox.widget {
          {
              text          = "Central widget",
              valign        = "center",
              align         = "center",
              forced_height = 30,
              forced_width  = 30,
              widget        = wibox.widget.textbox
          },
          borders      = 10,
          border_image = image_path,
          fill         = fill,
          widget       = wibox.container.border
      }

  Click to display more

  ### Emit signals:

  - `property::fill` When the fill value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` fill The new value affected to the property.
🔗 paddings number or table · 1 signal
  Add some space between the border and the inner widget.

  This is pretty much exactly what wibox.container.margin would be used for, but since this is a very common use case, this container also has it built-in.

  A common use case for this is asymetric borders such as soft shadows.

  ### Constraints:

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

  ### See also:

  wibox.container.margin | Add a margin around a widget. | module

  ### Usage:

      local paddings = {
          0,
          5,
          10,
          {
              left   = 5,
              top    = 5,
              bottom = 10,
              right  = 10,
          }
      }

      for _, padding in ipairs(paddings) do
          local w = wibox.widget {
              {
                  {
                      markup        = "<b>Central widget</b>",
                      valign        = "center",
                      align         = "center",
                      forced_height = 30,
                      forced_width  = 30,
                      widget        = wibox.widget.textbox
                  },
                  bg     = stripe_pattern,
                  widget = wibox.container.background
              },
              borders      = 10,
              paddings     = padding,
              border_image = image_path,
              widget       = wibox.container.border
          }
      end

  Click to display more

  ### Emit signals:

  - `property::paddings` When the paddings value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` paddings The new value affected to the property.
🔗 border_widgets table or nil · 1 signal
  Use individual widgets as a border.

  Please note that this is mutually exclusive for each corner or side with border_images. It has priority over border_image.

  Please note that if borders is not defined, the side widgets (`left`, `right`, `top` and `bottom`) will be used to compute the side of the borders. If you only have corner widgets, then borders need to be defined.

  ### Constraints:

  Default value | : `nil`
  Table keys:
  top_left (wibox.widget)
  top (wibox.widget)
  top_right (wibox.widget)
  right (wibox.widget)
  bottom_right (wibox.widget)
  bottom (wibox.widget)
  bottom_left (wibox.widget)
  left (wibox.widget)

  ### Usage:

      local w = wibox.widget {
          {
              text          = "Central widget",
              valign        = "center",
              align         = "center",
              widget        = wibox.widget.textbox
          },
          border_widgets = {
              top_left     = generic_widget("top_left"),
              top          = generic_widget("top"),
              top_right    = generic_widget("top_right"),
              right        = generic_widget("right"),
              bottom_right = generic_widget("bottom_right"),
              bottom       = generic_widget("bottom"),
              bottom_left  = generic_widget("bottom_left"),
              left         = generic_widget("left"),
          },
          widget = wibox.container.border
      }

  Click to display more

  ### Emit signals:

  - `property::border_widgets` When the border_widgets value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` border_widgets The new value affected to the property.
🔗 border_merging table or nil · 1 signal
  Merge the corners widgets into the side widgets.

  Rather than have corner widgets/images, let the side widget span the entire area. This feature is coupled with border_widgets and does nothing when only an image is present.

  ### Constraints:

  Table keys:
  top (boolean) | : Extend the `top` side widget by replacing the `top_left` and `top_right` widgets.
  bottom (boolean) | : Extend the `bottom` side widget by replacing the `bottom_left` and `bottom_right` widgets.
  left (boolean) | : Extend the `left` side widget by replacing the `top_left` and `bottom_left` widgets.
  right (boolean) | : Extend the `right` side widget by replacing the `top_right` and `bottom_right` widgets.

  ### Usage:

      for _, side in ipairs { "top", "bottom", "left", "right" } do
          l:add(wibox.widget {
              {
                  text   = side .. " = true",
                  valign = "center",
                  align  = "center",
                  widget = wibox.widget.textbox
              },
              border_merging = {
                  -- This is the equaivalent "side = true,". "side" is the loop
                  -- variable.
                  [side] = true
              },
              border_widgets = {
                  top_left     = generic_widget("top_left"),
                  top          = generic_widget("top"),
                  top_right    = generic_widget("top_right"),
                  right        = generic_widget("right"),
                  bottom_right = generic_widget("bottom_right"),
                  bottom       = generic_widget("bottom"),
                  bottom_left  = generic_widget("bottom_left"),
                  left         = generic_widget("left"),
              },
              widget = wibox.container.border
          })
      end

  Click to display more

  ### Emit signals:

  - `property::border_merging` When the border_merging value changes.
  - `self` wibox.container.border The object which changed (useful when connecting many object to the same callback).
  - `new_value` border_merging The new value affected to the property.
🔗 expand_corners boolean
  When border_widgets is used, allow the border to grow due to corner widgets.

  ### Constraints:

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

  ### Usage:

      for _, expand in ipairs { false, true } do
          local w = wibox.widget {
              {
                  text          = "expand_corners = " .. (expand and "true" or "false"),
                  valign        = "center",
                  align         = "center",
                  widget        = wibox.widget.textbox
              },
              border_widgets = {
                  top_left     = generic_widget("top_left"),
                  top          = generic_widget("top"),
                  top_right    = generic_widget("top_right"),
                  right        = generic_widget("right"),
                  bottom_right = generic_widget("bottom_right"),
                  bottom       = generic_widget("bottom"),
                  bottom_left  = generic_widget("bottom_left"),
                  left         = generic_widget("left"),
              },
              expand_corners = expand,
              widget         = wibox.container.border
          }
      end

🔗 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

🔗 :reset ()
  Reset this layout. The widget will be removed and the rotation reset.
🔗 :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".
🔗 :connect_signal (name, func) · Inherited from gears.object
  Connect to a signal.

  **Usage example output**:

  In slot [obj] nil nil nil In slot [obj] foo bar 42

  ### Parameters:

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

  ### Usage:

      local o = gears.object{}
      -- Function can be attached to signals
      local function slot(obj, a, b, c)
          print("In slot", obj, a, b, c)
      end
      o:connect_signal("my_signal", slot)
      -- Emitting can be done without arguments. In that case, the object will be
      -- implicitly added as an argument.
      o:emit_signal "my_signal"
      -- It is also possible to add as many random arguments are required.
      o:emit_signal("my_signal", "foo", "bar", 42)
      -- Finally, to allow the object to be garbage collected (the memory freed), it
      -- is necessary to disconnect the signal or use weak_connect_signal
      o:disconnect_signal("my_signal", slot)
      -- This time, the slot wont be called as it is no longer connected.
      o:emit_signal "my_signal"

🔗 :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.

🔗 :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.

🔗 :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()

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