Module: awful.widget.layoutlist

Display the available client layouts for a screen.

This is what the layoutlist looks like by default with a vertical layout:

awful.popup {
    widget = awful.widget.layoutlist {
        screen      = 1,
        base_layout = wibox.layout.flex.vertical
    },
    maximum_height = #awful.layout.layouts * 24,
    minimum_height = #awful.layout.layouts * 24,
    placement      = awful.placement.centered,
}

In the second example, it is shown how to create a popup in the center of the screen:

local ll = awful.widget.layoutlist {
    base_layout = wibox.widget {
        spacing         = 5,
        forced_num_cols = 5,
        layout          = wibox.layout.grid.vertical,
    },
    widget_template = {
        {
            {
                id            = 'icon_role',
                forced_height = 22,
                forced_width  = 22,
                widget        = wibox.widget.imagebox,
            },
            margins = 4,
            widget  = wibox.container.margin,
        },
        id              = 'background_role',
        forced_width    = 24,
        forced_height   = 24,
        shape           = gears.shape.rounded_rect,
        widget          = wibox.container.background,
    },
}

local layout_popup = awful.popup {
    widget = wibox.widget {
        ll,
        margins = 4,
        widget  = wibox.container.margin,
    },
    border_color = beautiful.border_color,
    border_width = beautiful.border_width,
    placement    = awful.placement.centered,
    ontop        = true,
    visible      = false,
    shape        = gears.shape.rounded_rect
}

-- Make sure you remove the default Mod4+Space and Mod4+Shift+Space
-- keybindings before adding this.
awful.keygrabber {
    start_callback = function() layout_popup.visible = true  end,
    stop_callback  = function() layout_popup.visible = false end,
    export_keybindings = true,
    stop_event = "release",
    stop_key = {"Escape", "Super_L", "Super_R"},
    keybindings = {
        {{ modkey          } , " " , function()
            awful.layout.set((gears.table.cycle_value(ll.layouts, ll.current_layout, 1)))
        end},
        {{ modkey, "Shift" } , " " , function()
            awful.layout.set((gears.table.cycle_value(ll.layouts, ll.current_layout, -1)), nil)
        end},
    }
}

This example extends awful.widget.layoutbox to show a layout list popup:

-- Normally you would use your existing bars, but for this example, we add one
local lb = awful.widget.layoutbox(screen[1])
local l = wibox.layout.align.horizontal(nil, lb, nil)
l.expand = "outside"
awful.wibar { widget = l }

local p = awful.popup {
    widget = wibox.widget {
        awful.widget.layoutlist {
            source      = awful.widget.layoutlist.source.default_layouts,
            screen      = 1,
            base_layout = wibox.widget {
                spacing         = 5,
                forced_num_cols = 3,
                layout          = wibox.layout.grid.vertical,
            },
            widget_template = {
                {
                    {
                        id            = 'icon_role',
                        forced_height = 22,
                        forced_width  = 22,
                        widget        = wibox.widget.imagebox,
                    },
                    margins = 4,
                    widget  = wibox.container.margin,
                },
                id              = 'background_role',
                forced_width    = 24,
                forced_height   = 24,
                shape           = gears.shape.rounded_rect,
                widget          = wibox.container.background,
            },
        },
        margins = 4,
        widget  = wibox.container.margin,
    },
    preferred_anchors = "middle",
    border_color      = beautiful.border_color,
    border_width      = beautiful.border_width,
    shape             = gears.shape.infobubble,
}
p:bind_to_widget(lb)

This example shows how to add a layout subset to the default wibar:

wb:setup {
    layout = wibox.layout.align.horizontal,
    { -- Left widgets
        mytaglist,
        awful.widget.layoutlist {
            screen = 1,
            style = {
                disable_name = true,
                spacing      = 3,
            },
            source = function() return {
                awful.layout.suit.floating,
                awful.layout.suit.tile,
                awful.layout.suit.tile.left,
                awful.layout.suit.tile.bottom,
                awful.layout.suit.tile.top,
            } end
        },
        layout = wibox.layout.fixed.horizontal,
    },
    mytasklist, -- Middle widget
    { -- Right widgets
        layout = wibox.layout.fixed.horizontal,
        mykeyboardlayout,
        mytextclock,
        mylayoutbox,
    },
}

Class Hierarchy

Info:

Constructors

awful.widget.layoutlist {[args]} Create a layout list.

Object properties

base_layout wibox.layout The layoutlist default widget layout.
widget_template template or nil The delegate widget template.
screen screen The layoutlist screen.
source function A function that returns the list of layout to display.
layouts table The currenly displayed layouts.
current_layout layout or nil The currently selected layout. Read only
count number The current number of layouts. Read only
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

Theme variables

beautiful.layoutlist_fg_normal string or pattern The default foreground (text) color.
beautiful.layoutlist_bg_normal string or pattern The default background color.
beautiful.layoutlist_fg_selected string or pattern The selected layout foreground (text) color.
beautiful.layoutlist_bg_selected string or pattern The selected layout background color.
beautiful.layoutlist_disable_icon boolean Disable the layout icons (only show the name label).
beautiful.layoutlist_disable_name boolean Disable the layout name label (only show the icon).
beautiful.layoutlist_font string The layoutlist font.
beautiful.layoutlist_align string The selected layout alignment.
beautiful.layoutlist_font_selected string The selected layout title font.
beautiful.layoutlist_spacing number The space between the layouts.
beautiful.layoutlist_shape gears.shape The default layoutlist elements shape.
beautiful.layoutlist_shape_border_width number The default layoutlist elements border width.
beautiful.layoutlist_shape_border_color string or color The default layoutlist elements border color.
beautiful.layoutlist_shape_selected gears.shape The selected layout shape.
beautiful.layoutlist_shape_border_width_selected number The selected layout border width.
beautiful.layoutlist_shape_border_color_selected string or color The selected layout border color.

List source functions

awful.widget.layoutlist.source.for_screen The layout list for the first selected tag of a screen.
awful.widget.layoutlist.source.current_screen The layouts available for the first selected tag of awful.screen.focused().
awful.widget.layoutlist.source.default_layouts The default layout list.

Object methods

: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) Disonnect 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


Constructors

🔗 awful.widget.layoutlist {[args]}
Create a layout list.

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.widget.layoutlist{}. This is a Lua shortcut syntax equivalent to awful.widget.layoutlist({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args table Not applicable
base_layout widget The widget layout (not to be confused with client layout). Not applicable
buttons table A table with buttons binding to set. Not applicable
source Optional function A function to generate the list of layouts. awful.widget.layoutlist.source.for_screen
widget_template Optional table A custom widget to be used for each action. Undefined
screen Optional screen A screen ascreen.focused()
style Optional table Extra look and feel parameters {}
style.disable_icon Optional boolean beautiful.layoutlist_disable_icon
style.disable_name Optional boolean beautiful.layoutlist_disable_name
style.fg_normal Optional string or pattern beautiful.layoutlist_fg_normal
style.bg_normal Optional string or pattern beautiful.layoutlist_bg_normal
style.fg_selected Optional string or pattern beautiful.layoutlist_fg_selected
style.bg_selected Optional string or pattern beautiful.layoutlist_bg_selected
style.font Optional string beautiful.layoutlist_font
style.font_selected Optional string beautiful.layoutlist_font_selected
style.align Optional string left, right or center beautiful.layoutlist_align
style.spacing Optional number beautiful.layoutlist_spacing
style.shape Optional gears.shape beautiful.layoutlist_shape
style.shape_border_width Optional number beautiful.layoutlist_shape_border_width
style.shape_border_color Optional string or pattern beautiful.layoutlist_shape_border_color
style.shape_selected Optional gears.shape beautiful.layoutlist_shape_selected
style.shape_border_width_selected Optional string or pattern beautiful.layoutlist_shape_border_width_selected
style.shape_border_color_selected Optional string or pattern beautiful.layoutlist_shape_border_color_selected

Returns:

    widget The action widget.

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.layoutlist_disable_icon
beautiful.layoutlist_disable_name
beautiful.layoutlist_fg_normal
beautiful.layoutlist_bg_normal
beautiful.layoutlist_fg_selected
beautiful.layoutlist_bg_selected
beautiful.layoutlist_font
beautiful.layoutlist_font_selected
beautiful.layoutlist_align
beautiful.layoutlist_spacing
beautiful.layoutlist_shape
beautiful.layoutlist_shape_border_width
beautiful.layoutlist_shape_border_color
beautiful.layoutlist_shape_selected
beautiful.layoutlist_shape_border_width_selected
beautiful.layoutlist_shape_border_color_selected

Object properties

🔗 base_layout wibox.layout · 1 signal
The layoutlist default widget layout.

If no layout is specified, a wibox.layout.fixed.vertical will be created automatically.

Constraints:

Default value : wibox.layout.fixed.vertical

See also:

wibox.layout.fixed.vertical Creates and returns a new vertical fixed layout. (wibox.layout.fixed) constructors
base_layout The layoutlist default widget layout. object properties

Click to display more

Emit signals:

  • property::base_layout When the base_layout value changes.
    • self awful.widget.layoutlist The object which changed (useful when connecting many object to the same callback).
    • new_value base_layout The new value affected to the property.
🔗 widget_template template or nil · 1 signal
The delegate widget template.

Constraints:

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

Click to display more

Emit signals:
🔗 screen screen
The layoutlist screen.

Constraints:

Default value : Obtained from the constructor.
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.
🔗 source function
A function that returns the list of layout to display.

Constraints:

Default value : awful.widget.layoutlist.source.for_screen
Function prototype:
Parameters:
s (screen) : The layoutlist screen.
metadata (table) : Various metadata.
Return (table) : The list of layouts.
🔗 layouts table
The currenly displayed layouts.

Constraints:

Default value : {}
Table content : A list of awful.layout.suit.
🔗 current_layout layout or nil · read only
The currently selected layout.

Constraints:

Default value : nil
🔗 count number · 1 signal · read only
The current number of layouts.

Constraints:

Default value : This current number of layouts.
Negative allowed : false
Valid values : The number of layouts.

Click to display more

Emit signals:

  • property::count When the count value changes.
    • self awful.widget.layoutlist The object which changed (useful when connecting many object to the same callback).
    • new_value count The new value affected to the property.
🔗 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:

all_children Get all direct and indirect children widgets. object properties
🔗 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:

children Get or set the children elements. object properties
🔗 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:

forced_width Force a widget width. object properties
🔗 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:

forced_height Force a widget height. object properties
🔗 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:

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

Constraints:

Default value : true
Valid values : true or false.

See also:

opacity The widget opacity (transparency). object properties
🔗 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

Theme variables

🔗 beautiful.layoutlist_fg_normal string or pattern
The default foreground (text) color.

See also:

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

Click to display more

Used by:
🔗 beautiful.layoutlist_bg_normal string or pattern
The default background color.

See also:

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

Click to display more

Used by:
🔗 beautiful.layoutlist_fg_selected string or pattern
The selected layout foreground (text) color.

See also:

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

Click to display more

Used by:
🔗 beautiful.layoutlist_bg_selected string or pattern
The selected layout background color.

See also:

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

Click to display more

Used by:
🔗 beautiful.layoutlist_disable_icon boolean
Disable the layout icons (only show the name label).
Click to display more

Used by:
🔗 beautiful.layoutlist_disable_name boolean
Disable the layout name label (only show the icon).
Click to display more

Used by:
🔗 beautiful.layoutlist_font string
The layoutlist font.
Click to display more

Used by:
🔗 beautiful.layoutlist_align string
The selected layout alignment.

Type constraints:

Name Type(s) Description Default value
align Optional string left, right or center "left"

Click to display more

Used by:
🔗 beautiful.layoutlist_font_selected string
The selected layout title font.
Click to display more

Used by:
🔗 beautiful.layoutlist_spacing number
The space between the layouts.

Type constraints:

Name Type(s) Description Default value
spacing Optional number The spacing between layouts. 0

Click to display more

Used by:
🔗 beautiful.layoutlist_shape gears.shape
The default layoutlist elements shape.
Click to display more

Used by:
🔗 beautiful.layoutlist_shape_border_width number
The default layoutlist elements border width.
Click to display more

Used by:
🔗 beautiful.layoutlist_shape_border_color string or color
The default layoutlist elements border color.

See also:

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

Click to display more

Used by:
🔗 beautiful.layoutlist_shape_selected gears.shape
The selected layout shape.
Click to display more

Used by:
🔗 beautiful.layoutlist_shape_border_width_selected number
The selected layout border width.
Click to display more

Used by:
🔗 beautiful.layoutlist_shape_border_color_selected string or color
The selected layout border color.

See also:

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

Click to display more

Used by:

List source functions

🔗 awful.widget.layoutlist.source.for_screen
The layout list for the first selected tag of a screen.
Name Type(s) Description
s screen The screen.
🔗 awful.widget.layoutlist.source.current_screen
The layouts available for the first selected tag of awful.screen.focused().
🔗 awful.widget.layoutlist.source.default_layouts
The default layout list.

See also:

awful.layout.layouts The default list of layouts. (awful.layout) fields

Object methods

🔗 :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
Disonnect 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.4.6