# Module: `wibox`

Box where widget can be displayed.

### Info:

- Copyright: 2010 Uli Schlachter
- Originally authored by: Uli Schlachter
  (Full contributors list available on our github project)

## Constructors

wibox.wibox {[args]} | Create a wibox. |

## Static module functions

wibox.connect_signal (name, func) | Connect a global signal on the wibox class. |
wibox.emit_signal (name, ...) | Emit a wibox signal. |
wibox.disconnect_signal (name, func) -> boolean | Disconnect a signal from a source. |

## Object properties

border_width | integer | Border width. |
border_color | string | Border color. |
ontop | boolean | On top of other windows. |
cursor | string or nil | The mouse cursor. |
visible | boolean | Visibility. |
opacity | number | The opacity of the wibox, between 0 and 1. |
type | string | The window type (desktop, normal, dock, ...). |
x | integer | The x coordinates. |
y | integer | The y coordinates. |
width | integer | The width of the wibox. |
height | integer | The height of the wibox. |
screen | screen | The wibox screen. |
widget | widget or nil | The widget that the wibox displays. |
window | string | The X window id. |
shape_bounding | surface._native | The wibox's bounding shape as a (native) cairo surface. |
shape_clip | surface._native | The wibox's clip shape as a (native) cairo surface. |
shape_input | surface._native | The wibox's input shape as a (native) cairo surface. |
shape | shape | The wibar's shape. |
input_passthrough | boolean | Forward the inputs to the client below the wibox. |
buttons | table | Get or set mouse buttons bindings to a wibox. |
bg | color | The background of the wibox. |
bgimage | image or nil | The background image of the drawable. |
fg | color | The foreground (text) of the wibox. |

## Object methods

:geometry (geo) -> table | Get or set wibox geometry. |
:struts (struts) -> () | Get or set wibox struts. |
:setup {[args]} | Set a declarative widget hierarchy description. |
:find_widgets (x, y) -> table | Find a widget by a point. |
:to_widget () -> widget | Create a widget that reflects the current state of this wibox. |
:save_to_svg (path, context) | Save a screenshot of the wibox to `path`. |
:draw (wibox) | Redraw a wibox. |

## Constructors

🔗 wibox.wibox {[args]}
  Create a wibox.

  ### 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 `wibox{}`. This is a Lua shortcut syntax equivalent to `wibox({})`. `args` is only a placeholder name for the "lone table argument" used in named parameters calls.

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  args | Optional | table |  | `nil`
  border_width |  | integer | Border width. | Not applicable
  border_color |  | string | Border color. | Not applicable
  ontop | Optional | boolean | On top of other windows. | `false`
  cursor |  | string | The mouse cursor. | Not applicable
  visible |  | boolean | Visibility. | Not applicable
  opacity | Optional | number | The opacity, between 0 and 1. | `1`
  type |  | string | The window type (desktop, normal, dock, …). | Not applicable
  x |  | integer | The x coordinates. | Not applicable
  y |  | integer | The y coordinates. | Not applicable
  width |  | integer | The width. | Not applicable
  height |  | integer | The height. | Not applicable
  screen |  | screen | The wibox screen. | Not applicable
  widget |  | wibox.widget | The widget that the wibox displays. | Not applicable
  shape_bounding |  |  | The wibox’s bounding shape as a (native) cairo surface. | Not applicable
  shape_clip |  |  | The wibox’s clip shape as a (native) cairo surface. | Not applicable
  shape_input |  |  | The wibox’s input shape as a (native) cairo surface. | Not applicable
  bg |  | color | The background. | Not applicable
  bgimage |  | surface | The background image of the drawable. | Not applicable
  fg |  | color | The foreground (text) color. | Not applicable
  shape |  | gears.shape | The shape. | Not applicable
  input_passthrough | Optional | boolean | If the inputs are forward to the element below. | `false`

  ### Returns:

  wibox The new wibox

## Static module functions

🔗 wibox.connect_signal (name, func)
  Connect a global signal on the wibox class.

  Functions connected to this signal source will be executed when any wibox object emits the signal.

  It is also used for some generic wibox signals such as `request::geometry`.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal
  func |  | function | The function to attach

  ### Usage:

      wibox.connect_signal("added", function(notif)
         -- do something
      end)

🔗 wibox.emit_signal (name, ...)
  Emit a wibox signal.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The signal name.
  ... |  |  | The signal callback arguments

🔗 wibox.disconnect_signal (name, func) -> boolean
  Disconnect a signal from a source.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The name of the signal
  func |  | function | The attached function

  ### Returns:

  boolean If the disconnection was successful

## Object properties

🔗 border_width integer · 1 signal
  Border width.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::border_width` When the border_width value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 border_color string · 1 signal
  Border color.

  Please note that this property only support string based 24 bit or 32 bit colors:

  Red Blue _| _| #FF00FF T‾ Green

  Red Blue _| _| #FF00FF00 T‾ ‾T Green Alpha

  ### Constraints:

  Default value | : `beautiful.fg_normal`

  Click to display more

  ### Emit signals:

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

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.fg_normal |

🔗 ontop boolean · 1 signal
  On top of other windows.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::ontop` When the ontop value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 cursor string or nil · 1 signal
  The mouse cursor.

  ### Constraints:

  Default value | : `nil`
  Type description:
  nil | : Do not change the mouse cursor.

  ### See also:

  mouse | Manipulate and inspect the mouse cursor. | module

  Click to display more

  ### Emit signals:

  - `property::cursor` When the cursor value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 visible boolean · 1 signal
  Visibility.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::visible` When the visible value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 opacity number · 1 signal
  The opacity of the wibox, between 0 and 1.

  ### Constraints:

  Default value | : `true`
  Minimum value | : 0.0
  Maximum value | : 1.0

  Click to display more

  ### Emit signals:

  - `property::opacity` When the opacity value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 type string · 1 signal
  The window type (desktop, normal, dock, ...).

  ### Constraints:

  Default value | : `\"\"`

  ### See also:

  client.type | The window type. (client) | object properties

  Click to display more

  ### Emit signals:

  - `property::type` When the type value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 x integer · 1 signal
  The x coordinates.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::x` When the x value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 y integer · 1 signal
  The y coordinates.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::y` When the y value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 width integer · 1 signal
  The width of the wibox.

  ### Constraints:

  Default value | : `1`
  Unit | : pixel
  Minimum value | : 1
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::width` When the width value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 height integer · 1 signal
  The height of the wibox.

  ### Constraints:

  Default value | : `1`
  Unit | : pixel
  Minimum value | : 1
  Negative allowed | : false

  Click to display more

  ### Emit signals:

  - `property::height` When the height value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 screen screen · 1 signal
  The wibox screen.

  ### Constraints:

  Default value | : The screen which contains `0x0`.
  Type description:
  screen | : A valid screen object such as retured by `awful.screen.focused()` or mouse.screen.
  integer | : A screen global id. Avoid using this since they are unsorted.
  string | : The `"primary"` value is also valid.

  Click to display more

  ### Emit signals:

  - `property::screen` When the screen value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
  - `new_value` screen The new value affected to the property.
🔗 widget widget or nil · 1 signal
  The widget that the wibox displays.

  ### Constraints:

  Default value | : `nil`

  Click to display more

  ### Emit signals:

  - `property::widget` When the widget value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
  - `new_value` widget The new value affected to the property.
🔗 window string · 1 signal
  The X window id.

  ### Constraints:

  Default value | : Autogenerated.

  ### See also:

  client.window | The X window id. (client) | object properties

  Click to display more

  ### Emit signals:

  - `property::window` When the window value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 shape_bounding surface._native · 1 signal
  The wibox's bounding shape as a (native) cairo surface.

  If you want to set a shape, let say some rounded corners, use the shape property rather than this. If you want something very complex, for example, holes, then use this.

  ### Constraints:

  Default value | : Fill all pixels.

  ### See also:

  shape | The wibar's shape. | object properties

  Click to display more

  ### Emit signals:

  - `property::shape_bounding` When the shape_bounding value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 shape_clip surface._native · 1 signal
  The wibox's clip shape as a (native) cairo surface.

  The clip shape is the shape of the window *content* rather than the outer window shape.

  ### Constraints:

  Default value | : Fill all pixels.

  ### See also:

  shape | The wibar's shape. | object properties

  Click to display more

  ### Emit signals:

  - `property::shape_clip` When the shape_clip value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 shape_input surface._native · 1 signal
  The wibox's input shape as a (native) cairo surface.

  The input shape allows to disable clicks and mouse events on part of the window. This is how input_passthrough is implemented.

  ### Constraints:

  Default value | : Fill all pixels.

  ### See also:

  input_passthrough | Forward the inputs to the client below the wibox. | object properties

  Click to display more

  ### Emit signals:

  - `property::shape_input` When the shape_input value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 shape shape · 1 signal
  The wibar's shape.

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

  Click to display more

  ### Emit signals:

  - `property::shape` When the shape value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
  - `new_value` shape The new value affected to the property.
🔗 input_passthrough boolean · 1 signal
  Forward the inputs to the client below the wibox.

  This replace the shape_input mask with an empty area. All mouse and keyboard events are sent to the object (such as a client) positioned below this wibox. When used alongside compositing, it allows, for example, to have a subtle transparent wibox on top a fullscreen client to display important data such as a low battery warning.

  ### Constraints:

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

  ### See also:

  shape_input | The wibox's input shape as a (native) cairo surface. | object properties

  Click to display more

  ### Emit signals:

  - `property::input_passthrough` When the input_passthrough value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
  - `new_value` input_passthrough The new value affected to the property.
🔗 buttons table · 1 signal
  Get or set mouse buttons bindings to a wibox.

  ### Constraints:

  Default value | : `{}`
  Table content | : A list of awful.buttons.
  Valid values | : A table of buttons objects, or nothing.

  Click to display more

  ### Emit signals:

  - `property::buttons` When the buttons value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
🔗 bg color · 1 signal · 1 theme variable
  The background of the wibox.

  The background color can be transparent. If there is a compositing manager such as compton, then it will be real transparency and may include blur (provided by the compositor). When there is no compositor, it will take a picture of the wallpaper and blend it.

  ### Constraints:

  Default value | : `beautiful.bg_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)
  Valid values | : The background to use. This must either be a cairo pattern object, nil or a string that gears.color() understands.

  ### See also:

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

  Click to display more

  ### Emit signals:

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

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.bg_normal | The default (fallback) bg color.
  beautiful.bg_normal |

🔗 bgimage image or nil · 1 signal
  The background image of the drawable.

  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.

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

  gears.surface | Utilities to integrate and manipulate Cairo drawing surfaces. | module

  Click to display more

  ### Emit signals:

  - `property::bgimage` When the bgimage value changes.
  - `self` wibox The object which changed (useful when connecting many object to the same callback).
  - `new_value` bgimage The new value affected to the property.
🔗 fg color · 1 signal · 1 theme variable
  The foreground (text) of the wibox.

  ### Constraints:

  Default value | : `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

  Click to display more

  ### Emit signals:

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

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.fg_normal | The default (fallback) fg color.
  beautiful.fg_normal |

## Object methods

🔗 :geometry (geo) -> table · 1 signal
  Get or set wibox geometry. That's the same as accessing or setting the x, y, width or height properties of a wibox.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  geo | Optional | table or nil | A table with coordinates to modify. If nothing is specified, it only returns the current geometry. | `nil`

  ### Returns:

  table A table with wibox coordinates and geometry.
  Click to display more

  ### Emit signals:

  - `property::geometry` When the geometry change.
  - `geo` table The geometry table.
🔗 :struts (struts) -> () · 1 signal
  Get or set wibox struts.

  Struts are the area which should be reserved on each side of the screen for this wibox. This is used to make bars and docked displays. Note that awful.wibar implements all the required boilerplate code to make bar. Only use this if you want special type of bars (like bars not fully attached to the side of the screen).

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  struts |  | table | A table with new strut, or nothing.

  ### Returns:

  The wibox strut in a table.

  ### See also:

  client.struts | Return client struts (reserved space at the edge of the screen). (client) | object methods

  Click to display more

  ### Emit signals:

  - `property::struts`
🔗 :setup {[args]}
  Set a declarative widget hierarchy description. See [The declarative layout system](../documentation/03-declarative-layout.md.html)

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  args |  |  | An array containing the widgets disposition

🔗 :find_widgets (x, y) -> table
  Find a widget by a point. The wibox must have drawn itself at least once for this to work.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  x |  | number | X coordinate of the point
  y |  | number | Y coordinate of the point

  ### Returns:

  table A sorted table of widgets positions. The first element is the biggest container while the last is the topmost widget. The table contains *x*, *y*, *width*, *height* and *widget*.
🔗 :to_widget () -> widget
  Create a widget that reflects the current state of this wibox.

  ### Returns:

  widget A new widget.
🔗 :save_to_svg (path, context)
  Save a screenshot of the wibox to `path`.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  path |  | string | The path. | Not applicable
  context | Optional | table | A widget context. | `nil`

🔗 :draw (wibox)
  Redraw a wibox. You should never have to call this explicitely because it is automatically called when needed.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  wibox |  |  |

generated by LDoc 1.5.0