Built-in Widgets¶

class libqtile.widget.AGroupBox(**config)¶

A widget that graphically displays the current group.

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

class libqtile.widget.Backlight(**config)¶

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

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)¶

A simple but flexible text-based battery widget.

key	default	description
`low_foreground`	`'FF0000'`	font color when battery is low
`format`	`'{char} {percent:2.0%} {hour:d}:{min:02d}'`	Display format
`charge_char`	`'^'`	Character to indicate the battery is charging
`discharge_char`	`'V'`	Character to indicate the battery is discharging
`low_percentage`	`0.1`	0 < x < 1 at which to indicate battery is low with low_foreground
`hide_threshold`	`None`	Hide the text when there is enough energy

class libqtile.widget.BatteryIcon(**config)¶

Battery life indicator widget

key	default	description
`theme_path`	`'/var/build/user_builds/qtile-dmp/checkouts/feature-docs-ng/libqtile/resources/battery-icons'`	Path of the icons
`custom_icons`	`{}`	dict containing key->filename icon map

class libqtile.widget.BitcoinTicker(**config)¶

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

key	default	description
`currency`	`''`	The currency the value of bitcoin is displayed in
`format`	`'BTC Buy: {buy}, Sell: {sell}'`	Display format, allows buy, sell, high, low, avg, vol, vol_cur, last, variables.

class libqtile.widget.CPUGraph(**config)¶

Display CPU usage graph.

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

class libqtile.widget.Canto(**config)¶

Display RSS feeds updates using the canto console reader.

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.Clipboard(width=CALCULATED, **config)¶

Display current clipboard contents.

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(fmt=None, **config)¶

A simple but flexible text-based clock.

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.Countdown(**config)¶

A simple countdown timer text widget.

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(2015, 1, 15, 11, 53, 48, 741904)`	The datetime for the endo of the countdown

class libqtile.widget.CurrentLayout(width=CALCULATED, **config)¶

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

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.DF(**config)¶

Disk Free Widget

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

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(width=CALCULATED, **config)¶

Displays debugging infos about selected window

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

__init__(width=CALCULATED, **config)¶

width: A fixed width, or bar.CALCULATED to calculate the width

automatically (wich is recommended).

class libqtile.widget.GmailChecker(settings=None, **config)¶

A simple gmail checker. settings = {

‘username’: username, ‘password’: password, ‘email_path’: valide email path, ‘fmt’: “format string fot textbox widget”, #if status_only_unseen is True #example “my unseen[%s]”, #if status_only_unseen is False #example “messages: %s, unseen: %s” status_only_unseen: True or False

}

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)¶

A widget that graphically displays the current group.

key	default	description
`active`	`'FFFFFF'`	Active group font colour
`inactive`	`'404040'`	Inactive group font colour
`urgent_text`	`'FF0000'`	Urgent group font color
`highlight_method`	`'border'`	Method of highlighting (one of ‘border’ or ‘block’) Uses *_border color settings
`rounded`	`True`	To round or not to round borders
`this_current_screen_border`	`'215578'`	Border colour for group on this screen when focused.
`urgent_alert_method`	`'border'`	Method for alerting you of WM urgent hints (one of ‘border’, ‘text’ or ‘block’)
`disable_drag`	`False`	Disable dragging and dropping of group names on widget
`this_screen_border`	`'215578'`	Border colour for group on this screen.
`other_screen_border`	`'404040'`	Border colour for group on other screen.
`urgent_border`	`'FF0000'`	Urgent border color
`invert_mouse_wheel`	`False`	Whether to invert mouse wheel group movement

class libqtile.widget.HDDBusyGraph(**config)¶

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

key	default	description
`device`	`'sda'`	Block device to display info for

class libqtile.widget.HDDGraph(**config)¶

Display HDD free or used space graph.

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

class libqtile.widget.Image(width=CALCULATED, **config)¶

Display a PNG image on the bar.

key	default	description
`scale`	`True`	Enable/Disable image scaling
`filename`	`None`	PNG Image filename. Can contain ‘~’

class libqtile.widget.KeyboardLayout(**config)¶

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

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(maildirPath=None, subFolders=None, separator=' ', **config)¶

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

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.MemoryGraph(**config)¶

Displays a memory usage graph.

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.Net(**config)¶

Displays interface down and up speed.

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

class libqtile.widget.NetGraph(**config)¶

Display a network usage graph.

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)¶

A notify widget

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

class libqtile.widget.Pacman(**config)¶

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

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)¶

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

key	default	description
`cursorblink`	`0.5`	Cursor blink rate. 0 to disable.
`prompt`	`'{prompt}: '`	Text displayed at the prompt

class libqtile.widget.Sep(**config)¶

A visible widget separator.

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

class libqtile.widget.She(**config)¶

Widget to display the Super Hybrid Engine status. can display either the mode or CPU speed on eeepc computers.

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(width=STRETCH)¶

Just an empty space on the bar. Often used with width equal to bar.STRETCH to push bar widgets to the right edge of the screen.

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

__init__(width=STRETCH)¶

width: Width of the widget. Can be either bar.STRETCH or a width in pixels.

class libqtile.widget.SwapGraph(**config)¶

Display a swap info graph.

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)¶

A widget that manage system tray

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

class libqtile.widget.TaskList(**config)¶

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)¶

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

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.

__init__(text=' ', width=CALCULATED, **config)¶

text: Initial widget text.
width: An integer width, bar.STRETCH, or bar.CALCULATED .

class libqtile.widget.ThermalSensor(**config)¶

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.

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)¶

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

key	default	description
`cardid`	`0`	Card Id
`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

class libqtile.widget.WindowName(width=STRETCH, **config)¶

Displays the name of the window that currently has focus.

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.WindowTabs(**config)¶

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.

key	default	description
`separator`	`' \| '`	Task separator text.
`selected`	`('<', '>')`	Selected task indicator

class libqtile.widget.YahooWeather(**config)¶

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, wind_direction, wind_speed

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} \xc2\xb0{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