# Class `awful.wibar`

Wibox module for awful.

This module allows you to easily create wibox and attach them to the edge of a screen.

### Info:

- Copyright: 2016 Emmanuel Lepage Vallee
- Author: Emmanuel Lepage Vallee <elv1313@gmail.com>

## Functions

awful.wibar ([arg=nil]) | Create a new wibox and attach it to a screen edge.

## Object properties

awful.wibar.position | The wibox position.
awful.wibar.stretch | Stretch the wibar.
awful.wibar.border_width | Border width.
awful.wibar.border_color | Border color.
awful.wibar.ontop | On top of other windows.
awful.wibar.cursor | The mouse cursor.
awful.wibar.visible | Visibility.
awful.wibar.opacity | The opacity of the wibox, between 0 and 1.
awful.wibar.type | The window type (desktop, normal, dock, ...).
awful.wibar.x | The x coordinates.
awful.wibar.y | The y coordinates.
awful.wibar.width | The width of the wibox.
awful.wibar.height | The height of the wibox.
awful.wibar.screen | The wibox screen.
awful.wibar.drawable | The wibox's drawable.
awful.wibar.widget | The widget that the wibox displays.
awful.wibar.window | The X window id.
awful.wibar.shape_bounding | The wibox's bounding shape as a (native) cairo surface.
awful.wibar.shape_clip | The wibox's clip shape as a (native) cairo surface.
awful.wibar.bg | The background of the wibox.
awful.wibar.bgimage | The background image of the drawable.
awful.wibar.fg | The foreground (text) of the wibox.

## Theme variables

beautiful.bg_normal | The default background color.
beautiful.fg_normal | The default foreground (text) color.

## Deprecated functions

awful.wibar.get_position | Get a wibox position if it has been set, or return top.
awful.wibar.set_position | Put a wibox on a screen at this position.
awful.wibar.attach | Attach a wibox to a screen.
awful.wibar.align | Align a wibox.
awful.wibox.stretch | Stretch a wibox so it takes all screen width or height.

## Methods

awful.wibar:remove () | Remove a wibar.
awful.wibar:buttons (buttons_table) | Get or set mouse buttons bindings to a wibox.
awful.wibar:geometry (A) | Get or set wibox geometry.
awful.wibar:struts (strut) | Get or set wibox struts.
awful.wibar:setup (args) | Set a declarative widget hierarchy description.
awful.wibar:find_widgets (x, y) | Find a widget by a point.

## Functions

Methods

awful.wibar ([arg=nil])
  Create a new wibox and attach it to a screen edge. You can add also position key with value top, bottom, left or right. You can also use width or height in % and set align to center, right or left. You can also set the screen key with a screen number to attach the wibox. If not specified, the primary screen is assumed.
  - arg
    - position string The position.
    - stretch string If the wibar need to be stretched to fill the screen.
    - border_width integer Border width.
    - border_color string Border color.
    - ontop boolean On top of other windows.
    - cursor string 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 wibox.widget The widget that the wibox displays.
    - shape_bounding The wibox’s bounding shape as a (native) cairo surface.
    - shape_clip The wibox’s clip shape as a (native) cairo surface.
    - bg color The background of the wibox.
    - bgimage surface The background image of the drawable.
    - fg color The foreground (text) of the wibox.

  ### Returns:

  The new wibar

  ### See also:

  wibox

## Object properties

awful.wibar.position
  The wibox position.

  ### Type:

  - string Either "left", right", "top" or "bottom"
awful.wibar.stretch
  Stretch the wibar.

  ### Type:

  - boolean (default true)
awful.wibar.border_width

  Border width.

  Signal:

  - *property::border_width*

  ### Type:

  - integer
awful.wibar.border_color

  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

  Signal:

  - *property::border_color*

  ### Type:

  - string
awful.wibar.ontop

  On top of other windows.

  Signal:

  - property::ontop

  ### Type:

  - boolean
awful.wibar.cursor

  The mouse cursor.

  Signal:

  - property::cursor

  ### Type:

  - string

  ### See also:

  mouse
awful.wibar.visible

  Visibility.

  Signal:

  - property::visible

  ### Type:

  - boolean
awful.wibar.opacity

  The opacity of the wibox, between 0 and 1.

  Signal:

  - property::opacity

  ### Type:

  - opacity number (between 0 and 1)
awful.wibar.type

  The window type (desktop, normal, dock, ...).

  Signal:

  - property::type

  ### Type:

  - string

  ### See also:

  client.type
awful.wibar.x

  The x coordinates.

  Signal:

  - property::x

  ### Type:

  - integer
awful.wibar.y

  The y coordinates.

  Signal:

  - property::y

  ### Type:

  - integer
awful.wibar.width

  The width of the wibox.

  Signal:

  - property::width

  ### Type:

  - width
awful.wibar.height

  The height of the wibox.

  Signal:

  - property::height

  ### Type:

  - height
awful.wibar.screen
  The wibox screen.

  ### Type:

  - screen
awful.wibar.drawable

  The wibox's drawable.

  Signal:

  - property::drawable

  ### Type:

  - drawable drawable
awful.wibar.widget
  The widget that the wibox displays.

  ### Type:

  - widget
awful.wibar.window

  The X window id.

  Signal:

  - property::window

  ### Type:

  - string

  ### See also:

  client.window
awful.wibar.shape_bounding

  The wibox's bounding shape as a (native) cairo surface.

  Signal:

  - *property::shape_bounding*
awful.wibar.shape_clip

  The wibox's clip shape as a (native) cairo surface.

  Signal:

  - *property::shape_clip*
awful.wibar.bg
  The background of the wibox.

  ### Type:

  - c The background to use. This must either be a cairo pattern object, nil or a string that gears.color() understands.

  ### See also:

  gears.color
awful.wibar.bgimage
  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.

  ### Type:

  - image A background image or a function

  ### See also:

  gears.surface
awful.wibar.fg
  The foreground (text) of the wibox.

  ### Type:

  - c The foreground to use. This must either be a cairo pattern object, nil or a string that gears.color() understands.

  ### See also:

  gears.color

## Theme variables

beautiful.bg_normal
  The default background color.

  ### See also:

  bg
beautiful.fg_normal
  The default foreground (text) color.

  ### See also:

  fg

## Deprecated functions

awful.wibar.get_position
  Get a wibox position if it has been set, or return top.

  ### param:

  - wb The wibox
awful.wibar.set_position
  Put a wibox on a screen at this position.

  ### param:

  - wb The wibox to attach.
  - position The position: top, bottom left or right.
  - screen This argument is deprecated, use wb.screen directly.
awful.wibar.attach
  Attach a wibox to a screen.

  This function has been moved to the awful.placement module. Calling this no longer does anything.

  ### param:

  - wb The wibox to attach.
  - position The position of the wibox: top, bottom, left or right.
  - screen The screen to attach to

  ### See also:

  awful.placement
awful.wibar.align

  Align a wibox.

  Supported alignment are:

  - top_left
  - top_right
  - bottom_left
  - bottom_right
  - left
  - right
  - top
  - bottom
  - centered
  - center_vertical
  - center_horizontal

  ### param:

  - wb The wibox.
  - align The alignment
  - screen This argument is deprecated. It is not used. Use wb.screen directly.

  ### See also:

  awful.placement.align
awful.wibox.stretch
  Stretch a wibox so it takes all screen width or height.

  This function has been removed.

  ### See also:

  - awful.placement
  - awful.wibar.stretch

## Methods

awful.wibar:remove ()
  Remove a wibar.
awful.wibar:buttons (buttons_table)
  Get or set mouse buttons bindings to a wibox.
  - buttons_table A table of buttons objects, or nothing.
awful.wibar:geometry (A)
  Get or set wibox geometry. That's the same as accessing or setting the x, y, width or height properties of a wibox.
  - A table with coordinates to modify.

  ### Returns:

  A table with wibox coordinates and geometry.
awful.wibar:struts (strut)
  Get or set wibox struts.
  - strut A table with new strut, or nothing

  ### Returns:

  The wibox strut in a table.

  ### See also:

  client.struts
awful.wibar:setup (args)
  Set a declarative widget hierarchy description. See The declarative layout system
  - args An array containing the widgets disposition
awful.wibar:find_widgets (x, y)
  Find a widget by a point. The wibox must have drawn itself at least once for this to work.
  - 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.

generated by LDoc 1.4.6 Last updated 2017-01-20 01:17:18