Popup Utilities

The popup module provides popup window functionality for displaying temporary UI elements in Qtile.

NotificationPopup

A full-screen popup for displaying notifications with a trash bin icon.

Basic Usage

from qtile_expanded import NotificationPopup

# In your config.py keybindings
def show_notifications(qtile):
    popup = NotificationPopup(
        qtile,
        notifications=[
            {"app_name": "Test", "summary": "Hello", "body": "World"}
        ],
        on_clear=lambda: print("All cleared"),
        on_dismiss=lambda idx: print(f"Dismissed {idx}"),
    )
    popup.show()

keys = [
    Key([], "F12", lazy.function(show_notifications)),
]

Configuration Options

popup = NotificationPopup(
    qtile,
    notifications=notifications,  # List of notification dicts
    background="#1a1a2e",        # Background color
    foreground="#eeeeee",        # Text color
    border_color="#333333",      # Border color
    border_width=2,             # Border width
    corner_radius=8,            # Corner radius
    opacity=0.95,               # Opacity (0.0 to 1.0)
    font="sans",                # Font family
    fontsize=14,                # Base font size
    title_fontsize=18,         # Title font size
    padding=20,                 # Padding
    item_padding=15,            # Padding between items
    max_width=800,              # Max content width
    max_notifications=10,       # Max notifications to display
    trash_icon="\u267b",        # Unicode trash bin icon
    trash_size=24,              # Trash icon size
    on_close=callback,          # Called when popup closes
    on_clear=callback,          # Called when trash is clicked
    on_dismiss=callback,        # Called when notification is dismissed
)

Methods

popup.show()                      # Show the popup
popup.hide()                      # Hide the popup
popup.update_notifications(lst)  # Update notification list
popup.draw()                      # Redraw the popup

Notification Structure

Each notification should be a dictionary with these optional fields:

{
    "app_name": "Application Name",
    "summary": "Notification Title",
    "body": "Notification body text",
    "icon": "/path/to/icon.png",
    "urgency": 1,  # 0=low, 1=normal, 2=critical
    "timestamp": "2026-01-01T12:00:00",
}

SimplePopup

A simple centered popup for any purpose.

Basic Usage

from qtile_expanded import SimplePopup

popup = SimplePopup(qtile, text="Hello, World!", timeout=5)
popup.show()

Configuration Options

popup = SimplePopup(
    qtile,
    text="Message",               # Text to display
    background="#1a1a2e",        # Background color
    foreground="#eeeeee",        # Text color
    border_color="#333333",      # Border color
    border_width=2,             # Border width
    corner_radius=8,            # Corner radius
    opacity=0.95,               # Opacity
    font="sans",                # Font family
    fontsize=14,                # Font size
    padding=20,                 # Padding
    max_width=400,              # Maximum width
    timeout=5,                  # Auto-close timeout in seconds (None for no timeout)
)

Methods

popup.show(text)    # Show the popup with optional new text
popup.hide()        # Hide the popup
popup.draw()        # Redraw the popup

API Reference

Popup utilities for Qtile Expanded.

This module provides popup window functionality for displaying notifications and other temporary UI elements.

Features: - NotificationPopup: Full-screen popup for displaying notifications - SimplePopup: General-purpose centered popup - Button: Clickable elements within popups - Layout helpers for organizing popup content

All popups inherit from BasePopup which provides: - Automatic registration when shown - Automatic unregistration when hidden - External control via close_all_popups() function

class qtile_expanded.extensions.popup.NotificationPopup(*args: Any, **kwargs: Any)[source]

Bases: BasePopup

A full-screen popup for displaying notifications.

This popup covers the entire screen and displays a list of notifications with the ability to dismiss them individually or all at once.

Inherits from BasePopup, which automatically registers the popup when shown and unregisters when hidden, enabling external control via close_all_popups().

Args:

qtile: The Qtile instance notifications: List of notification dicts with keys:

app_name: Application name

summary: Notification summary

body: Notification body text

icon: Optional icon path

urgency: Urgency level (0=low, 1=normal, 2=critical)

timestamp: When the notification was received

on_close: Callback when popup is closed on_clear: Callback when all notifications are cleared on_dismiss: Callback when a specific notification is dismissed

__init__(qtile, notifications=None, on_close=None, on_clear=None, on_dismiss=None, **config)[source]: Initialize the notification popup.

defaults = [('background', '#1a1a2e', 'Background color of the popup.'), ('foreground', '#eeeeee', 'Text color.'), ('border_color', '#333333', 'Border color.'), ('border_width', 2, 'Border width.'), ('corner_radius', 8, 'Corner radius for rounded corners.'), ('opacity', 0.95, 'Opacity of the popup (0.0 to 1.0).'), ('font', 'sans', 'Font family.'), ('fontsize', 14, 'Base font size.'), ('title_fontsize', 18, 'Font size for notification titles.'), ('padding', 20, 'Padding around the popup content.'), ('item_padding', 15, 'Padding between notification items.'), ('max_width', 800, 'Maximum width for notification content.'), ('max_notifications', 10, 'Maximum number of notifications to display.'), ('trash_icon', '♻', 'Unicode trash bin icon.'), ('trash_size', 24, 'Size of the trash icon.'), ('close_on_click_outside', True, 'Close popup when clicking outside.')]

draw()[source]: Draw the popup with all notifications.

show(notifications=None)[source]: Show the popup with the given notifications.

update_notifications(notifications)[source]: Update the list of notifications and redraw.

class qtile_expanded.extensions.popup.SimplePopup(*args: Any, **kwargs: Any)[source]

Bases: BasePopup

A simple popup dialog for Qtile.

This is a more general-purpose popup that can be used for any purpose.

Inherits from BasePopup, which automatically registers the popup when shown and unregisters when hidden, enabling external control via close_all_popups().

Args:: qtile: The Qtile instance text: Text to display **config: Additional Popup configuration

__init__(qtile, text='', **config)[source]: Initialize the simple popup.

defaults = [('background', '#1a1a2e', 'Background color.'), ('foreground', '#eeeeee', 'Text color.'), ('border_color', '#333333', 'Border color.'), ('border_width', 2, 'Border width.'), ('corner_radius', 8, 'Corner radius.'), ('opacity', 0.95, 'Opacity.'), ('font', 'sans', 'Font family.'), ('fontsize', 14, 'Font size.'), ('padding', 20, 'Padding.'), ('max_width', 400, 'Maximum width.'), ('timeout', None, 'Auto-close timeout in seconds, or None.')]

draw()[source]: Draw the popup.

show(text=None)[source]: Show the popup with optional new text.