Module: awful.wibar

The main AwesomeWM "bar" module.

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

local wb = awful.wibar { position = "top" }
wb:setup {
    layout = wibox.layout.align.horizontal,
    {
        mytaglist,
        layout = wibox.layout.fixed.horizontal,
    },
    mytasklist,
    {
        layout = wibox.layout.fixed.horizontal,
        mykeyboardlayout,
        mytextclock,
    },
}

You can even have vertical bars too.

local wb = awful.wibar { position = "left" }
wb:setup {
    layout = wibox.layout.align.vertical,
    {
        -- Rotate the widgets with the container
        {
            mytaglist,
            direction = 'west',
            widget = wibox.container.rotate
        },
        layout = wibox.layout.fixed.vertical,
    },
    mytasklist,
    {
        layout = wibox.layout.fixed.vertical,
        {
            -- Rotate the widgets with the container
            {
                mykeyboardlayout,
                mytextclock,
                layout = wibox.layout.fixed.horizontal
            },
            direction = 'west',
            widget = wibox.container.rotate
        }
    },
}

Class Hierarchy

Info:

Constructors

awful.wibar {[args]} Create a new wibox and attach it to a screen edge.

Object properties

stretch boolean or nil If the wibar needs to be stretched to fill the screen.
align string or nil How to align non-stretched wibars.
margins number or table or nil Margins on each side of the wibar.
restrict_workarea boolean Allow or deny the tiled clients to cover the wibar.
position string The wibox position.
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

Object methods

:remove () Remove a wibar.
: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

Theme variables

beautiful.wibar_stretch boolean If the wibar needs to be stretched to fill the screen.
beautiful.wibar_favor_vertical boolean If there is both vertical and horizontal wibar, give more space to vertical ones.
beautiful.wibar_border_width integer The wibar border width.
beautiful.wibar_border_color string The wibar border color.
beautiful.wibar_ontop boolean If the wibar is to be on top of other windows.
beautiful.wibar_cursor string The wibar's mouse cursor.
beautiful.wibar_opacity number The wibar opacity, between 0 and 1.
beautiful.wibar_type string The window type (desktop, normal, dock, …).
beautiful.wibar_width integer The wibar's width.
beautiful.wibar_height integer The wibar's height.
beautiful.wibar_bg color The wibar's background color.
beautiful.wibar_bgimage surface The wibar's background image.
beautiful.wibar_fg color The wibar's foreground (text) color.
beautiful.wibar_shape gears.shape The wibar's shape.
beautiful.wibar_margins number or table The wibar's margins.
beautiful.wibar_align string The wibar's alignments.

Deprecated functions

awful.wibar.attach (wb, position, screen) Attach a wibox to a screen. Deprecated
awful.wibar.align (wb, align, screen) Align a wibox. Deprecated
awful.wibox.stretch () Stretch a wibox so it takes all screen width or height. Deprecated


Constructors

🔗 awful.wibar {[args]} · 13 theme variables
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.

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 awful.wibar{}. This is a Lua shortcut syntax equivalent to awful.wibar({}). 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
position string The position. Not applicable
stretch string If the wibar need to be stretched to fill the screen. Not applicable
restrict_workarea boolean Allow or deny the tiled clients to cover the wibar. Not applicable
align string How to align non-stretched wibars. Not applicable
margins table or number The wibar margins. 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

Returns:

    The new wibar

See also:

wibox Box where widget can be displayed. module

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.wibar_favor_vertical
beautiful.wibar_border_width
beautiful.wibar_border_color
beautiful.wibar_ontop
beautiful.wibar_cursor
beautiful.wibar_opacity
beautiful.wibar_type
beautiful.wibar_width
beautiful.wibar_height
beautiful.wibar_bg
beautiful.wibar_bgimage
beautiful.wibar_fg
beautiful.wibar_shape

Object properties

🔗 stretch boolean or nil · 1 signal · 1 theme variable
If the wibar needs to be stretched to fill the screen.

Constraints:

Default value : true
Type description:
nil : Fallback to the current value of beautiful.wibar_stretch.

See also:

align How to align non-stretched wibars. object properties

Usage:

    awful.wibar {
        position = "top",
        screen   = screen[1],
        stretch  = true,
        width    = 196,
        widget   = {
            text   = "stretched",
            halign = "center",
            widget = wibox.widget.textbox
        },
    }
    
    awful.wibar {
        position = "top",
        screen   = screen[2],
        stretch  = false,
        width    = 196,
        widget   = {
            text   = "not stretched",
            align  = "center",
            widget = wibox.widget.textbox
        },
    }

Click to display more

Emit signals:

  • property::stretch When the stretch value changes.
    • self awful.wibar The object which changed (useful when connecting many object to the same callback).
    • new_value stretch The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.wibar_stretchFallback when stretch isn't set.
🔗 align string or nil · 1 signal · 1 theme variable
How to align non-stretched wibars.

Constraints:

Default value : "centered"
Type description:
nil : Fallback to the current value of beautiful.wibar_align.
Valid values:
"top"
"bottom"
"left"
"right"
"centered"

See also:

stretch If the wibar needs to be stretched to fill the screen. object properties

Usage:

    for s, align in ipairs { "left", "centered", "right" } do
        awful.wibar {
            position = "top",
            screen   = screen[s],
            stretch  = false,
            width    = 196,
            align    = align,
            widget   = {
                text   = align,
                halign = "center",
                widget = wibox.widget.textbox
            },
        }
    end
    
    for s, align in ipairs { "top", "centered", "bottom" } do
        awful.wibar {
            position = "left",
            screen   = screen[s+3],
            stretch  = false,
            height   = 128,
            align    = align,
            widget   = {
                {
                    text   = align,
                    align  = "center",
                    widget = wibox.widget.textbox
                },
                direction = "east",
                widget    = wibox.container.rotate
            },
        }
    end

Click to display more

Emit signals:

  • property::align When the align value changes.
    • self awful.wibar The object which changed (useful when connecting many object to the same callback).
    • new_value align The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.wibar_alignFallback when align isn't set.
🔗 margins number or table or nil · 1 signal · 1 theme variable
Margins on each side of the wibar.

It can either be a table with top, bottom, left and right properties, or a single number that applies to all four sides.

Constraints:

Default value : 0
Type description:
number : A single value for each side.
table: : A different value for each side.
left (number)
right (number)
top (number)
bottom (number)
nil : Fallback to beautiful.wibar_margins.
Unit : pixel
Negative allowed : true

Usage:

    awful.wibar {
        position = "top",
        screen   = screen[1],
        stretch  = false,
        width    = 196,
        margins  = 24,
        widget   = {
            halign = "center",
            text   = "unform margins",
            widget = wibox.widget.textbox
        }
    }
    
    awful.wibar {
        position = "top",
        screen   = screen[2],
        stretch  = false,
        width    = 196,
        margins = {
            top    = 12,
            bottom = 5
        },
        widget   = {
            halign = "center",
            text   = "non unform margins",
            widget = wibox.widget.textbox
        }
    }

Click to display more

Emit signals:

  • property::margins When the margins value changes.
    • self awful.wibar The object which changed (useful when connecting many object to the same callback).
    • new_value margins The new value affected to the property.

Consumed theme variables:

Theme variable Usage
beautiful.wibar_marginsFallback when margins isn't set.
🔗 restrict_workarea boolean · 1 signal
Allow or deny the tiled clients to cover the wibar.

In the example below, we can see that the first screen workarea shrunk by the height of the wibar while the second screen is unchanged.

Constraints:

Default value : true
Valid values : true or false.

See also:

client.struts Return client struts (reserved space at the edge of the screen). (client) object methods
screen.workarea The screen workarea. (screen) object properties

Usage:

    local screen1_wibar = awful.wibar {
        position          = "top",
        restrict_workarea = true,
        height            = 24,
        screen            = screen[1],
    }
    
    local screen2_wibar = awful.wibar {
        position          = "top",
        restrict_workarea = false,
        height            = 24,
        screen            = screen[2],
    }

Click to display more

Emit signals:

  • property::restrict_workarea When the restrict_workarea value changes.
    • self awful.wibar The object which changed (useful when connecting many object to the same callback).
    • new_value restrict_workarea The new value affected to the property.
🔗 position string · 1 signal

The wibox position.

local colors = {
    top    = "#ffff00",
    bottom = "#ff00ff",
    left   = "#00ffff",
    right  = "#ffcc00"
}

for _, position in ipairs { "top", "bottom", "left", "right" } do
    awful.wibar {
        position = position,
        bg       = colors[position],
        widget   = {
            {
                text   = position,
                halign = "center",
                widget = wibox.widget.textbox
            },
            direction = (position == "left" or position == "right") and
                "east" or "north",
            widget    = wibox.container.rotate
        },
    }
end

Constraints:

Default value : "top"
Valid values:
"left"
"right"
"top"
"bottom"

Click to display more

Emit signals:

  • property::position When the position value changes.
    • self awful.wibar The object which changed (useful when connecting many object to the same callback).
    • new_value position The new value affected to the property.
🔗 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
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.
cairo.pattern : Any valid Cairo pattern.
cairo.pattern : A texture build from an image by gears.color.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_normalThe 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.
cairo.pattern : Any valid Cairo pattern.
cairo.pattern : A texture build from an image by gears.color.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_normalThe default (fallback) fg color.
beautiful.fg_normal

Object methods

🔗 :remove ()
Remove a wibar.
🔗 :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

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

Theme variables

🔗 beautiful.wibar_stretch boolean
If the wibar needs to be stretched to fill the screen.
Click to display more

Used by:

  • stretch If the wibar needs to be stretched to fill the screen.
🔗 beautiful.wibar_favor_vertical boolean
If there is both vertical and horizontal wibar, give more space to vertical ones.

By default, if multiple wibars risk overlapping, it will be resolved by giving more space to the horizontal one:

wibar position

If this variable is to to true, it will behave like:


Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_border_width integer
The wibar border width.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_border_color string
The wibar border color.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_ontop boolean
If the wibar is to be on top of other windows.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_cursor string
The wibar's mouse cursor.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_opacity number
The wibar opacity, between 0 and 1.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_type string
The window type (desktop, normal, dock, …).
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_width integer
The wibar's width.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_height integer
The wibar's height.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_bg color
The wibar's background color.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_bgimage surface
The wibar's background image.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_fg color
The wibar's foreground (text) color.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_shape gears.shape
The wibar's shape.
Click to display more

Used by:

  • awful.wibar Create a new wibox and attach it to a screen edge.
🔗 beautiful.wibar_margins number or table
The wibar's margins.
Click to display more

Used by:

  • margins Margins on each side of the wibar.
🔗 beautiful.wibar_align string
The wibar's alignments.
Click to display more

Used by:

  • align How to align non-stretched wibars.

Deprecated functions

🔗 awful.wibar.attach (wb, position, screen)
Attach a wibox to a screen.

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

Parameters:

Name Type(s) Description
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 Algorithms used to place various drawables. module
🔗 awful.wibar.align (wb, align, screen)

Align a wibox.

Supported alignment are:

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

Parameters:

Name Type(s) Description
wb The wibox.
align The alignment
screen This argument is deprecated. It is not used. Use wb.screen directly.

See also:

awful.placement.align Move the drawable (client or wibox) d to a screen position or side. (awful.placement) static module functions
🔗 awful.wibox.stretch ()
Stretch a wibox so it takes all screen width or height.

This function has been removed.

See also:

awful.placement Algorithms used to place various drawables. module
awful.wibar.stretch If the wibar needs to be stretched to fill the screen. object properties
generated by LDoc 1.5.0