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:

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

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:

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,
            row_count = 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
}

Class Hierarchy

Info:

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 or nil A function called when the tasklist is refreshed.
widget_template template or nil 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.base
all_children table Get all direct and indirect children widgets. Inherited from wibox.widget.base
forced_height number or nil Force a widget height. Inherited from wibox.widget.base
forced_width number or nil Force a widget width. Inherited from wibox.widget.base
opacity number The widget opacity (transparency). Inherited from wibox.widget.base
visible boolean The widget visibility. Inherited from wibox.widget.base
buttons table The widget buttons. Inherited from wibox.widget.base

Object methods

: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
: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
:disconnect_signal (name, func) Disconnect from a signal. Inherited from gears.object

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_minimized string Extra tasklist client property notification icon for clients with the minimized 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.
beautiful.tasklist_icon_size integer The icon size.

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.

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.tasklist (args, filter, buttons, style, update_function, base_widget) · 1 theme variable
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:

Name Type(s) Description Default value
args table Not applicable
screen screen The screen to draw tasklist for. Not applicable
filter function Filter function to define what clients will be listed. Not applicable
buttons table A table with buttons binding to set. Not applicable
update_function Optional function Function to create a tag widget on each update. See awful.widget.common.list_update. Undefined
layout Optional table Container widget for tag widgets. Default is wibox.layout.flex.horizontal. Undefined
source Optional function The function used to generate the list of client. awful.widget.tasklist.source.all_clients
widget_template Optional table A custom widget to be used for each client Undefined
style Optional table The style overrides default theme. {}
style.fg_normal Optional string or pattern beautiful.tasklist_fg_normal
style.bg_normal Optional string or pattern beautiful.tasklist_bg_normal
style.fg_focus Optional string or pattern beautiful.tasklist_fg_focus or beautiful.fg_focus
style.bg_focus Optional string or pattern beautiful.tasklist_bg_focus or beautiful.bg_focus
style.fg_urgent Optional string or pattern beautiful.tasklist_fg_urgent or beautiful.fg_urgent
style.bg_urgent Optional string or pattern beautiful.tasklist_bg_urgent or beautiful.bg_urgent
style.fg_minimize Optional string or pattern beautiful.tasklist_fg_minimize or beautiful.fg_minimize
style.bg_minimize Optional string or pattern beautiful.tasklist_bg_minimize or beautiful.bg_minimize
style.bg_image_normal Optional string beautiful.tasklist_bg_image_normal
style.bg_image_focus Optional string beautiful.tasklist_bg_image_focus
style.bg_image_urgent Optional string beautiful.tasklist_bg_image_urgent
style.bg_image_minimize Optional string beautiful.tasklist_bg_image_minimize
style.disable_icon Optional boolean beautiful.tasklist_disable_icon
style.icon_size Optional number The size of the icon beautiful.tasklist_icon_size
style.sticky Optional string Extra icon when client is sticky beautiful.tasklist_sticky or '▪'
style.ontop Optional string Extra icon when client is ontop beautiful.tasklist_ontop or '⌃'
style.above Optional string Extra icon when client is above beautiful.tasklist_above or '▴'
style.below Optional string Extra icon when client is below beautiful.tasklist_below or '▾'
style.floating Optional string Extra icon when client is floating beautiful.tasklist_floating or '✈'
style.maximized Optional string Extra icon when client is maximized beautiful.tasklist_maximized or '+'
style.maximized_horizontal Optional string Extra icon when client is maximized_horizontal beautiful.tasklist_maximized_horizontal or '⬌'
style.maximized_vertical Optional string Extra icon when client is maximized_vertical beautiful.tasklist_maximized_vertical or '⬍'
style.disable_task_name Optional boolean beautiful.tasklist_disable_task_name or false
style.font Optional string beautiful.tasklist_font
style.align Optional string left, right or center beautiful.tasklist_align or "left"
style.font_focus Optional string beautiful.tasklist_font_focus
style.font_minimized Optional string beautiful.tasklist_font_minimized
style.font_urgent Optional string beautiful.tasklist_font_urgent
style.spacing Optional number The spacing between tags. beautiful.tasklist_spacing
style.shape Optional gears.shape beautiful.tasklist_shape
style.shape_border_width Optional number beautiful.tasklist_shape_border_width
style.shape_border_color Optional string or color beautiful.tasklist_shape_border_color
style.shape_focus Optional gears.shape beautiful.tasklist_shape_focus
style.shape_border_width_focus Optional number beautiful.tasklist_shape_border_width_focus
style.shape_border_color_focus Optional string or color beautiful.tasklist_shape_border_color_focus
style.shape_minimized Optional gears.shape beautiful.tasklist_shape_minimized
style.shape_border_width_minimized Optional number beautiful.tasklist_shape_border_width_minimized
style.shape_border_color_minimized Optional string or color beautiful.tasklist_shape_border_color_minimized
style.shape_urgent Optional gears.shape beautiful.tasklist_shape_urgent
style.shape_border_width_urgent Optional number beautiful.tasklist_shape_border_width_urgent
style.shape_border_color_urgent Optional string or color beautiful.tasklist_shape_border_color_urgent
style.minimized Optional string or color beautiful.tasklist_minimized
filter DEPRECATED use args.filter Not applicable
buttons DEPRECATED use args.buttons Not applicable
style DEPRECATED use args.style Not applicable
update_function DEPRECATED use args.update_function Not applicable
base_widget DEPRECATED use args.base_layout Not applicable

Click to display more

Consumed theme variables:

Theme variable Usage
beautiful.tasklist_plain_task_name
beautiful.tasklist_fg_normal
beautiful.tasklist_bg_normal
beautiful.tasklist_fg_focus
beautiful.fg_focus
beautiful.tasklist_bg_focus
beautiful.bg_focus
beautiful.tasklist_fg_urgent
beautiful.fg_urgent
beautiful.tasklist_bg_urgent
beautiful.bg_urgent
beautiful.tasklist_fg_minimize
beautiful.fg_minimize
beautiful.tasklist_bg_minimize
beautiful.bg_minimize
beautiful.tasklist_bg_image_normal
beautiful.tasklist_bg_image_focus
beautiful.tasklist_bg_image_urgent
beautiful.tasklist_bg_image_minimize
beautiful.tasklist_disable_icon
beautiful.tasklist_icon_size
beautiful.tasklist_sticky
beautiful.tasklist_ontop
beautiful.tasklist_above
beautiful.tasklist_below
beautiful.tasklist_floating
beautiful.tasklist_maximized
beautiful.tasklist_maximized_horizontal
beautiful.tasklist_maximized_vertical
beautiful.tasklist_disable_task_name
beautiful.tasklist_font
beautiful.tasklist_align
beautiful.tasklist_font_focus
beautiful.tasklist_font_minimized
beautiful.tasklist_font_urgent
beautiful.tasklist_spacing
beautiful.tasklist_shape
beautiful.tasklist_shape_border_width
beautiful.tasklist_shape_border_color
beautiful.tasklist_shape_focus
beautiful.tasklist_shape_border_width_focus
beautiful.tasklist_shape_border_color_focus
beautiful.tasklist_shape_minimized
beautiful.tasklist_shape_border_width_minimized
beautiful.tasklist_shape_border_color_minimized
beautiful.tasklist_shape_urgent
beautiful.tasklist_shape_border_width_urgent
beautiful.tasklist_shape_border_color_urgent
beautiful.tasklist_minimized

Object properties

🔗 count number · 1 signal · read only
The current number of clients.

Note that the tasklist is usually lazy-loaded. Reading this property may cause the widgets to be created. Depending on where the property is called from, it might, in theory, cause an infinite loop.

Constraints:

Default value : The current number of client.
Negative allowed : false

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

 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 {
             row_count   = 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

Constraints:

Default value : wibox.layout.flex.horizontal

See also:

wibox.layout.flex.horizontal Creates and returns a new horizontal flex layout. (wibox.layout.flex) constructors

Click to display more

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. 

 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]

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.

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. 

 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

Constraints:

Default value : awful.widget.tasklist.filter.alltags
Function prototype:
Parameters:
c (client) : The client to accept or reject.
s (screen) : The value of the tasklist screen property.
Return (boolean) : true if the client is accepter or false if it is rejected.

See also:

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

Click to display more

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 or nil · 1 signal
A function called when the tasklist is refreshed.

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

Constraints:

Default value : The default function delegate everything to the widget_template.
Function prototype:
Parameters:
layout (widget) : The base layout object.
buttons (table) : The buttons for this client entry (see below).
label (string) : The client name.
data (table) : Arbitrary metadate.
clients (table) : The list of clients (ordered).
metadata (table) : Other values.
Return : The function returns nothing.

Click to display more

Emit signals:
🔗 widget_template template or nil · 1 signal

A template for creating the client widgets. 

 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,
 }

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:
🔗 source function · 1 signal

A function to gather the clients to display. 

 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

Constraints:

Default value : awful.widget.tasklist.source.all_clients
Function prototype:
Parameters:
s (screen) : The tasklist screen.
metadata (table) : Various metadata.
Return (table) : The list of clients.

See also:

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

Click to display more

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.base
Get or set the children elements.

Constraints:

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

See also:

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

Constraints:

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

See also:

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

Constraints:

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

See also:

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

Constraints:

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

See also:

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

Constraints:

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

See also:

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

Constraints:

Default value : true
Valid values : true or false.

See also:

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

The table contains a list of awful.button objects.

Constraints:

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

See also:

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

Object methods

🔗 :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().
🔗 :connect_signal (name, func) · Inherited from gears.object
Connect to a signal.

Parameters:

Name Type(s) Description
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 Type(s) Description
name string The name of the signal.
func function The callback to call when the signal is emitted.
🔗 :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".
🔗 :disconnect_signal (name, func) · Inherited from gears.object
Disconnect from a signal.

Parameters:

Name Type(s) Description
name string The name of the signal.
func function The callback that should be disconnected.

Theme variables

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

See also:

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

Usage:

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

Click to display more

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

See also:

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

Usage:

    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_normal = col
end

Click to display more

Used by:
🔗 beautiful.tasklist_fg_focus string or pattern
The focused client foreground (text) color.

See also:

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

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_bg_focus string or pattern
The focused client background color.

See also:

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

Usage:

    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_focus = col
end

Click to display more

Used by:
🔗 beautiful.tasklist_fg_urgent string or pattern
The urgent clients foreground (text) color.

See also:

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

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_bg_urgent string or pattern
The urgent clients background color.

See also:

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

Usage:

    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_urgent = col
end

Click to display more

Used by:
🔗 beautiful.tasklist_fg_minimize string or pattern
The minimized clients foreground (text) color.

See also:

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

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_bg_minimize string or pattern
The minimized clients background color.

See also:

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

Usage:

    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

Click to display more

Used by:
🔗 beautiful.tasklist_bg_image_normal string
The elements default background image.
Click to display more

Used by:
🔗 beautiful.tasklist_bg_image_focus string
The focused client background image.
Click to display more

Used by:
🔗 beautiful.tasklist_bg_image_urgent string
The urgent clients background image.
Click to display more

Used by:
🔗 beautiful.tasklist_bg_image_minimize string
The minimized clients background image.
Click to display more

Used by:
🔗 beautiful.tasklist_disable_icon boolean
Disable the tasklist client icons.

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_disable_task_name boolean
Disable the tasklist client titles.

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_plain_task_name boolean
Disable the extra tasklist client property notification icons.

See the Status icons section for more details.

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_sticky string
Extra tasklist client property notification icon for clients with the sticky property set.
Click to display more

Used by:
🔗 beautiful.tasklist_ontop string
Extra tasklist client property notification icon for clients with the ontop property set.
Click to display more

Used by:
🔗 beautiful.tasklist_above string
Extra tasklist client property notification icon for clients with the above property set.
Click to display more

Used by:
🔗 beautiful.tasklist_below string
Extra tasklist client property notification icon for clients with the below property set.
Click to display more

Used by:
🔗 beautiful.tasklist_floating string
Extra tasklist client property notification icon for clients with the floating property set.
Click to display more

Used by:
🔗 beautiful.tasklist_maximized string
Extra tasklist client property notification icon for clients with the maximized property set.
Click to display more

Used by:
🔗 beautiful.tasklist_maximized_horizontal string
Extra tasklist client property notification icon for clients with the maximized_horizontal property set.
Click to display more

Used by:
🔗 beautiful.tasklist_maximized_vertical string
Extra tasklist client property notification icon for clients with the maximized_vertical property set.
Click to display more

Used by:
🔗 beautiful.tasklist_minimized string
Extra tasklist client property notification icon for clients with the minimized property set.
Click to display more

Used by:
🔗 beautiful.tasklist_align string
The focused client alignment.

Type constraints:

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

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_font string
The tasklist font.

See also:

wibox.widget.textbox.font Set a textbox font. (wibox.widget.textbox) object properties

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_font_focus string
The focused client title alignment.

See also:

wibox.widget.textbox.font Set a textbox font. (wibox.widget.textbox) object properties

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_font_minimized string
The minimized clients font.

See also:

wibox.widget.textbox.font Set a textbox font. (wibox.widget.textbox) object properties

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_font_urgent string
The urgent clients font.

See also:

wibox.widget.textbox.font Set a textbox font. (wibox.widget.textbox) object properties

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_spacing number
The space between the tasklist elements.

Type constraints:

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

Usage:

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape gears.shape
The default tasklist elements shape.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_width number
The default tasklist elements border width.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_color string or color
The default tasklist elements border color.

See also:

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

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_focus gears.shape
The focused client shape.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_width_focus number
The focused client border width.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_color_focus string or color
The focused client border color.

See also:

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

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_minimized gears.shape
The minimized clients shape.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_width_minimized number
The minimized clients border width.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_color_minimized string or color
The minimized clients border color.

See also:

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

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_urgent gears.shape
The urgent clients shape.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_width_urgent number
The urgent clients border width.

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

Click to display more

Used by:
🔗 beautiful.tasklist_shape_border_color_urgent string or color
The urgent clients border color.

See also:

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

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

Click to display more

Used by:
🔗 beautiful.tasklist_icon_size integer
The icon size.
Click to display more

Used by:

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. 

 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. 

 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
Name Type(s) Description
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.

 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
Name Type(s) Description
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. 

 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
Name Type(s) Description
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. 

 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
Name Type(s) Description
c client The client.
screen screen The screen we are drawing on.

Signals

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

See also:

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

See also:

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

Arguments:

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

See also:

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

Arguments:

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

See also:

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

Arguments:

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

See also:

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

Arguments:

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

See also:

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