Built-in Widgets¶

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

A widget that graphically displays the current group.

Supported bar orientations: horizontal only

key	default	description
`border`	`'000000'`	group box border color

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

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

Supported bar orientations: horizontal only

key	default	description
`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
`max_brightness_file`	`'max_brightness'`	Name of file with the maximum brightness in /sys/class/backlight/backlight_name
`update_interval`	`0.2`	The delay in seconds between updates

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

A simple but flexible text-based battery widget.

Supported bar orientations: horizontal only

key	default	description
`charge_char`	`'^'`	Character to indicate the battery is charging
`discharge_char`	`'V'`	Character to indicate the battery is discharging
`error_message`	`'Error'`	Error message if something is wrong
`format`	`'{char} {percent:2.0%} {hour:d}:{min:02d}'`	Display format
`hide_threshold`	`None`	Hide the text when there is enough energy
`low_percentage`	`0.1`	Indicates when to use the low_foreground color 0 < x < 1
`low_foreground`	`'FF0000'`	Font color on low battery

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

Battery life indicator widget.

Supported bar orientations: horizontal only

key	default	description
`theme_path`	`'/home/docs/checkouts/readthedocs.org/user_builds/qtile/checkouts/v0.10.4/libqtile/resources/battery-icons'`	Path of the icons
`custom_icons`	`{}`	dict containing key->filename icon map

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

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

# display the average price of bitcoin in local currency
widget.BitcoinTicker(format="BTC: {avg}")

# display the average price of litecoin in local currency
widget.BitcoinTicker(format="LTC: {avg}", source_currency='ltc')

# display the average price of litecoin in bitcoin
widget.BitcoinTicker(format="BTC: ฿{avg}", source_currency='ltc', currency='btc', round=False)

Supported bar orientations: horizontal only

key	default	description
`currency`	`''`	The currency the value that bitcoin is displayed in
`source_currency`	`'btc'`	The source currency to convert from
`round`	`True`	whether or not to use locale.currency to round the values
`format`	`'BTC Buy: {buy}, Sell: {sell}'`	Display format, allows buy, sell, high, low, avg, vol, vol_cur, last, variables.

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

Display CPU usage graph.

Supported bar orientations: horizontal only

key	default	description
`core`	`'all'`	Which core to show (all/0/1/2/...)

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

Display RSS feeds updates using the canto console reader.

Supported bar orientations: horizontal only

key	default	description
`fetch`	`False`	Whether to fetch new items on update
`feeds`	`[]`	List of feeds to display, empty for all
`one_format`	`'{name}: {number}'`	One feed display format
`all_format`	`'{number}'`	All feeds display format

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

Shows number of pending updates in different unix systems.

Supported bar orientations: horizontal only

key	default	description
`distro`	`'Arch'`	Name of your distribution
`update_interval`	`60`	Update interval in seconds.
`execute`	`None`	Command to execute on click
`display_format`	`'Updates: {updates}'`	Display format if updates available
`colour_no_updates`	`'ffffff'`	Colour when there’s no updates.
`colour_have_updates`	`'ffffff'`	Colour when there are updates.

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

Display current clipboard contents.

Supported bar orientations: horizontal only

key	default	description
`selection`	`'CLIPBOARD'`	the selection to display(CLIPBOARD or PRIMARY)
`max_width`	`10`	maximum number of characters to display (None for all, useful when width is bar.STRETCH)
`timeout`	`10`	Default timeout (seconds) for display text, None to keep forever
`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

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

A simple but flexible text-based clock.

Supported bar orientations: horizontal only

key	default	description
`format`	`'%H:%M'`	A Python datetime format string
`update_interval`	`1.0`	Update interval for the clock
`timezone`	`None`	The timezone to use for this clock, e.g. “US/Central” (or anything in /usr/share/zoneinfo). None means the default timezone.

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
`play_color`	`'00ff00'`	Text colour when playing.
`noplay_color`	`'cecece'`	Text colour when not playing.
`max_chars`	`0`	Maximum number of characters to display in widget.
`update_interval`	`0.5`	Update Time in seconds.

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

A simple countdown timer text widget.

Supported bar orientations: horizontal only

key	default	description
`format`	`'{D}d {H}h {M}m {S}s'`	Format of the displayed text. Available variables:{D} == days, {H} == hours, {M} == minutes, {S} seconds.
`update_interval`	`1.0`	Update interval in seconds for the clock
`date`	`datetime.datetime(2016, 1, 19, 15, 59, 51, 717635)`	The datetime for the endo of the countdown

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
`font`	`'Arial'`	Default font
`fontsize`	`None`	Font size. Calculated if None.
`padding`	`None`	Padding. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`markup`	`False`	Whether or not to use pango markup

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_text`	`'A'`	Text displayed when the screen is active
`inactive_text`	`'I'`	Text displayed when the screen is inactive
`active_color`	`'00ff00'`	Color when screen is active
`inactive_color`	`'ff0000'`	Color when screen is inactive

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
`partition`	`'/'`	the partition to check space
`warn_color`	`'ff0000'`	Warning color
`warn_space`	`2`	Warning space in scale defined by the `measure` option.
`visible_on_warn`	`True`	Only display if warning
`measure`	`'G'`	Measurement (G, M, B)
`format`	`'{p} ({uf}{m})'`	String format (p: partition, s: size, f: free space, uf: user free space, m: measure)
`update_interval`	`60`	The update inteval.

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

Displays debugging infos about selected window

Supported bar orientations: horizontal only

key	default	description
`font`	`'Arial'`	Default font
`fontsize`	`None`	Font size. Calculated if None.
`padding`	`None`	Padding. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`markup`	`False`	Whether or not to use pango markup

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
`func`	`None`	Poll Function

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
`url`	`None`	Url
`data`	`None`	Post Data
`parse`	`None`	Parse Function
`json`	`True`	Is Json?
`user_agent`	`'Qtile'`	Set the user agent
`headers`	`{}`	Extra Headers

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

A simple gmail checker.

Supported bar orientations: horizontal only

key	default	description
`update_interval`	`30`	Update time in seconds.
`username`	`None`	username
`password`	`None`	password
`email_path`	`'INBOX'`	email_path
`fmt`	`'inbox[%s],unseen[%s]'`	fmt
`status_only_unseen`	`False`	Only show unseen messages

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

A widget that graphically displays the current group.

Supported bar orientations: horizontal only

key	default	description
`active`	`'FFFFFF'`	Active group font colour
`inactive`	`'404040'`	Inactive group font colour
`highlight_method`	`'border'`	Method of highlighting (‘border’, ‘block’, ‘text’, or ‘line’)Uses *_border color settings
`rounded`	`True`	To round or not to round box borders
`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.
`other_screen_border`	`'404040'`	Border or line colour for group on other screen.
`highlight_color`	`['000000', '282828']`	Active group highlight color when using ‘line’ highlight method.
`urgent_alert_method`	`'border'`	Method for alerting you of WM urgent hints (one of ‘border’, ‘text’, ‘block’, or ‘line’)
`urgent_text`	`'FF0000'`	Urgent group font color
`urgent_border`	`'FF0000'`	Urgent border or line color
`disable_drag`	`False`	Disable dragging and dropping of group names on widget
`invert_mouse_wheel`	`False`	Whether to invert mouse wheel group movement
`visible_groups`	`None`	Groups that will be visible (if set to None or [], all groups will be visible)

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

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
`device`	`'sda'`	Block device to display info for

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

Display HDD free or used space graph.

Supported bar orientations: horizontal only

key	default	description
`path`	`'/'`	Partition mount point.
`space_type`	`'used'`	free/used

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
`scale`	`True`	Enable/Disable image scaling
`filename`	`None`	PNG Image filename. Can contain ‘~’

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

Widget for changing and displaying the current keyboard layout. It requires setxkbmap to be available in the system.

Supported bar orientations: horizontal only

key	default	description
`update_interval`	`1`	Update time in seconds.
`configured_keyboards`	`['us']`	A list of predefined keyboard layouts represented as strings. For example: [‘us’, ‘us colemak’, ‘es’, ‘fr’].

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
`maildirPath`	`'~/Mail'`	path to the Maildir folder
`subFolders`	`[]`	The subfolders to scan (e.g. [{“path”: “INBOX”, “label”: “Home mail”}, {“path”: “spam”, “label”: “Home junk”}]
`separator`	`' '`	the string to put between the subfolder strings.

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

Displays memory usage.

Supported bar orientations: horizontal only

key	default	description
`fmt`	`'{MemUsed}M/{MemTotal}M'`	see /proc/meminfo for field names

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

Displays a memory usage graph.

Supported bar orientations: horizontal only

key	default	description
`graph_color`	`'18BAEB'`	Graph color
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`margin_x`	`3`	Margin X
`margin_y`	`3`	Margin Y
`samples`	`100`	Count of graph samples.
`frequency`	`1`	Update frequency in seconds
`type`	`'linefill'`	‘box’, ‘line’, ‘linefill’
`line_width`	`3`	Line width
`start_pos`	`'bottom'`	Drawer starting position (‘bottom’/’top’)

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
`play_color`	`'00ff00'`	Text colour when playing.
`noplay_color`	`'cecece'`	Text colour when not playing.
`max_chars`	`0`	Maximum number of characters to display in widget.
`update_interval`	`0.5`	Update Time in seconds.

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

Displays interface down and up speed.

Supported bar orientations: horizontal only

key	default	description
`interface`	`'wlan0'`	The interface to monitor
`update_interval`	`1`	The update interval.

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

Display a network usage graph.

Supported bar orientations: horizontal only

key	default	description
`interface`	`'auto'`	Interface to display info for (‘auto’ for detection)
`bandwidth_type`	`'down'`	down(load)/up(load)

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

A notify widget.

Supported bar orientations: horizontal only

key	default	description
`foreground_urgent`	`'ff0000'`	Foreground urgent priority colour
`foreground_low`	`'dddddd'`	Foreground low priority colour
`default_timeout`	`None`	Default timeout (seconds) for notifications
`audiofile`	`None`	Audiofile played during notifications

class libqtile.widget.Pacman(**config)[source]¶

Shows number of available updates. Needs the pacman package manager installed. So will only work in Arch Linux installation.

Supported bar orientations: horizontal only

key	default	description
`unavailable`	`'ffffff'`	Unavailable Color - no updates.
`execute`	`None`	Command to execute on click
`update_interval`	`60`	The update interval.

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

A widget that prompts for user input. Input should be started using the .startInput method on this class.

Supported bar orientations: horizontal only

key	default	description
`cursor`	`True`	Show a cursor
`cursorblink`	`0.5`	Cursor blink rate. 0 to disable.
`cursor_color`	`'bef098'`	Color for the cursor and text over it.
`prompt`	`'{prompt}: '`	Text displayed at the prompt
`record_history`	`True`	Keep a record of executed commands
`max_history`	`100`	Commands to keep in history. 0 for no limit.
`bell_style`	`'audible'`	Alert at the begin/end of the command history. Posible values: ‘audible’, ‘visual’ and None.
`visual_bell_color`	`'ff0000'`	Color for the visual bell (changes prompt background).
`visual_bell_time`	`0.2`	Visual bell duration (in seconds).

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

A visible widget separator.

Supported bar orientations: horizontal and vertical

key	default	description
`padding`	`2`	Padding on either side of separator.
`linewidth`	`1`	Width of separator line.
`foreground`	`'888888'`	Separator line colour.
`size_percent`	`80`	Size as a percentage of bar size (0-100).

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
`device`	`'/sys/devices/platform/eeepc/cpufv'`	sys path to cpufv
`format`	`'speed'`	Type of info to display “speed” or “name”
`update_interval`	`0.5`	Update Time in seconds.

class libqtile.widget.Spacer(length=STRETCH, width=None)[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.

Supported bar orientations: horizontal and vertical

key	default	description
`background`	`None`	Widget background color

__init__(length=STRETCH, width=None)[source]¶

length: Length of the widget. Can be either bar.STRETCH or a length in pixels.
width: DEPRECATED, same as length.

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

Display a swap info graph.

Supported bar orientations: horizontal only

key	default	description
`graph_color`	`'18BAEB'`	Graph color
`fill_color`	`'1667EB.3'`	Fill color for linefill graph
`border_color`	`'215578'`	Widget border color
`border_width`	`2`	Widget border width
`margin_x`	`3`	Margin X
`margin_y`	`3`	Margin Y
`samples`	`100`	Count of graph samples.
`frequency`	`1`	Update frequency in seconds
`type`	`'linefill'`	‘box’, ‘line’, ‘linefill’
`line_width`	`3`	Line width
`start_pos`	`'bottom'`	Drawer starting position (‘bottom’/’top’)

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

A widget that manages system tray.

Supported bar orientations: horizontal only

key	default	description
`icon_size`	`20`	Icon width
`padding`	`5`	Padding between icons

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
`font`	`'Arial'`	Default font
`fontsize`	`None`	Font size. Calculated if None.
`foreground`	`'ffffff'`	Foreground colour
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`borderwidth`	`2`	Current group border width
`border`	`'215578'`	Border colour
`rounded`	`True`	To round or not to round borders
`highlight_method`	`'border'`	Method of highlighting (one of ‘border’ or ‘block’) Uses *_border color settings
`urgent_border`	`'FF0000'`	Urgent border color
`urgent_alert_method`	`'border'`	Method for alerting you of WM urgent hints (one of ‘border’ or ‘text’)
`max_title_width`	`200`	size in pixels of task title

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

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

Supported bar orientations: horizontal only

key	default	description
`font`	`'Arial'`	Text font
`fontsize`	`None`	Font pixel size. Calculated if None.
`fontshadow`	`None`	font shadow color, default is None(no shadow)
`padding`	`None`	Padding left and right. Calculated if None.
`foreground`	`'#ffffff'`	Foreground colour.

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

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
`metric`	`True`	True to use metric/C, False to use imperial/F
`show_tag`	`False`	Show tag sensor
`update_interval`	`2`	Update interval in seconds
`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
`foreground_alert`	`'ff0000'`	Foreground colour alert

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

Widget that display and change volume if theme_path is set it draw widget as icons.

Supported bar orientations: horizontal only

key	default	description
`cardid`	`None`	Card Id
`device`	`'default'`	Device Name
`channel`	`'Master'`	Channel
`padding`	`3`	Padding left and right. Calculated if None.
`theme_path`	`None`	Path of the icons
`update_interval`	`0.2`	Update time in seconds.
`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.
`mute_command`	`None`	Mute command
`volume_up_command`	`None`	Volume up command
`volume_down_command`	`None`	Volume down command
`get_volume_command`	`None`	Command to get the current volume

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

Supported bar orientations: horizontal only

key	default	description
`directory`	`'/home/docs/Pictures/wallpapers/'`	Wallpaper Directory
`wallpaper`	`None`	Wallpaper
`wallpaper_command`	`None`	Wallpaper command

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
`show_state`	`True`	show window status before window name

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
`separator`	`' \| '`	Task separator text.
`selected`	`('<', '>')`	Selected task indicator

class libqtile.widget.YahooWeather(**config)[source]¶

A weather widget, data provided by the Yahoo! Weather API.

Format options:

astronomy_sunrise

astronomy_sunset

atmosphere_humidity

atmosphere_visibility

atmosphere_pressure

atmosphere_rising

condition_text

condition_code

condition_temp

condition_date

location_city

location_region

location_country

units_temperature

units_distance

units_pressure

units_speed

wind_chill

Supported bar orientations: horizontal only

key	default	description
`location`	`None`	Location to fetch weather for. Ignored if woeid is set.
`woeid`	`None`	Where On Earth ID. Auto-calculated if location is set.
`format`	`'{location_city}: {condition_temp} °{units_temperature}'`	Display format
`metric`	`True`	True to use metric/C, False to use imperial/F
`up`	`'^'`	symbol for rising atmospheric pressure
`down`	`'v'`	symbol for falling atmospheric pressure
`steady`	`'s'`	symbol for steady atmospheric pressure