Module: wibox.container.border

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

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

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

Advanced usage

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

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

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

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

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

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

Class Hierarchy

Info:

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

Object properties

widget widget or nil The widget to display inside of the border.
border_image string or image or nil A single border image for the border.
slice boolean Sice the border_image to fit the content.
border_image_stylesheet string Set a stylesheet for the slice surface.
image_scaling_quality string How the border_image(s) are scaled.
border_images table or image or nil Use images for each of the side/corner/filling sections.
borders table or number The size of the border on each side.
sides_fit_policy string How the sliced image is resized for the border sides.
filling_fit_policy string How the sliced image is resized for the border filling.
corners_fit_policy string How the sliced image is resized for the border corners.
honor_borders boolean Stretch the child widget over the entire area.
ontop boolean Draw the child widget below or on top of the border.
fill boolean Use the center portion of the border_image as a background.
paddings number or table Add some space between the border and the inner widget.
border_widgets table or nil Use individual widgets as a border.
border_merging table or nil Merge the corners widgets into the side widgets.
expand_corners boolean When border_widgets is used, allow the border to grow due to corner widgets.
children table Get or set the children elements. Inherited from wibox.widget.base
all_children table Get all direct and indirect children widgets. Inherited from wibox.widget.base
forced_height number or nil Force a widget height. Inherited from wibox.widget.base
forced_width number or nil Force a widget width. Inherited from wibox.widget.base
opacity number The widget opacity (transparency). Inherited from wibox.widget.base
visible boolean The widget visibility. Inherited from wibox.widget.base
buttons table The widget buttons. Inherited from wibox.widget.base

Object methods

:reset () Reset this layout.
:add_button (button) Add a new awful.button to this widget. Inherited from wibox.widget.base
:emit_signal_recursive (signal_name, ...) Emit a signal and ensure all parent widgets in the hierarchies also forward the signal. Inherited from wibox.widget.base
:index (widget, recursive, ...) -> (number, widget, table) Get the index of a widget. Inherited from wibox.widget.base
:connect_signal (name, func) Connect to a signal. Inherited from gears.object
:weak_connect_signal (name, func) Connect to a signal weakly. Inherited from gears.object
:disconnect_signal (name, func) Disconnect from a signal. Inherited from gears.object
:emit_signal (name, ...) Emit a signal. Inherited from gears.object

Signals

widget::layout_changed When the layout (size) change. Inherited from wibox.widget.base
widget::redraw_needed When the widget content changed. Inherited from wibox.widget.base
button::press When a mouse button is pressed over the widget. Inherited from wibox.widget.base
button::release When a mouse button is released over the widget. Inherited from wibox.widget.base
mouse::enter When the mouse enter a widget. Inherited from wibox.widget.base
mouse::leave When the mouse leave a widget. Inherited from wibox.widget.base


Object properties

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

Constraints:

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

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

Constraints:

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

See also:

borders The size of the border on each side. object properties
border_images Use images for each of the side/corner/filling sections. object properties
🔗 slice boolean · 1 signal
Sice the border_image to fit the content.

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

Constraints:

Default value : true
Valid values : true or false.

Usage:

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

Click to display more

Emit signals:

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

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

Constraints:

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

See also:

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

Usage:

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

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

local w = wibox.widget {
    {
        text   = "Center widget",
        valign = "center",
        align  = "center",
        widget = wibox.widget.textbox
    },
    borders                 = 50,
    border_image_stylesheet = style,
    border_image            = image_path,
    honor_borders           = false,
    widget                  = wibox.container.border
}
🔗 image_scaling_quality string
How the border_image(s) are scaled.

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

Value Description
fastA high-performance filter
goodA reasonable-performance filter
bestThe highest-quality available
nearestNearest-neighbor filtering (blocky)
bilinearLinear interpolation in two dimensions

Constraints:

Default value : "nearest"
Valid values:
"fast" : A high-performance filter.
"good" : A reasonable-performance filter.
"best" : The highest-quality available.
"nearest" : Nearest-neighbor filtering (blocky).
"bilinear" : Linear interpolation in two dimensions.
🔗 border_images table or image or nil · 1 signal
Use images for each of the side/corner/filling sections.

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

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

Constraints:

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

See also:

border_image A single border image for the border. object properties

Usage:

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

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

Click to display more

Emit signals:
🔗 borders table or number
The size of the border on each side.

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

Constraints:

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

Usage:

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

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

Constraints:

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

See also:

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

Usage:

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

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

Click to display more

Emit signals:
🔗 filling_fit_policy string · 1 signal
How the sliced image is resized for the border filling.

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

Constraints:

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

See also:

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

Usage:

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

Click to display more

Emit signals:
🔗 corners_fit_policy string · 1 signal
How the sliced image is resized for the border corners.

Constraints:

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

See also:

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

Usage:

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

Click to display more

Emit signals:
🔗 honor_borders boolean · 1 signal
Stretch the child widget over the entire area.

By default, the widget honors the borders.

Constraints:

Default value : true
Valid values : true or false.

See also:

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

Usage:

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

Click to display more

Emit signals:
🔗 ontop boolean · 1 signal
Draw the child widget below or on top of the border.

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

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

Constraints:

Default value : true
Valid values : true or false.

See also:

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

Usage:

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

Click to display more

Emit signals:

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

Constraints:

Default value : false
Valid values : true or false.

See also:

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

Usage:

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

Click to display more

Emit signals:

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

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

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

Constraints:

Default value : 0
Negative allowed : false

See also:

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

Usage:

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

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

Click to display more

Emit signals:

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

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

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

Constraints:

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

Usage:

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

Click to display more

Emit signals:
🔗 border_merging table or nil · 1 signal
Merge the corners widgets into the side widgets.

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

Constraints:

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

Usage:

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

Click to display more

Emit signals:
🔗 expand_corners boolean
When border_widgets is used, allow the border to grow due to corner widgets.

Constraints:

Default value : false
Valid values : true or false.

Usage:

    for _, expand in ipairs { false, true } do
    local w = wibox.widget {
        {
            text          = "expand_corners = " .. (expand and "true" or "false"),
            valign        = "center",
            align         = "center",
            widget        = wibox.widget.textbox
        },
        border_widgets = {
            top_left     = generic_widget("top_left"),
            top          = generic_widget("top"),
            top_right    = generic_widget("top_right"),
            right        = generic_widget("right"),
            bottom_right = generic_widget("bottom_right"),
            bottom       = generic_widget("bottom"),
            bottom_left  = generic_widget("bottom_left"),
            left         = generic_widget("left"),
        },
        expand_corners = expand,
        widget         = wibox.container.border
    }
end
🔗 children table · Inherited from wibox.widget.base
Get or set the children elements.

Constraints:

Default value : {}
Table content : A list of wibox.widget.

See also:

wibox.widget.base.all_children
🔗 all_children table · Inherited from wibox.widget.base
Get all direct and indirect children widgets. This will scan all containers recursively to find widgets Warning: This method it prone to stack overflow if there is a loop in the widgets hierarchy. A hierarchy loop is when a widget, or any of its children, contain (directly or indirectly) itself.

Constraints:

Default value : {}
Table content : A list of wibox.widget.

See also:

wibox.widget.base.children
🔗 forced_height number or nil · Inherited from wibox.widget.base
Force a widget height.

Constraints:

Default value : nil
Type description:
nil : Let the layout decide the height. Usually using the widget native height.
number : Enforce a number of pixels.
Unit : pixel
Negative allowed : false

See also:

wibox.widget.base.forced_width
🔗 forced_width number or nil · Inherited from wibox.widget.base
Force a widget width.

Constraints:

Default value : nil
Type description:
nil : Let the layout decide the width. Usually using the widget native width.
number : Enforce a number of pixels.
Unit : pixel
Negative allowed : false

See also:

wibox.widget.base.forced_height
🔗 opacity number · Inherited from wibox.widget.base
The widget opacity (transparency).

Constraints:

Default value : 1.0
Unit : A gradient between transparent (0.0) and opaque (1.0).
Minimum value : 0.0
Maximum value : 1.0

See also:

wibox.widget.base.visible
🔗 visible boolean · Inherited from wibox.widget.base
The widget visibility.

Constraints:

Default value : true
Valid values : true or false.

See also:

wibox.widget.base.opacity
🔗 buttons table · Inherited from wibox.widget.base
The widget buttons.

The table contains a list of awful.button objects.

Constraints:

Default value : {}
Table content : A list of awful.button.

See also:

awful.button Create easily new buttons objects ignoring certain modifiers. module

Object methods

🔗 :reset ()
Reset this layout. The widget will be removed and the rotation reset.
🔗 :add_button (button) · Inherited from wibox.widget.base
Add a new awful.button to this widget.

Parameters:

Name Type(s) Description
button awful.button The button to add.
🔗 :emit_signal_recursive (signal_name, ...) · Inherited from wibox.widget.base

Emit a signal and ensure all parent widgets in the hierarchies also forward the signal.

This is useful to track signals when there is a dynamic set of containers and layouts wrapping the widget.

Note that this function has some flaws:

  1. The signal is only forwarded once the widget tree has been built. This happens after all currently scheduled functions have been executed. Therefore, it will not start to work right away.
  2. In case the widget is present multiple times in a single widget tree, this function will also forward the signal multiple times (once per upward tree path).
  3. If the widget is removed from the widget tree, the signal is still forwarded for some time, similar to the first case.

Parameters:

Name Type(s) Description
signal_name string
... Other arguments
🔗 :index (widget, recursive, ...) -> (number, widget, table) · Inherited from wibox.widget.base
Get the index of a widget.

Parameters:

Name Type(s) Description
widget widget The widget to look for.
recursive Optional boolean Recursively check accross the sub-widgets hierarchy.
... Optional widget Additional widgets to add at the end of the sub-widgets hierarchy "path".

Returns:

  1. number The widget index.
  2. widget The parent widget.
  3. table The hierarchy path between "self" and "widget".
🔗 :connect_signal (name, func) · Inherited from gears.object

Connect to a signal.

Usage example output:

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

Parameters:

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

Usage:

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

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens. Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

Name Type(s) Description
name string The name of the signal.
func function The callback to call when the signal is emitted.
🔗 :disconnect_signal (name, func) · Inherited from gears.object
Disconnect from a signal.

Parameters:

Name Type(s) Description
name string The name of the signal.
func function The callback that should be disconnected.
🔗 :emit_signal (name, ...) · Inherited from gears.object
Emit a signal.

Parameters:

Name Type(s) Description
name string The name of the signal
... Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal()

Signals

🔗 widget::layout_changed · Inherited from wibox.widget.base
When the layout (size) change. This signal is emitted when the previous results of :layout() and :fit() are no longer valid. Unless this signal is emitted, :layout() and :fit() must return the same result when called with the same arguments.

See also:

widget::redraw_needed When the widget content changed. signals
🔗 widget::redraw_needed · Inherited from wibox.widget.base
When the widget content changed. This signal is emitted when the content of the widget changes. The widget will be redrawn, it is not re-layouted. Put differently, it is assumed that :layout() and :fit() would still return the same results as before.

See also:

widget::layout_changed When the layout (size) change. signals
🔗 button::press · Inherited from wibox.widget.base
When a mouse button is pressed over the widget.

Arguments:

Name Type(s) Description
self table The current object instance itself.
lx number The horizontal position relative to the (0,0) position in the widget.
ly number The vertical position relative to the (0,0) position in the widget.
button number The button number.
mods table The modifiers (mod4, mod1 (alt), Control, Shift)
find_widgets_result table The entry from the result of wibox:find_widgets for the position that the mouse hit.
drawable wibox.drawable The drawable containing the widget.
widget widget The widget being displayed.
hierarchy wibox.hierarchy The hierarchy managing the widget's geometry.
x number An approximation of the X position that the widget is visible at on the surface.
y number An approximation of the Y position that the widget is visible at on the surface.
width number An approximation of the width that the widget is visible at on the surface.
height number An approximation of the height that the widget is visible at on the surface.
widget_width number The exact width of the widget in its local coordinate system.
widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse Manipulate and inspect the mouse cursor. module
🔗 button::release · Inherited from wibox.widget.base
When a mouse button is released over the widget.

Arguments:

Name Type(s) Description
self table The current object instance itself.
lx number The horizontal position relative to the (0,0) position in the widget.
ly number The vertical position relative to the (0,0) position in the widget.
button number The button number.
mods table The modifiers (mod4, mod1 (alt), Control, Shift)
find_widgets_result table The entry from the result of wibox:find_widgets for the position that the mouse hit.
drawable wibox.drawable The drawable containing the widget.
widget widget The widget being displayed.
hierarchy wibox.hierarchy The hierarchy managing the widget's geometry.
x number An approximation of the X position that the widget is visible at on the surface.
y number An approximation of the Y position that the widget is visible at on the surface.
width number An approximation of the width that the widget is visible at on the surface.
height number An approximation of the height that the widget is visible at on the surface.
widget_width number The exact width of the widget in its local coordinate system.
widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse Manipulate and inspect the mouse cursor. module
🔗 mouse::enter · Inherited from wibox.widget.base
When the mouse enter a widget.

Arguments:

Name Type(s) Description
self table The current object instance itself.
find_widgets_result table The entry from the result of wibox:find_widgets for the position that the mouse hit.
drawable wibox.drawable The drawable containing the widget.
widget widget The widget being displayed.
hierarchy wibox.hierarchy The hierarchy managing the widget's geometry.
x number An approximation of the X position that the widget is visible at on the surface.
y number An approximation of the Y position that the widget is visible at on the surface.
width number An approximation of the width that the widget is visible at on the surface.
height number An approximation of the height that the widget is visible at on the surface.
widget_width number The exact width of the widget in its local coordinate system.
widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse Manipulate and inspect the mouse cursor. module
🔗 mouse::leave · Inherited from wibox.widget.base
When the mouse leave a widget.

Arguments:

Name Type(s) Description
self table The current object instance itself.
find_widgets_result table The entry from the result of wibox:find_widgets for the position that the mouse hit.
drawable wibox.drawable The drawable containing the widget.
widget widget The widget being displayed.
hierarchy wibox.hierarchy The hierarchy managing the widget's geometry.
x number An approximation of the X position that the widget is visible at on the surface.
y number An approximation of the Y position that the widget is visible at on the surface.
width number An approximation of the width that the widget is visible at on the surface.
height number An approximation of the height that the widget is visible at on the surface.
widget_width number The exact width of the widget in its local coordinate system.
widget_height number The exact height of the widget in its local coordinate system.

See also:

mouse Manipulate and inspect the mouse cursor. module
generated by LDoc 1.5.0