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 uses the default values for almost everything. However, it is possible to override each aspect to create a very different widget. Here's an example that creates 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:

icon_role: A wibox.widget.imagebox
text_role: A wibox.widget.textbox
background_role: A wibox.container.background
text_margin_role: A wibox.container.margin
icon_margin_role: A wibox.container.margin

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 every time 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 resolution 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:

Copyright: 2008-2009 Julien Danjou
Originally authored by: Julien Danjou <julien@danjou.info>
(Full contributors list available on our github project)

Constructors

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

Create a new tasklist widget.

Object properties

count	number	The current number of clients. read only
base_layout	wibox.layout	Set the tasklist layout.
screen	screen	The tasklist screen.
filter	function	A function to narrow down the list of clients.
update_function	function	A function called when the tasklist is refreshed.
widget_template	table	A template for creating the client widgets.
source	function	A function to gather the clients to display.
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_sticky	string	Extra tasklist client property notification icon for clients with the sticky property set.
beautiful.tasklist_ontop	string	Extra tasklist client property notification icon for clients with the ontop property set.
beautiful.tasklist_above	string	Extra tasklist client property notification icon for clients with the above property set.
beautiful.tasklist_below	string	Extra tasklist client property notification icon for clients with the below property set.
beautiful.tasklist_floating	string	Extra tasklist client property notification icon for clients with the floating property set.
beautiful.tasklist_maximized	string	Extra tasklist client property notification icon for clients with the maximized property set.
beautiful.tasklist_maximized_horizontal	string	Extra tasklist client property notification icon for clients with the maximized_horizontal property set.
beautiful.tasklist_maximized_vertical	string	Extra tasklist client property notification icon for clients with the maximized_vertical property set.
beautiful.tasklist_align	string	The focused client alignment.
beautiful.tasklist_font	string	The tasklist font.
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.widget.tasklist.source.all_clients

Get all the clients in an undefined order.

List filters

awful.widget.tasklist.filter.allscreen	Filtering function to include all clients.
awful.widget.tasklist.filter.alltags	Filtering function to include the clients from all tags on the screen.
awful.widget.tasklist.filter.currenttags	Filtering function to include only the clients from currently selected tags.
awful.widget.tasklist.filter.minimizedcurrenttags	Filtering function to include only the minimized clients from currently selected tags.
awful.widget.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 (updatefunction 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.listupdate 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.widget.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.disable_icon boolean (default nil)
- style.icon_size number The size of the icon (default nil)
- style.sticky string Extra icon when client is sticky (default '▪')
- style.ontop string Extra icon when client is ontop (default '⌃')
- style.above string Extra icon when client is above (default '▴')
- style.below string Extra icon when client is below (default '▾')
- style.floating string Extra icon when client is floating (default '✈')
- style.maximized string Extra icon when client is maximized (default '+')
- style.maximized_horizontal string Extra icon when client is maximized_horizontal (default '⬌')
- style.maximized_vertical string Extra icon when client is maximized_vertical (default '⬍')
- 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_layout

Object properties

count number · 1 signal · read only

The current number of clients.

Type constraints:

The number number of client.

Click to display more

Emit signals:

property::count When the count value changes.

self awful.widget.tasklist The object which changed (useful when connecting many object to the same callback).
new_value The The new value affected to the property.

base_layout wibox.layout · 1 signal

Set the tasklist layout.

This can be used to change the layout based on the number of clients:

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
     buttons     = {
         awful.button({ }, 1, function (c)
             c:activate {
                 context = "tasklist",
                 action  = "toggle_minimization"
             }
         end),
         awful.button({ }, 3, function() awful.menu.client_list { theme = { width = 250 } } end),
         awful.button({ }, 4, function() awful.client.focus.byidx(-1) end),
         awful.button({ }, 5, function() awful.client.focus.byidx( 1) end),
     },
 }

 tasklist:connect_signal("property::count", function(self)
     local count = self.count

     if count > 5 and not self.is_grid then
         self.base_layout = wibox.widget {
             forced_num_rows = 2,
             homogeneous     = true,
             expand          = true,
             spacing         = 2,
             layout          = wibox.layout.grid.horizontal
         }

         self.is_grid = true
     elseif count <= 5 and self.is_grid then
         self.base_layout = wibox.widget {
             spacing = 2,
             layout  = wibox.layout.fixed.horizontal
         }

         self.is_grid = false
     end
 end)

 -- Spawn 5 clients.
 for i=1, 5 do
     awful.spawn("Client #"..i)
 end

 -- Spawn another client.
 awful.spawn("Client #6")

 -- Kill 3 clients.
 for _=1, 3 do
     client.get()[1]:kill()
 end

Emit signals:

property::base_layout When the base_layout value changes.

self awful.widget.tasklist The object which changed (useful when connecting many object to the same callback).
new_value base_layout The new value affected to the property.

screen screen · 1 signal

The tasklist screen.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = screen[1],
     filter      = awful.widget.tasklist.filter.currenttags,
     buttons     = {
         awful.button({ }, 1, function (c)
             c:activate {
                 context = "tasklist",
                 action  = "toggle_minimization"
             }
         end),
         awful.button({ }, 3, function() awful.menu.client_list { theme = { width = 250 } } end),
         awful.button({ }, 4, function() awful.client.focus.byidx(-1) end),
         awful.button({ }, 5, function() awful.client.focus.byidx( 1) end),
     },
 }

 -- Spawn 5 clients on screen 1.
 for i= 1, 5 do
     awful.spawn("Client #"..i, {screen = screen[1]})
 end

 -- Spawn 3 clients on screen 2.
 for i=1, 3 do
     awful.spawn("Client #"..(5+i), {screen = screen[2]})
 end

 -- Change the tastlist screen.
 tasklist.screen = screen[2]

Click to display more

Emit signals:

property::screen When the screen value changes.

self awful.widget.tasklist The object which changed (useful when connecting many object to the same callback).
new_value screen The new value affected to the property.

filter function · 1 signal

A function to narrow down the list of clients.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Spawn 5 clients on screen 1.
 for i= 1, 5 do
     awful.spawn("Client #"..i, {screen = screen[1]})
 end

 -- Spawn 3 clients on screen 2.
 for i=1, 3 do
     awful.spawn("Client #"..(5+i), {screen = screen[2]})
 end

 -- Set the filter to allscreen.
 tasklist.filter = awful.widget.tasklist.filter.allscreen

 -- Create a pointless demo filter to only have clients
 -- with off numbers in the name. Because... example!
 tasklist.filter = function(c, screen) -- luacheck: no unused args
     return c.name:match("[13579]") and c or nil
 end

Emit signals:

property::filter When the filter value changes.

self awful.widget.tasklist The object which changed (useful when connecting many object to the same callback).
new_value filter The new value affected to the property.

update_function function · 1 signal

A function called when the tasklist is refreshed.

This is a very low level API, prefer widget_template whenever you can.

Click to display more

Emit signals:

property::update_function When the update_function value changes.

self awful.widget.tasklist The object which changed (useful when connecting many object to the same callback).
new_value update_function The new value affected to the property.

widget_template table · 1 signal

A template for creating the client widgets.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Change the widget template.
 tasklist.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,
 }

Click to display more

Emit signals:

property::widget_template When the widget_template value changes.

self awful.widget.tasklist The object which changed (useful when connecting many object to the same callback).
new_value widget_template The new value affected to the property.

source function · 1 signal

A function to gather the clients to display.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Spawn 5 clients on screen 1.
 for i= 1, 5 do
     awful.spawn("Client #"..i, {screen = screen[1]})
 end

 -- Make 2 clients floating.
 client.get()[2].floating = true
 client.get()[4].floating = true

 -- Only select the floating clients for the tasklist screen.
 tasklist.source = function(screen)
     local ret = {}

     for _, c in ipairs(screen.clients) do
         if c.floating then
             table.insert(ret, c)
         end
     end

     return ret
 end

Emit signals:

property::source When the source value changes.

self awful.widget.tasklist The object which changed (useful when connecting many object to the same callback).
new_value source The new value affected to the property.

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.

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.

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.

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.

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.

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.

local grad = gears.color {
    type  = "linear",
    from  = { 0, 0 },
    to    = { 0, 22 },
    stops = {
        { 0, "#ff0000" },
        { 1, "#0000ff" },
    }
}

for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do
    beautiful.tasklist_bg_minimize = col
end

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.

Usage example

Usage:

for _, value in ipairs { true, false } do
    beautiful.tasklist_disable_icon = value
end

beautiful.tasklist_disable_task_name boolean

Disable the tasklist client titles.

Usage example

Usage:

for _, value in ipairs { true, false } do
    beautiful.tasklist_disable_task_name = value
end

beautiful.tasklist_plain_task_name boolean

Disable the extra tasklist client property notification icons.

See the Status icons section for more details.

Usage example

Usage:

for _, value in ipairs { true, false } do
    beautiful.tasklist_plain_task_name = value
end

beautiful.tasklist_sticky string

Extra tasklist client property notification icon for clients with the sticky property set.

beautiful.tasklist_ontop string

Extra tasklist client property notification icon for clients with the ontop property set.

beautiful.tasklist_above string

Extra tasklist client property notification icon for clients with the above property set.

beautiful.tasklist_below string

Extra tasklist client property notification icon for clients with the below property set.

beautiful.tasklist_floating string

Extra tasklist client property notification icon for clients with the floating property set.

beautiful.tasklist_maximized string

Extra tasklist client property notification icon for clients with the maximized property set.

beautiful.tasklist_maximized_horizontal string

Extra tasklist client property notification icon for clients with the maximized_horizontal property set.

beautiful.tasklist_maximized_vertical string

Extra tasklist client property notification icon for clients with the maximized_vertical property set.

beautiful.tasklist_align string

The focused client alignment.

Usage example

Type constraints:

align string left, right or center (default left)

Usage:

for _, value in ipairs { "left", "center", "right" } do
    beautiful.tasklist_align = value
end

beautiful.tasklist_font string

The tasklist font.

Usage example

Usage:

for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do
    beautiful.tasklist_font = font
end

beautiful.tasklist_font_focus string

The focused client title alignment.

Usage example

Usage:

for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do
    beautiful.tasklist_font_focus = font
end

beautiful.tasklist_font_minimized string

The minimized clients font.

Usage example

Usage:

for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do
    beautiful.tasklist_font_minimized = font
end

beautiful.tasklist_font_urgent string

The urgent clients font.

Usage example

Usage:

for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do
    beautiful.tasklist_font_urgent = font
end

beautiful.tasklist_spacing number

The space between the tasklist elements.

Usage example

Type constraints:

spacing number The spacing between tasks. (default 0)

Usage:

for _, spacing in ipairs { 0, 4, 8, 12 } do
    beautiful.tasklist_spacing = spacing
end

beautiful.tasklist_shape gears.shape

The default tasklist elements shape.

Usage example

Usage:

beautiful.tasklist_spacing = 5

local function customized(cr, width, height)
    return gears.shape.parallelogram(cr, width, height, width - height)
end

for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do
    beautiful.tasklist_shape = shape
end

beautiful.tasklist_shape_border_width number

The default tasklist elements border width.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect

for _, bw in ipairs { 0, 2, 4, 6 } do
    beautiful.tasklist_shape_border_width = bw
end

beautiful.tasklist_shape_border_color string or color

The default tasklist elements border color.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect
beautiful.tasklist_shape_border_width = 2

local grad = gears.color {
    type  = "linear",
    from  = { 0, 0 },
    to    = { 0, 22 },
    stops = {
        { 0, "#ff0000" },
        { 1, "#0000ff" },
    }
}

for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do
    beautiful.tasklist_shape_border_color = col
end

beautiful.tasklist_shape_focus gears.shape

The focused client shape.

Usage example

Usage:

beautiful.tasklist_spacing = 5

local function customized(cr, width, height)
    return gears.shape.parallelogram(cr, width, height, width - height)
end

for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do
    beautiful.tasklist_shape_focus = shape
end

beautiful.tasklist_shape_border_width_focus number

The focused client border width.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect

for _, bw in ipairs { 0, 2, 4, 6 } do
    beautiful.tasklist_shape_border_width_focus = bw
end

beautiful.tasklist_shape_border_color_focus string or color

The focused client border color.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect
beautiful.tasklist_shape_border_width = 2

local grad = gears.color {
    type  = "linear",
    from  = { 0, 0 },
    to    = { 0, 22 },
    stops = {
        { 0, "#ff0000" },
        { 1, "#0000ff" },
    }
}

for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do
    beautiful.tasklist_shape_border_color_focus = col
end

beautiful.tasklist_shape_minimized gears.shape

The minimized clients shape.

Usage example

Usage:

beautiful.tasklist_spacing = 5

local function customized(cr, width, height)
    return gears.shape.parallelogram(cr, width, height, width - height)
end

for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do
    beautiful.tasklist_shape_minimized = shape
end

beautiful.tasklist_shape_border_width_minimized number

The minimized clients border width.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect

for _, bw in ipairs { 0, 2, 4, 6 } do
    beautiful.tasklist_shape_border_width_minimized = bw
end

beautiful.tasklist_shape_border_color_minimized string or color

The minimized clients border color.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect
beautiful.tasklist_shape_border_width = 2

local grad = gears.color {
    type  = "linear",
    from  = { 0, 0 },
    to    = { 0, 22 },
    stops = {
        { 0, "#ff0000" },
        { 1, "#0000ff" },
    }
}

for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do
    beautiful.tasklist_shape_border_color_minimized = col
end

beautiful.tasklist_shape_urgent gears.shape

The urgent clients shape.

Usage example

Usage:

beautiful.tasklist_spacing = 5

local function customized(cr, width, height)
    return gears.shape.parallelogram(cr, width, height, width - height)
end

for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do
    beautiful.tasklist_shape_focus = shape
end

beautiful.tasklist_shape_border_width_urgent number

The urgent clients border width.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect

for _, bw in ipairs { 0, 2, 4, 6 } do
    beautiful.tasklist_shape_border_width_urgent = bw
end

beautiful.tasklist_shape_border_color_urgent string or color

The urgent clients border color.

Usage example

Usage:

beautiful.tasklist_spacing = 5
beautiful.tasklist_shape = gears.shape.rounded_rect
beautiful.tasklist_shape_border_width = 2

local grad = gears.color {
    type  = "linear",
    from  = { 0, 0 },
    to    = { 0, 22 },
    stops = {
        { 0, "#ff0000" },
        { 1, "#0000ff" },
    }
}

for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do
    beautiful.tasklist_shape_border_color_urgent = col
end

List source functions

awful.widget.tasklist.source.all_clients

Get all the clients in an undefined order.

This is the default source.

List filters

awful.widget.tasklist.filter.allscreen

Filtering function to include all clients.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Spawn 5 clients on screen 1.
 for i= 1, 5 do
     awful.spawn("Client #"..i, {screen = screen[1]})
 end

 -- Spawn 3 clients on screen 2.
 for i=1, 3 do
     awful.spawn("Client #"..(5+i), {screen = screen[2]})
 end

 -- Set the filter to allscreen.
 tasklist.filter = awful.widget.tasklist.filter.allscreen

awful.widget.tasklist.filter.alltags

Filtering function to include the clients from all tags on the screen.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Spawn 5 clients on screen 1.
 for i= 1, 5 do
     awful.spawn("Client #"..i, {tags = {screen[1].tags[1]}})
 end

 -- Spawn 3 clients on screen 2.
 for i=1, 3 do
     awful.spawn("Client #"..(5+i), {tags = {screen[1].tags[2]}})
 end

 -- Set the filter to alltags.
 tasklist.filter = awful.widget.tasklist.filter.alltags

c client The client.
screen screen The screen we are drawing on.

awful.widget.tasklist.filter.currenttags

Filtering function to include only the clients from currently selected tags.

This is the filter used in the default rc.lua.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Spawn 5 clients on screen 1.
 for k, t in ipairs(screen[1].tags) do
     for i= 1, 2 do
         awful.spawn("Client #"..(k-1)*2 + i, {tags = {t}})
     end
 end

 -- Selected some tags.
 screen[1].tags[3].selected = true
 screen[1].tags[5].selected = true

 -- Set the filter to currenttags.
 tasklist.filter = awful.widget.tasklist.filter.currenttags

c client The client.
screen screen The screen we are drawing on.

awful.widget.tasklist.filter.minimizedcurrenttags

Filtering function to include only the minimized clients from currently selected tags.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Spawn 5 clients on screen 1.
 for k, t in ipairs(screen[1].tags) do
     for i= 1, 2 do
         awful.spawn("Client #"..(k-1)*2 + i, {tags = {t}, minimized = i == 1})
     end
 end

 -- Selected some tags.
 screen[1].tags[3].selected = true
 screen[1].tags[5].selected = true

 -- Set the filter to minimizedcurrenttags.
 tasklist.filter = awful.widget.tasklist.filter.minimizedcurrenttags

c client The client.
screen screen The screen we are drawing on.

awful.widget.tasklist.filter.focused

Filtering function to include only the currently focused client.

Usage example

 local tasklist = awful.widget.tasklist {
     screen      = s,
     filter      = awful.widget.tasklist.filter.currenttags,
     base_layout = wibox.widget {
         spacing = 2,
         layout  = wibox.layout.fixed.horizontal,
     },
 }

 -- Spawn 5 clients on screen 1.
 for i= 1, 5 do
     awful.spawn("Client #"..i, {screen = screen[1]})
 end

 -- Set the filter to focused.
 tasklist.filter = awful.widget.tasklist.filter.focused

c client The client.
screen screen The screen we are drawing on.

awesome

Contents

Widgets

Core components

Input handling

Declarative rules

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

Documentation

Module: awful.widget.tasklist

Info:

Constructors

Object properties

Object methods

Signals

Theme variables

List source functions

List filters

Constructors

Parameters:

Object properties

Type constraints:

Emit signals:

See also:

Emit signals:

Emit signals:

See also:

Emit signals:

Emit signals:

Emit signals:

See also:

Emit signals:

Type constraints:

Type constraints:

Type constraints:

Type constraints:

Type constraints:

See also:

Object methods

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Signals

See also:

See also:

Arguments:

See also:

Arguments:

See also:

Arguments:

See also:

Arguments:

See also:

Theme variables

See also:

Usage:

See also:

Usage:

See also:

Usage:

See also:

Usage:

See also:

Usage:

See also:

Usage:

See also:

Usage:

See also:

Usage:

Module: `awful.widget.tasklist`