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.3/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.
Supported bar orientations: horizontal only
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)[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(2015, 12, 25, 19, 53, 1, 445755)
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.txtSupported 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
-
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