Popup Toolkit

Popup Toolkit Layouts

Layouts are the container that houses all the controls. In order to give the greatest flexibility to users, there are a number of different layouts available in the toolkit.

PopupAbsoluteLayout

class qtile_extras.popup.toolkit.PopupAbsoluteLayout(qtile: Qtile | None = None, **config)[source]

The absolute layout is the simplest layout of all. Controls are placed based on the following parameters:

`pos_x`, `pos_y`: top left corner
`width`, `height`: size of control

No further adjustments are made to the controls.

Note: the layout currently ignores the margin attribute i.e. a control placed at (0,0) will display there even if a margin is defined.

key	default	description
`background`	`'000000'`	Popup background colour
`border`	`'111111'`	Border colour for popup
`border_width`	`0`	Popup border width
`close_on_click`	`True`	Hide the popup when control is clicked
`controls`	`[]`	Controls to display
`height`	`200`	Height of tooltip
`hide_interval`	`0.5`	Timeout after mouse leaves popup before popup is lilled
`hide_on_mouse_leave`	`False`	Hide the popup if the mouse pointer leaves the popup
`hide_on_timeout`	`0`	Timeout before popup closes (0 = disabled). Useful for notifications
`initial_focus`	`0`	Index of control to be focused at startup.
`keyboard_navigation`	`True`	Whether popup controls can be navigated by keys
`keymap`	`{'close': ['Escape'], 'down': ['Down', 'k'], 'left': ['Left', 'h'], 'right': ['Right', 'l'], 'select': ['Return', 'space'], 'step': ['Tab'], 'up': ['Up', 'j']}`	Keyboard controls. NB Navigation logic is very rudimentary. The popup will try to select the nearest control in the direction pressed but some controls may be inaccessible. In that scenario, use the mouse or Tab to cycle through controls.
`margin`	`5`	Margin around edge of tooltip
`opacity`	`1`	Popup window opacity. ‘None’ inherits bar opacity
`width`	`200`	Width of tooltip

PopupGridLayout

class qtile_extras.popup.toolkit.PopupGridLayout(qtile, **config)[source]

The grid layout should be familiar to users who have used Tkinter.

In addition to the width and height attributes, the grid layout also requires rows and cols to define the grid. Grid cells are evenly sized.a

Controls can then be placed in the grid via the row, col, row_span and col_span parameters.

For example:

PopupGridLayout(rows=6, cols=6, controls=[
    PopupImage(filename="A",row=0, col=2, row_span=2, col_span=2),
    PopupImage(filename="B",row=2, col=2, row_span=2, col_span=2),
    PopupImage(filename="C",row=3, col=1),
    PopupImage(filename="D",row=3, col=4),
    PopupText(row=4,col_span=6),
])

would result in a tooltip looking like:

-------------------------
|   |   |       |   |   |
---------   A   ---------
|   |   |       |   |   |
-------------------------
|   |   |       |   |   |
---------   B   ---------
|   | C |       | D |   |
-------------------------
|         TEXT          |
-------------------------
|   |   |   |   |   |   |
-------------------------

row and col are both zero-indexed.

key	default	description
`background`	`'000000'`	Popup background colour
`border`	`'111111'`	Border colour for popup
`border_width`	`0`	Popup border width
`close_on_click`	`True`	Hide the popup when control is clicked
`cols`	`2`	Number of columns in grid
`controls`	`[]`	Controls to display
`height`	`200`	Height of tooltip
`hide_interval`	`0.5`	Timeout after mouse leaves popup before popup is lilled
`hide_on_mouse_leave`	`False`	Hide the popup if the mouse pointer leaves the popup
`hide_on_timeout`	`0`	Timeout before popup closes (0 = disabled). Useful for notifications
`initial_focus`	`0`	Index of control to be focused at startup.
`keyboard_navigation`	`True`	Whether popup controls can be navigated by keys
`keymap`	`{'close': ['Escape'], 'down': ['Down', 'k'], 'left': ['Left', 'h'], 'right': ['Right', 'l'], 'select': ['Return', 'space'], 'step': ['Tab'], 'up': ['Up', 'j']}`	Keyboard controls. NB Navigation logic is very rudimentary. The popup will try to select the nearest control in the direction pressed but some controls may be inaccessible. In that scenario, use the mouse or Tab to cycle through controls.
`margin`	`5`	Margin around edge of tooltip
`opacity`	`1`	Popup window opacity. ‘None’ inherits bar opacity
`rows`	`2`	Number of rows in grid
`width`	`200`	Width of tooltip

PopupRelativeLayout

class qtile_extras.popup.toolkit.PopupRelativeLayout(qtile: Qtile | None = None, **config)[source]

The relative layout positions controls based on a percentage of the parent tooltip’s dimensions.

The positions are defined with the following parameters:

`pos_x`, `pos_y`: top left corner
`width`, `height`: size of control

All four of these parameters should be a value between 0 and 1. Values outside of this range will generate a warning in the log but will not raise an exception.

For example:

PopupRelativeLayout(rows=6, cols=6, controls=[
    PopupImage(filename="A",pos_x=0.1, pos_y=0.2, width=0.5, height=0.5)
])

Would result in a tooltip with dimensions of 200x200 (the default), with an image placed at (20, 40) with dimensions of (100, 100).

Note: images are not stretched but are, instead, centered within the rect.

key	default	description
`background`	`'000000'`	Popup background colour
`border`	`'111111'`	Border colour for popup
`border_width`	`0`	Popup border width
`close_on_click`	`True`	Hide the popup when control is clicked
`controls`	`[]`	Controls to display
`height`	`200`	Height of tooltip
`hide_interval`	`0.5`	Timeout after mouse leaves popup before popup is lilled
`hide_on_mouse_leave`	`False`	Hide the popup if the mouse pointer leaves the popup
`hide_on_timeout`	`0`	Timeout before popup closes (0 = disabled). Useful for notifications
`initial_focus`	`0`	Index of control to be focused at startup.
`keyboard_navigation`	`True`	Whether popup controls can be navigated by keys
`keymap`	`{'close': ['Escape'], 'down': ['Down', 'k'], 'left': ['Left', 'h'], 'right': ['Right', 'l'], 'select': ['Return', 'space'], 'step': ['Tab'], 'up': ['Up', 'j']}`	Keyboard controls. NB Navigation logic is very rudimentary. The popup will try to select the nearest control in the direction pressed but some controls may be inaccessible. In that scenario, use the mouse or Tab to cycle through controls.
`margin`	`5`	Margin around edge of tooltip
`opacity`	`1`	Popup window opacity. ‘None’ inherits bar opacity
`width`	`200`	Width of tooltip

Popup Toolkit Controls

Controls are the building blocks for your popup. You can place text, images and progress bars and have each of these react to input events or display information dynamically.

PopupCircularProgress

class qtile_extras.popup.toolkit.PopupCircularProgress(value=None, **config)[source]

Draws a circular progress bar.

colour_below should be used to set the colour of the progress bar while colour_above will draw a background ring.

Note

This is a special control that is designed to be used in conjunction with other controls. By default, clip is set to True which means that only the area that would be covered by the full circular progress bar is drawn i.e. there is no rectangular background to this control. The result is that any control underneath the circular progress bar is visible.

To place this control above another, it should be defined after that control. For example:

layout = PopupRelativeLayout(
    controls=[
        PopupImage(...),  # image to display beneath progress bar
        PopupCircularProgress(...)
    ]
)

key	default	description
`background`	`None`	Background colour for control
`bar_border_colour`	`'ffffff'`	Colour of border drawn around bar
`bar_border_margin`	`0`	Size of gap between border and bar
`bar_border_size`	`0`	Thickness of border around bar
`bar_size`	`2`	Thickness of bar
`can_focus`	`'auto'`	Whether or not control can be focussed. Focussed control will be highlighted if highlight attribute is set. Possible value are: True, False or ‘auto’ (which sets to True if a ‘Button1’ mouse_callback is set).
`clip`	`True`	When `True` the drawing area is limited to the circular progress bar. This allows the progress bar to be placed on top of other controls and still show their content.
`clockwise`	`True`	Progress increases in a clockwise direction.
`col`	`0`	Column position (for grid layout)
`col_span`	`1`	Number of columns covered by control
`colour_above`	`'#888888'`	Colour for bar above value
`colour_below`	`'#ffffff'`	Colour for bar below value
`drag_callback`	`None`	Callback to run after dragging slider. Callback should take a single argument `new_value`.
`end_margin`	`5`	Gap between edge of control and ends of the bar/border
`height`	`50`	height of control
`highlight`	`'#006666'`	Highlight colour
`highlight_border`	`2`	Border width for focused controls
`highlight_method`	`'block'`	How to highlight focused control. Options are ‘border’ and ‘block’.
`highlight_radius`	`5`	Corner radius for highlight
`horizontal`	`True`	Orientation. False = vertical
`marker_colour`	`'#bbbbbb'`	Colour of marker
`marker_size`	`10`	Size of marker
`max_value`	`1.0`	Maximum value
`min_value`	`0`	Minimum value
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts lazy objects.
`name`	`None`	A unique name for the control. Is only necessary if you wish to update the control’s value via `popup.update_controls()`.
`pos_x`	`0`	x position of control
`pos_y`	`0`	y position of control
`row`	`0`	Row position (for grid layout)
`row_span`	`1`	Number of rows covered by control
`start_angle`	`0`	Starting angle (in degrees) for progress marker. 0 is 12 o’clock and angle increases in a clockwise direction.
`width`	`50`	width of control

PopupImage

class qtile_extras.popup.toolkit.PopupImage(**config)[source]

Control to display an image.

Image will be scaled (locked aspect ratio) to fit within the control rect. The image will also be centered vertically and horizontally.

key	default	description
`background`	`None`	Background colour for control
`can_focus`	`'auto'`	Whether or not control can be focussed. Focussed control will be highlighted if highlight attribute is set. Possible value are: True, False or ‘auto’ (which sets to True if a ‘Button1’ mouse_callback is set).
`col`	`0`	Column position (for grid layout)
`col_span`	`1`	Number of columns covered by control
`colour`	`'ffffff'`	Colour to use to fill image when using mask mode
`filename`	`None`	path to image file.
`height`	`50`	height of control
`highlight`	`'#006666'`	Highlight colour
`highlight_border`	`2`	Border width for focused controls
`highlight_filename`	`None`	path to image to be displayed when highlight method is ‘image’
`highlight_method`	`'block'`	How to highlight focused control. Options are ‘image’, ‘border’, ‘block’ and ‘mask’.
`highlight_radius`	`5`	Corner radius for highlight
`mask`	`False`	Use the image as a mask
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts lazy objects.
`name`	`None`	A unique name for the control. Is only necessary if you wish to update the control’s value via `popup.update_controls()`.
`pos_x`	`0`	x position of control
`pos_y`	`0`	y position of control
`row`	`0`	Row position (for grid layout)
`row_span`	`1`	Number of rows covered by control
`width`	`50`	width of control

PopupSlider

class qtile_extras.popup.toolkit.PopupSlider(value=None, **config)[source]

Control to display slider/progress bar.

Bar can be displayed horizontally (draws left-to-right) or vertically (bottom-to-top).

In addition, a border can be drawn around the bar using the bar_border_colour/size/margin parameters.

key	default	description
`background`	`None`	Background colour for control
`bar_border_colour`	`'ffffff'`	Colour of border drawn around bar
`bar_border_margin`	`0`	Size of gap between border and bar
`bar_border_size`	`0`	Thickness of border around bar
`bar_size`	`2`	Thickness of bar
`can_focus`	`'auto'`	Whether or not control can be focussed. Focussed control will be highlighted if highlight attribute is set. Possible value are: True, False or ‘auto’ (which sets to True if a ‘Button1’ mouse_callback is set).
`col`	`0`	Column position (for grid layout)
`col_span`	`1`	Number of columns covered by control
`colour_above`	`'#888888'`	Colour for bar above value
`colour_below`	`'#ffffff'`	Colour for bar below value
`drag_callback`	`None`	Callback to run after dragging slider. Callback should take a single argument `new_value`.
`end_margin`	`5`	Gap between edge of control and ends of the bar/border
`height`	`50`	height of control
`highlight`	`'#006666'`	Highlight colour
`highlight_border`	`2`	Border width for focused controls
`highlight_method`	`'block'`	How to highlight focused control. Options are ‘border’ and ‘block’.
`highlight_radius`	`5`	Corner radius for highlight
`horizontal`	`True`	Orientation. False = vertical
`marker_colour`	`'#bbbbbb'`	Colour of marker
`marker_size`	`10`	Size of marker
`max_value`	`1.0`	Maximum value
`min_value`	`0`	Minimum value
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts lazy objects.
`name`	`None`	A unique name for the control. Is only necessary if you wish to update the control’s value via `popup.update_controls()`.
`pos_x`	`0`	x position of control
`pos_y`	`0`	y position of control
`row`	`0`	Row position (for grid layout)
`row_span`	`1`	Number of rows covered by control
`width`	`50`	width of control

PopupText

class qtile_extras.popup.toolkit.PopupText(text='', **config)[source]

Simple control to display text.

key	default	description
`background`	`None`	Background colour for control
`can_focus`	`'auto'`	Whether or not control can be focussed. Focussed control will be highlighted if highlight attribute is set. Possible value are: True, False or ‘auto’ (which sets to True if a ‘Button1’ mouse_callback is set).
`col`	`0`	Column position (for grid layout)
`col_span`	`1`	Number of columns covered by control
`font`	`'sans'`	Font name
`fontsize`	`12`	Font size
`foreground`	`'#ffffff'`	Font colour
`foreground_highlighted`	`None`	Font colour when highlighted via block (None to use foreground value)
`h_align`	`'left'`	Text alignment: left, center or right.
`height`	`50`	height of control
`highlight`	`'#006666'`	Highlight colour
`highlight_border`	`2`	Border width for focused controls
`highlight_method`	`'block'`	Available options: ‘border’, ‘block’ or ‘text’.
`highlight_radius`	`5`	Corner radius for highlight
`markup`	`False`	Enable pango markup
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts lazy objects.
`name`	`None`	A unique name for the control. Is only necessary if you wish to update the control’s value via `popup.update_controls()`.
`pos_x`	`0`	x position of control
`pos_y`	`0`	y position of control
`row`	`0`	Row position (for grid layout)
`row_span`	`1`	Number of rows covered by control
`v_align`	`'middle'`	Vertical alignment: top, middle or bottom.
`width`	`50`	width of control
`wrap`	`False`	Wrap text in layout

PopupWidget

class qtile_extras.popup.toolkit.PopupWidget(**config)[source]

Control to display a Qtile widget in a Popup window.

Mouse clicks are passed on to the widgets.

Currently, widgets will be sized based on the dimensions of the control. This will override any width/stretching settings in thw widget.

key	default	description
`background`	`None`	Background colour for control
`can_focus`	`'auto'`	Whether or not control can be focussed. Focussed control will be highlighted if highlight attribute is set. Possible value are: True, False or ‘auto’ (which sets to True if a ‘Button1’ mouse_callback is set).
`col`	`0`	Column position (for grid layout)
`col_span`	`1`	Number of columns covered by control
`height`	`50`	height of control
`highlight`	`'#006666'`	Highlight colour
`highlight_border`	`2`	Border width for focused controls
`highlight_method`	`'block'`	How to highlight focused control. Options are ‘border’ and ‘block’.
`highlight_radius`	`5`	Corner radius for highlight
`horizontal`	`True`	Widget is horizontal. False = vertical.
`mouse_callbacks`	`{}`	Dict of mouse button press callback functions. Accepts lazy objects.
`name`	`None`	A unique name for the control. Is only necessary if you wish to update the control’s value via `popup.update_controls()`.
`pos_x`	`0`	x position of control
`pos_y`	`0`	y position of control
`row`	`0`	Row position (for grid layout)
`row_span`	`1`	Number of rows covered by control
`vertical_left`	`True`	If using vertical orientation, mimic bar on left hand side of screen (causes text to read from bottom to top).
`widget`	`None`	Widget instance.
`width`	`50`	width of control