Widgets

ALSAWidget

class qtile_extras.widget.ALSAWidget(**config)

The widget is very simple and, so far, just allows controls for volume up, down and mute.

Volume control is handled by running the appropriate amixer command. The widget is updated instantly when volume is changed via this code, but will also update on an interval (i.e. it will reflect changes to volume made by other programs).

The widget displays volume level via an icon, bar or both. The icon is permanently visible while the bar only displays when the volume is changed and will hide after a user-defined period.

Supported bar orientations: horizontal only

../../_images/volumecontrol-icon.gif

‘icon’ mode

../../_images/volumecontrol-bar.gif

‘bar’ mode

../../_images/volumecontrol-both.gif

‘both’ mode

key default description
background None Widget background color
bar_colour_high '999900' Colour of bar if high range
bar_colour_loud '990000' Colour of bar in loud range
bar_colour_mute '999999' Colour of bar if muted
bar_colour_normal '009900' Colour of bar in normal range
bar_width 75 Width of display bar
decorations [] Decorations for widgets
device 'Master' Name of ALSA device
font 'sans' Default font
fontsize None Font size
foreground 'ffffff' Font colour
hide_interval 5 Timeout before bar is hidden after update
limit_high 90 Max percentage for high range
limit_loud 100 Max percentage for loud range
limit_normal 70 Max percentage for normal range
margin 3 Margin inside the box
margin_x None X Margin. Overrides 'margin' if set
margin_y None Y Margin. Overrides 'margin' if set
mode 'bar' Display mode: 'icon', 'bar', 'both'.
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
padding 3 Padding inside the box
padding_x None X Padding. Overrides 'padding' if set
padding_y None Y Padding. Overrides 'padding' if set
step 5 Amount to increase volume by
text_format '{volume}%' String format
theme_path None Path to theme icons.
update_interval 5 Interval to update widget (e.g. if changes made in other apps).
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_toggle_mute(*args, **kwargs)

Mute audio output

cmd_volume_down(*args, **kwargs)

Decrease volume

cmd_volume_up(*args, **kwargs)

Increase volume

AnalogueClock

class qtile_extras.widget.AnalogueClock(**config)

An analogue clock for your Bar.

Supported bar orientations: horizontal and vertical

../../_images/analogue_clock1.png

Default config

../../_images/analogue_clock2.png

With square clock face

key default description
background None Widget background color
decorations [] Decorations for widgets
face_background None Shading for clock face
face_border_colour '00ffff' Border colour for clock face
face_border_width 1 Thickness of clock face border
face_shape None 'square', 'circle' or None
hour_length 0.6 Length of hour hand as percentage of radius
hour_size 2 Thickness of hour hand
margin 2 Margin around clock
minute_length 0.95 Length of minute hand as percentage of radius
minute_size 2 Thickness of minute hand
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
padding 2 Additional padding at edges of widget
second_length 0.95 Length of minute hand as percentage of radius
second_size 0 Thickness of second hand, 0 to hide.
update_interval 1 Polling interval in secs.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

BrightnessControl

class qtile_extras.widget.BrightnessControl(**config)

This module provides basic screen brightness controls and a simple widget showing the brightness level for Qtile.

Brightness control is handled by writing to the appropriate /sys/class/backlight device. The widget is updated instantly when the brightness is changed via this code and will autohide after a user-defined timeout.

Note

This script will not work unless the user has write access to the relevant backlight device.

This can be achieved via a udev rule which modifies the group and write permissions. The rule should be saved at /etc/udev/rules.d

An example rule is as follows:

# Udev rule to change group and write permissions for screen backlight
ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="intel_backlight", RUN+="/bin/chgrp video /sys/class/backlight/%k/brightness"
ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="intel_backlight", RUN+="/bin/chmod g+w /sys/class/backlight/%k/brightness"

You should then ensure that your user is a member of the video group.

Supported bar orientations: horizontal only

../../_images/brightnesscontrol-demo.gif
key default description
background None Widget background color
bar_colour '008888' Colour of bar displaying brightness level.
brightness_on_battery '50%' Brightness level on battery power (accepts integer value or percentage as string)
brightness_on_mains '100%' Brightness level on mains power (accepts integer valueor percentage as string)
brightness_path 'brightness' Name of file holding brightness value
decorations [] Decorations for widgets
device '/sys/class/backlight/intel_backlight' Path to backlight device
enable_power_saving False Automatically set brightness depending on status. Note: this is not checked when the widget is first started.
error_colour '880000' Colour of bar when displaying an error
font 'sans' Default font
fontsize None Font size
foreground 'ffffff' Colour of text.
max_brightness None Set value or leave as None to allow device maximum
max_brightness_path 'max_brightness' Name of file holding max brightness value
min_brightness 100 Minimum brightness. Do not set to 0!
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
step '5%' Amount to change brightness (accepts int or percentage as string)
text_format '{percentage}%' Text to display.
timeout_interval 5 Time before widet is hidden.
widget_width 75 Width of bar when widget displayed
cmd_brightness_down()

Decrease the brightness level

cmd_brightness_up()

Increase the brightness level

cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_set_brightness_percent(percent)

Set brightness to percentage (0.0-1.0) of max value

cmd_set_brightness_value(value)

Set brightess to set value

CurrentLayoutIcon

class qtile_extras.widget.CurrentLayoutIcon(**config)

A modified version of Qtile’s CurrentLayoutIcon.

The default version behaves the same as the main qtile version of the widget. However, if you set use_mask to True then you can set the colour of the icon via the foreground parameter.

Supported bar orientations: horizontal only

../../_images/currentlayouticon.png

You can use a single colour or a list of colours.

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.
decorations [] Decorations for widgets
fmt '{}' To format the string returned by the widget. For example, if the clock widget returns '08:46' we can do fmt='time {}' do print 'time 08:46' on the widget. To format the individual strings like hour and minutes use the format paramater of the widget (if it has one)
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. Accepts functions and ``lazy`` calls.
padding None Padding. Calculated if None.
scale 1 Scale factor relative to the bar height. Defaults to 1
scroll False Whether text should be scrolled. When True, you must set the widget's ``width``.
scroll_clear False Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay 2 Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_hide False Whether the widget should hide when scrolling has finished
scroll_interval 0.1 Time in seconds before next scrolling step
scroll_repeat True Whether text should restart scrolling once the text has ended
scroll_step 1 Number of pixels to scroll with each step
use_mask False Uses the icon file as a mask. Icon colour will be set via the ``foreground`` parameter.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_set_font(font=UNSPECIFIED, fontsize=UNSPECIFIED, fontshadow=UNSPECIFIED)

Change the font used by this widget. If font is None, the current font is used.

GithubNotifications

class qtile_extras.widget.GithubNotifications(**config)

A widget to show when you have new github notifications.

The widget requires a personal access token (see here). The token needs the notifications scope to be enabled. This token should then be saved in a file and the path provided to the token_file parameter.

If your key expires, re-generate a new key, save it to the same file and then call the reload_token command (e.g. via qtile cmd-obj).

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

../../_images/github_notifications.png
key default description
active_colour '00ffff' Colour when there are notifications
background None Widget background color
decorations [] Decorations for widgets
error_colour 'ffff00' Colour when client has an error (check logs)
icon_size None Icon size. None = autofit.
inactive_colour 'ffffff' Colour when there are no notifications.
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
padding 2 Padding around icon.
token_file '~/.config/qtile-extras/github.token' Path to file containing personal access token.
update_interval 150 Number of seconds before checking status.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_reload_token()

Force reload of access token.

LiveFootballScores

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.LiveFootballScores(**config)

The module uses a module I wrote a number of years ago that parses data from the BBC Sport website.

The underlying module needs work so it will probably only work if you pick a “big” team.

You can select more than one team and league. Scores can be scrolled by using the mousewheel over the widget.

Goals and red cards are indicated by a coloured bar next to the relevant team name. The match status is indicated by a coloured bar underneath the match summary. All colours are customisable.

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

../../_images/livefootballscores.gif

The different screens show: live score, elapsed time, home and away goalscorers and competition name. In addition, the amount of text shown can be customised by using python’s string formatting techniques e.g. the default line {H:.3} {h}-{a} {A:.3} shows the first 3 letters of team names rather than the full name as shown above.

key default description
always_show_red True Continue to show red card indicator
background None Widget background color
decorations [] Decorations for widgets
font 'sans' Default font
fontsize None Font size
foreground 'ffffff' Text colour
goal_indicator '009999' Colour of line to show team that scores
info_text ['{T:^12}', '{H:.3}: {G:10}', '{A:.3}: {g:10}', '{C}'] \n Add extra text lines which can be displayed by clicking on widget.\n Available fields are:\n {H}: Home Team name\n {A}: Away Team name\n {h}: Home score\n {a}: Away score\n {C}: Competition\n {v}: Venue\n {T}: Display time (kick-off, elapsed time, HT, FT)\n {S}: Status (as above but no elapsed time)\n {G}: Home goalscorers\n {g}: Away goalscorers\n {R}: Home red cards\n {r}: Away red cards\n
info_timeout 5 Time before reverting to default text
leagues [] List of leagues you want to display
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. Accepts functions and ``lazy`` calls.
popup_display_timeout 10 Seconds to show recordings.
popup_font 'monospace' Font to use for displaying upcoming recordings. A monospace font is recommended
popup_opacity 0.8 Opacity for popup window.
popup_padding 10 Padding for popup window.
popup_text '{H:>20.20} {h}-{a} {A:<20.20} {T:<5}' Format to use for popup window.
red_card_indicator 'bb0000' Colour of line to show team has had a player sent off.
refresh_interval 60 Time to update data
startup_delay 30 Time before sending first web request
status_fixture '000000' Colour when match has not started
status_fulltime '666666' Colour when match has ended
status_halftime 'aaaa00' Colour when half time
status_live '008800' Colour when match is live
status_text '{H:.3} {h}-{a} {A:.3}' Default widget match text
team 'Liverpool' Team whose scores you want to display
teams [] List of other teams you want to display
underline_status True Bar at bottom of widget to indicate status.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_get()

Get displayed text. Removes padding.

cmd_info()

Show information about all matches

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_popup()

Display popup window

cmd_reboot()

Restart the widget. Useful if updates seem to stop.

cmd_refresh()

Force a poll of match data

ScriptExit

class qtile_extras.widget.ScriptExit(**config)

An updated version of Qtile’s QuickExit widget.

Takes an additional argument exit_script which will be run before qtile exits.

Supported bar orientations: horizontal and vertical

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.
decorations [] Decorations for widgets
default_text '[ shutdown ]' A text displayed as a button
exit_script '' Script to run on exit.
fmt '{}' To format the string returned by the widget. For example, if the clock widget returns '08:46' we can do fmt='time {}' do print 'time 08:46' on the widget. To format the individual strings like hour and minutes use the format paramater of the widget (if it has one)
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. Accepts functions and ``lazy`` calls.
padding None Padding. Calculated if None.
scroll False Whether text should be scrolled. When True, you must set the widget's ``width``.
scroll_clear False Whether text should scroll completely away (True) or stop when the end of the text is shown (False)
scroll_delay 2 Number of seconds to pause before starting scrolling and restarting/clearing text at end
scroll_hide False Whether the widget should hide when scrolling has finished
scroll_interval 0.1 Time in seconds before next scrolling step
scroll_repeat True Whether text should restart scrolling once the text has ended
scroll_step 1 Number of pixels to scroll with each step
timer_interval 1 A countdown interval.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_set_font(font=UNSPECIFIED, fontsize=UNSPECIFIED, fontshadow=UNSPECIFIED)

Change the font used by this widget. If font is None, the current font is used.

cmd_trigger()

SnapCast

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.SnapCast(**config)

A widget to run a snapclient instance in the background.

This is a work in progress. The plan is to add the ability for the client to change groups from widget.

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

../../_images/snapcast.png

Snapclient active running in background

key default description
active_colour 'ffffff' Colour when client is active and connected to server
background None Widget background color
client_name None Client name (as recognised by server).
decorations [] Decorations for widgets
error_colour 'ffff00' Colour when client has an error (check logs)
icon_size None Icon size. None = autofit.
inactive_colour '999999' Colour when client is inactive
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
options '' Options to be passed to snapclient.
padding 2 Padding around icon (and text).
server_address 'localhost' Name or IP address of server.
snapclient '/usr/bin/snapclient' Path to snapclient
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

StatusNotifier

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.StatusNotifier(**config)

A modified version of the default Qtile StatusNotifier widget.

Added the ability to render context menus by right-clicking on the icon.

Required Dependencies

This module requires the following third-party libraries: dbus-next, xdg

Supported bar orientations: horizontal and vertical

../../_images/statusnotifier.png

Widget showing Remmina icon and context menu.

key default description
background None Widget background color
decorations [] Decorations for widgets
hide_after 0.5 Time in seconds before hiding menu atfer mouse leave
highlight_colour '0060A0' Colour of highlight for menu items (None for no highlight)
icon_size 16 Icon width
icon_theme None Name of theme to use for app icons
menu_background '333333' Background colour for menu
menu_font 'sans' Font for menu text
menu_fontsize 12 Font size for menu text
menu_foreground 'ffffff' Font colour for menu text
menu_row_height None Height of menu row (NB text entries are 2 rows tall, separators are 1 row tall.) "None" will attempt to calculate height based on font size.
menu_width 200 Context menu width
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
opacity 1 Menu opactity
padding 3 Padding between icons
separator_colour '555555' Colour of menu separator
show_menu_icons True Show icons in context menu
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

StravaWidget

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.StravaWidget(**config)

This module provides a simple widget showing some Strava stats.

The widget text can be customised using the following keys:

prefix

suffix

value

C

Current month

Y

Calendar year

A

All time

D

Distance

C

Count

T

Time

P

Pace

N

Name

A

Date

For example, the default text {CA:%b} {CD:.1f}km displays the current date in abbreviated month name format and the distance run that month: “Aug 143.1km”.

Extended info is provided by clicking on the widget.

Note

You will need to follow the instuctions at https://developers.strava.com/ to create a new app and authorise it.

Your id and secret should be put in a json file called auth.json in ~/.cache/stravawidget

The token file generated by the authorisation process, strava.json, should also be placed in the same folder.

Required Dependencies

This module requires the following third-party libraries: stravalib, units

Supported bar orientations: horizontal only

../../_images/strava_widget.png
../../_images/strava_widget_detail.png

Extended info. I’ve blurred out details of my runs for privacy reasons.

key default description
background None Widget background color
decorations [] Decorations for widgets
font 'sans' Default font
fontsize None Font size
foreground 'ffffff' Text 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
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
popup_display_timeout 15 Time to display extended info
refresh_interval 1800 Time to update data
startup_delay 10 Time before sending first web request
text '{CA:%b} {CD:.1f}km' Widget text
warning_colour 'aaaa00' Highlight when there is an error.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

TVHWidget

class qtile_extras.widget.TVHWidget(**config)

A widget to show whether a TVHeadend server is currently recording or not.

The widget will also show a popup displaying upcoming recordings.

When the server is recording a red line will be shown under the icon. If there’s an error, a yellow line will show above the icon (and check the logs).

NB if you use a username and password, these are stored in plain text. You may therefore wish to create an unprivileged user account in TVHeadend that only has access to scheduled recordings data.

Required Dependencies

This module requires the following third-party libraries: requests

Supported bar orientations: horizontal only

../../_images/tvh_widget.gif
key default description
auth None Auth details for accessing tvh. Can be None, tuple of (username, password).
background None Widget background color
decorations [] Decorations for widgets
hide_duplicates True Remove duplicate recordings from list of upcoming recordings.
host 'http://localhost:9981/api' TVHeadend server address
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. Accepts functions and ``lazy`` calls.
popup_display_timeout 10 Seconds to show recordings.
popup_font 'monospace' Font to use for displaying upcoming recordings. A monospace font is recommended
popup_format '{start:%a %d %b %H:%M}: {title:.40}' Upcoming recording text.
popup_opacity 0.8 Opacity for popup window.
popup_padding 10 Padding for popup window.
recording_colour 'bb0000' Highlight when TVHeadend is recording
refresh_interval 30 Time to update data
startup_delay 5 Time before sending first web request
tvh_timeout 5 Seconds before timeout for timeout request
upcoming_recordings_path '/dvr/entry/grid_upcoming' API point for retrieving data on upcoming recordings.
warning_colour 'aaaa00' Highlight when there is an error.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

UPowerWidget

class qtile_extras.widget.UPowerWidget(**config)

A graphical widget to display laptop battery level.

The widget uses dbus to read the battery information from the UPower interface.

The widget will display one icon for each battery found or users can specify the name of the battery if they only wish to display one.

Clicking on the widget will display the battery level and the time to empty/full.

All colours can be customised as well as low/critical percentage levels.

Required Dependencies

This module requires the following third-party libraries: dbus-next

Supported bar orientations: horizontal only

../../_images/battery_normal.png

Normal

../../_images/battery_low.png

Low

../../_images/battery_critical.png

Critical

../../_images/battery_charging.png

Charging

../../_images/battery_multiple.png

Multiple batteries

../../_images/battery_textdisplay.gif

Showing text

key default description
background None Widget background color
battery_height 10 Height of battery icon
battery_name None Battery name. None = all batteries
battery_width 20 Size of battery icon
border_charge_colour '8888ff' Border colour when charging.
border_colour 'dbdbe0' Border colour when discharging.
border_critical_colour 'cc0000' Border colour when battery low.
decorations [] Decorations for widgets
fill_charge None Override fill colour when charging
fill_critical 'cc0000' Fill when critically low
fill_low 'aa00aa' Fill colour when battery low
fill_normal 'dbdbe0' Fill when normal
font 'sans' Default font
fontsize None Font size
foreground 'ffffff' Font colour for information text
margin 2 Margin on sides of widget
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
percentage_critical 0.1 Critical level threshold.
percentage_low 0.2 Low level threshold.
spacing 5 Space between batteries
text_charging '({percentage:.0f}%) {ttf} until fully charged' Text to display when charging.
text_discharging '({percentage:.0f}%) {tte} until empty' Text to display when on battery.
text_displaytime 5 Time for text to remain before hiding
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

UnitStatus

class qtile_extras.widget.UnitStatus(**config)

UnitStatus is a basic widget for Qtile which shows the current status of systemd units.

It may not be particular useful for you and was primarily written as an exercise to familiarise myself with writing Qtile widgets and interacting with d-bus.

The widget is incredibly basic. It subscribes to the systemd d-bus interface, finds the relevant service and displays an icon based on the current status. The widget listens for announced changes to the service and updates the icon accordingly.

Required Dependencies

This module requires the following third-party libraries: dbus-next

Supported bar orientations: horizontal only

../../_images/widget-unitstatus-screenshot.png
key default description
background None Widget background color
bus_name 'system' Which bus to use. Accepts 'system' or 'session'.
colour_active '00ff00' Colour for active indicator
colour_dead '666666' Colour for dead indicator
colour_failed 'ff0000' Colour for active indicator
colour_inactive 'ffffff' Colour for active indicator
decorations [] Decorations for widgets
font 'sans' Default font
fontsize None Font size
foreground 'ffffff' Font colour
indicator_size 10 Size of indicator (None = up to margin)
label 'NM' Short text to display next to indicator.
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. Accepts functions and ``lazy`` calls.
padding 3 Padding inside the box
padding_x None X Padding. Overrides 'padding' if set
padding_y None Y Padding. Overrides 'padding' if set
state_map {'activating': ('colour_active', 'colour_inactive'), 'active': ('colour_active', 'colour_active'), 'deactivating': ('colour_inactive', 'colour_active'), 'dead': ('colour_dead', 'colour_dead'), 'failed': ('colour_failed', 'colour_failed'), 'inactive': ('colour_inactive', 'colour_inactive'), 'not-found': ('colour_inactive', 'colour_failed')} Map of indicator colours (border, fill)
unitname 'NetworkManager.service' Name of systemd unit.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

Visualiser

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

class qtile_extras.widget.Visualiser(**config)

A widget to draw an audio visualiser in your bar.

The widget requires cava to be installed. This may also be packaged by your distro.

cava is configured through the widget. Currently, you can set the number of bars and the framerate.

Supported bar orientations: horizontal only

../../_images/visualiser.gif

Default config.

key default description
autostart True Start visualiser automatically
background None Widget background color
bar_colour '#ffffff' Colour of visualiser bars
bar_height 20 Height of visualiser bars
bars 8 Number of bars
cava_path None Path to cava. Set if file is not in your PATH.
cava_pipe '/tmp/cava.pipe' Pipe for cava's output
decorations [] Decorations for widgets
framerate 25 Cava sampling rate.
hide True Hide the visualiser when not active
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
spacing 2 Space between bars
width 100 Widget width
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_start()

Start the visualiser.

cmd_stop()

Stop this visualiser.

cmd_toggle()

Toggle visualiser state.

Visualizer

Warning

This class has been marked as experimental.

The widget may behave unexpectedly, have missing features and will probably crash at some point!

Feedback on any issues would be appreciated.

qtile_extras.widget.Visualizer

alias of Visualiser

WiFiIcon

class qtile_extras.widget.WiFiIcon(**config)

An simple graphical widget that shows WiFi status.

Left-clicking the widget will show the name of the network.

Required Dependencies

This module requires the following third-party libraries: iwlib

Supported bar orientations: horizontal only

../../_images/wifi_simple.png
../../_images/wifi_expanded.png

Additional detail is visible when clicking on icon

key default description
active_colour 'ffffff' Colour for wifi strength.
background None Widget background color
decorations [] Decorations for widgets
expanded_timeout 5 Time in secs for expanded information to display when clicking on icon.
font 'sans' Default font
fontsize None Font size
foreground 'ffffff' Font colour for information text
inactive_colour '666666' Colour for wifi background.
interface 'wlan0' Name of wifi interface.
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
padding 3 Padding inside the box
padding_x None X Padding. Overrides 'padding' if set
padding_y None Y Padding. Overrides 'padding' if set
update_interval 1 Polling interval in secs.
wifi_arc 75 Width of arc in degrees.
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_show_text()

WordClock

class qtile_extras.widget.WordClock(**config)

A widget to draw a word clock to the screen.

This is not a traditional widget in that you will not see anything displayed in your bar. The widget works in the background and updates the screen wallpaper when required. However, having this as a widget provides an easy way for users to install and configure the clock.

The clocks are currently designed to update on 5 minute intervals “five past” -> “ten past” etc. This may be changed in the future.

Custom layouts can be added by referring to the instructions in qtile_extras/resources/wordclock/english.py.

Supported languages

Available languages: Dutch, English, Finnish, French, Portuguese, Spanish, Swedish

Supported bar orientations: horizontal and vertical

../../_images/wordclock.png
key default description
active '00AAAA' Colour for active characters
background '000000' Background colour.
cache '~/.cache/qtile-extras' Location to store wallpaper
decorations [] Decorations for widgets
font 'sans' Font for text
fontsize 70 Font size for letters
inactive '202020' Colour for inactive characters
language 'english' Display language. Choose from 'dutch', 'english', 'finnish', 'french', 'portuguese', 'spanish', 'swedish'.
mouse_callbacks {} Dict of mouse button press callback functions. Accepts functions and ``lazy`` calls.
update_interval 1 Interval to check time
cmd_commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(code: str) → tuple[bool, str | None]

Evaluates code in the module namespace of the command object

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

cmd_function(function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) → tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

Mixins

TooltipMixin

class qtile_extras.widget.mixins.TooltipMixin

Mixin that provides a tooltip for widgets.

To use it, subclass and add this to __init__:

TooltipMixin.__init__(self, **kwargs)
self.add_defaults(TooltipMixin.defaults)

Widgets should set self.tooltip_text to change display text.

../../_images/tooltip_mixin.gif
key default description
tooltip_background '#000000' Background colour for tooltip
tooltip_color '#ffffff' Font colur for tooltop
tooltip_delay 1 Time in seconds before tooltip displayed
tooltip_font 'sans' Font colour for tooltop
tooltip_fontsize 12 Font size for tooltop
tooltip_padding 4 int for all sides or list for [top/bottom, left/right]