# Module: `naughty.layout.box`

A notification popup widget.

By default, the box is composed of many other widgets:

### Class Hierarchy

- wibox
- - awful.popup
  - - naughty.layout.box

### Info:

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

## Constructors

naughty.layout.box {[args]} | Create a notification popup box. |

## Object properties

notification | naughty.notification | The widget notification object. |
widget_template | template or nil | The widget template to construct the box content. |
preferred_positions | table or string | Set the preferred popup position relative to its parent. | Inherited from awful.popup
preferred_anchors | table or string | Set the preferred popup anchors relative to the parent. | Inherited from awful.popup
current_position | string | The current position relative to the parent object. | Read only Inherited from awful.popup
current_anchor | string | Get the current anchor relative to the parent object. | Read only Inherited from awful.popup
hide_on_right_click | boolean | Hide the popup when right clicked. | Inherited from awful.popup
minimum_width | integer | The popup minimum width. | Inherited from awful.popup
minimum_height | integer | The popup minimum height. | Inherited from awful.popup
maximum_width | integer | The popup maximum width. | Inherited from awful.popup
maximum_height | integer | The popup maximum height. | Inherited from awful.popup
offset | table or integer | The distance between the popup and its parent (if any). | Inherited from awful.popup
placement | placement or string or boolean | Set the placement function. | Inherited from awful.popup
border_width | integer | Border width. | Inherited from wibox
border_color | string | Border color. | Inherited from wibox
ontop | boolean | On top of other windows. | Inherited from wibox
cursor | string or nil | The mouse cursor. | Inherited from wibox
visible | boolean | Visibility. | Inherited from wibox
opacity | number | The opacity of the wibox, between 0 and 1. | Inherited from wibox
type | string | The window type (desktop, normal, dock, ...). | Inherited from wibox
x | integer | The x coordinates. | Inherited from wibox
y | integer | The y coordinates. | Inherited from wibox
width | integer | The width of the wibox. | Inherited from wibox
height | integer | The height of the wibox. | Inherited from wibox
screen | screen | The wibox screen. | Inherited from wibox
widget | widget or nil | The widget that the wibox displays. | Inherited from wibox
window | string | The X window id. | Inherited from wibox
shape_bounding | surface._native | The wibox's bounding shape as a (native) cairo surface. | Inherited from wibox
shape_clip | surface._native | The wibox's clip shape as a (native) cairo surface. | Inherited from wibox
shape_input | surface._native | The wibox's input shape as a (native) cairo surface. | Inherited from wibox
shape | shape | The wibar's shape. | Inherited from wibox
input_passthrough | boolean | Forward the inputs to the client below the wibox. | Inherited from wibox
buttons | table | Get or set mouse buttons bindings to a wibox. | Inherited from wibox
bg | color | The background of the wibox. | Inherited from wibox
bgimage | image or nil | The background image of the drawable. | Inherited from wibox
fg | color | The foreground (text) of the wibox. | Inherited from wibox

## Theme variables

beautiful.notification_max_width | number | The maximum notification width. |
beautiful.notification_position | string | The maximum notification position. |

## Object methods

:move_next_to (obj) -> table | Move the wibox to a position relative to `geo`. | Inherited from awful.popup
:bind_to_widget (widget, button) | Bind the popup to a widget button press. | Inherited from awful.popup
:unbind_to_widget (widget) | Unbind the popup from a widget button. | Inherited from awful.popup
:geometry (geo) -> table | Get or set wibox geometry. | Inherited from wibox
:struts (struts) -> () | Get or set wibox struts. | Inherited from wibox
:setup {[args]} | Set a declarative widget hierarchy description. | Inherited from wibox
:find_widgets (x, y) -> table | Find a widget by a point. | Inherited from wibox
:to_widget () -> widget | Create a widget that reflects the current state of this wibox. | Inherited from wibox
:save_to_svg (path, context) | Save a screenshot of the wibox to `path`. | Inherited from wibox
:draw (wibox) | Redraw a wibox. | Inherited from wibox

## Constructors

🔗 naughty.layout.box {[args]} · 1 theme variable
  Create a notification popup box.

  ### 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.layout.box{}`. This is a Lua shortcut syntax equivalent to `naughty.layout.box({})`. `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`
  widget_template |  | table | A widget definition template which will be instantiated for each box. | Not applicable
  notification |  | naughty.notification | The notification object. | Not applicable
  position |  | string | The position. See naughty.notification.position. | Not applicable
  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`

  Click to display more

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_position | If `position` is not defined in the notification object (or in this constructor).

## Object properties

🔗 notification naughty.notification · 1 signal
  The widget notification object.

  ### Constraints:

  Default value | : This must be provided by the constructor.

  Click to display more

  ### Emit signals:

  - `property::notification` When the notification value changes.
  - `self` naughty.layout.box The object which changed (useful when connecting many object to the same callback).
  - `new_value` notification The new value affected to the property.
🔗 widget_template template or nil · 1 theme variable
  The widget template to construct the box content.

  The default template is (less or more):

  { { { { { naughty.widget.icon, { naughty.widget.title, naughty.widget.message, spacing = 4, layout = wibox.layout.fixed.vertical, }, fill_space = true, spacing = 4, layout = wibox.layout.fixed.horizontal, }, naughty.list.actions, spacing = 10, layout = wibox.layout.fixed.vertical, }, margins = beautiful.notification_margin, widget = wibox.container.margin, }, id = "background_role", widget = naughty.container.background, }, strategy = "max", width = width(beautiful.notification_max_width or beautiful.xresources.apply_dpi(500)), widget = wibox.container.constraint, }

  ### Constraints:

  Default value | : `nil`
  Type description:
  table | : A table containing a widget tree definition. WARNING: This is really a table and **NOT** a widget object. Use the `widget = come.class.here` to define the topmost class rather than construct an instance.

  Click to display more

  ### Consumed theme variables:

  Theme variable | Usage
  --- | ---
  beautiful.notification_max_width | The maximum width for the resulting widget.

🔗 preferred_positions table or string · Inherited from awful.popup · 1 signal
  Set the preferred popup position relative to its parent.

  This allows, for example, to have a submenu that goes on the right of the parent menu. If there is no space on the right, it tries on the left and so on.

  The basic use case for this method is to give it a parent wibox:

  for _, v in ipairs {"left", "right", "bottom", "top"} do local p2 = awful.popup { widget = wibox.widget { text = "On the "..v, widget = wibox.widget.textbox }, border_color = "#777777", border_width = 2, preferred_positions = v, ontop = true, } p2:move_next_to(p) end

  As demonstrated by this second example, it is also possible to use a widget as a parent object:

  for _, v in ipairs {"left", "right"} do local p2 = awful.popup { widget = wibox.widget { text = "On the "..v, forced_height = 100, widget = wibox.widget.textbox }, border_color = "#0000ff", preferred_positions = v, border_width = 2, } p2:move_next_to(textboxinstance, v) end

  ### Constraints:

  Default value | : `{ "right", "left", "top", "bottom" }`
  Type description:
  string | : A single position with no fallback. It will be used even if it doesn't fit.
  table | : A list of possible positions. The first one to fit will be used.
  Valid values:
  `"left"`
  `"right"`
  `"top"`
  `"bottom"`

  ### See also:

  awful.placement.next_to | Move a drawable to a relative position next to another one. (awful.placement) | static module functions
  awful.popup.preferred_anchors | Set the preferred popup anchors relative to the parent. | object properties

  Click to display more

  ### Emit signals:

  - `property::preferred_positions` When the `preferred_positions` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `preferred_positions` The new value affected to the property.
🔗 preferred_anchors table or string · Inherited from awful.popup · 1 signal
  Set the preferred popup anchors relative to the parent.

  For details information, see the awful.placement.next_to documentation.

  In this example, it is possible to see the effect of having a fallback preferred anchors when the popup would otherwise not fit:

  local p2 = awful.popup { widget = wibox.widget { text = "A popup", forced_height = 100, widget = wibox.widget.textbox }, border_color = "#777777", border_width = 2, preferred_positions = "right", preferred_anchors = {"front", "back"}, } local p4 = awful.popup { widget = wibox.widget { text = "A popup2", forced_height = 100, widget = wibox.widget.textbox }, border_color = "#777777", border_width = 2, preferred_positions = "right", preferred_anchors = {"front", "back"}, }

  ### Constraints:

  Default value | : `"back"`
  Type description:
  string | : A single anchor value with no fallback.
  table | : A list of possible anchor, the first one has the higher priority, but will fallback if it doesn't fit.
  Valid values: | : ordered by priority.
  `"front"`
  `"middle"`
  `"back"`

  ### See also:

  awful.placement.next_to | Move a drawable to a relative position next to another one. (awful.placement) | static module functions
  awful.popup.preferred_positions | Set the preferred popup position relative to its parent. | object properties

  Click to display more

  ### Emit signals:

  - `property::preferred_anchors` When the `preferred_anchors` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `preferred_anchors` The new value affected to the property.
🔗 current_position string · Inherited from awful.popup · read only
  The current position relative to the parent object.

  If there is a parent object (widget, wibox, wibar, client or the mouse), then this property returns the current position. This is determined using `preferred_positions`. It is usually the preferred position, but when there isn't enough space, it can also be one of the fallback.

  ### Constraints:

  Default value | : This depends on where the popup was displayed.
  Valid values:
  `"left"`
  `"right"`
  `"top"`
  `"bottom"`

  ### See also:

  awful.popup.preferred_positions | Set the preferred popup position relative to its parent. | object properties

🔗 current_anchor string · Inherited from awful.popup · read only
  Get the current anchor relative to the parent object.

  If there is a parent object (widget, wibox, wibar, client or the mouse), then this property returns the current anchor. The anchor is the "side" of the parent object on which the popup is based on. It will "grow" in the opposite direction from the anchor.

  ### Constraints:

  Default value | : This depends on where the popup was displayed.
  Valid values:
  `"front"`
  `"middle"`
  `"back"`

  ### See also:

  awful.popup.preferred_anchors | Set the preferred popup anchors relative to the parent. | object properties

🔗 hide_on_right_click boolean · Inherited from awful.popup · 1 signal
  Hide the popup when right clicked.

  ### Constraints:

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

  Click to display more

  ### Emit signals:

  - `property::hide_on_right_click` When the `hide_on_right_click` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `hide_on_right_click` The new value affected to the property.
🔗 minimum_width integer · Inherited from awful.popup · 1 signal
  The popup minimum width.

  ### Constraints:

  Default value | : `1`
  Unit | : pixel
  Minimum value | : 1

  Click to display more

  ### Emit signals:

  - `property::minimum_width` When the `minimum_width` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `minimum_width` The new value affected to the property.
🔗 minimum_height integer · Inherited from awful.popup · 1 signal
  The popup minimum height.

  ### Constraints:

  Default value | : `1`
  Unit | : pixel
  Minimum value | : 1

  Click to display more

  ### Emit signals:

  - `property::minimum_height` When the `minimum_height` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `minimum_height` The new value affected to the property.
🔗 maximum_width integer · Inherited from awful.popup · 1 signal
  The popup maximum width.

  ### Constraints:

  Default value | : `1`
  Unit | : pixel
  Minimum value | : 1

  Click to display more

  ### Emit signals:

  - `property::maximum_width` When the `maximum_width` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `maximum_width` The new value affected to the property.
🔗 maximum_height integer · Inherited from awful.popup · 1 signal
  The popup maximum height.

  ### Constraints:

  Default value | : `1`
  Unit | : pixel
  Minimum value | : 1

  Click to display more

  ### Emit signals:

  - `property::maximum_height` When the `maximum_height` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `maximum_height` The new value affected to the property.
🔗 offset table or integer · Inherited from awful.popup · 1 signal
  The distance between the popup and its parent (if any).

  Here is an example of 5 popups stacked one below the other with an y axis offset (spacing).

  local previous = nil for i=1, 5 do local p2 = awful.popup { widget = wibox.widget { text = "Hello world! "..i.." aaaa.", widget = wibox.widget.textbox }, border_color = beautiful.border_color, preferred_positions = "bottom", border_width = 2, preferred_anchors = "back", placement = (not previous) and awful.placement.top or nil, offset = { y = 10, }, } p2:move_next_to(previous) previous = p2 end

  ### Constraints:

  Default value | : `0`
  Type description:
  integer | : A value for both `x` and `y` simultaneously.
  table: | : Specify values for `x` and `y` individually.
  x (integer) | : The horizontal offset.
  y (integer) | : The vertical offset.
  Unit | : pixel
  Negative allowed | : true

  Click to display more

  ### Emit signals:

  - `property::offset` When the `offset` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `offset` The new value affected to the property.
🔗 placement placement or string or boolean · Inherited from awful.popup · 1 signal
  Set the placement function.

  ### Constraints:

  Default value | : `awful.placement.next_to`
  Type description:
  boolean | : Use `false` to disable automatic placement.
  string | : The name of an awful.placement function, like `"next_to"`.
  function: | : A custom callback to generate *and set* the geometry.
  Function prototype:
  Parameters:
  obj (object) | : Any object with a `geometry` property or method.
  args (table) | : The `placement` arguments. See awful.placement for a complete list.
  Return (table) | : A table with an `x`, `y`, `width` and `height` keys.
  placement | : Any of the awful.placement function or constructs.

  ### See also:

  awful.placement | Algorithms used to place various drawables. | module

  Click to display more

  ### Emit signals:

  - `property::placement` When the `placement` value changes.
  - `self` awful.popup The object which changed (useful when connecting many object to the same callback).
  - `new_value` `placement` The new value affected to the property.
🔗 border_width integer · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 · Inherited from wibox · 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 |

## Theme variables

🔗 beautiful.notification_max_width number
  The maximum notification width.
  Click to display more

  ### Used by:

  - widget_template The widget template to construct the box content.
  - `max_width` The maximum popup width.
🔗 beautiful.notification_position string
  The maximum notification position.

  Valid values are:

  * top_left * top_middle * top_right * bottom_left * bottom_middle * bottom_right

  Click to display more

  ### Used by:

  - naughty.layout.box Create a notification popup box.
  - `position` Corner of the workarea displaying the popups.
  - `position` Corner of the workarea displaying the popups.

## Object methods

🔗 :move_next_to (obj) -> table · Inherited from awful.popup
  Move the wibox to a position relative to `geo`. This will try to avoid overlapping the source wibox and auto-detect the right direction to avoid going off-screen.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  obj | Optional |  | An object such as a wibox, client or a table entry returned by `wibox:find_widgets()`. | `mouse`

  ### Returns:

  table The new geometry

  ### See also:

  awful.placement.next_to | Move a drawable to a relative position next to another one. (awful.placement) | static module functions
  awful.popup.preferred_positions | Set the preferred popup position relative to its parent. | object properties
  awful.popup.preferred_anchors | Set the preferred popup anchors relative to the parent. | object properties

🔗 :bind_to_widget (widget, button) · Inherited from awful.popup
  Bind the popup to a widget button press.

  ### Parameters:

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  widget |  | widget | The widget | Not applicable
  button | Optional | number | The button index | `1`

🔗 :unbind_to_widget (widget) · Inherited from awful.popup
  Unbind the popup from a widget button.

  ### Parameters:

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

🔗 :geometry (geo) -> table · Inherited from wibox · 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) -> () · Inherited from wibox · 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]} · Inherited from wibox
  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 · Inherited from wibox
  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 · Inherited from wibox
  Create a widget that reflects the current state of this wibox.

  ### Returns:

  widget A new widget.
🔗 :save_to_svg (path, context) · Inherited from wibox
  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) · Inherited from 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