Module: awful.widget.tasklist

Tasklist widget module for awful.

Status icons:

By default, the tasklist prepends some symbols in front of the client name. This is used to notify that the client has some specific properties that are currently enabled. This can be disabled using beautiful.tasklist_plain_task_name=true in the theme.

Icon Client property
sticky
ontop
above
below
floating
+maximized
maximized_horizontal
maximized_vertical

Customizing the tasklist:

The tasklist created by rc.lua use the default values for almost everything. However, it is possible to override each aspects to create a very different widget. Here’s an example that create a tasklist similar to the default one, but with an explicit layout and some spacing widgets:

Usage example

s.mytasklist = awful.widget.tasklist {
    screen   = s,
    filter   = awful.widget.tasklist.filter.currenttags,
    buttons  = tasklist_buttons,
    style    = {
        border_width = 1,
        border_color = '#777777',
        shape        = gears.shape.rounded_bar,
    },
    layout   = {
        spacing = 10,
        spacing_widget = {
            {
                forced_width = 5,
                shape        = gears.shape.circle,
                widget       = wibox.widget.separator
            },
            valign = 'center',
            halign = 'center',
            widget = wibox.container.place,
        },
        layout  = wibox.layout.flex.horizontal
    },
    -- Notice that there is *NO* wibox.wibox prefix, it is a template,
    -- not a widget instance.
    widget_template = {
        {
            {
                {
                    {
                        id     = 'icon_role',
                        widget = wibox.widget.imagebox,
                    },
                    margins = 2,
                    widget  = wibox.container.margin,
                },
                {
                    id     = 'text_role',
                    widget = wibox.widget.textbox,
                },
                layout = wibox.layout.fixed.horizontal,
            },
            left  = 10,
            right = 10,
            widget = wibox.container.margin
        },
        id     = 'background_role',
        widget = wibox.container.background,
    },
}

As demonstrated in the example above, there are a few “shortcuts” to avoid re-inventing the wheel. By setting the predefined roles as widget ids, awful.widget.common will do most of the work to update the values automatically. All of them are optional. The supported roles are:

awful.widget.common also has 2 callbacks to give more control over the widget:

  • create_callback: Called once after the widget instance is created
  • update_callback: Called everytime the data is refreshed

Both callback have the same parameters:

  • self: The widget instance (widget).
  • c: The client (client)
  • index: The widget position in the list (number)
  • clients: The list of client, in order (table)

It is also possible to omit some roles and create an icon only tasklist. Notice that this example use the awful.widget.clienticon widget instead of an imagebox. This allows higher resoluton icons to be loaded. This example reproduces the Windows 10 tasklist look and feel:

Usage example

s.mytasklist = awful.widget.tasklist {
    screen   = s,
    filter   = awful.widget.tasklist.filter.currenttags,
    buttons  = tasklist_buttons,
    layout   = {
        spacing_widget = {
            {
                forced_width  = 5,
                forced_height = 24,
                thickness     = 1,
                color         = '#777777',
                widget        = wibox.widget.separator
            },
            valign = 'center',
            halign = 'center',
            widget = wibox.container.place,
        },
        spacing = 1,
        layout  = wibox.layout.fixed.horizontal
    },
    -- Notice that there is *NO* wibox.wibox prefix, it is a template,
    -- not a widget instance.
    widget_template = {
        {
            wibox.widget.base.make_widget(),
            forced_height = 5,
            id            = 'background_role',
            widget        = wibox.container.background,
        },
        {
            awful.widget.clienticon,
            margins = 5,
            widget  = wibox.container.margin
        },
        nil,
        layout = wibox.layout.align.vertical,
    },
}

The tasklist can also be created in an awful.popup in case there is no permanent awful.wibar:

Usage example

awful.popup {
    widget = awful.widget.tasklist {
        screen   = screen[1],
        filter   = awful.widget.tasklist.filter.allscreen,
        buttons  = tasklist_buttons,
        style    = {
            shape = gears.shape.rounded_rect,
        },
        layout   = {
            spacing = 5,
            forced_num_rows = 2,
            layout = wibox.layout.grid.horizontal
        },
        widget_template = {
            {
                {
                    id     = 'clienticon',
                    widget = awful.widget.clienticon,
                },
                margins = 4,
                widget  = wibox.container.margin,
            },
            id              = 'background_role',
            forced_width    = 48,
            forced_height   = 48,
            widget          = wibox.container.background,
            create_callback = function(self, c, index, objects) --luacheck: no unused
                self:get_children_by_id('clienticon')[1].client = c
            end,
        },
    },
    border_color = '#777777',
    border_width = 2,
    ontop        = true,
    placement    = awful.placement.centered,
    shape        = gears.shape.rounded_rect
}

Info:

Constructors

awful.widget.tasklist (args, filter, buttons, style[, update_function[, base_widget]]) Create a new tasklist widget.

Object properties

children table Get or set the children elements. Inherited from wibox.widget
all_children table Get all direct and indirect children widgets. Inherited from wibox.widget
forced_height number or nil Force a widget height. Inherited from wibox.widget
forced_width number or nil Force a widget width. Inherited from wibox.widget
opacity number The widget opacity (transparency). Inherited from wibox.widget
visible boolean The widget visibility. Inherited from wibox.widget
buttons table The widget buttons. Inherited from wibox.widget

Object methods

:setup {[args]} Set a declarative widget hierarchy description. Inherited from wibox.widget
:add_button (button) Add a new awful.button to this widget. Inherited from wibox.widget
:emit_signal_recursive (signal_name, ...) Emit a signal and ensure all parent widgets in the hierarchies also forward the signal. Inherited from wibox.widget
:emit_signal (name, ...) Emit a signal. Inherited from gears.object
: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

Signals

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

Theme variables

beautiful.tasklist_fg_normal string or pattern The default foreground (text) color.
beautiful.tasklist_bg_normal string or pattern The default background color.
beautiful.tasklist_fg_focus string or pattern The focused client foreground (text) color.
beautiful.tasklist_bg_focus string or pattern The focused client background color.
beautiful.tasklist_fg_urgent string or pattern The urgent clients foreground (text) color.
beautiful.tasklist_bg_urgent string or pattern The urgent clients background color.
beautiful.tasklist_fg_minimize string or pattern The minimized clients foreground (text) color.
beautiful.tasklist_bg_minimize string or pattern The minimized clients background color.
beautiful.tasklist_bg_image_normal string The elements default background image.
beautiful.tasklist_bg_image_focus string The focused client background image.
beautiful.tasklist_bg_image_urgent string The urgent clients background image.
beautiful.tasklist_bg_image_minimize string The minimized clients background image.
beautiful.tasklist_disable_icon boolean Disable the tasklist client icons.
beautiful.tasklist_disable_task_name boolean Disable the tasklist client titles.
beautiful.tasklist_plain_task_name boolean Disable the extra tasklist client property notification icons.
beautiful.tasklist_font string The tasklist font.
beautiful.tasklist_align string The focused client alignment.
beautiful.tasklist_font_focus string The focused client title alignment.
beautiful.tasklist_font_minimized string The minimized clients font.
beautiful.tasklist_font_urgent string The urgent clients font.
beautiful.tasklist_spacing number The space between the tasklist elements.
beautiful.tasklist_shape gears.shape The default tasklist elements shape.
beautiful.tasklist_shape_border_width number The default tasklist elements border width.
beautiful.tasklist_shape_border_color string or color The default tasklist elements border color.
beautiful.tasklist_shape_focus gears.shape The focused client shape.
beautiful.tasklist_shape_border_width_focus number The focused client border width.
beautiful.tasklist_shape_border_color_focus string or color The focused client border color.
beautiful.tasklist_shape_minimized gears.shape The minimized clients shape.
beautiful.tasklist_shape_border_width_minimized number The minimized clients border width.
beautiful.tasklist_shape_border_color_minimized string or color The minimized clients border color.
beautiful.tasklist_shape_urgent gears.shape The urgent clients shape.
beautiful.tasklist_shape_border_width_urgent number The urgent clients border width.
beautiful.tasklist_shape_border_color_urgent string or color The urgent clients border color.

List source functions

awful.tasklist.source.all_clients Get all the clients in an undefined order.

List filters

awful.tasklist.filter.allscreen Filtering function to include all clients.
awful.tasklist.filter.alltags Filtering function to include the clients from all tags on the screen.
awful.tasklist.filter.currenttags Filtering function to include only the clients from currently selected tags.
awful.tasklist.filter.minimizedcurrenttags Filtering function to include only the minimized clients from currently selected tags.
awful.tasklist.filter.focused Filtering function to include only the currently focused client.


Constructors

awful.widget.tasklist (args, filter, buttons, style[, update_function[, base_widget]])
Create a new tasklist widget. The last two arguments (update_function and layout) serve to customize the layout of the tasklist (eg. to make it vertical). For that, you will need to copy the awful.widget.common.list_update function, make your changes to it and pass it as update_function here. Also change the layout if the default is not what you want.

Parameters:

  • args
    • screen screen The screen to draw tasklist for.
    • filter function Filter function to define what clients will be listed.
    • buttons table A table with buttons binding to set.
    • update_function function Function to create a tag widget on each update. See awful.widget.common.list_update. (optional)
    • layout table Container widget for tag widgets. Default is wibox.layout.flex.horizontal. (optional)
    • source function The function used to generate the list of client. (default awful.tasklist.source.all_clients)
    • widget_template table A custom widget to be used for each client (optional)
    • style table The style overrides default theme. (default {})
    • style.fg_normal string or pattern (default nil)
    • style.bg_normal string or pattern (default nil)
    • style.fg_focus string or pattern (default nil)
    • style.bg_focus string or pattern (default nil)
    • style.fg_urgent string or pattern (default nil)
    • style.bg_urgent string or pattern (default nil)
    • style.fg_minimize string or pattern (default nil)
    • style.bg_minimize string or pattern (default nil)
    • style.bg_image_normal string (default nil)
    • style.bg_image_focus string (default nil)
    • style.bg_image_urgent string (default nil)
    • style.bg_image_minimize string (default nil)
    • style.tasklist_disable_icon boolean (default nil)
    • style.icon_size number The size of the icon (default nil)
    • style.disable_task_name boolean (default false)
    • style.font string (default nil)
    • style.align string left, right or center (default left)
    • style.font_focus string (default nil)
    • style.font_minimized string (default nil)
    • style.font_urgent string (default nil)
    • style.spacing number The spacing between tags. (default nil)
    • style.shape gears.shape (default nil)
    • style.shape_border_width number (default nil)
    • style.shape_border_color string or color (default nil)
    • style.shape_focus gears.shape (default nil)
    • style.shape_border_width_focus number (default nil)
    • style.shape_border_color_focus string or color (default nil)
    • style.shape_minimized gears.shape (default nil)
    • style.shape_border_width_minimized number (default nil)
    • style.shape_border_color_minimized string or color (default nil)
    • style.shape_urgent gears.shape (default nil)
    • style.shape_border_width_urgent number (default nil)
    • style.shape_border_color_urgent string or color (default nil)
  • filter DEPRECATED use args.filter
  • buttons DEPRECATED use args.buttons
  • style DEPRECATED use args.style
  • update_function DEPRECATED use args.update_function
  • base_widget DEPRECATED use args.base_widget

Object properties

children (table) · Inherited from wibox.widget
Get or set the children elements.

Type constraints:

  • children table The children.
all_children (table) · Inherited from wibox.widget
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:

  • children table The children.
forced_height (number or nil) · Inherited from wibox.widget
Force a widget height.

Type constraints:

  • height number or nil The height (nil for automatic)
forced_width (number or nil) · Inherited from wibox.widget
Force a widget width.

Type constraints:

  • width number or nil The width (nil for automatic)
opacity (number) · Inherited from wibox.widget
The widget opacity (transparency).

Type constraints:

  • opacity number The opacity (between 0 and 1) (default 1)
visible (boolean) · Inherited from wibox.widget
The widget visibility.
buttons (table) · Inherited from wibox.widget
The widget buttons.

The table contains a list of awful.button objects.

See also:

Object methods

:setup {[args]} · Inherited from wibox.widget
Set a declarative widget hierarchy description. See The declarative layout system

Parameters:

  • args An array containing the widgets disposition
:add_button (button) · Inherited from wibox.widget
Add a new awful.button to this widget.

Parameters:

  • button awful.button The button to add.
:emit_signal_recursive (signal_name, ...) · Inherited from wibox.widget
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, ...) · Inherited from gears.object
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) · Inherited from gears.object
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) · 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 string The name of the signal.
  • func function The callback to call when the signal is emitted.

Signals

widget::layout_changed · Inherited from wibox.widget
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 · Inherited from wibox.widget
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:

button::press · Inherited from wibox.widget
When a mouse button is pressed over the widget.

Arguments:

  • 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 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:

button::release · Inherited from wibox.widget
When a mouse button is released over the widget.

Arguments:

  • 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 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::enter · Inherited from wibox.widget
When the mouse enter a widget.

Arguments:

  • self table The current object instance itself.
  • 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::leave · Inherited from wibox.widget
When the mouse leave a widget.

Arguments:

  • self table The current object instance itself.
  • 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:

Theme variables

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

See also:

beautiful.tasklist_bg_normal (string or pattern)
The default background color.

See also:

beautiful.tasklist_fg_focus (string or pattern)
The focused client foreground (text) color.

See also:

beautiful.tasklist_bg_focus (string or pattern)
The focused client background color.

See also:

beautiful.tasklist_fg_urgent (string or pattern)
The urgent clients foreground (text) color.

See also:

beautiful.tasklist_bg_urgent (string or pattern)
The urgent clients background color.

See also:

beautiful.tasklist_fg_minimize (string or pattern)
The minimized clients foreground (text) color.

See also:

beautiful.tasklist_bg_minimize (string or pattern)
The minimized clients background color.

See also:

beautiful.tasklist_bg_image_normal (string)
The elements default background image.
beautiful.tasklist_bg_image_focus (string)
The focused client background image.
beautiful.tasklist_bg_image_urgent (string)
The urgent clients background image.
beautiful.tasklist_bg_image_minimize (string)
The minimized clients background image.
beautiful.tasklist_disable_icon (boolean)
Disable the tasklist client icons.
beautiful.tasklist_disable_task_name (boolean)
Disable the tasklist client titles.
beautiful.tasklist_plain_task_name (boolean)
Disable the extra tasklist client property notification icons.

See the Status icons section for more details.

beautiful.tasklist_font (string)
The tasklist font.
beautiful.tasklist_align (string)
The focused client alignment.

Type constraints:

  • align string left, right or center (default left)
beautiful.tasklist_font_focus (string)
The focused client title alignment.
beautiful.tasklist_font_minimized (string)
The minimized clients font.
beautiful.tasklist_font_urgent (string)
The urgent clients font.
beautiful.tasklist_spacing (number)
The space between the tasklist elements.

Type constraints:

  • spacing number The spacing between tasks. (default 0)
beautiful.tasklist_shape (gears.shape)
The default tasklist elements shape.
beautiful.tasklist_shape_border_width (number)
The default tasklist elements border width.
beautiful.tasklist_shape_border_color (string or color)
The default tasklist elements border color.

See also:

beautiful.tasklist_shape_focus (gears.shape)
The focused client shape.
beautiful.tasklist_shape_border_width_focus (number)
The focused client border width.
beautiful.tasklist_shape_border_color_focus (string or color)
The focused client border color.

See also:

beautiful.tasklist_shape_minimized (gears.shape)
The minimized clients shape.
beautiful.tasklist_shape_border_width_minimized (number)
The minimized clients border width.
beautiful.tasklist_shape_border_color_minimized (string or color)
The minimized clients border color.

See also:

beautiful.tasklist_shape_urgent (gears.shape)
The urgent clients shape.
beautiful.tasklist_shape_border_width_urgent (number)
The urgent clients border width.
beautiful.tasklist_shape_border_color_urgent (string or color)
The urgent clients border color.

See also:

List source functions

awful.tasklist.source.all_clients
Get all the clients in an undefined order.

This is the default source.

List filters

awful.tasklist.filter.allscreen
Filtering function to include all clients.
awful.tasklist.filter.alltags
Filtering function to include the clients from all tags on the screen.
  • c The client.
  • screen The screen we are drawing on.
awful.tasklist.filter.currenttags
Filtering function to include only the clients from currently selected tags.
  • c The client.
  • screen The screen we are drawing on.
awful.tasklist.filter.minimizedcurrenttags
Filtering function to include only the minimized clients from currently selected tags.
  • c The client.
  • screen The screen we are drawing on.
awful.tasklist.filter.focused
Filtering function to include only the currently focused client.
  • c The client.
  • screen The screen we are drawing on.
generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00