Built-in Widgets¶
AGroupBox¶
Backlight¶
-
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
Battery¶
-
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
BatteryIcon¶
-
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.5/libqtile/resources/battery-icons'
Path of the icons custom_icons
{}
dict containing key->filename icon map
BitcoinTicker¶
-
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.
CPUGraph¶
Canto¶
-
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
CheckUpdates¶
-
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.
Clipboard¶
-
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
Clock¶
-
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.
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 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.
Countdown¶
-
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, 3, 11, 13, 49, 42, 978586)
The datetime for the endo of the countdown
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 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
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_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
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 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 interval.
DebugInfo¶
-
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
GenPollText¶
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 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
GmailChecker¶
-
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
GroupBox¶
-
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)
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.txtSupported bar orientations: horizontal only
key default description device
'sda'
Block device to display info for
HDDGraph¶
Image¶
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):
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/
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.
Supported bar orientations: horizontal only
key default description mbox
'"INBOX"'
mailbox to fetch label
'INBOX'
label for display user
None
email username server
None
email server name
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 update_interval
1
Update interval in seconds. configured_keyboards
['us', 'ir']
your predefined list of keyboard layouts.example: [‘us’, ‘ir’, ‘es’] colours
None
foreground colour for each layouteither ‘None’ or a list of colours.example: [‘ffffff’, ‘E6F0AF’].
KeyboardLayout¶
-
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’].
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.
Supported bar orientations: horizontal only
key default description reminder_color
'FF0000'
color of calendar entries during reminder time foreground
'FFFF33'
default foreground color remindertime
10
reminder time in minutes lookahead
7
days to look ahead in the calendar
LaunchBar¶
-
class
libqtile.widget.
LaunchBar
(progs=None, width=CALCULATED, **config)[source]¶ A widget that display icons to launch the associated command
Parameters: progs :
a list of tuples
(software_name, command_to_execute, comment)
, for example:('thunderbird', 'thunderbird -safe-mode', 'launch thunderbird in safe mode') ('logout', 'qsh:self.qtile.cmd_shutdown()', 'logout from qtile')
Supported bar orientations: horizontal only
key default description padding
2
Padding between icons default_icon
'/usr/share/icons/oxygen/256x256/mimetypes/application-x-executable.png'
Default icon not found
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 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.
Memory¶
MemoryGraph¶
-
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’)
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 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.
Mpd¶
-
class
libqtile.widget.
Mpd
(host='localhost', port=6600, password=False, fmt_playing='%a - %t [%v%%]', fmt_stopped='Stopped [%v%%]', msg_nc='Mpd off', do_color_progress=True, **config)[source]¶ A widget for the Music Player Daemon (MPD)
Initialize the widget with the following parameters
Parameters: host :
host to connect to
port :
port to connect to
password :
password to use
fmt_playing :
format string to display when playing/paused
fmt_stopped :
format strings to display when stopped
msg_nc :
which message to show when we’re not connected
do_color_progress :
whether to indicate progress in song by altering message color
width :
A fixed width, or bar.CALCULATED to calculate the width automatically (which is recommended).
Supported bar orientations: horizontal only
key default description foreground_progress
'ffffff'
Foreground progress colour reconnect
False
attempt to reconnect if initial connection failed reconnect_interval
1
Time to delay between connection attempts. update_interval
0.5
Update Time in seconds.
Mpris¶
-
class
libqtile.widget.
Mpris
(name='clementine', width=CALCULATED, objname='org.mpris.clementine', **config)[source]¶ MPRIS player widget
A widget which displays the current track/artist of your favorite MPRIS player. It should work with all players which implement a reasonably correct version of MPRIS, though I have only tested it with clementine.
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
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 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 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 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
Net¶
NetGraph¶
Notify¶
-
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
Pacman¶
-
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.
Prompt¶
-
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. Possible 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).
Sep¶
-
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).
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 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.
Spacer¶
-
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.
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
SwapGraph¶
-
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’)
Systray¶
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 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
TextBox¶
-
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.
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 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
Volume¶
-
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
Wallpaper¶
WindowName¶
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 separator
' | '
Task separator text. selected
('<', '>')
Selected task indicator
Wlan¶
-
class
libqtile.widget.
Wlan
(**config)[source]¶ Displays Wifi ssid and quality
Supported bar orientations: horizontal only
key default description interface
'wlan0'
The interface to monitor update_interval
1
The update interval. disconnected_message
'Disconnected'
String to show when the wlan is diconnected. format
'{essid} {quality}/70'
Display format. For percents you can use “{essid} {percent:2.0%}”
YahooWeather¶
-
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