Built-in Widgets

AGroupBox

class libqtile.widget.AGroupBox(**config)[source]

A widget that graphically displays the current group

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

border

'000000'

‘group box border color’

borderwidth

3

‘Current group border width’

center_aligned

True

‘center-aligned group box’

fmt

'{}'

‘How to format the text’

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’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

padding_x

None

“X Padding. Overrides ‘padding’ if set”

padding_y

None

“Y Padding. Overrides ‘padding’ if set”

Backlight

class libqtile.widget.Backlight(**config)[source]

A simple widget to show the current brightness of a monitor.

If the change_command parameter is set to None, the widget will attempt to use the interface at /sys/class to change brightness. Depending on the setup, the user may need to be added to the video group to have permission to write to this interface. This depends on having the correct udev rules the brightness file; these are typically installed alongside brightness tools such as brightnessctl (which changes the group to ‘video’) so installing that is an easy way to get it working.

You can also bind keyboard shortcuts to the backlight widget with:

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

backlight_name

'acpi_video0'

‘ACPI name of a backlight device’

brightness_file

'brightness'

‘Name of file with the current brightness in /sys/class/backlight/backlight_name’

change_command

'xbacklight -set {0}'

‘Execute command to change value’

fmt

'{}'

‘How to format the text’

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

'{percent:2.0%}'

‘Display format’

markup

True

‘Whether or not to use pango markup’

max_brightness_file

'max_brightness'

‘Name of file with the maximum brightness in /sys/class/backlight/backlight_name’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

step

10

‘Percent of backlight every scroll changed’

update_interval

0.2

‘The delay in seconds between updates’

Battery

class libqtile.widget.Battery(**config)[source]

A text-based battery monitoring widget currently supporting FreeBSD

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

battery

0

‘Which battery should be monitored (battery number or name)’

charge_char

'^'

‘Character to indicate the battery is charging’

discharge_char

'V'

‘Character to indicate the battery is discharging’

empty_char

'x'

‘Character to indicate the battery is empty’

fmt

'{}'

‘How to format the text’

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

'{char} {percent:2.0%} {hour:d}:{min:02d} {watt:.2f} W'

‘Display format’

full_char

'='

‘Character to indicate the battery is full’

hide_threshold

None

‘Hide the text when there is enough energy 0 <= x < 1’

low_foreground

'FF0000'

‘Font color on low battery’

low_percentage

0.1

‘Indicates when to use the low_foreground color 0 < x < 1’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

notify_below

None

‘Send a notification below this battery level.’

padding

None

‘Padding. Calculated if None.’

show_short_text

True

‘Show “Full” or “Empty” rather than formated text’

unknown_char

'?'

‘Character to indicate the battery status is unknown’

update_interval

60

‘Seconds between status updates’

BatteryIcon

class libqtile.widget.BatteryIcon(**config)[source]

Battery life indicator widget.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

battery

0

‘Which battery should be monitored’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

theme_path

'/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/stable/libqtile/resources/battery-icons'

‘Path of the icons’

update_interval

60

‘Seconds between status updates’

BitcoinTicker

class libqtile.widget.BitcoinTicker(**config)[source]

A bitcoin ticker widget, data provided by the coinbase.com API. Defaults to displaying currency in whatever the current locale is. Examples:

# display the average price of bitcoin in local currency
widget.BitcoinTicker()

# display it in Euros:
widget.BitcoinTicker(currency="EUR")

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

currency

''

‘The currency the value that bitcoin is displayed in’

data

None

‘Post Data’

fmt

'{}'

‘How to format the text’

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’

headers

{}

‘Extra Headers’

json

True

‘Is Json?’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

parse

None

‘Parse Function’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

url

None

‘Url’

user_agent

'Qtile'

‘Set the user agent’

xml

False

‘Is XML?’

CPU

class libqtile.widget.CPU(**config)[source]

A simple widget to display CPU load and frequency.

Widget requirements: psutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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

'CPU {freq_current}GHz {load_percent}%'

‘CPU display format’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

1.0

‘Update interval for the CPU widget’

CPUGraph

class libqtile.widget.CPUGraph(**config)[source]

Display CPU usage graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

border_color

'215578'

‘Widget border color’

border_width

2

‘Widget border width’

core

'all'

‘Which core to show (all/0/1/2/…)’

fill_color

'1667EB.3'

‘Fill color for linefill graph’

frequency

1

‘Update frequency in seconds’

graph_color

'18BAEB'

‘Graph color’

line_width

3

‘Line width’

margin_x

3

‘Margin X’

margin_y

3

‘Margin Y’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

samples

100

‘Count of graph samples.’

start_pos

'bottom'

“Drawer starting position (‘bottom’/’top’)”

type

'linefill'

“‘box’, ‘line’, ‘linefill’”

Canto

class libqtile.widget.Canto(**config)[source]

Display RSS feeds updates using the canto console reader

Supported bar orientations: horizontal only

key

default

description

all_format

'{number}'

‘All feeds display format’

background

None

‘Widget background color’

feeds

[]

‘List of feeds to display, empty for all’

fetch

False

‘Whether to fetch new items on update’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

one_format

'{name}: {number}'

‘One feed display format’

padding

None

‘Padding. Calculated if None.’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

CapsNumLockIndicator

class libqtile.widget.CapsNumLockIndicator(**config)[source]

Really simple widget to show the current Caps/Num Lock state.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

0.5

‘Update Time in seconds.’

CheckUpdates

class libqtile.widget.CheckUpdates(**config)[source]

Shows number of pending updates in different unix systems

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

colour_have_updates

'ffffff'

‘Colour when there are updates.’

colour_no_updates

'ffffff'

“Colour when there’s no updates.”

custom_command

None

‘Custom shell command for checking updates (counts the lines of the output)’

display_format

'Updates: {updates}'

‘Display format if updates available’

distro

'Arch'

‘Name of your distribution’

execute

None

‘Command to execute on click’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

no_update_string

''

‘String to display if no updates available’

padding

None

‘Padding. Calculated if None.’

restart_indicator

''

‘Indicator to represent reboot is required. (Ubuntu only)’

update_interval

60

‘Update interval in seconds.’

Chord

class libqtile.widget.Chord(width=CALCULATED, **config)[source]

Display current key chord

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

chords_colors

{}

“colors per chord in form of tuple (‘bg’, ‘fg’).”

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

name_transform

<function Chord.<lambda> at 0x7fc2145b5440>

‘preprocessor for chord name it is pure function string -> string’

padding

None

‘Padding. Calculated if None.’

Clipboard

class libqtile.widget.Clipboard(width=CALCULATED, **config)[source]

Display current clipboard contents

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

blacklist

['keepassx']

‘list with blacklisted wm_class, sadly not every clipboard window sets them, keepassx does.Clipboard contents from blacklisted wm_classes will be replaced by the value of blacklist_text.’

blacklist_text

'***********'

‘text to display when the wm_class is blacklisted’

fmt

'{}'

‘How to format the text’

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_width

10

‘maximum number of characters to display (None for all, useful when width is bar.STRETCH)’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

selection

'CLIPBOARD'

‘the selection to display(CLIPBOARD or PRIMARY)’

timeout

10

‘Default timeout (seconds) for display text, None to keep forever’

Clock

class libqtile.widget.Clock(**config)[source]

A simple but flexible text-based clock

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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

'%H:%M'

‘A Python datetime format string’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

timezone

None

‘The timezone to use for this clock, either as string if pytz or dateutil is installed (e.g. “US/Central” or anything in /usr/share/zoneinfo), or as tzinfo (e.g. datetime.timezone.utc). None means the system local timezone and is the default.’

update_interval

1.0

‘Update interval for the clock’

Cmus

class libqtile.widget.Cmus(**config)[source]

A simple Cmus widget.

Show the artist and album of now listening song and allow basic mouse control from the bar:

  • toggle pause (or play if stopped) on left click;

  • skip forward in playlist on scroll up;

  • skip backward in playlist on scroll down.

Cmus (https://cmus.github.io) should be installed.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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

noplay_color

'cecece'

‘Text colour when not playing.’

padding

None

‘Padding. Calculated if None.’

play_color

'00ff00'

‘Text colour when playing.’

update_interval

0.5

‘Update Time in seconds.’

Countdown

class libqtile.widget.Countdown(**config)[source]

A simple countdown timer text widget

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

date

datetime.datetime(2021, 2, 13, 15, 2, 52, 286895)

‘The datetime for the endo of the countdown’

fmt

'{}'

‘How to format the text’

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

'{D}d {H}h {M}m {S}s'

‘Format of the displayed text. Available variables:{D} == days, {H} == hours, {M} == minutes, {S} seconds.’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

1.0

‘Update interval in seconds for the clock’

CurrentLayout

class libqtile.widget.CurrentLayout(width=CALCULATED, **config)[source]

Display the name of the current layout of the current group of the screen, the bar containing the widget, is on.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

CurrentLayoutIcon

class libqtile.widget.CurrentLayoutIcon(**config)[source]

Display the icon representing the current layout of the current group of the screen on which the bar containing the widget is.

If you are using custom layouts, a default icon with question mark will be displayed for them. If you want to use custom icon for your own layout, for example, FooGrid, then create a file named “layout-foogrid.png” and place it in ~/.icons directory. You can as well use other directories, but then you need to specify those directories in custom_icon_paths argument for this plugin.

The order of icon search is:

  • dirs in custom_icon_paths config argument

  • ~/.icons

  • built-in qtile icons

Supported bar orientations: horizontal only

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

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

scale

1

‘Scale factor relative to the bar height. Defaults to 1’

CurrentScreen

class libqtile.widget.CurrentScreen(width=CALCULATED, **config)[source]

Indicates whether the screen this widget is on is currently active or not

Supported bar orientations: horizontal only

key

default

description

active_color

'00ff00'

‘Color when screen is active’

active_text

'A'

‘Text displayed when the screen is active’

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

inactive_color

'ff0000'

‘Color when screen is inactive’

inactive_text

'I'

‘Text displayed when the screen is inactive’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

DF

class libqtile.widget.DF(**config)[source]

Disk Free Widget

By default the widget only displays if the space is less than warn_space.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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

'{p} ({uf}{m}|{r:.0f}%)'

‘String format (p: partition, s: size, f: free space, uf: user free space, m: measure, r: ratio (uf/s))’

markup

True

‘Whether or not to use pango markup’

measure

'G'

‘Measurement (G, M, B)’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

partition

'/'

‘the partition to check space’

update_interval

60

‘The update interval.’

visible_on_warn

True

‘Only display if warning’

warn_color

'ff0000'

‘Warning color’

warn_space

2

‘Warning space in scale defined by the measure option.’

DebugInfo

class libqtile.widget.DebugInfo(**config)[source]

Displays debugging infos about selected window

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

GenPollText

class libqtile.widget.GenPollText(**config)[source]

A generic text widget that polls using poll function to get the text

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

func

None

‘Poll Function’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

GenPollUrl

class libqtile.widget.GenPollUrl(**config)[source]

A generic text widget that polls an url and parses it using parse function

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

data

None

‘Post Data’

fmt

'{}'

‘How to format the text’

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’

headers

{}

‘Extra Headers’

json

True

‘Is Json?’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

parse

None

‘Parse Function’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

url

None

‘Url’

user_agent

'Qtile'

‘Set the user agent’

xml

False

‘Is XML?’

GmailChecker

class libqtile.widget.GmailChecker(**config)[source]

A simple gmail checker. If ‘status_only_unseen’ is True - set ‘fmt’ for one argument, ex. ‘unseen: {0}’

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

display_fmt

'inbox[{0}],unseen[{1}]'

‘Display format’

email_path

'INBOX'

‘email_path’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

password

None

‘password’

status_only_unseen

False

‘Only show unseen messages’

update_interval

30

‘Update time in seconds.’

username

None

‘username’

GroupBox

class libqtile.widget.GroupBox(**config)[source]

A widget that graphically displays the current group. All groups are displayed by their label. If the label of a group is the empty string that group will not be displayed.

Supported bar orientations: horizontal only

key

default

description

active

'FFFFFF'

‘Active group font colour’

background

None

‘Widget background color’

block_highlight_text_color

None

‘Selected group font colour’

borderwidth

3

‘Current group border width’

center_aligned

True

‘center-aligned group box’

disable_drag

False

‘Disable dragging and dropping of group names on widget’

fmt

'{}'

‘How to format the text’

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_unused

False

‘Hide groups that have no windows and that are not displayed on any screen.’

highlight_color

['000000', '282828']

“Active group highlight color when using ‘line’ highlight method.”

highlight_method

'border'

“Method of highlighting (‘border’, ‘block’, ‘text’, or ‘line’)Uses *_border color settings”

inactive

'404040'

‘Inactive group font colour’

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

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

other_current_screen_border

'404040'

‘Border or line colour for group on other screen when focused.’

other_screen_border

'404040'

‘Border or line colour for group on other screen when unfocused.’

padding

None

‘Padding. Calculated if None.’

padding_x

None

“X Padding. Overrides ‘padding’ if set”

padding_y

None

“Y Padding. Overrides ‘padding’ if set”

rounded

True

‘To round or not to round box borders’

spacing

None

‘Spacing between groups(if set to None, will be equal to margin_x)’

this_current_screen_border

'215578'

‘Border or line colour for group on this screen when focused.’

this_screen_border

'215578'

‘Border or line colour for group on this screen when unfocused.’

urgent_alert_method

'border'

“Method for alerting you of WM urgent hints (one of ‘border’, ‘text’, ‘block’, or ‘line’)”

urgent_border

'FF0000'

‘Urgent border or line color’

urgent_text

'FF0000'

‘Urgent group font color’

use_mouse_wheel

True

‘Whether to use mouse wheel events’

visible_groups

None

‘Groups that will be visible. If set to None or [], all groups will be visible.Visible groups are identified by name not by their displayed label.’

HDDBusyGraph

class libqtile.widget.HDDBusyGraph(**config)[source]

Display HDD busy time graph

Parses /sys/block/<dev>/stat file and extracts overall device IO usage, based on io_ticks’s value. See https://www.kernel.org/doc/Documentation/block/stat.txt

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

border_color

'215578'

‘Widget border color’

border_width

2

‘Widget border width’

device

'sda'

‘Block device to display info for’

fill_color

'1667EB.3'

‘Fill color for linefill graph’

frequency

1

‘Update frequency in seconds’

graph_color

'18BAEB'

‘Graph color’

line_width

3

‘Line width’

margin_x

3

‘Margin X’

margin_y

3

‘Margin Y’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

samples

100

‘Count of graph samples.’

start_pos

'bottom'

“Drawer starting position (‘bottom’/’top’)”

type

'linefill'

“‘box’, ‘line’, ‘linefill’”

HDDGraph

class libqtile.widget.HDDGraph(**config)[source]

Display HDD free or used space graph

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

border_color

'215578'

‘Widget border color’

border_width

2

‘Widget border width’

fill_color

'1667EB.3'

‘Fill color for linefill graph’

frequency

1

‘Update frequency in seconds’

graph_color

'18BAEB'

‘Graph color’

line_width

3

‘Line width’

margin_x

3

‘Margin X’

margin_y

3

‘Margin Y’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

path

'/'

‘Partition mount point.’

samples

100

‘Count of graph samples.’

space_type

'used'

‘free/used’

start_pos

'bottom'

“Drawer starting position (‘bottom’/’top’)”

type

'linefill'

“‘box’, ‘line’, ‘linefill’”

IdleRPG

class libqtile.widget.IdleRPG(**config)[source]

A widget for monitoring and displaying IdleRPG stats.

# display idlerpg stats for the player 'pants' on freenode's #idlerpg
widget.IdleRPG(url="http://xethron.lolhosting.net/xml.php?player=pants")

Widget requirements: xmltodict.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

data

None

‘Post Data’

fmt

'{}'

‘How to format the text’

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

'IdleRPG: {online} TTL: {ttl}'

‘Display format’

headers

{}

‘Extra Headers’

json

False

‘Not json :)’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

parse

None

‘Parse Function’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

url

None

‘Url’

user_agent

'Qtile'

‘Set the user agent’

xml

True

‘Is XML :)’

Image

class libqtile.widget.Image(length=CALCULATED, width=None, **config)[source]

Display a PNG image on the bar

Supported bar orientations: horizontal and vertical

key

default

description

background

None

‘Widget background color’

filename

None

“Image filename. Can contain ‘~’”

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

rotate

0.0

‘rotate the image in degrees counter-clockwise’

scale

True

‘Enable/Disable image scaling’

ImapWidget

class libqtile.widget.ImapWidget(**config)[source]

Email IMAP widget

This widget will scan one of your imap email boxes and report the number of unseen messages present. I’ve configured it to only work with imap with ssl. Your password is obtained from the Gnome Keyring.

Writing your password to the keyring initially is as simple as (changing out <userid> and <password> for your userid and password):

  1. create the file ~/.local/share/python_keyring/keyringrc.cfg with the following contents:

    [backend]
    default-keyring=keyring.backends.Gnome.Keyring
    keyring-path=/home/<userid>/.local/share/keyring/
    
  2. Execute the following python shell script once:

    #!/usr/bin/env python3
    import keyring
    user = <userid>
    password = <password>
    keyring.set_password('imapwidget', user, password)
    

mbox names must include the path to the mbox (except for the default INBOX). So, for example if your mailroot is ~/Maildir, and you want to look at the mailbox at HomeMail/fred, the mbox setting would be: mbox="~/Maildir/HomeMail/fred". Note the nested sets of quotes! Labels can be whatever you choose, of course.

Widget requirements: keyring.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

label

'INBOX'

‘label for display’

markup

True

‘Whether or not to use pango markup’

mbox

'"INBOX"'

‘mailbox to fetch’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

server

None

‘email server name’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

user

None

‘email username’

KeyboardKbdd

class libqtile.widget.KeyboardKbdd(**config)[source]

Widget for changing keyboard layouts per window, using kbdd

kbdd should be installed and running, you can get it from: https://github.com/qnikst/kbdd

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

colours

None

“foreground colour for each layouteither ‘None’ or a list of colours.example: [‘ffffff’, ‘E6F0AF’]. “

configured_keyboards

['us', 'ir']

“your predefined list of keyboard layouts.example: [‘us’, ‘ir’, ‘es’]”

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

1

‘Update interval in seconds.’

KeyboardLayout

class libqtile.widget.KeyboardLayout(**config)[source]

Widget for changing and displaying the current keyboard layout

To use this widget effectively you need to specify keyboard layouts you want to use (using “configured_keyboards”) and bind function “next_keyboard” to specific keys in order to change layouts.

For example:

Key([mod], “space”, lazy.widget[“keyboardlayout”].next_keyboard(), desc=”Next keyboard layout.”),

It requires setxkbmap to be available in the system.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

configured_keyboards

['us']

“A list of predefined keyboard layouts represented as strings. For example: [‘us’, ‘us colemak’, ‘es’, ‘fr’].”

display_map

{}

“Custom display of layout. Key should be in format ‘layout variant’. For example: {‘us’: ‘us ‘, ‘lt sgs’: ‘sgs’, ‘ru phonetic’: ‘ru ‘}”

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

option

None

“string of setxkbmap option. Ex., ‘compose:menu,grp_led:scroll’”

padding

None

‘Padding. Calculated if None.’

update_interval

1

‘Update time in seconds.’

KhalCalendar

class libqtile.widget.KhalCalendar(**config)[source]

Khal calendar widget

This widget will display the next appointment on your Khal calendar in the qtile status bar. Appointments within the “reminder” time will be highlighted.

Widget requirements: dateutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

font

'sans'

‘Default font’

fontshadow

None

‘font shadow color, default is None(no shadow)’

fontsize

None

‘Font size. Calculated if None.’

foreground

'FFFF33'

‘default foreground color’

lookahead

7

‘days to look ahead in the calendar’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

reminder_color

'FF0000'

‘color of calendar entries during reminder time’

remindertime

10

‘reminder time in minutes’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

LaunchBar

class libqtile.widget.LaunchBar(progs=None, width=CALCULATED, **config)[source]

A widget that display icons to launch the associated command

Widget requirements: pyxdg.

Parameters
progs :

a list of tuples (software_name, command_to_execute, comment), for example:

('thunderbird', 'thunderbird -safe-mode', 'launch thunderbird in safe mode')
('logout', 'qshell:self.qtile.cmd_shutdown()', 'logout from qtile')

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

default_icon

'/usr/share/icons/oxygen/256x256/mimetypes/application-x-executable.png'

‘Default icon not found’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

2

‘Padding between icons’

Maildir

class libqtile.widget.Maildir(**config)[source]

A simple widget showing the number of new mails in maildir mailboxes

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

empty_color

None

‘Display color when no new mail is available’

fmt

'{}'

‘How to format the text’

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_when_empty

False

‘Whether not to display anything if the subfolder has no new mail’

maildir_path

'~/Mail'

‘path to the Maildir folder’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

nonempty_color

None

‘Display color when new mail is available’

padding

None

‘Padding. Calculated if None.’

separator

' '

‘the string to put between the subfolder strings.’

sub_folders

[]

‘The subfolders to scan (e.g. [{“path”: “INBOX”, “label”: “Home mail”}, {“path”: “spam”, “label”: “Home junk”}]’

subfolder_fmt

'{label}: {value}'

‘Display format for one subfolder’

total

False

‘Whether or not to sum subfolders into a grand total. The first label will be used.’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

Memory

class libqtile.widget.Memory(**config)[source]

Displays memory/swap usage

MemUsed: Returns memory in use MemTotal: Returns total amount of memory MemFree: Returns amount of memory free MemPercent: Returns memory in use as a percentage Buffers: Returns buffer amount Active: Returns active memory Inactive: Returns inactive memory Shmem: Returns shared memory SwapTotal: Returns total amount of swap SwapFree: Returns amount of swap free SwapUsed: Returns amount of swap in use SwapPercent: Returns swap in use as a percentage

Widget requirements: psutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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

'{MemUsed}M/{MemTotal}M'

‘Formatting for field names.’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

1.0

‘Update interval for the Memory’

MemoryGraph

class libqtile.widget.MemoryGraph(**config)[source]

Displays a memory usage graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

border_color

'215578'

‘Widget border color’

border_width

2

‘Widget border width’

fill_color

'1667EB.3'

‘Fill color for linefill graph’

frequency

1

‘Update frequency in seconds’

graph_color

'18BAEB'

‘Graph color’

line_width

3

‘Line width’

margin_x

3

‘Margin X’

margin_y

3

‘Margin Y’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

samples

100

‘Count of graph samples.’

start_pos

'bottom'

“Drawer starting position (‘bottom’/’top’)”

type

'linefill'

“‘box’, ‘line’, ‘linefill’”

Mirror

class libqtile.widget.Mirror(reflection)[source]

Supported bar orientations: horizontal and vertical

key

default

description

background

None

‘Widget background color’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

Moc

class libqtile.widget.Moc(**config)[source]

A simple MOC widget.

Show the artist and album of now listening song and allow basic mouse control from the bar:

  • toggle pause (or play if stopped) on left click;

  • skip forward in playlist on scroll up;

  • skip backward in playlist on scroll down.

MOC (http://moc.daper.net) should be installed.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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

noplay_color

'cecece'

‘Text colour when not playing.’

padding

None

‘Padding. Calculated if None.’

play_color

'00ff00'

‘Text colour when playing.’

update_interval

0.5

‘Update Time in seconds.’

Mpd2

class libqtile.widget.Mpd2(**config)[source]

Mpd2 Object.

Parameters
status_format :

format string to display status

For a full list of values, see:

MPDClient.status() and MPDClient.currentsong()

https://musicpd.org/doc/protocol/command_reference.html#command_status https://musicpd.org/doc/protocol/tags.html

Default:

'{play_status} {artist}/{title} \
    [{repeat}{random}{single}{consume}{updating_db}]'

``play_status`` is a string from ``play_states`` dict

Note that the ``time`` property of the song renamed to ``fulltime``
to prevent conflicts with status information during formating.
idle_format :

format string to display status when no song is in queue.

Default:

'{play_status} {idle_message} \
    [{repeat}{random}{single}{consume}{updating_db}]'
idle_message :

text to display instead of song information when MPD is idle. (i.e. no song in queue)

Default:: “MPD IDLE”

prepare_status :

dict of functions to replace values in status with custom characters.

f(status, key, space_element) => str

New functionality allows use of a dictionary of plain strings.

Default:

status_dict = {
    'repeat': 'r',
    'random': 'z',
    'single': '1',
    'consume': 'c',
    'updating_db': 'U'
}
format_fns :

A dict of functions to format the various elements.

‘Tag’ : f(str) => str

Default:: { ‘all’: lambda s: cgi.escape(s) }

N.B. if ‘all’ is present, it is processed on every element of song_info

before any other formatting is done.

mouse_buttons :

A dict of mouse button numbers to actions

Widget requirements: python-mpd2_.
.. _python-mpd2: https://pypi.org/project/python-mpd2/

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

color_progress

None

‘Text color to indicate track progress.’

command

<function default_cmd at 0x7fc214579950>

‘command to be executed by mapped mouse button.’

fmt

'{}'

‘How to format the text’

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_fns

{'all': <function <lambda> at 0x7fc2145799e0>}

‘Dictionary of format methods’

host

'localhost'

‘Host of mpd server’

idle_format

'{play_status} {idle_message}[{repeat}{random}{single}{consume}{updating_db}]'

‘format for status when mpd has no playlist.’

idle_message

'MPD IDLE'

‘text to display when mpd is idle.’

idletimeout

5

‘MPDClient idle command timeout’

keys

{'command': None, 'next': 5, 'previous': 4, 'stop': 3, 'toggle': 1}

‘mouse button mapping. action -> b_num. deprecated.’

markup

True

‘Whether or not to use pango markup’

mouse_buttons

{}

‘b_num -> action. replaces keys.’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

no_connection

'No connection'

‘Text when mpd is disconnected’

padding

None

‘Padding. Calculated if None.’

password

None

‘Password for auth on mpd server’

play_states

{'pause': '⏸', 'play': '▶', 'stop': '■'}

‘Play state mapping’

port

6600

‘Port of mpd server’

prepare_status

{'consume': 'c', 'random': 'z', 'repeat': 'r', 'single': '1', 'updating_db': 'U'}

‘characters to show the status of MPD’

space

'-'

‘Space keeper’

status_format

'{play_status} {artist}/{title} [{repeat}{random}{single}{consume}{updating_db}]'

‘format for displayed song info.’

timeout

30

‘MPDClient timeout’

update_interval

1

‘Interval of update widget’

Mpris2

class libqtile.widget.Mpris2(**config)[source]

An MPRIS 2 widget

A widget which displays the current track/artist of your favorite MPRIS player. It should work with all MPRIS 2 compatible players which implement a reasonably correct version of MPRIS, though I have only tested it with audacious. This widget scrolls the text if neccessary and information that is displayed is configurable.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

display_metadata

['xesam:title', 'xesam:album', 'xesam:artist']

‘Which metadata identifiers to display. See http://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/#index5h3 for available values’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

name

'audacious'

‘Name of the MPRIS widget.’

objname

'org.mpris.MediaPlayer2.audacious'

‘DBUS MPRIS 2 compatible player identifier- Find it out with dbus-monitor - Also see: http://specifications.freedesktop.org/mpris-spec/latest/#Bus-Name-Policy

padding

None

‘Padding. Calculated if None.’

scroll_chars

30

‘How many chars at once to display.’

scroll_interval

0.5

‘Scroll delay interval.’

scroll_wait_intervals

8

‘Wait x scroll_interval beforescrolling/removing text’

stop_pause_text

None

‘Optional text to display when in the stopped/paused state’

Net

class libqtile.widget.Net(**config)[source]

Displays interface down and up speed

Widget requirements: psutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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

'{interface}: {down} ↓↑ {up}'

‘Display format of down-/upload speed of given interfaces’

interface

None

‘List of interfaces or single NIC as string to monitor, None to displays all active NICs combined’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

1

‘The update interval.’

use_bits

False

‘Use bits instead of bytes per second?’

NetGraph

class libqtile.widget.NetGraph(**config)[source]

Display a network usage graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

bandwidth_type

'down'

‘down(load)/up(load)’

border_color

'215578'

‘Widget border color’

border_width

2

‘Widget border width’

fill_color

'1667EB.3'

‘Fill color for linefill graph’

frequency

1

‘Update frequency in seconds’

graph_color

'18BAEB'

‘Graph color’

interface

'auto'

“Interface to display info for (‘auto’ for detection)”

line_width

3

‘Line width’

margin_x

3

‘Margin X’

margin_y

3

‘Margin Y’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

samples

100

‘Count of graph samples.’

start_pos

'bottom'

“Drawer starting position (‘bottom’/’top’)”

type

'linefill'

“‘box’, ‘line’, ‘linefill’”

Notify

class libqtile.widget.Notify(width=CALCULATED, **config)[source]

A notify widget

Supported bar orientations: horizontal only

key

default

description

audiofile

None

‘Audiofile played during notifications’

background

None

‘Widget background color’

default_timeout

None

‘Default timeout (seconds) for notifications’

fmt

'{}'

‘How to format the text’

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’

foreground_low

'dddddd'

‘Foreground low priority colour’

foreground_urgent

'ff0000'

‘Foreground urgent priority colour’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

OpenWeather

class libqtile.widget.OpenWeather(**config)[source]

A weather widget, data provided by the OpenWeather API.

Some format options:
  • location_city

  • location_cityid

  • location_country

  • location_lat

  • location_long

  • weather

  • weather_details

  • units_temperature

  • units_wind_speed

  • isotime

  • humidity

  • pressure

  • sunrise

  • sunset

  • temp

  • visibility

  • wind_speed

  • wind_deg

  • wind_direction

  • weather_0_icon # See: https://openweathermap.org/weather-conditions; TODO: Use icons.

  • main_feels_like

  • main_temp_min

  • main_temp_max

  • clouds_all

Supported bar orientations: horizontal only

key

default

description

app_key

'7834197c2338888258f8cb94ae14ef49'

‘Open Weather access key. A default is provided, butn for prolonged use obtaining your own is suggested:n https://home.openweathermap.org/users/sign_up’

background

None

‘Widget background color’

cityid

None

‘City ID. Can be looked up on e.g.:n https://openweathermap.org/findn Takes precedence over location and coordinates.n Note that this is not equal to a WOEID.’

coordinates

None

‘Dictionary containing latitude and longituden Example: coordinates={“longitude”: “77.22”,n “latitude”: “28.67”}’

data

None

‘Post Data’

dateformat

'%Y-%m-%d '

‘Format for dates, defaults to ISO.n For details see: https://docs.python.org/3/library/time.html#time.strftime

fmt

'{}'

‘How to format the text’

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

'{location_city}: {main_temp} °{units_temperature} {humidity}% {weather_details}'

‘Display format’

headers

{}

‘Extra Headers’

json

True

‘Is Json?’

language

'en'

‘Language of response. List of languages supported cann be seen at: https://openweathermap.org/current undern Multilingual support’

location

None

‘Name of the city. Country name can be appendedn like cambridge,NZ. Takes precedence over zip-code.’

markup

True

‘Whether or not to use pango markup’

metric

True

‘True to use metric/C, False to use imperial/F’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

parse

None

‘Parse Function’

timeformat

'%H:%M'

‘Format for times, defaults to ISO.n For details see: https://docs.python.org/3/library/time.html#time.strftime

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

url

None

‘Url’

user_agent

'Qtile'

‘Set the user agent’

xml

False

‘Is XML?’

zip

None

‘Zip code (USA) or “zip code,country code” forn other countries. E.g. 12345,NZ. Takes precedence overn coordinates.’

Pomodoro

class libqtile.widget.Pomodoro(**config)[source]

Pomodoro technique widget

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

color_active

'00ff00'

‘Colour then pomodoro is running’

color_break

'ffff00'

‘Colour then it is break time’

color_inactive

'ff0000'

‘Colour then pomodoro is inactive’

fmt

'{}'

‘fmt’

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’

length_long_break

15

‘Length of a long break in minutes’

length_pomodori

25

‘Length of one pomodori in minutes’

length_short_break

5

‘Length of a short break in minutes’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

notification_on

True

‘Turn notifications on’

num_pomodori

4

‘Number of pomodori to do in a cycle’

padding

None

‘Padding. Calculated if None.’

prefix_active

''

‘Prefix then app is active’

prefix_break

'B '

‘Prefix during short break’

prefix_inactive

'POMODORO'

‘Prefix when app is inactive’

prefix_long_break

'LB '

‘Prefix during long break’

prefix_paused

'PAUSE'

‘Prefix during pause’

update_interval

1

‘Update interval in seconds, if none, the widget updates whenever the event loop is idle.’

Prompt

class libqtile.widget.Prompt(name='prompt', **config)[source]

A widget that prompts for user input

Input should be started using the .start_input() method on this class.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

bell_style

'audible'

“Alert at the begin/end of the command history. Possible values: ‘audible’, ‘visual’ and None.”

cursor

True

‘Show a cursor’

cursor_color

'bef098'

‘Color for the cursor and text over it.’

cursorblink

0.5

‘Cursor blink rate. 0 to disable.’

fmt

'{}'

‘How to format the text’

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’

ignore_dups_history

False

“Don’t store duplicates in history”

markup

True

‘Whether or not to use pango markup’

max_history

100

‘Commands to keep in history. 0 for no limit.’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

prompt

'{prompt}: '

‘Text displayed at the prompt’

record_history

True

‘Keep a record of executed commands’

visual_bell_color

'ff0000'

‘Color for the visual bell (changes prompt background).’

visual_bell_time

0.2

‘Visual bell duration (in seconds).’

PulseVolume

libqtile.widget.PulseVolume

alias of libqtile.widget.import_error.make_error.<locals>.ImportErrorWidget

QuickExit

class libqtile.widget.QuickExit(widget=CALCULATED, **config)[source]

A button of exiting the running qtile easily. When clicked this button, a countdown start. If the button pushed with in the countdown again, the qtile shutdown.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

countdown_format

'[ {} seconds ]'

‘This text is showed when counting down.’

countdown_start

5

‘Time to accept the second pushing.’

default_text

'[ shutdown ]'

‘A text displayed as a button’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

timer_interval

1

‘A countdown interval.’

Sep

class libqtile.widget.Sep(height_percent=None, **config)[source]

A visible widget separator

Supported bar orientations: horizontal and vertical

key

default

description

background

None

‘Widget background color’

foreground

'888888'

‘Separator line colour.’

linewidth

1

‘Width of separator line.’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

2

‘Padding on either side of separator.’

size_percent

80

‘Size as a percentage of bar size (0-100).’

She

class libqtile.widget.She(**config)[source]

Widget to display the Super Hybrid Engine status

Can display either the mode or CPU speed on eeepc computers.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

device

'/sys/devices/platform/eeepc/cpufv'

‘sys path to cpufv’

fmt

'{}'

‘How to format the text’

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

'speed'

‘Type of info to display “speed” or “name”’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

0.5

‘Update Time in seconds.’

Spacer

class libqtile.widget.Spacer(length=STRETCH, width=None, **config)[source]

Just an empty space on the bar

Often used with length equal to bar.STRETCH to push bar widgets to the right or bottom edge of the screen.

Parameters
length :

Length of the widget. Can be either bar.STRETCH or a length in pixels.

width :

DEPRECATED, same as length.

Supported bar orientations: horizontal and vertical

key

default

description

background

None

‘Widget background color’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

StockTicker

class libqtile.widget.StockTicker(**config)[source]

A stock ticker widget, based on the alphavantage API. Users must acquire an API key from https://www.alphavantage.co/support/#api-key

The widget defaults to the TIME_SERIES_INTRADAY API function (i.e. stock symbols), but arbitrary Alpha Vantage API queries can be made by passing extra arguments to the constructor.

# Display AMZN
widget.StockTicker(apikey=..., symbol="AMZN")

# Display BTC
widget.StockTicker(apikey=..., function="DIGITAL_CURRENCY_INTRADAY", symbol="BTC", market="USD")

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

data

None

‘Post Data’

fmt

'{}'

‘How to format the text’

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’

function

'TIME_SERIES_INTRADAY'

‘The default API function to query’

headers

{}

‘Extra Headers’

interval

'1min'

‘The default latency to query’

json

True

‘Is Json?’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

parse

None

‘Parse Function’

update_interval

600

“Update interval in seconds, if none, the widget updates whenever it’s done’.”

url

None

‘Url’

user_agent

'Qtile'

‘Set the user agent’

xml

False

‘Is XML?’

SwapGraph

class libqtile.widget.SwapGraph(**config)[source]

Display a swap info graph.

Widget requirements: psutil.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

border_color

'215578'

‘Widget border color’

border_width

2

‘Widget border width’

fill_color

'1667EB.3'

‘Fill color for linefill graph’

frequency

1

‘Update frequency in seconds’

graph_color

'18BAEB'

‘Graph color’

line_width

3

‘Line width’

margin_x

3

‘Margin X’

margin_y

3

‘Margin Y’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

samples

100

‘Count of graph samples.’

start_pos

'bottom'

“Drawer starting position (‘bottom’/’top’)”

type

'linefill'

“‘box’, ‘line’, ‘linefill’”

Systray

class libqtile.widget.Systray(**config)[source]

A widget that manages system tray

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

icon_size

20

‘Icon width’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

5

‘Padding between icons’

TaskList

class libqtile.widget.TaskList(**config)[source]

Displays the icon and name of each window in the current group

Contrary to WindowTabs this is an interactive widget. The window that currently has focus is highlighted.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

border

'215578'

‘Border colour’

borderwidth

2

‘Current group border width’

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’

highlight_method

'border'

“Method of highlighting (one of ‘border’ or ‘block’) Uses *_border color settings”

icon_size

None

‘Icon size. (Calculated if set to None. Icons are hidden if set to 0.)’

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_floating

None

‘Text markup of the floating window state. Supports pangomarkup with markup=True.e.g., “{}” or “<span underline=”low”>{}</span>”’

markup_focused

None

‘Text markup of the focused window state. Supports pangomarkup with markup=True.e.g., “{}” or “<span underline=”low”>{}</span>”’

markup_maximized

None

‘Text markup of the maximized window state. Supports pangomarkup with markup=True.e.g., “{}” or “<span underline=”low”>{}</span>”’

markup_minimized

None

‘Text markup of the minimized window state. Supports pangomarkup with markup=True.e.g., “{}” or “<span underline=”low”>{}</span>”’

markup_normal

None

‘Text markup of the normal window state. Supports pangomarkup with markup=True.e.g., “{}” or “<span underline=”low”>{}</span>”’

max_title_width

None

‘Max size in pixels of task title.(if set to None, as much as available.)’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

3

‘Padding inside the box’

padding_x

None

“X Padding. Overrides ‘padding’ if set”

padding_y

None

“Y Padding. Overrides ‘padding’ if set”

rounded

True

‘To round or not to round borders’

spacing

None

‘Spacing between tasks.(if set to None, will be equal to margin_x)’

title_width_method

None

“Method to compute the width of task title. (None, ‘uniform’.)Defaults to None, the normal behaviour.”

txt_floating

'V '

‘Text representation of the floating window state. e.g., “V ” or “🗗 “’

txt_maximized

'[] '

‘Text representation of the maximized window state. e.g., “[] ” or “🗖 “’

txt_minimized

'_ '

‘Text representation of the minimized window state. e.g., “_ ” or “🗕 “’

unfocused_border

None

“Border color for unfocused windows. Affects only hightlight_method ‘border’ and ‘block’. Defaults to None, which means no special color.”

urgent_alert_method

'border'

“Method for alerting you of WM urgent hints (one of ‘border’ or ‘text’)”

urgent_border

'FF0000'

‘Urgent border color’

TextBox

class libqtile.widget.TextBox(text=' ', width=CALCULATED, **config)[source]

A flexible textbox that can be updated from bound keys, scripts, and qshell.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

font

'sans'

‘Text font’

fontshadow

None

‘font shadow color, default is None(no shadow)’

fontsize

None

‘Font pixel size. Calculated if None.’

foreground

'#ffffff'

‘Foreground colour.’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding left and right. Calculated if None.’

ThermalSensor

class libqtile.widget.ThermalSensor(**config)[source]

Widget to display temperature sensor information

For using the thermal sensor widget you need to have lm-sensors installed. You can get a list of the tag_sensors executing “sensors” in your terminal. Then you can choose which you want, otherwise it will display the first available.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

foreground_alert

'ff0000'

‘Foreground colour alert’

markup

True

‘Whether or not to use pango markup’

metric

True

‘True to use metric/C, False to use imperial/F’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

show_tag

False

‘Show tag sensor’

tag_sensor

None

‘Tag of the temperature sensor. For example: “temp1” or “Core 0”’

threshold

70

‘If the current temperature value is above, then change to foreground_alert colour’

update_interval

2

‘Update interval in seconds’

Volume

class libqtile.widget.Volume(**config)[source]

Widget that display and change volume

By default, this widget uses amixer to get and set the volume so users will need to make sure this is installed. Alternatively, users may set the relevant parameters for the widget to use a different application.

If theme_path is set it draw widget as icons.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

cardid

None

‘Card Id’

channel

'Master'

‘Channel’

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

fmt

'{}'

‘How to format the text’

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’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

mute_command

None

‘Mute command’

padding

3

‘Padding left and right. Calculated if None.’

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’

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’

Wallpaper

class libqtile.widget.Wallpaper(**config)[source]

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

directory

'~/Pictures/wallpapers/'

‘Wallpaper Directory’

fmt

'{}'

‘How to format the text’

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’

label

None

‘Use a fixed label instead of image name.’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

option

'fill'

“How to fit the wallpaper when wallpaper_command isNone. None, ‘fill’ or ‘stretch’.”

padding

None

‘Padding. Calculated if None.’

random_selection

False

‘If set, use random initial wallpaper and randomly cycle through the wallpapers.’

wallpaper

None

‘Wallpaper’

wallpaper_command

['feh', '--bg-fill']

‘Wallpaper command. If None, thewallpaper will be painted without the use of a helper.’

WidgetBox

class libqtile.widget.WidgetBox(widgets=[], **config)[source]

A widget to declutter your bar.

WidgetBox is a widget that hides widgets by default but shows them when the box is opened.

Widgets that are hidden will still update etc. as if they were on the main bar.

Button clicks are passed to widgets when they are visible so callbacks will work.

Widgets in the box also remain accessible via command interfaces.

Widgets can only be added to the box via the configuration file. The widget is configured by adding widgets to the “widgets” parameter as follows:

widget.WidgetBox(widgets=[
    widget.TextBox(text="This widget is in the box"),
    widget.Memory()
    ]
),

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

close_button_location

'left'

“Location of close button when box open (‘left’ or ‘right’)”

font

'sans'

‘Text font’

fontshadow

None

‘font shadow color, default is None(no shadow)’

fontsize

None

‘Font pixel size. Calculated if None.’

foreground

'#ffffff'

‘Foreground colour.’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

text_closed

'[<]'

‘Text when box is closed’

text_open

'[>]'

‘Text when box is open’

WindowCount

class libqtile.widget.WindowCount(text=' ', width=CALCULATED, **config)[source]

A simple widget to show the number of windows in the current group.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

font

'sans'

‘Text font’

fontshadow

None

‘font shadow color, default is None(no shadow)’

fontsize

None

‘Font pixel size. Calculated if None.’

foreground

'#ffffff'

‘Foreground colour.’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding left and right. Calculated if None.’

show_zero

False

‘Show window count when no windows’

text_format

'{num}'

‘Format for message’

WindowName

class libqtile.widget.WindowName(width=STRETCH, **config)[source]

Displays the name of the window that currently has focus

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

empty_group_string

' '

‘string to display when no windows are focused on current group’

fmt

'{}'

‘How to format the text’

font

'sans'

‘Default font’

fontshadow

None

‘font shadow color, default is None(no shadow)’

fontsize

None

‘Font size. Calculated if None.’

for_current_screen

False

‘instead of this bars screen use currently active screen’

foreground

'ffffff'

‘Foreground colour’

format

'{state}{name}'

‘format of the text’

markup

True

‘Whether or not to use pango markup’

max_chars

0

‘max chars before truncating with ellipsis’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

WindowTabs

class libqtile.widget.WindowTabs(**config)[source]

Displays the name of each window in the current group. Contrary to TaskList this is not an interactive widget. The window that currently has focus is highlighted.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

fmt

'{}'

‘How to format the text’

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’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

selected

('<b>', '</b>')

‘Selected task indicator’

separator

' | '

‘Task separator text.’

Wlan

class libqtile.widget.Wlan(**config)[source]

Displays Wifi SSID and quality.

Widget requirements: iwlib.

Supported bar orientations: horizontal only

key

default

description

background

None

‘Widget background color’

disconnected_message

'Disconnected'

‘String to show when the wlan is diconnected.’

fmt

'{}'

‘How to format the text’

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

'{essid} {quality}/70'

‘Display format. For percents you can use “{essid} {percent:2.0%}”’

interface

'wlan0'

‘The interface to monitor’

markup

True

‘Whether or not to use pango markup’

mouse_callbacks

{}

‘Dict of mouse button press callback functions.’

padding

None

‘Padding. Calculated if None.’

update_interval

1

‘The update interval.’