Module: `awful.widget.taglist`

Taglist widget module for awful.

Here is a more advanced example of how to extent the taglist. It provides:

mouse "hover" color
an extra index field
a powerline look and feel

Usage example

s.mytaglist = awful.widget.taglist {
    screen  = s,
    filter  = awful.widget.taglist.filter.all,
    style   = {
        shape = gears.shape.powerline
    },
    layout   = {
        spacing = -12,
        spacing_widget = {
            color  = "#dddddd",
            shape  = gears.shape.powerline,
            widget = wibox.widget.separator,
        },
        layout  = wibox.layout.fixed.horizontal
    },
    widget_template = {
        {
            {
                {
                    {
                        {
                            id     = "index_role",
                            widget = wibox.widget.textbox,
                        },
                        margins = 4,
                        widget  = wibox.container.margin,
                    },
                    bg     = "#dddddd",
                    shape  = gears.shape.circle,
                    widget = wibox.container.background,
                },
                {
                    {
                        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  = 18,
            right = 18,
            widget = wibox.container.margin
        },
        id     = "background_role",
        widget = wibox.container.background,
        -- Add support for hover colors and an index label
        create_callback = function(self, c3, index, objects) --luacheck: no unused args
            self:get_children_by_id("index_role")[1].markup = "<b> "..c3.index.." </b>"
            self:connect_signal("mouse::enter", function()
                if self.bg ~= "#ff0000" then
                    self.backup     = self.bg
                    self.has_backup = true
                end
                self.bg = "#ff0000"
            end)
            self:connect_signal("mouse::leave", function()
                if self.has_backup then self.bg = self.backup end
            end)
        end,
        update_callback = function(self, c3, index, objects) --luacheck: no unused args
            self:get_children_by_id("index_role")[1].markup = "<b> "..c3.index.." </b>"
        end,
    },
    buttons = taglist_buttons
}

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

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

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

create_callback: Called once after the widget instance is created
update_callback: Called every time the data is refreshed

Both callback have the same parameters:

self: The widget instance (widget).
t: The tag (tag)
index: The widget position in the list (number)
tags: The list of tag, in order (table)

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.taglist (args, filter, buttons, style[, update_function[, base_widget]])

Create a new taglist widget.

Object properties

screen	screen	The taglist screen.
base_layout	wibox.layout	Set the taglist layout.
count	number	The current number of tags. read only
update_function	function	An alternative function to configure the content.
filter	function	A function to restrict the content of the taglist.
source	function	The function used to gather the group of tags.
widget_template	table	A templete used to genetate the individual tag widgets.
children	table	Get or set the children elements.	Inherited from wibox.widget
all_children	table	Get all direct and indirect children widgets.	Inherited from wibox.widget
forced_height	number or nil	Force a widget height.	Inherited from wibox.widget
forced_width	number or nil	Force a widget width.	Inherited from wibox.widget
opacity	number	The widget opacity (transparency).	Inherited from wibox.widget
visible	boolean	The widget visibility.	Inherited from wibox.widget
buttons	table	The widget buttons.	Inherited from wibox.widget

Object methods

:setup {[args]}	Set a declarative widget hierarchy description.	Inherited from wibox.widget
:add_button (button)	Add a new awful.button to this widget.	Inherited from wibox.widget
:emit_signal_recursive (signal_name, ...)	Emit a signal and ensure all parent widgets in the hierarchies also forward the signal.	Inherited from wibox.widget
:emit_signal (name, ...)	Emit a signal.	Inherited from gears.object
:connect_signal (name, func)	Connect to a signal.	Inherited from gears.object
:weak_connect_signal (name, func)	Connect to a signal weakly.	Inherited from gears.object

Signals

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

Theme variables

beautiful.taglist_fg_focus	color	The tag list main foreground (text) color.
beautiful.taglist_bg_focus	color	The tag list main background color.
beautiful.taglist_fg_urgent	color	The tag list urgent elements foreground (text) color.
beautiful.taglist_bg_urgent	color	The tag list urgent elements background color.
beautiful.taglist_bg_occupied	color	The tag list occupied elements background color.
beautiful.taglist_fg_occupied	color	The tag list occupied elements foreground (text) color.
beautiful.taglist_bg_empty	color	The tag list empty elements background color.
beautiful.taglist_fg_empty	color	The tag list empty elements foreground (text) color.
beautiful.taglist_bg_volatile	color	The tag list volatile elements background color.
beautiful.taglist_fg_volatile	color	The tag list volatile elements foreground (text) color.
beautiful.taglist_squares_sel	surface	The selected elements background image.
beautiful.taglist_squares_unsel	surface	The unselected elements background image.
beautiful.taglist_squares_sel_empty	surface	The selected empty elements background image.
beautiful.taglist_squares_unsel_empty	surface	The unselected empty elements background image.
beautiful.taglist_squares_resize	boolean	If the background images can be resized.
beautiful.taglist_disable_icon	boolean	Do not display the tag icons, even if they are set.
beautiful.taglist_font	string	The taglist font.
beautiful.taglist_spacing	number	The space between the taglist elements.
beautiful.taglist_shape	gears.shape	The main shape used for the elements.
beautiful.taglist_shape_border_width	number	The shape elements border width.
beautiful.taglist_shape_border_color	color	The elements shape border color.
beautiful.taglist_shape_empty	gears.shape	The shape used for the empty elements.
beautiful.taglist_shape_border_width_empty	number	The shape used for the empty elements border width.
beautiful.taglist_shape_border_color_empty	color	The empty elements shape border color.
beautiful.taglist_shape_focus	gears.shape	The shape used for the selected elements.
beautiful.taglist_shape_border_width_focus	number	The shape used for the selected elements border width.
beautiful.taglist_shape_border_color_focus	color	The selected elements shape border color.
beautiful.taglist_shape_urgent	gears.shape	The shape used for the urgent elements.
beautiful.taglist_shape_border_width_urgent	number	The shape used for the urgent elements border width.
beautiful.taglist_shape_border_color_urgent	color	The urgents elements shape border color.
beautiful.taglist_shape_volatile	gears.shape	The shape used for the volatile elements.
beautiful.taglist_shape_border_width_volatile	number	The shape used for the volatile elements border width.
beautiful.taglist_shape_border_color_volatile	color	The volatile elements shape border color.

List source functions

awful.widget.taglist.source.for_screen

All tags for the defined screen ordered by indices.

List filters

awful.widget.taglist.filter.noempty	Filtering function to include all nonempty tags on the screen.
awful.widget.taglist.filter.selected	Filtering function to include selected tags on the screen.
awful.widget.taglist.filter.all	Filtering function to include all tags on the screen.

Constructors

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

Create a new taglist widget. The last two arguments (updatefunction and layout) serve to customize the layout of the taglist (eg. to make it vertical). For that, you will need to copy the awful.widget.common.listupdate function, make your changes to it and pass it as update_function here. Also change the layout if the default is not what you want.

Parameters:

args
- screen screen The screen to draw taglist for.
- filter function[opt=nil] Filter function to define what clients will be listed.
- buttons table A table with buttons binding to set.
- update_function function Function to create a tag widget on each update. See awful.widget.common. (optional)
- layout widget Optional layout widget for tag widgets. Default is wibox.layout.fixed.horizontal(). (optional)
- source function The function used to generate the list of tag. (default awful.widget.taglist.source.for_screen)
- widget_template table A custom widget to be used for each tag (optional)
- style table The style overrides default theme. (default {})
- style.fg_focus string or pattern The foreground color for focused client.
- style.bg_focus string or pattern The background color for focused client.
- style.fg_urgent string or pattern The foreground color for urgent clients.
- style.bg_urgent string or pattern The background color for urgent clients.
- style.bg_occupied string or pattern (default nil)
- style.fg_occupied string or pattern (default nil)
- style.bg_empty string or pattern (default nil)
- style.fg_empty string or pattern (default nil)
- style.bg_volatile string or pattern (default nil)
- style.fg_volatile string or pattern (default nil)
- style.squares_sel string A user provided image for selected squares. (optional)
- style.squares_unsel string A user provided image for unselected squares. (optional)
- style.squares_sel_empty string A user provided image for selected squares for empty tags. (optional)
- style.squares_unsel_empty string A user provided image for unselected squares for empty tags. (optional)
- style.squares_resize boolean True or false to resize squares. (optional)
- style.disable_icon string (default nil)
- style.font string The font.
- style.spacing number The spacing between tags. (default nil)
- style.squares_sel string A user provided image for selected squares. (optional)
- style.squares_unsel string A user provided image for unselected squares. (optional)
- style.squares_sel_empty string A user provided image for selected squares for empty tags. (optional)
- style.squares_unsel_empty string A user provided image for unselected squares for empty tags. (optional)
- style.squares_resize boolean True or false to resize squares. (optional)
- style.bg_focus string or pattern The background color for focused client.
- style.fg_focus string or pattern The foreground color for focused client.
- style.bg_urgent string or pattern The background color for urgent clients.
- style.fg_urgent string or pattern The foreground color for urgent clients.
- style.font string The font.
filter DEPRECATED use args.filter
buttons DEPRECATED use args.buttons
style DEPRECATED use args.style
update_function DEPRECATED use args.update_function
base_widget DEPRECATED use args.base_layout

Object properties

screen screen

The taglist screen.

base_layout wibox.layout

Set the taglist layout.

Type constraints:

The number number of tags.

Click to display more

Emit signals:

property::count When the count value changes.

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

update_function function

An alternative function to configure the content.

You should use widget_template if it fits your use case first. This API is very low level.

filter function

A function to restrict the content of the taglist.

Type constraints:

children table The children.

all_children table · Inherited from wibox.widget

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

Type constraints:

children table The children.

forced_height number or nil · Inherited from wibox.widget

Force a widget height.

Type constraints:

height number or nil The height (nil for automatic)

forced_width number or nil · Inherited from wibox.widget

Force a widget width.

Type constraints:

width number or nil The width (nil for automatic)

opacity number · Inherited from wibox.widget

The widget opacity (transparency).

Type constraints:

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

visible boolean · Inherited from wibox.widget

The widget visibility.

buttons table · Inherited from wibox.widget

The widget buttons.

The table contains a list of awful.button objects.

Object methods

:setup {[args]} · Inherited from wibox.widget

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

Parameters:

args An array containing the widgets disposition

:add_button (button) · Inherited from wibox.widget

Add a new awful.button to this widget.

Parameters:

button awful.button The button to add.

:emit_signal_recursive (signal_name, ...) · Inherited from wibox.widget

Emit a signal and ensure all parent widgets in the hierarchies also forward the signal. This is useful to track signals when there is a dynamic set of containers and layouts wrapping the widget.

Parameters:

signal_name string
... Other arguments

:emit_signal (name, ...) · Inherited from gears.object

Emit a signal.

Parameters:

name string The name of the signal.
... Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

:connect_signal (name, func) · Inherited from gears.object

Connect to a signal.

Parameters:

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

:weak_connect_signal (name, func) · Inherited from gears.object

Connect to a signal weakly.

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

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

Signals

widget::layout_changed · Inherited from wibox.widget

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

Arguments:

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

Arguments:

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

Arguments:

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

Arguments:

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

Theme variables

beautiful.taglist_fg_focus color

The tag list main foreground (text) color.

Type constraints:

spacing number The spacing between tags. (default 0)

beautiful.taglist_shape gears.shape

The main shape used for the elements. This will be the fallback for state specific shapes. To get a shape for the whole taglist, use wibox.container.background.

List source functions

awful.widget.taglist.source.for_screen

All tags for the defined screen ordered by indices.

This is the default source.

List filters

awful.widget.taglist.filter.noempty

Filtering function to include all nonempty tags on the screen.

t The tag.

awful.widget.taglist.filter.selected

Filtering function to include selected tags on the screen.

t The tag.

awful.widget.taglist.filter.all

Filtering function to include all tags on the screen.

awesome

Contents

Widgets

Core components

Input handling

Declarative rules

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

Documentation

Module: awful.widget.taglist

Info:

Constructors

Object properties

Object methods

Signals

Theme variables

List source functions

List filters

Constructors

Parameters:

Object properties

See also:

Type constraints:

Emit signals:

See also:

See also:

Type constraints:

Type constraints:

Type constraints:

Type constraints:

Type constraints:

See also:

Object methods

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Signals

See also:

See also:

Arguments:

See also:

Arguments:

See also:

Arguments:

See also:

Arguments:

See also:

Theme variables

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

Type constraints:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

Module: `awful.widget.taglist`