awesome

• Index

Contents

• Constructors
• Functions
• Object properties
• Object methods
• Signals
• Theme variables
• List source functions

Widgets

• awful.widget.button
• awful.widget.clienticon
• awful.widget.keyboardlayout
• awful.widget.launcher
• awful.widget.layoutbox
• awful.widget.layoutlist
• awful.widget.prompt
• awful.widget.taglist
• awful.widget.tasklist
• awful.widget.watch
• naughty.list.actions
• naughty.list.notifications
• naughty.widget.icon
• naughty.widget.message
• naughty.widget.title
• wibox.widget.calendar
• wibox.widget.checkbox
• wibox.widget.graph
• wibox.widget.imagebox
• wibox.widget.piechart
• wibox.widget.progressbar
• wibox.widget.separator
• wibox.widget.slider
• wibox.widget.systray
• wibox.widget.textbox
• wibox.widget.textclock

Core components

• awesome
• awful.keygrabber
• client and awful.client
• drawable
• gears.timer
• mousegrabber
• naughty.action
• naughty.notification
• root
• screen and awful.screen
• tag and awful.tag

Input handling

• awful.button
• awful.key
• awful.keyboard
• mouse

Widget containers

• awful.widget.only_on_screen
• naughty.widget.background
• wibox.container.arcchart
• wibox.container.background
• wibox.container.constraint
• wibox.container.margin
• wibox.container.mirror
• wibox.container.place
• wibox.container.radialprogressbar
• wibox.container.rotate
• wibox.container.scroll

Widget layouts

• wibox.layout.align
• wibox.layout.fixed
• wibox.layout.flex
• wibox.layout.grid
• wibox.layout.manual
• wibox.layout.ratio
• wibox.layout.stack

Popups and bars

• awful.hotkeys_popup.widget
• awful.menu
• awful.popup
• awful.titlebar
• awful.tooltip
• awful.wibar
• awful.widget.calendar_popup
• menubar
• naughty.layout.box
• naughty.layout.legacy
• wibox

Utility libraries

• gears.debug
• gears.filesystem
• gears.geometry
• gears.math
• gears.object
• gears.protected_call
• gears.sort
• gears.string
• gears.table
• gears.wallpaper

Theme related libraries

• beautiful
• gears.color
• gears.shape

Libraries

• awful.completion
• awful.ewmh
• awful.hotkeys_popup
• awful.layout
• awful.placement
• awful.prompt
• awful.rules
• awful.spawn
• awful.util
• dbus
• gears.matcher
• gears.surface
• menubar.menu_gen
• menubar.utils
• naughty
• selection
• wibox.widget

Sample files

• rc.lua
• theme.lua

Classes

• awful.widget.common
• gears.cache
• gears.matrix
• menubar.icon_theme
• menubar.index_theme
• signals
• wibox.drawable
• wibox.hierarchy
• wibox.widget.base
• xproperties

Documentation

• Authors
• Readme
• Contributing
• The AwesomeWM widget system
• Creating new widget
• Default configuration file documentation
• Change Awesome appearance
• My first Awesome
• Using Cairo and LGI
• Tips for upgrading your configuration
• NEWS
• FAQ

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,
    release_event = 'release',
    stop_key = {'Escape', 'Super_L', 'Super_R'},
    keybindings = {
        {{ modkey          } , ' ' , function()
            awful.layout.set(gears.table.iterate_value(ll.layouts, ll.current_layout, 1))
        end},
        {{ modkey, 'Shift' } , ' ' , function()
            awful.layout.set(gears.table.iterate_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,
    },
}

Info:

• Copyright: 2010, 2018 Emmanuel Lepage Vallee
• Author: Emmanuel Lepage Vallee <[email protected]>

Constructors

awful.widget.layoutlist {[args]}

Create a layout list.

Functions

awful.widget.layoutlist.add_button (button)

Add a new awful.button to this widget.

Object properties

base_layout	widget	The layoutlist default widget layout.
widget_template	table	The delegate widget template.
screen	screen	The layoutlist screen.
source	function	A function that returns the list of layout to display.
filter	function	The layoutlist filter function.
buttons	table	The layoutlist buttons.
layouts	table	The currenly displayed layouts.
current_layout	layout	The currently selected layout.
children	table	Get or set the children elements.
all_children	table	Get all direct and indirect children widgets.
forced_height	number or nil	Force a widget height.
forced_width	number or nil	Force a widget width.
opacity	number	The widget opacity (transparency).
visible	boolean	The widget visibility.
buttons	table	The widget buttons.

Object methods

:setup {[args]}	Set a declarative widget hierarchy description.
:emit_signal_recursive (signal_name, ...)	Emit a signal and ensure all parent widgets in the hierarchies also forward the signal.
:emit_signal (name, ...)	Emit a signal.
:connect_signal (name, func)	Connect to a signal.
:weak_connect_signal (name, func)	Connect to a signal weakly.

Signals

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

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.

Constructors

awful.widget.layoutlist {[args]}

Create a layout list.

Parameters:

• args
  • layout widget The widget layout (not to be confused with client layout).
  • buttons table The list of awful.buttons. (default nil)
  • source function A function to generate the list of layouts. (default awful.widget.layoutlist.source.for_screen)
  • widget_template table A custom widget to be used for each action. (optional)
  • screen screen A screen (default ascreen.focused())
  • buttons table The list of awful.buttons. (default nil)
  • style table Extra look and feel parameters (default {})
  • style.disable_icon boolean
  • style.disable_name boolean
  • style.fg_normal string or pattern
  • style.bg_normal string or pattern
  • style.fg_selected string or pattern
  • style.bg_selected string or pattern
  • style.font string
  • style.font_selected string
  • style.align string left, right or center
  • style.spacing number
  • style.shape gears.shape
  • style.shape_border_width number
  • style.shape_border_color string or pattern
  • style.shape_selected gears.shape
  • style.shape_border_width_selected string or pattern
  • style.shape_border_color_selected string or pattern

Returns:

widget The action widget.

Functions

awful.widget.layoutlist.add_button (button)

Add a new awful.button to this widget.

Parameters:

• button awful.button The button to add.

Object properties

base_layout (widget)

The layoutlist default widget layout. If no layout is specified, a wibox.layout.fixed.vertical will be created automatically.

See also:

• wibox.layout.fixed.vertical
• base_layout

widget_template (table)

The delegate widget template.

screen (screen)

The layoutlist screen.

source (function)

A function that returns the list of layout to display.

filter (function)

The layoutlist filter function.

buttons (table)

The layoutlist buttons.

The default is:

gears.table.join(
    awful.button({ }, 1, awful.layout.set)
)

layouts (table)

The currenly displayed layouts.

current_layout (layout)

The currently selected layout.

children (table)

Get or set the children elements.

Type constraints:

• The table children

all_children (table)

Get all direct and indirect children widgets. This will scan all containers recursively to find widgets Warning: This method it prone to stack overflow id the widget, or any of its children, contain (directly or indirectly) itself.

Type constraints:

• The table children

forced_height (number or nil)

Force a widget height.

Type constraints:

• height number or nil The height (nil for automatic)

forced_width (number or nil)

Force a widget width.

Type constraints:

• width number or nil The width (nil for automatic)

opacity (number)

The widget opacity (transparency).

Type constraints:

• opacity number The opacity (between 0 and 1) (default 1)

visible (boolean)

The widget visibility.

buttons (table)

The widget buttons.

The table contains a list of awful.button objects.

See also:

awful.button

Object methods

:setup {[args]}

Set a declarative widget hierarchy description. See The declarative layout system

Parameters:

• args An array containing the widgets disposition

:emit_signal_recursive (signal_name, ...)

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.

Parameters:

• signal_name string
• ... Other arguments

:emit_signal (name, ...)

Emit a signal.

Parameters:

• 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().

:connect_signal (name, func)

Connect to a signal.

Parameters:

• name string The name of the signal.
• func function The callback to call when the signal is emitted.

:weak_connect_signal (name, func)

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 string The name of the signal.
• func function The callback to call when the signal is emitted.

Signals

widget::layout_changed

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

widget::redraw_needed

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

button::press

When a mouse button is pressed over the widget.

Arguments:

• 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 The entry from the result of wibox.drawable: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

button::release

When a mouse button is released over the widget.

Arguments:

• 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 The entry from the result of wibox.drawable: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

mouse::enter

When the mouse enter a widget.

Arguments:

• find_widgets_result The entry from the result of wibox.drawable: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

mouse::leave

When the mouse leave a widget.

Arguments:

• find_widgets_result The entry from the result of wibox.drawable: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

Theme variables

beautiful.layoutlist_fg_normal (string or pattern)

The default foreground (text) color.

See also:

gears.color

beautiful.layoutlist_bg_normal (string or pattern)

The default background color.

See also:

gears.color

beautiful.layoutlist_fg_selected (string or pattern)

The selected layout foreground (text) color.

See also:

gears.color

beautiful.layoutlist_bg_selected (string or pattern)

The selected layout background color.

See also:

gears.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.

Type constraints:

• align string left, right or center (default left)

beautiful.layoutlist_font_selected (string)

The selected layout title font.

beautiful.layoutlist_spacing (number)

The space between the layouts.

Type constraints:

• spacing number The spacing between tasks. (default 0)

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.

See also:

gears.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.

See also:

gears.color

List source functions

awful.widget.layoutlist.source.for_screen

The layout list for the first selected tag of a screen.

• 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