# 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 `id`s, 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:

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

- gears.object
- - wibox.widget.base
  - - awful.widget.tasklist

### 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 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 (update_function and layout) serve to customize the layout of the tasklist (eg. to make it vertical). For that, you will need to copy the awful.widget.common.list_update function, make your changes to it and pass it as update_function here. Also change the layout if the default is not what you want.

  ### Parameters:

  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:

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

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

  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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_bg_image_normal string
  The elements default background image.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_bg_image_focus string
  The focused client background image.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_bg_image_urgent string
  The urgent clients background image.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_bg_image_minimize string
  The minimized clients background image.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_sticky string
  Extra tasklist client property notification icon for clients with the sticky property set.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_ontop string
  Extra tasklist client property notification icon for clients with the ontop property set.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_above string
  Extra tasklist client property notification icon for clients with the above property set.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_below string
  Extra tasklist client property notification icon for clients with the below property set.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_floating string
  Extra tasklist client property notification icon for clients with the floating property set.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_maximized string
  Extra tasklist client property notification icon for clients with the maximized property set.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_minimized string
  Extra tasklist client property notification icon for clients with the minimized property set.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 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:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.
🔗 beautiful.tasklist_icon_size integer
  The icon size.
  Click to display more

  ### Used by:

  - awful.widget.tasklist Create a new tasklist widget.
  - awful.widget.tasklist Create a new tasklist widget.

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