Widgets

ALSAWidget

class qtile_extras.widget.ALSAWidget(*args, **kwargs)

The widget is very simple and, so far, just allows controls for volume up, down and mute.

Volume control is handled by running the appropriate amixer command. The widget is updated instantly when volume is changed via this code, but will also update on an interval (i.e. it will reflect changes to volume made by other programs).

The widget displays volume level via an icon, bar or both. The icon is permanently visible while the bar only displays when the volume is changed and will hide after a user-defined period.

Alternatively, if you select the popup mode then no widget will appear on the bar and, instead, a small popup will be displayed.

The layout of the popup can be customised via the popup_layout parameter. Users should provide a _PopupLayout object. The layout should have at least one of the following controls: a PopupSlider named volume and a PopupText control named text as these controls will be updated whenever the volume changes.

Supported bar orientations: horizontal only

‘icon’ mode

‘bar’ mode

‘both’ mode

Available hooks:

• volume_change

• volume_mute_change

key	default	description
background	None	Widget background color
bar_background	None	Colour of bar background.
bar_colour	'00ffff'	Colour of bar (NB this setting may be overridden by other widget settings).
bar_colour_high	'999900'	Colour of bar if high range
bar_colour_loud	'990000'	Colour of bar in loud range
bar_colour_mute	'999999'	Colour of bar if muted
bar_colour_normal	'009900'	Colour of bar in normal range
bar_height	None	Height of bar (None = full bar height).
bar_text	''	Text to show over bar
bar_text_font	None	Font to use for bar text
bar_text_fontsize	None	Fontsize for bar text
bar_text_foreground	'ffffff'	Colour for bar text
bar_width	75	Width of display bar
decorations	[]	Decorations for widgets
device	'Master'	Name of ALSA device
font	'sans'	Default font
fontsize	None	Font size
foreground	'ffffff'	Font colour
hide_interval	5	Timeout before bar is hidden after update
icon_size	None	Size of the volume icon
limit_high	90	Max percentage for high range
limit_loud	100	Max percentage for loud range
limit_normal	70	Max percentage for normal range
mode	'bar'	Display mode: ‘icon’, ‘bar’, ‘both’, ‘popup’.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	0	Padding before icon
popup_hide_timeout	5	Time before popup hides
popup_layout	<qtile_extras.popup.toolkit.PopupRelativeLayout object at 0x7f8808f207c0>	Layout for popup mode
popup_show_args	{'relative_to': 2, 'relative_to_bar': True, 'y': 50}	Control position of popup
step	5	Amount to increase volume by
text_format	'{volume}%'	String format
theme_path	None	Path to theme icons.
update_interval	5	Interval to update widget (e.g. if changes made in other apps).

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

show_popup()

Method to display the popup.

toggle_mute(*args, **kwargs)

Mute audio output

volume_down(*args, **kwargs)

Decrease volume

volume_up(*args, **kwargs)

Increase volume

AnalogueClock

class qtile_extras.widget.AnalogueClock(*args, **kwargs)

An analogue clock for your Bar.

The size of the clock will be the size of the bar minus 2x the margin. Use padding to add spacing before and after the widget. Finally, the position can be fine adjusted using the adjust_x/y values.

Supported bar orientations: horizontal and vertical

Default config

With square clock face

key	default	description
adjust_x	0	Adjust the x position of the widget
adjust_y	0	Adjust the y position of the widget
background	None	Widget background color
decorations	[]	Decorations for widgets
face_background	None	Shading for clock face
face_border_colour	'00ffff'	Border colour for clock face
face_border_width	1	Thickness of clock face border
face_shape	None	‘square’, ‘circle’ or None
hour_colour	'ffffff'	Colour for the hour hand
hour_length	0.6	Length of hour hand as percentage of radius
hour_size	2	Thickness of hour hand
margin	2	Margin around clock
minute_colour	'ffffff'	Colour for the minute hand
minute_length	0.95	Length of minute hand as percentage of radius
minute_size	2	Thickness of minute hand
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	2	Additional padding at edges of widget
second_colour	'ffffff'	Colour for the second hand
second_length	0.95	Length of minute hand as percentage of radius
second_size	0	Thickness of second hand, 0 to hide.
update_interval	1	Polling interval in secs.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

AnimatedImage

class qtile_extras.widget.AnimatedImage(*args, **kwargs)

A widget to display an animation when clicked.

Supported bar orientations: horizontal and vertical

key	default	description
background	None	Widget background color
decorations	[]	Decorations for widgets
filenames	[]	List of image filename. Can contain ‘~’. Can also be a url.
frame_interval	0.1	Time between individual images
loop_count	1	Number of time to loop through images. 0 to loop forever.
loop_interval	1	Interval before restarting loop
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	0	Padding to left and right of image on horizontal bar, or above and below widget on vertical bar.
scale	True	Resize images to fit bar (as adjusted by margin settings).

animate()

Start the animation.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

stop()

Stop the animation.

Bluetooth

class qtile_extras.widget.Bluetooth(*args, **kwargs)

Modified version of the stock Qtile widget.

The only difference is to add a context menu (on Button 3) to show options for all adapters and devices.

Supported bar orientations: horizontal and vertical

key	default	description
adapter_format	'Adapter: {name} [{powered}{discovery}]'	Text to display when showing adapter device.
adapter_paths	[]	List of DBus object path for bluetooth adapter (e.g. ‘/org/bluez/hci0’). Empty list will show all adapters.
background	None	Widget background color
decorations	[]	Decorations for widgets
default_show_battery	False	Include battery level of ‘connected_devices’ in ‘default_text’. Uses ‘device_battery_format’.
default_text	'BT {connected_devices}'	Text to show when not scrolling through menu. Available fields: ‘connected_devices’ list of connected devices, ‘num_connected_devices’ number of connected devices, ‘adapters’ list of bluetooth adapters, ‘num_adapters’ number of bluetooth adapters.
default_timeout	None	Time before reverting to default_text. If ‘None’, text will stay on selected item.
device	None	Device path, can be found with d-feet or similar dbus explorer. When set, the widget will default to showing this device status.
device_battery_format	' ({battery}%)'	Text to be shown if device reports battery level
device_format	'Device: {name}{battery_level} [{symbol}]'	Text to display when showing bluetooth device. The {adapter field is also available if you’re using multiple adapters.
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
hide_unnamed_devices	False	Devices with no name will be hidden from scan results
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_theme	None	Icon theme for DBus menu items
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	200	Context menu width
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
opacity	1	Menu opacity
padding	None	Padding. Calculated if None.
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
separator	', '	Separator for lists in ‘default_text’.
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu
symbol_connected	'*'	Symbol to indicate device is connected
symbol_discovery	('D', '')	Symbols when adapter is discovering and not discovering
symbol_paired	'-'	Symbol to indicate device is paired but unconnected
symbol_powered	('*', '-')	Symbols when adapter is powered and unpowered.
symbol_unknown	'?'	Symbol to indicate device is unpaired

click()

Perform default action on visible item.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

scroll_down()

Scroll down to next item.

scroll_up()

Scroll up to next item.

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

show_devices(x=None, y=None, centered=False, warp_pointer=False, relative_to=1, relative_to_bar=False, hide_on_timeout=None)

Show menu with available adapters and devices.

BrightnessControl

class qtile_extras.widget.BrightnessControl(*args, **kwargs)

This module provides basic screen brightness controls and a simple widget showing the brightness level for Qtile.

Brightness control is handled by writing to the appropriate /sys/class/backlight device. The widget is updated instantly when the brightness is changed via this code and will autohide after a user-defined timeout.

Note

This script will not work unless the user has write access to the relevant backlight device.

This can be achieved via a udev rule which modifies the group and write permissions. The rule should be saved at /etc/udev/rules.d

An example rule is as follows:

# Udev rule to change group and write permissions for screen backlight
ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="intel_backlight", RUN+="/bin/chgrp video /sys/class/backlight/%k/brightness"
ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="intel_backlight", RUN+="/bin/chmod g+w /sys/class/backlight/%k/brightness"

You should then ensure that your user is a member of the video group.

Supported bar orientations: horizontal only

key	default	description
background	None	Widget background color
bar_background	None	Colour of bar background.
bar_colour	'008888'	Colour of bar displaying brightness level.
bar_height	None	Height of bar (None = full bar height).
bar_text	''	Text to show over bar
bar_text_font	None	Font to use for bar text
bar_text_fontsize	None	Fontsize for bar text
bar_text_foreground	'ffffff'	Colour for bar text
bar_width	75	Width of bar.
brightness_on_battery	'50%'	Brightness level on battery power (accepts integer value or percentage as string)
brightness_on_mains	'100%'	Brightness level on mains power (accepts integer valueor percentage as string)
brightness_path	'brightness'	Name of file holding brightness value
decorations	[]	Decorations for widgets
device	'/sys/class/backlight/intel_backlight'	Path to backlight device
enable_power_saving	False	Automatically set brightness depending on status. Note: this is not checked when the widget is first started.
error_colour	'880000'	Colour of bar when displaying an error
font	'sans'	Default font
fontsize	None	Font size
foreground	'ffffff'	Colour of text.
max_brightness	None	Set value or leave as None to allow device maximum
max_brightness_path	'max_brightness'	Name of file holding max brightness value
min_brightness	100	Minimum brightness. Do not set to 0!
mode	'bar'	Display mode: ‘bar’ shows bar in widget, ‘popup’ to display a popup window
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
popup_hide_timeout	5	Time before popup hides
popup_layout	<qtile_extras.popup.toolkit.PopupRelativeLayout object at 0x7f8808f22cb0>	Layout for popup mode
popup_show_args	{'relative_to': 2, 'relative_to_bar': True, 'y': 50}	Control position of popup
step	'5%'	Amount to change brightness (accepts int or percentage as string)
text_format	'{percentage}%'	Text to display.
timeout_interval	5	Time before widet is hidden.

brightness_down()

Decrease the brightness level

brightness_up()

Increase the brightness level

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

set_brightness_percent(percent)

Set brightness to percentage (0.0-1.0) of max value

set_brightness_value(value)

Set brightess to set value

show_popup()

Method to display the popup.

CPUGraph

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.CPUGraph(*args, **kwargs)

ContinuousPoll

class qtile_extras.widget.ContinuousPoll(*args, **kwargs)

A widget for displaying the continuous output from a process.

Every time a new line is output, the widget will update.

The widget takes an optional parse_line parameter which should be a callable object accepting a line object. The object should return a string to be displayed in the widget. NB the line received by the object is a raw bytestring so you may want to decode() it before manipulating it. The default behaviour (i.e. with no function) is to run .decode().strip() on the text to remove any trailing new line character.

Supported bar orientations: horizontal and vertical

key	default	description
background	None	Widget background color
cmd	None	Command to execute.
decorations	[]	Decorations for widgets
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	None	Padding. Calculated if None.
parse_line	None	Function to parse output of line. See docs for more.
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

run_process(command=None)

Re-run the command or provide a new command to run.

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

stop_process(kill=False)

Stop the running process.

CurrentLayoutIcon

class qtile_extras.widget.CurrentLayoutIcon(*args, **kwargs)

A modified version of Qtile’s CurrentLayoutIcon.

The default version behaves the same as the main qtile version of the widget. However, if you set use_mask to True then you can set the colour of the icon via the foreground parameter.

Supported bar orientations: horizontal only

You can use a single colour or a list of colours.

key	default	description
background	None	Widget background color
custom_icon_paths	[]	List of folders where to search icons beforeusing built-in icons or icons in ~/.icons dir. This can also be used to providemissing icons for custom layouts. Defaults to empty list.
decorations	[]	Decorations for widgets
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	None	Padding. Calculated if None.
scale	1	Scale factor relative to the bar height. Defaults to 1
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
use_mask	False	Uses the icon file as a mask. Icon colour will be set via the foreground parameter.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

GithubNotifications

class qtile_extras.widget.GithubNotifications(*args, **kwargs)

A widget to show when you have new github notifications.

The widget requires a personal access token (see here). The token needs the notifications scope to be enabled. This token should then be saved in a file and the path provided to the token_file parameter.

If your key expires, re-generate a new key, save it to the same file and then call the reload_token command (e.g. via qtile cmd-obj).

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

Available hooks:

• ghn_new_notification

key	default	description
active_colour	'00ffff'	Colour when there are notifications
background	None	Widget background color
decorations	[]	Decorations for widgets
error_colour	'ffff00'	Colour when client has an error (check logs)
icon_size	None	Icon size. None = autofit.
inactive_colour	'ffffff'	Colour when there are no notifications.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	2	Padding around icon.
token_file	'~/.config/qtile-extras/github.token'	Path to file containing personal access token.
update_interval	150	Number of seconds before checking status.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

reload_token()

Force reload of access token.

update()

Trigger a check for new notifications.

GlobalMenu

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.GlobalMenu(*args, **kwargs)

A widget to display a Global Menu (File Edit etc.) in your bar.

Only works with apps that export their menu via DBus.

Wayland support is “experimental” at best. Expect unexpected behaviour!

Required Dependencies

This module requires the following third-party libraries: dbus-next

Supported bar orientations: horizontal only

Showing VLC menu in the bar.

key	default	description
background	None	Widget background color
decorations	[]	Decorations for widgets
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_theme	None	Icon theme for DBus menu items
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	200	Context menu width
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
opacity	1	Menu opacity
padding	3	Padding between items in menu bar
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

GroupBox2

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.GroupBox2(*args, **kwargs)

Formatting of the group box is determined by applying user-defined rules to each group.

Overview:

A rule can set any combination of the following formats:

• text_colour - a string representing the hex value of the colour for the text

• block_colour - a string or list of strings to fill a block

• block_border_width - an integer representing the width of a block border

• block_border_colour - a string representing the colour of the block border

• block_corner_radius - an integer representing radius for curved corners

• line_colour - a string representing the colour of a line

• line_width - an integer representing the width of the line

• line_position - a flag representing where the line should be drawn

• image - path to an image file

• custom_draw - a function that draws to the box

• text - string representing text to display

• box_size - integer to force the size of the individual box

Whether a rule is applied will depend on whether it meets the relevant conditions set for each rule. A rule can set any combination of the following conditions:

• Which screen the group is on (same screen as bar, different screen, no screen)

• Whether the group is focused (i.e. the current group) - boolean True/False

• Whether the group has windows - boolean True/False

• Whether the group has any urgent windows - boolean True/False

• Whether the group name matches a given string

• Whether a user-defined function returns True

Order of drawing:

The widget draws the groupbox in the following order:

• Background colour

• Block

• Block border

• Line

• Image

• Custom draw function

• Text

Explanation of groupbox items:

Block:

Block is a rectangle that can be filled (with block_colour) and/or have an outline (with block_border_width and block_border_colour). The corners of the rectangle can be curved by setting the block_corner_radius value.

The block is positioned by using the margin(_x) and margin_y attributes. NB Currently, these are global for the widget and cannot be set by rules.

Line:

Line is a straight line on the edge of the widget. A line will be drawn at the bottom of the box by default (when a line_colour and line_width have been set). The position of lines can be changed by setting the line_position attribute with a LinePosition flag. For example to drawn lines at the top and bottom of the box you would set the line_position value to:

from qtile_extras.widget.groupbox2 import GroupBoxRule


GroupBoxRule.LINE_TOP | GroupBoxRule.LINE_BOTTOM

NB the line will be rendered at the edge of the box i.e. it is not currently offset by the margin value.

Image:

Image renders any image file in the box. The image will be shrunk so that the height fits within the bar and is also adjusted by the margin(_x) and margin(_y) attributes.

Text:

A rule is able to set custom text for a group box. Where this is not set, the box will display the group’s label or name by default. Setting a value of None will prevent text from being shown.

Custom draw:

You can define a function to draw directly to the box. The function should take a single argument which is the instance of the box. You can access the drawer object and its context via the box.drawer and box.drawer.ctx attributes.

The drawing should be constrained to the rectangle defined by (x=0, y=0, width=box.size, height=box.bar.height). The origin is the top left corner.

For example, to define a rule that draws a red square in the middle of the box for occupied groups, you would do the following:

from qtile_extras.widget.groupbox2 import GroupBoxRule


def draw_red_square(box):

    w = 10
    h = 10
    x = (box.size - w) // 2
    y = (box.bar.height - h) // 2
    box.drawer.ctx.rectangle(x, y, w, h)
    box.drawer.set_source_rgb("ff0000")
    box.drawer.ctx.fill()

# Add this to your rules:
GroupBoxRule(custom_draw=draw_red_square).when(occupied=True)

Creating rules:

Creating a rule has two steps:

• Setting the desired format

• Setting the conditions required for that rule

To help readibility of config files, this is split so the format is set in the rule’s constructor while the conditions are set by the rule’s when() method.

For example, to set a rule that sets the font colour to cyan when a group has windows but is not focused, you would create the following rule:

from qtile_extras.widget.groupbox2 import GroupBoxRule


GroupBoxRule(text_colour="00ffff").when(focused=False, occupied=True)
#                    ^                            ^
#      Format set via constructor    Conditions set via when() method

How to match conditions:

Screen:

Matching a screen condition uses a ScreenRule object. Available options are:

• GroupBoxRule.SCREEN_UNSET (default) - rule ignores screen condition

• GroupBoxRule.SCREEN_THIS - group is on same screen as widget’s bar

• GroupBoxRule.SCREEN_OTHER - group is a different screen to the widget’s bar

• GroupBoxRule.SCREEN_ANY (same as GroupBoxRule.SCREEN_THIS | GroupBoxRule.SCREEN_OTHER) - group is on any screen

• GroupBoxRule.SCREEN_NONE - group is not displayed on a screen

Group focus:

You can match a rule if the group is focused or unfocused by setting focused to True or False respectively. Leaving this attribute blank will ignore focus.

Group has windows:

You can match a rule if the group has windows or is empty by setting occupied to True or False respectively. Leaving this attribute blank will ignore the contents of a group.

Group has urgent windows:

You can match a rule if the group has or does not have any ugent windows by setting urgent to True or False respectively. Leaving this attribute blank will ignore the urgency state of a group.

Match group name:

You can tie a rule to a specific group by setting group_name to the name of a particular group. Leaving this blank will ignore the group’s name.

User-defined functions:

Using custom functions can extend the possibilities for customising the widget. These are set via the func argument.

A function must take two arguments (the GroupBoxRule object and the Box object (that draws the specific box)) and return a boolean (True if the rule should be applied or False if not).

By accessing properties of the Box object, it is possible to fine tune the criteria against which the rule will match. The Box has the following attributes which may be of use here: qtile - the qtile object, group - the specific group represented by the box, bar - the Bar containing this widget.

As an example, to create a rule that is matched when a specific app is open in the group:

from qtile_extras.widget.groupbox2 import GroupBoxRule


def has_vlc(rule, box):
    for win in box.group.windows:
        if "VLC" in win.name:
            return True

    return False

# Include this in your group box rules
# Turns label a nice shade of orange if the group has a VLC window open
GroupBoxRule(text_colour="E85E00").when(func=has_vlc)

In addition, a user-defined function can set display properties dynamically. For example, to have a different icon depending on the state of the group:

from qtile_extras.widget.groupbox2 import GroupBoxRule


def set_label(rule, box):
    if box.focused:
        rule.text = "◉"
    elif box.occupied:
        rule.text = "◎"
    else:
        rule.text = "○"

    return True

# Include this in your group box rules
# NB: The function returns True so this rule will always be run
GroupBoxRule().when(func=set_label)

Rule hierarchy:

Rules are applied in a hierarchy according to the order that they appear in the rules parameter. Once a format has been set by a rule, it cannot be updated by a later rule. However, if one rule sets the text colour a later rule can still set another format (e.g. border colour). To prevent lower priority rules from setting a value, a rule can set the None value for that attribute.

For example:

from qtile_extras.widget.groupbox2 import GroupBoxRule


rules = [
    GroupBoxRule(block_colour="009999").when(screen=GroupBoxRule.SCREEN_THIS),
    GroupBoxRule(block_colour="999999").when(occupied=True),
    GroupBoxRule(text_colour="ffffff")
]

This rule will set all text white but will apply a blue block when the group is shown on the same screen as the widget even if the group is occupied. An occupied group will have a grey background provided it’s not on the same screen as the widget.

Supported bar orientations: horizontal only

example	config
	default
	visible_groups=['1', '2', '3', '4']
	padding_x=5, rules=[<GroupBoxRule format(block_colour=00ffff) when(screen=ScreenRule.THIS)>, <GroupBoxRule format(block_border_colour=999999) when(screen=ScreenRule.OTHER)>, <GroupBoxRule format(text_colour=ffffff) when(occupied=True)>, <GroupBoxRule format(text_colour=999999) when(occupied=False)>]
	padding_x=5, rules=[<GroupBoxRule format(line_colour=00ffff, line_position=LinePosition.RIGHT|LEFT) when(screen=ScreenRule.THIS)>, <GroupBoxRule format(text=+) when(occupied=True)>, <GroupBoxRule format(text=-) when(occupied=False)>, <GroupBoxRule format(text_colour=ffffff) when()>]
	padding_x=5, rules=[<GroupBoxRule format() when(func=<function rainbow at 0x7f16c555ecb0>)>]
	fontsize=20, padding_x=5, rules=[<GroupBoxRule format() when(func=<function set_label at 0x7f16c555ed40>)>, <GroupBoxRule format(text_colour=ff00ff) when(screen=ScreenRule.THIS)>, <GroupBoxRule format(text_colour=e85e00) when(screen=ScreenRule.OTHER)>, <GroupBoxRule format(text_colour=999999) when()>]

key	default	description
background	None	Widget background color
current_screen_focused_width	None	Sets a fixed width for the focused group on the current screen.
decorations	[]	Decorations for widgets
font	'sans'	Font to use for label.
fontshadow	None	Font shadow
fontsize	None	Fontsize for labels,
invert_mouse_wheel	False	Whether to invert mouse wheel group movement
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
markup	False	Use markup.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	3	Padding inside the box
padding_x	None	X Padding. Overrides ‘padding’ if set
padding_y	None	Y Padding. Overrides ‘padding’ if set
rules	[<GroupBoxRule format(line_colour=00ffff) when(screen=ScreenRule.THIS)>, <GroupBoxRule format(line_colour=999999) when(screen=ScreenRule.OTHER)>, <GroupBoxRule format(text_colour=ffffff) when(occupied=True)>, <GroupBoxRule format(text_colour=999999) when(occupied=False)>]	Rules for determining how to format group box. See docstring for fuller explanation.
use_mouse_wheel	True	Whether to use mouse wheel events
visible_groups	None	List of names of groups to show in widget. ‘None’ (default) to show all groups.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

HDDBusyGraph

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.HDDBusyGraph(*args, **kwargs)

HDDGraph

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.HDDGraph(*args, **kwargs)

IWD

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.IWD(*args, **kwargs)

This widget provides information about your wireless connection using iwd.

The widget also allows you to scan for and connect to different networks. If the network is unknown (i.e. you haven’t connected to it before), the widget will launch a window to enter the password (using zenity by default).

NB you cannot join 802.1x networks unless they have already been configured.

Supported bar orientations: horizontal and vertical

example	config
	default
	show_image=True, show_text=False
	show_image=True, show_text=False, wifi_shape='rectangle', wifi_rectangle_width=10

key	default	description
active_colour	'ffffff'	Colour for wifi strength.
background	None	Widget background color
check_connection_interval	0	Interval to check if device connected to internet (0 to disable)
decorations	[]	Decorations for widgets
disconnected_colour	'aa0000'	Colour when device has no internet connection
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
format	'{ssid} ({quality}%)'	Text format. Available fields: ssid, rssi, quality
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_theme	None	Icon theme for DBus menu items
inactive_colour	'666666'	Colour for wifi background.
interface	None	Name of wireless interface. You should only need to set this if you have more than one wireless adapter on your system.
internet_check_host	'8.8.8.8'	IP adddress to check for internet connection
internet_check_port	53	Port to check for internet connection
internet_check_timeout	5	Period before internet check times out and widget reports no internet connection.
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	200	Context menu width
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
opacity	1	Menu opacity
padding	None	Padding. Calculated if None.
password_entry_app	'zenity'	Application for password entry.
password_entry_args	['--entry', '--text', 'Enter password:', '--hide-text']	Additional args to pass to password entry command.
scanning_colour	'3abb3a'	Colour to use for image when scanning is active.
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
separator_colour	'555555'	Colour of menu separator
show_image	False	Shows a graphical representation of signal strength.
show_menu_icons	True	Show icons in context menu
show_text	True	Displays text in bar.
update_interval	2	Polling interval in seconds.
wifi_arc	75	Angle of arc in degrees.
wifi_rectangle_width	5	Width of rectangle in pixels.
wifi_shape	'arc'	‘arc’ or ‘rectangle’

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

scan()

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

show_networks(x=None, y=None, centered=False, warp_pointer=False, relative_to=1, relative_to_bar=False, hide_on_timeout=None)

Show menu with available networks.

Image

class qtile_extras.widget.Image(*args, **kwargs)

A modified version of Qtile’s Image widget.

The two key differences are: 1) The widget accepts a url and will download the image from the internet. 2) The image can be used as a mask and filled with a user-defined colour.

Supported bar orientations: horizontal and vertical

key	default	description
adjust_x	0	Fine x-axis adjustment of icon position
adjust_y	0	Fine y-axis adjustment of icon position
background	None	Widget background color
colour	'ffffff'	Colour to paint maksed image
decorations	[]	Decorations for widgets
filename	None	Image filename. Can contain ‘~’. Can also be a url.
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
mask	False	Use the image as a mask and fill with colour.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	0	Padding to left and right of image on horizontal bar, or above and below widget on vertical bar.
rotate	0.0	rotate the image in degrees counter-clockwise
scale	True	Enable/Disable image scaling

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

update(filename)

LiveFootballScores

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.LiveFootballScores(*args, **kwargs)

The module uses a module I wrote a number of years ago that parses data from the BBC Sport website.

The underlying module needs work so it will probably only work if you pick a “big” team.

You can select more than one team and league. Scores can be scrolled by using the mousewheel over the widget.

Goals and red cards are indicated by a coloured bar next to the relevant team name. The match status is indicated by a coloured bar underneath the match summary. All colours are customisable.

Right-clicking the widget will bring up a list of all matches that meet your selected criteria. Clicking on any of those matches will open a popup showing more detail.

The popup can be accessed directly by the show_detail() command. When this is used, the selected match is the one currently visible in the widget.

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

The different screens show: live score, elapsed time, home and away goalscorers and competition name. In addition, the amount of text shown can be customised by using python’s string formatting techniques e.g. the default line {H:.3} {h}-{a} {A:.3} shows the first 3 letters of team names rather than the full name as shown above.

Available hooks:

• lfs_goal_scored

• lfs_status_change

• lfs_red_card

key	default	description
always_show_red	True	Continue to show red card indicator
background	None	Widget background color
decorations	[]	Decorations for widgets
font	'sans'	Default font
fontsize	None	Font size
foreground	'ffffff'	Text colour
goal_indicator	'009999'	Colour of line to show team that scores
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_theme	None	Icon theme for DBus menu items
info_text	['{T:^12}', '{H:.3}: {G:10}', '{A:.3}: {g:10}', '{C}']	n Add extra text lines which can be displayed by clicking on widget.n Available fields are:n {H}: Home Team namen {A}: Away Team namen {h}: Home scoren {a}: Away scoren {C}: Competitionn {v}: Venuen {T}: Display time (kick-off, elapsed time, HT, FT)n {S}: Status (as above but no elapsed time)n {G}: Home goalscorersn {g}: Away goalscorersn {R}: Home red cardsn {r}: Away red cardsn
info_timeout	5	Time before reverting to default text
leagues	[]	List of leagues you want to display
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	300	Width of menu showing all matches
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
opacity	1	Menu opacity
popup_display_timeout	10	Seconds to show recordings.
popup_font	'monospace'	Font to use for displaying upcoming recordings. A monospace font is recommended
popup_hide_timeout	0	Number of seconds before popup is hidden (0 to disable).
popup_layout	<qtile_extras.popup.toolkit.PopupRelativeLayout object at 0x7f8808d709a0>	Layout to use for extended match information
popup_show_args	{'centered': True, 'hide_on_timeout': 5}	Arguments to set behaviour of extended popup
popup_text	'{H:.20} {h}-{a} {A:.20} ({T:.5})'	Format to use for popup window.
red_card_indicator	'bb0000'	Colour of line to show team has had a player sent off.
refresh_interval	60	Time to update data
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu
startup_delay	30	Time before sending first web request
status_fixture	'000000'	Colour when match has not started
status_fulltime	'666666'	Colour when match has ended
status_halftime	'aaaa00'	Colour when half time
status_live	'008800'	Colour when match is live
status_text	'{H:.3} {h}-{a} {A:.3}'	Default widget match text
team	'Liverpool'	Team whose scores you want to display
teams	[]	List of other teams you want to display
underline_status	True	Bar at bottom of widget to indicate status.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

get()

Get displayed text. Removes padding.

info()

Show information about all matches

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

popup()

Display window listing all matches

reboot()

Sometimes the widget won’t update (and I don’t know why). This method should reset everything and start the widget again.

Can be bound to a key e.g.:

lazy.widget[“livefootballscores”].reboot

refresh()

Force a poll of match data.

show_detail()

Displays popup showing detailed info about match.

show_matches(x=None, y=None, centered=False, warp_pointer=False, relative_to=1, relative_to_bar=False, hide_on_timeout=None)

Show menu with followed matchs.

show_popup()

Method to display the popup.

MemoryGraph

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.MemoryGraph(*args, **kwargs)

Mpris2

class qtile_extras.widget.Mpris2(*args, **kwargs)

Modified version of the base Mpris2 widget.

This version adds a popup with player controls. Users can provide a custom template for the popup using the popup_layout parameter.

The popup can be toggled with the toggle_player command.

The following fields are available (controls should set their ‘name’ to this value):

• ‘title’: Track title

• ‘artist’: Track artist

• ‘album’: Album name

• ‘player’: Media player name

• ‘artwork’: Path to artwork (to be used with a PopupImage control)

• ‘progress’: Progress through thrack (to be used with a PopupSlider control)

• ‘position’: Current playback position e.g. ‘03:40’

• ‘length’: Track length e.g. ‘05:15’

• ‘time’: String showing position and total length e.g. ‘03:40 / 05:15’

To control playback, the template should have controls named:

• ‘play_pause’

• ‘stop’

• ‘previous’

• ‘next’

When shown, the controls can be selected using the mouse or keyboard navigation. The popup can be hidden by pressing <escape> or by calling the toggle_player command.

Two pre-defined layouts are currently provided and can be loadeded via:

from qtile_extras import widget
from qtile_extras.popup.templates.mpris2 import COMPACT_LAYOUT, DEFAULT_LAYOUT

...

# NB DEFAULT_LAYOUT is included by default and does not need to be imported in
# your config
widget.Mpris2(popup_layout=COMPACT_LAYOUT)

The layouts look like this:

DEFAULT_LAYOUT
COMPACT_LAYOUT

Supported bar orientations: horizontal and vertical

Available hooks:

• mpris_new_track

• mpris_status_change

key	default	description
background	None	Widget background color
decorations	[]	Decorations for widgets
default_artwork	'/home/docs/checkouts/readthedocs.org/user_builds/qtile-extras/checkouts/v0.27.0.post1/qtile_extras/resources/media-icons/default.png'	Image to display in popup when there’s no art
display_metadata	['xesam:title', 'xesam:album', 'xesam:artist']	(Deprecated) Which metadata identifiers to display.
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
format	'{xesam:title} - {xesam:album} - {xesam:artist}'	Format string for displaying metadata. See http://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/#index5h3 for available values
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
name	'audacious'	Name of the MPRIS widget.
no_metadata_text	'No metadata for current track'	Text to show when track has no metadata
objname	None	DBUS MPRIS 2 compatible player identifier- Find it out with dbus-monitor - Also see: http://specifications.freedesktop.org/mpris-spec/latest/#Bus-Name-Policy. None will listen for notifications from all MPRIS2 compatible players.
padding	None	Padding. Calculated if None.
parse_artwork	<function parse_artwork at 0x7f8808c1e7a0>	Function to parse artwork path.
paused_text	'Paused: {track}'	Text to show when paused
playing_text	'{track}'	Text to show when playing
poll_interval	0	Periodic background polling interval of player (0 to disable polling).
popup_hide_timeout	0	Number of seconds before popup is hidden (0 to disable).
popup_layout	<qtile_extras.popup.toolkit.PopupRelativeLayout object at 0x7f8808d088e0>	Layout for player controls.
popup_show_args	{'relative_to': 2, 'relative_to_bar': True}	Where to place popup
scroll	True	Whether text should scroll.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
separator	', '	Separator for metadata fields that are a list.
stop_pause_text	None	(Deprecated) Optional text to display when in the stopped/paused state
stopped_text	''	Text to show when stopped

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

What’s the current state of the widget?

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

next() → None

Play the next track.

play_pause() → None

Toggle the playback status.

previous() → None

Play the previous track.

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

show_popup()

Method to display the popup.

stop() → None

Stop playback.

toggle_player()

NetGraph

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.NetGraph(*args, **kwargs)

PulseVolume

class qtile_extras.widget.PulseVolume(*args, **kwargs)

Same as qtile’s PulseVolume widget but includes the ability to select the default output sink via the select_sink() command. This is bound to the middle-click button on the widget by default.

Supported bar orientations: horizontal only

key	default	description
background	None	Widget background color
cardid	None	Card Id
channel	'Master'	Channel
check_mute_command	None	Command to check mute status
check_mute_string	'[off]'	String expected from check_mute_command when volume is muted.When the output of the command matches this string, theaudio source is treated as muted.
decorations	[]	Decorations for widgets
device	'default'	Device Name
emoji	False	Use emoji to display volume states, only if theme_path is not set.The specified font needs to contain the correct unicode characters.
emoji_list	['🔇', '🔈', '🔉', '🔊']	List of emojis/font-symbols to display volume states, only if emoji is set. List contains 4 symbols, from lowest volume to highest.
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
get_volume_command	None	Command to get the current volume. The expected output should include 1-3 numbers and a % sign.
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_theme	None	Icon theme for DBus menu items
limit_max_volume	False	Limit maximum volume to 100%
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	300	Width of list showing available sinks.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
mute_command	None	Mute command
mute_foreground	None	Foreground color for mute volume.
mute_format	'M'	Format to display when volume is muted.
opacity	1	Menu opacity
padding	3	Padding left and right. Calculated if None.
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu
step	2	Volume change for up an down commands in percentage.Only used if volume_up_command and volume_down_command are not set.
theme_path	None	Path of the icons
unmute_format	'{volume}%'	Format of text to display when volume is not muted.
update_interval	0.2	Update time in seconds.
volume_app	None	App to control volume
volume_down_command	None	Volume down command
volume_up_command	None	Volume up command

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

decrease_vol(value=None)

Decrease volume.

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

increase_vol(value=None)

Increase volume.

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

mute()

Mute the sound device.

run_app()

select_sink(x=None, y=None, centered=False, warp_pointer=False, relative_to=1, relative_to_bar=False, hide_on_timeout=None)

Select output sink from available sinks.

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

PulseVolumeExtra

class qtile_extras.widget.PulseVolumeExtra(*args, **kwargs)

Volume widget for systems using PulseAudio.

The appearance is identical to ALSAWidget but this widget uses qtile’s PulseVolume widget to set/retrieve volume levels. As a result, you will need the pulsectl_asyncio library to use this widget.

Finally, the widget allows users to select the output sink by middle clicking on the widget or calling the select_sink() command.

Supported bar orientations: horizontal only

‘icon’ mode

‘bar’ mode

‘both’ mode

Available hooks:

• volume_change

• volume_mute_change

key	default	description
background	None	Widget background color
bar_background	None	Colour of bar background.
bar_colour	'00ffff'	Colour of bar (NB this setting may be overridden by other widget settings).
bar_colour_high	'999900'	Colour of bar if high range
bar_colour_loud	'990000'	Colour of bar in loud range
bar_colour_mute	'999999'	Colour of bar if muted
bar_colour_normal	'009900'	Colour of bar in normal range
bar_height	None	Height of bar (None = full bar height).
bar_text	''	Text to show over bar
bar_text_font	None	Font to use for bar text
bar_text_fontsize	None	Fontsize for bar text
bar_text_foreground	'ffffff'	Colour for bar text
bar_width	75	Width of display bar
cardid	None	Card Id
channel	'Master'	Channel
check_mute_command	None	Command to check mute status
check_mute_string	'[off]'	String expected from check_mute_command when volume is muted.When the output of the command matches this string, theaudio source is treated as muted.
decorations	[]	Decorations for widgets
device	'Master'	Name of ALSA device
emoji	False	Use emoji to display volume states, only if theme_path is not set.The specified font needs to contain the correct unicode characters.
emoji_list	['🔇', '🔈', '🔉', '🔊']	List of emojis/font-symbols to display volume states, only if emoji is set. List contains 4 symbols, from lowest volume to highest.
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size
foreground	'ffffff'	Font colour
get_volume_command	None	Command to get the current volume. The expected output should include 1-3 numbers and a % sign.
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
hide_interval	5	Timeout before bar is hidden after update
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_size	None	Size of the volume icon
icon_theme	None	Icon theme for DBus menu items
limit_high	90	Max percentage for high range
limit_loud	100	Max percentage for loud range
limit_max_volume	False	Limit maximum volume to 100%
limit_normal	70	Max percentage for normal range
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	300	Width of list showing available sinks.
mode	'bar'	Display mode: ‘icon’, ‘bar’, ‘both’, ‘popup’.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
mute_command	None	Mute command
mute_foreground	None	Foreground color for mute volume.
mute_format	'M'	Format to display when volume is muted.
opacity	1	Menu opacity
padding	0	Padding before icon
popup_hide_timeout	5	Time before popup hides
popup_layout	<qtile_extras.popup.toolkit.PopupRelativeLayout object at 0x7f8808f207c0>	Layout for popup mode
popup_show_args	{'relative_to': 2, 'relative_to_bar': True, 'y': 50}	Control position of popup
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu
step	5	Amount to increase volume by
text_format	'{volume}%'	String format
theme_path	None	Path to theme icons.
unmute_format	'{volume}%'	Format of text to display when volume is not muted.
update_interval	5	Interval to update widget (e.g. if changes made in other apps).
volume_app	None	App to control volume
volume_down_command	None	Volume down command
volume_up_command	None	Volume up command

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

decrease_vol(value=None)

Decrease volume.

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

increase_vol(value=None)

Increase volume.

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

mute()

Mute the sound device.

run_app()

select_sink(x=None, y=None, centered=False, warp_pointer=False, relative_to=1, relative_to_bar=False, hide_on_timeout=None)

Select output sink from available sinks.

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

show_popup()

Method to display the popup.

toggle_mute(*args, **kwargs)

Mute audio output

volume_down(value=None)

Decrease volume.

volume_up(value=None)

Increase volume.

QTEMirror

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.QTEMirror(*args, **kwargs)

A modified version of Qtile’s Mirror widget.

The only difference is to ensure mirrored widgets are sized correctly.

..important:

The mirror will also reflect any decorations of the original widget. Therefore,
if you need different decoration behaviour, you must create a new instance of the
widget.

This widget should not be created directly by users.

ScriptExit

class qtile_extras.widget.ScriptExit(*args, **kwargs)

An updated version of Qtile’s QuickExit widget.

Takes an additional argument exit_script which will be run before qtile exits.

Supported bar orientations: horizontal and vertical

key	default	description
background	None	Widget background color
countdown_format	'[ {} seconds ]'	The text displayed when counting down.
countdown_start	5	The number to count down from.
decorations	[]	Decorations for widgets
default_text	'[ shutdown ]'	The text displayed on the button.
exit_script	''	Script to run on exit.
fmt	'{}'	Format to apply to the string returned by the widget. Main purpose: applying markup. For a widget that returns foo, using fmt='<i>{}</i>' would give you <i>foo</i>. To control what the widget outputs in the first place, use the format paramater of the widget (if it has one).
font	'sans'	Default font
fontshadow	None	font shadow color, default is None(no shadow)
fontsize	None	Font size. Calculated if None.
foreground	'ffffff'	Foreground colour
markup	True	Whether or not to use pango markup
max_chars	0	Maximum number of characters to display in widget.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	None	Padding. Calculated if None.
scroll	False	Whether text should be scrolled. When True, you must set the widget’s width.
scroll_clear	False	Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay	2	Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_fixed_width	False	When scroll=True the width parameter is a maximum width and, when text is shorter than this, the widget will resize. Setting scroll_fixed_width=True will force the widget to have a fixed width, regardless of the size of the text.
scroll_hide	False	Whether the widget should hide when scrolling has finished
scroll_interval	0.1	Time in seconds before next scrolling step
scroll_repeat	True	Whether text should restart scrolling once the text has ended
scroll_step	1	Number of pixels to scroll with each step
timer_interval	1	The countdown interval.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

set_font(font: str | None = None, fontsize: int = 0, fontshadow: str | tuple[int, int, int] | tuple[int, int, int, float] = '')

Change the font used by this widget. If font is None, the current font is used.

trigger()

SnapCast

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.SnapCast(*args, **kwargs)

A widget to run a snapclient instance in the background.

This is a work in progress. The plan is to add the ability for the client to change groups from widget.

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

Snapclient active running in background

key	default	description
active_colour	'ffffff'	Colour when client is active and connected to server
background	None	Widget background color
client_name	None	Client name (as recognised by server).
decorations	[]	Decorations for widgets
error_colour	'ffff00'	Colour when client has an error (check logs)
icon_size	None	Icon size. None = autofit.
inactive_colour	'999999'	Colour when client is inactive
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
options	''	Options to be passed to snapclient.
padding	2	Padding around icon (and text).
server_address	'localhost'	Name or IP address of server.
server_reconnect_interval	15	Interval before retrying to find player on server after failed attempt
snapclient	'/usr/bin/snapclient'	Path to snapclient

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

toggle_state()

Toggle Snapcast on and off.

StatusNotifier

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.StatusNotifier(*args, **kwargs)

A modified version of the default Qtile StatusNotifier widget.

Added the ability to render context menus by right-clicking on the icon.

Required Dependencies

This module requires the following third-party libraries: dbus-next, xdg

Supported bar orientations: horizontal and vertical

Widget showing Remmina icon and context menu.

key	default	description
background	None	Widget background color
decorations	[]	Decorations for widgets
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_size	16	Icon width
icon_theme	None	Name of theme to use for app icons
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	200	Context menu width
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
opacity	1	Menu opacity
padding	3	Padding between icons
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

StravaWidget

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.StravaWidget(*args, **kwargs)

This module provides a simple widget showing some Strava stats.

The widget text can be customised using the following keys:

prefix	suffix	value
C		Current month
Y		Calendar year
A		All time
	D	Distance
	C	Count
	T	Time
	P	Pace
	N	Name
	A	Date

For example, the default text {CA:%b} {CD:.1f}km displays the current date in abbreviated month name format and the distance run that month: “Aug 143.1km”.

Extended info is provided by clicking on the widget.

Note

You will need to follow the instuctions at https://developers.strava.com/ to create a new app and authorise it.

Your id and secret should be put in a json file called auth.json in ~/.cache/stravawidget

The token file generated by the authorisation process, strava.json, should also be placed in the same folder.

Required Dependencies

This module requires the following third-party libraries: stravalib, pint

Supported bar orientations: horizontal only

Extended info. I’ve blurred out details of my runs for privacy reasons.

key	default	description
background	None	Widget background color
decorations	[]	Decorations for widgets
font	'sans'	Default font
fontsize	None	Font size
foreground	'ffffff'	Text colour
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
popup_display_timeout	15	Time to display extended info
refresh_interval	1800	Time to update data
startup_delay	10	Time before sending first web request
text	'{CA:%b} {CD:.1f}km'	Widget text
warning_colour	'aaaa00'	Highlight when there is an error.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

SwapGraph

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.SwapGraph(*args, **kwargs)

Syncthing

class qtile_extras.widget.Syncthing(*args, **kwargs)

A widget to show the sync status of a Syncthing server.

By default, the widget displays an icon in the bar which is grey when no syncing is occurring but changes to white when syncing starts.

The widget can be configured to monitor a specific device or folder. By default, it monitors the local device at the server address.

Note: there is no verification of SSL certificates when connecting to the host. If this is a problem for you, please start an issue on the github page.

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

Available hooks:

• st_sync_started

• st_sync_stopped

key	default	description
api_key	None	API key for the Syncthing server instance.
background	None	Widget background color
bar_background	None	Colour of bar background.
bar_colour	'008888'	Bar colour.
bar_height	10	Height of sync progress bar.
bar_text	''	Text to show over bar
bar_text_font	None	Font to use for bar text
bar_text_fontsize	None	Fontsize for bar text
bar_text_foreground	'ffffff'	Colour for bar text
bar_text_format	'{percentage:.0%}'	Format string to display text on progress bar.
bar_width	75	Width of bar.
decorations	[]	Decorations for widgets
filter	{}	Limit the status check to a specific folder or device. Takes a dictionary where the key is either ‘folder’ or ‘device’ and the value is the appropriate ID. An empty ‘folder’ will aggregate all folders. An empty ‘device’ will use the local device. Default (empty dictionary) aggregates all folders on local device.
hide_on_idle	True	Hide widget if no sync in progress.
icon_colour_error	'ffff00'	Colour for Syncthing logo when there’s an error.
icon_colour_idle	'999999'	Colour for Syncthing logo when idle.
icon_colour_sync	'ffffff'	Colour for Syncthing logo when syncing.
icon_size	None	Icon size. None = autofit.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	2	Padding around icon.
server	'http://localhost:8384'	Syncthing API server.
show_bar	False	Show progress bar when syncing.
show_icon	True	Show icon.
update_interval	5	Time before updating status.
update_interval_syncing	1	Time before updating while syncing.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

Systray

Note

This class has just been modified to enable compatibility with features provided by qtile-extras. No new functionality has been added.

class qtile_extras.widget.Systray(*args, **kwargs)

A modified version of Qtile’s Systray widget.

The only difference is to improve behaviour of the icon background when using RectDecoration decorations.

This widget does not and will not fix the issue with icons having a transparent background when displaying on a (semi-)transparent bar.

TVHWidget

class qtile_extras.widget.TVHWidget(*args, **kwargs)

A widget to show whether a TVHeadend server is currently recording or not.

The widget will also show a popup displaying upcoming recordings.

When the server is recording a red line will be shown under the icon. If there’s an error, a yellow line will show above the icon (and check the logs).

NB if you use a username and password, these are stored in plain text. You may therefore wish to create an unprivileged user account in TVHeadend that only has access to scheduled recordings data.

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

Available hooks:

• tvh_recording_started

• tvh_recording_ended

key	default	description
auth	None	Auth details for accessing tvh. Can be None, tuple of (username, password).
auth_type	'basic'	HTTP authentication type: ‘digest’ or ‘basic’
background	None	Widget background color
decorations	[]	Decorations for widgets
hide_duplicates	True	Remove duplicate recordings from list of upcoming recordings.
host	'http://localhost:9981/api'	TVHeadend server address
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
popup_display_timeout	10	Seconds to show recordings.
popup_font	'monospace'	Font to use for displaying upcoming recordings. A monospace font is recommended
popup_format	'{start:%a %d %b %H:%M}: {title:.40}'	Upcoming recording text.
popup_opacity	0.8	Opacity for popup window.
popup_padding	10	Padding for popup window.
recording_colour	'bb0000'	Highlight when TVHeadend is recording
refresh_interval	30	Time to update data
startup_delay	5	Time before sending first web request
tvh_timeout	5	Seconds before timeout for timeout request
upcoming_recordings_path	'/dvr/entry/grid_upcoming'	API point for retrieving data on upcoming recordings.
warning_colour	'aaaa00'	Highlight when there is an error.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

UPowerWidget

class qtile_extras.widget.UPowerWidget(*args, **kwargs)

A graphical widget to display laptop battery level.

The widget uses dbus to read the battery information from the UPower interface.

The widget will display one icon for each battery found or users can specify the name of the battery if they only wish to display one.

Clicking on the widget will display the battery level and the time to empty/full.

All colours can be customised as well as low/critical percentage levels.

Required Dependencies

This module requires the following third-party libraries: dbus-next

Supported bar orientations: horizontal only

Normal

Low

Critical

Charging

Multiple batteries

Showing text

Available hooks:

• up_power_connected

• up_power_disconnected

• up_battery_full

• up_battery_low

• up_battery_critical

key	default	description
background	None	Widget background color
battery_height	10	Height of battery icon
battery_name	None	Battery name. None = all batteries
battery_width	20	Size of battery icon
border_charge_colour	'8888ff'	Border colour when charging.
border_colour	'dbdbe0'	Border colour when discharging.
border_critical_colour	'cc0000'	Border colour when battery low.
decorations	[]	Decorations for widgets
fill_charge	None	Override fill colour when charging
fill_critical	'cc0000'	Fill when critically low
fill_low	'aa00aa'	Fill colour when battery low
fill_normal	'dbdbe0'	Fill when normal
font	'sans'	Default font
fontsize	None	Font size
foreground	'ffffff'	Font colour for information text
margin	2	Margin on sides of widget
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
percentage_critical	0.1	Critical level threshold.
percentage_low	0.2	Low level threshold.
spacing	5	Space between batteries
text_charging	'({percentage:.0f}%) {ttf} until fully charged'	Text to display when charging.
text_discharging	'({percentage:.0f}%) {tte} until empty'	Text to display when on battery.
text_displaytime	5	Time for text to remain before hiding

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

UnitStatus

class qtile_extras.widget.UnitStatus(*args, **kwargs)

UnitStatus is a basic widget for Qtile which shows the current status of systemd units.

It may not be particular useful for you and was primarily written as an exercise to familiarise myself with writing Qtile widgets and interacting with d-bus.

The widget is incredibly basic. It subscribes to the systemd d-bus interface, finds the relevant service and displays an icon based on the current status. The widget listens for announced changes to the service and updates the icon accordingly.

Required Dependencies

This module requires the following third-party libraries: dbus-next

Supported bar orientations: horizontal only

key	default	description
background	None	Widget background color
bus_name	'system'	Which bus to use. Accepts ‘system’ or ‘session’.
colour_active	'00ff00'	Colour for active indicator
colour_dead	'666666'	Colour for dead indicator
colour_failed	'ff0000'	Colour for active indicator
colour_inactive	'ffffff'	Colour for active indicator
decorations	[]	Decorations for widgets
font	'sans'	Default font
fontsize	None	Font size
foreground	'ffffff'	Font colour
indicator_size	10	Size of indicator (None = up to margin)
label	'NM'	Short text to display next to indicator.
margin	3	Margin inside the box
margin_x	None	X Margin. Overrides ‘margin’ if set
margin_y	None	Y Margin. Overrides ‘margin’ if set
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	3	Padding inside the box
padding_x	None	X Padding. Overrides ‘padding’ if set
padding_y	None	Y Padding. Overrides ‘padding’ if set
state_map	{'activating': ('colour_active', 'colour_inactive'), 'active': ('colour_active', 'colour_active'), 'deactivating': ('colour_inactive', 'colour_active'), 'dead': ('colour_dead', 'colour_dead'), 'failed': ('colour_failed', 'colour_failed'), 'inactive': ('colour_inactive', 'colour_inactive'), 'not-found': ('colour_inactive', 'colour_failed')}	Map of indicator colours (border, fill)
unitname	'NetworkManager.service'	Name of systemd unit.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

Visualiser

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.Visualiser(*args, **kwargs)

A widget to draw an audio visualiser in your bar.

The widget requires cava to be installed. This may also be packaged by your distro.

cava is configured through the widget. Currently, you can set the number of bars and the framerate.

Warning

Rendering the visualiser directly in qtile’s bar is almost certainly not an efficient way to have a visualiser in your setup. You should therefore be aware that this widget uses more processing power than other widgets so you may see CPU usage increase when using this. However, if the CPU usage continues to increase the longer you use the widget then that is likely to be a bug and should be reported!

Supported bar orientations: horizontal only

Default config.

key	default	description
autostart	True	Start visualiser automatically
background	None	Widget background color
bar_colour	'#ffffff'	Colour of visualiser bars
bar_height	20	Height of visualiser bars
bars	8	Number of bars
cava_path	None	Path to cava. Set if file is not in your PATH.
cava_pipe	'/tmp/cava.pipe'	Pipe for cava’s output
channels	'mono'	Visual channels. ‘mono’ or ‘stereo’.
decorations	[]	Decorations for widgets
framerate	25	Cava sampling rate.
hide	True	Hide the visualiser when not active
invert	False	When True, bars will draw from the top down
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
spacing	2	Space between bars
width	100	Widget width

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

start()

Start the visualiser.

stop()

Stop this visualiser.

toggle()

Toggle visualiser state.

Visualizer

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

qtile_extras.widget.Visualizer

alias of Visualiser

WiFiIcon

class qtile_extras.widget.WiFiIcon(*args, **kwargs)

An simple graphical widget that shows WiFi status.

Left-clicking the widget will show the name of the network.

The widget can also periodically poll an external IP address to check whether the device is connected to the internet. To enable this, you need to set the check_connection_interval.

Required Dependencies

This module requires the following third-party libraries: iwlib

Supported bar orientations: horizontal only

Additional detail is visible when clicking on icon

key	default	description
active_colour	'ffffff'	Colour for wifi strength.
background	None	Widget background color
check_connection_interval	0	Interval to check if device connected to internet (0 to disable)
decorations	[]	Decorations for widgets
disconnected_colour	'aa0000'	Colour when device has no internet connection
expanded_timeout	5	Time in secs for expanded information to display when clicking on icon.
font	'sans'	Default font
fontsize	None	Font size
foreground	'ffffff'	Font colour for information text
inactive_colour	'666666'	Colour for wifi background.
interface	'wlan0'	Name of wifi interface.
internet_check_host	'8.8.8.8'	IP adddress to check for internet connection
internet_check_port	53	Port to check for internet connection
internet_check_timeout	5	Period before internet check times out and widget reports no internet connection.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
padding	3	Padding inside the box
padding_x	None	X Padding. Overrides ‘padding’ if set
padding_y	None	Y Padding. Overrides ‘padding’ if set
show_ssid	False	Show SSID and signal strength.
update_interval	1	Polling interval in secs.
wifi_arc	75	Angle of arc in degrees.
wifi_rectangle_width	5	Width of rectangle in pixels.
wifi_shape	'arc'	‘arc’ or ‘rectangle’

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

hide()

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

show_text()

WordClock

class qtile_extras.widget.WordClock(*args, **kwargs)

A widget to draw a word clock to the screen.

This is not a traditional widget in that you will not see anything displayed in your bar. The widget works in the background and updates the screen wallpaper when required. However, having this as a widget provides an easy way for users to install and configure the clock.

The clocks are currently designed to update on 5 minute intervals “five past” -> “ten past” etc. This may be changed in the future.

Custom layouts can be added by referring to the instructions in qtile_extras/resources/wordclock/english.py.

Supported languages

Available languages: Dutch, English, Finnish, French, Portuguese, Spanish, Swedish

Supported bar orientations: horizontal and vertical

key	default	description
active	'00AAAA'	Colour for active characters
background	'000000'	Background colour.
cache	'~/.cache/qtile-extras'	Location to store wallpaper
decorations	[]	Decorations for widgets
font	'sans'	Font for text
fontsize	70	Font size for letters
inactive	'202020'	Colour for inactive characters
language	'english'	Display language. Choose from ‘dutch’, ‘english’, ‘finnish’, ‘french’, ‘portuguese’, ‘spanish’, ‘swedish’.
mouse_callbacks	{}	Dict of mouse button press callback functions. Accepts functions and lazy calls.
update_interval	1	Interval to check time

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) → tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) → None

Call a function with current object as argument

info()

Info for this object.

items(name: str) → tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a “naked” specification without an item seletion (e.g. “layout” defaults to current layout), and False if it does not (e.g. no default “widget”).

items: a list of contained items

Mixins

ConnectionCheckMixin

class qtile_extras.widget.mixins.ConnectionCheckMixin

Mixin to periodically check for internet connection and set the self.is_connected flag depending on status.

Your code should include the following lines to use the mixin.

class MyInternetWidget(ConnectionCheckMixin):
    def __init__(self):
        self.add_defaults(ConnectionCheckMixin.defaults)
        ConnectionCheckMixin.__init__(self)

    def _configure(self, qtile, bar):
        ConnectionCheckMixin._configure(self)

key	default	description
check_connection_interval	0	Interval to check if device connected to internet (0 to disable)
disconnected_colour	'aa0000'	Colour when device has no internet connection
internet_check_host	'8.8.8.8'	IP adddress to check for internet connection
internet_check_port	53	Port to check for internet connection
internet_check_timeout	5	Period before internet check times out and widget reports no internet connection.

DbusMenuMixin

class qtile_extras.widget.mixins.DbusMenuMixin(**config)

Builds a menu from qtile_extras.resources.dbusmenu.DBusMenuItem objects.

Should be used where a widget is accessing menu data over DBus.

When calling qtile_extras.resources.dbusmenu.DBusMenu.get_menu, the callback should be set to the widget’s display_menu method.

key	default	description
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_theme	None	Icon theme for DBus menu items
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	200	Context menu width
opacity	1	Menu opacity
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu

ExtendedPopupMixin

class qtile_extras.widget.mixins.ExtendedPopupMixin(**kwargs)

Mixin that provides the ability for a widget to display extended detail in popups via the Popup toolkit.

It is not mandatory for widgets to use this if they want to use the toolkit. However, the mixin provides some standard variable and method names.

self.extended_popup	the popup instance or None
self._popup_hide_timer	the current timer object for hiding the popup or None
self.has_popup	property that returns True is popup is defined and not killed
self.update_popup()	method to call to update popup contents. Should not be overriden as it calls self._update_popup (see below) but only if self.has_popup is True
self._update_popup()	method that actually updates the contents. This will raise a NotImplementedError if called without being overriden.
self._set_popup_timer()	sets the timer to kill the popup.
self._kill_popup()	kills the popup
self.show_popup()	displays the popup. Is also exposed to command interface so can be used in lazy calls etc.

key	default	description
popup_hide_timeout	0	Number of seconds before popup is hidden (0 to disable).
popup_layout	None	The popup layout definition
popup_show_args	{'centered': True}	Arguments to be passed to popup.show()

GraphicalWifiMixin

class qtile_extras.widget.mixins.GraphicalWifiMixin

Provides the ability to draw a graphical representation of wifi signal strength.

To use the mixin, your code needs to include the following:

class MyGraphicalInternetWidget(GraphicalWifiMixin):
    def __init__(self):
        self.add_defaults(GraphicalWifiMixin.defaults)
        GraphicalWifiMixin.__init__(self)

    def _configure(self, qtile, bar):
        ... # other configuration lines here

        self.set_wifi_sizes()

    def draw(self):
        # To draw the icon you need the following parameters:
        # - percentage: a value between 0 and 1
        # - foreground: the colour of the indicator
        # - background: the colour of the indicator background
        self.draw_wifi(percentage=percentage, foreground=foreground, background=background)

Note

This mixin does not set the width of your widget but does provide a self.wifi_width attribute which can be used for this purpose.

key	default	description
wifi_arc	75	Angle of arc in degrees.
wifi_rectangle_width	5	Width of rectangle in pixels.
wifi_shape	'arc'	‘arc’ or ‘rectangle’

MenuMixin

class qtile_extras.widget.mixins.MenuMixin(**config)

Provides the relevant settings to help configure a context menu to be displayed by the widget.

The use of the mixin ensures that all menus use the same property names which allows users to theme menus more easily e.g. by setting values in widget_defaults.

key	default	description
hide_after	0.5	Time in seconds before hiding menu atfer mouse leave
highlight_colour	'0060A0'	Colour of highlight for menu items (None for no highlight)
highlight_radius	5	Radius for menu highlight
icon_theme	None	Icon theme for DBus menu items
menu_background	'333333'	Background colour for menu
menu_border	'111111'	Menu border colour
menu_border_width	0	Width of menu border
menu_font	'sans'	Font for menu text
menu_fontsize	12	Font size for menu text
menu_foreground	'ffffff'	Font colour for menu text
menu_foreground_disabled	'aaaaaa'	Font colour for disabled menu items
menu_foreground_highlighted	None	Font colour for highlighted item (None to use menu_foreground value)
menu_icon_size	12	Size of icons in menu (where available)
menu_offset_x	0	Fine tune x position of menu
menu_offset_y	0	Fine tune y position of menu
menu_row_height	None	Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) “None” will attempt to calculate height based on font size.
menu_width	200	Context menu width
opacity	1	Menu opacity
separator_colour	'555555'	Colour of menu separator
show_menu_icons	True	Show icons in context menu

ProgressBarMixin

class qtile_extras.widget.mixins.ProgressBarMixin(**kwargs)

Mixin to allow widgets to display progress bars.

Bar is drawn based on a bar_value between 0.0 and 1.0 inclusive.

To use it, subclass and add this to __init__:

ProgressBarMixin.__init__(self, **kwargs)
self.add_defaults(ProgressBarMixin.defaults)

To draw the bar, you need to call self.bar_draw(). The method take a number of optional parameters. Where these are not set in the method call then the instance version i.e. self.parameter_name will be used insted.

bar.draw optional parameters:

• x_offset (default 0): horizontal positioning of the bar

• bar_colour: colour of the bar

• bar_background: colour drawn behind the bar (i.e. to show extent of bar)

• bar_text: text to draw on bar,

• bar_text_foreground: text colour,

• bar_value: percentage of bar to fill

Note

The widget should ensure that its width is sufficient to display the bar (the bar_width property is relevant here).

key	default	description
bar_background	None	Colour of bar background.
bar_colour	'00ffff'	Colour of bar (NB this setting may be overridden by other widget settings).
bar_height	None	Height of bar (None = full bar height).
bar_text	''	Text to show over bar
bar_text_font	None	Font to use for bar text
bar_text_fontsize	None	Fontsize for bar text
bar_text_foreground	'ffffff'	Colour for bar text
bar_width	75	Width of bar.

TooltipMixin

class qtile_extras.widget.mixins.TooltipMixin(**kwargs)

Mixin that provides a tooltip for widgets.

To use it, subclass and add this to __init__:

TooltipMixin.__init__(self, **kwargs)
self.add_defaults(TooltipMixin.defaults)

Widgets should set self.tooltip_text to change display text.

key	default	description
tooltip_background	'#000000'	Background colour for tooltip
tooltip_color	'#ffffff'	Font colur for tooltop
tooltip_delay	1	Time in seconds before tooltip displayed
tooltip_font	'sans'	Font colour for tooltop
tooltip_fontsize	12	Font size for tooltop
tooltip_padding	4	int for all sides or list for [top/bottom, left/right]