Extensions API

Qtile Expanded Extensions.

This module contains general Qtile extensions that are not specifically widgets.

Popup functionality: - BasePopup: Base class for all popups with auto-registration - PopupRegistry: Tracks all open popups - close_all_popups(): Close all open popups - is_popup_open(): Check if any popup is open - get_open_popups(): Get list of open popups - NotificationPopup: Full-screen notification display - SimplePopup: General-purpose popup

Notification management: - NotificationCenter: Centralized notification management with DBus support

class qtile_expanded.extensions.BasePopup(*args: Any, **kwargs: Any)

Bases: Popup

Base class for all Qtile Expanded popups.

This class extends Qtile’s Popup with: - Automatic registration in PopupRegistry when shown - Automatic unregistration when hidden - Support for external close commands (gestures, keybindings)

All popup classes should inherit from this class instead of directly from libqtile.popup.Popup.

Usage:

from qtile_expanded.extensions.base_popup import BasePopup

class MyPopup(BasePopup):

def __init__(self, qtile, **config):

super().__init__(qtile, **config) # Your initialization

__init__(qtile, **config)

Initialize the base popup.

classmethod close_all() → int

Close all popups of this type.

Returns:

Number of popups closed

classmethod is_any_open() → bool

Check if any popup is open.

show(*args, **kwargs)

Show the popup and register it.

class qtile_expanded.extensions.NotificationCenter(max_notifications: int = 50, storage_namespace: str = 'notification_center', persist_state: bool = True)

Bases: object

Centralized notification management for Qtile.

This class maintains a list of notifications and provides methods to: - Add notifications (from DBus or manually) - Remove notifications - Show notifications in a popup - Persist notifications across reloads

Usage:

from qtile_expanded.extensions.notification_center import NotificationCenter

# Create a notification center center = NotificationCenter()

# Add a notification center.add_notification(

app_name=”Firefox”, summary=”New message”, body=”Hello from Alice!”

)

# Show popup center.show_popup(qtile)

# Clear all center.clear()

Attributes:

notifications: List of notification dicts max_notifications: Maximum notifications to keep

__init__(max_notifications: int = 50, storage_namespace: str = 'notification_center', persist_state: bool = True)

Initialize NotificationCenter.

Args:

max_notifications: Maximum number of notifications to keep in history storage_namespace: Namespace for state storage persist_state: Whether to persist notifications across reloads

add_notification(summary: str = '', body: str = '', app_name: str = '', icon: str | None = None, urgency: int = 1, replaces_id: int = 0, hints: dict | None = None, **kwargs) → dict[str, Any]

Add a notification.

Args:

summary: Notification summary/title body: Notification body text app_name: Application name icon: Icon path urgency: Urgency level (0=low, 1=normal, 2=critical) replaces_id: ID of notification this replaces hints: Additional hints from DBus **kwargs: Additional metadata

Returns:

The created notification dict

clear() → None

Clear all notifications.

dismiss_notification(index: int) → bool

Dismiss a notification by index.

Args:

index: Index of notification to dismiss

Returns:

True if notification was dismissed, False otherwise

get_count() → int

Get the number of notifications.

classmethod get_instance() → NotificationCenter

Get or create the singleton instance.

get_unread_count() → int

Get the number of unread notifications.

hide_popup() → None

Hide the notification popup.

mark_all_as_read() → None

Mark all notifications as read.

show_popup(qtile, **config) → None

Show the notification popup.

Args:

qtile: The Qtile instance **config: Additional configuration for the popup

toggle_popup(qtile, **config) → None

Toggle the notification popup.

Args:

qtile: The Qtile instance **config: Additional configuration for the popup

class qtile_expanded.extensions.NotificationPopup(*args: Any, **kwargs: Any)

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)

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()

Draw the popup with all notifications.

show(notifications=None)

Show the popup with the given notifications.

update_notifications(notifications)

Update the list of notifications and redraw.

class qtile_expanded.extensions.PopupRegistry

Bases: object

Registry for tracking all open popups.

This singleton class maintains a list of all open popups, allowing external code to check if popups are open and close them programmatically.

Usage:

from qtile_expanded.extensions.base_popup import PopupRegistry

# Check if any popup is open if PopupRegistry.is_popup_open():

print(“A popup is open”)

# Close all popups PopupRegistry.close_all_popups()

# Get list of open popups open_popups = PopupRegistry.get_open_popups()

classmethod close_all_popups() → int

Close all open popups.

Returns:

Number of popups closed

classmethod close_popup(popup) → bool

Close a specific popup if it’s open.

Args:

popup: The popup instance to close

Returns:

True if the popup was open and closed, False otherwise

classmethod get_open_popups() → list

Get list of all open popups.

classmethod is_popup_open() → bool

Check if any popup is currently open.

classmethod register(popup) → None

Register a popup as open.

classmethod unregister(popup) → None

Unregister a popup when it’s closed.

class qtile_expanded.extensions.SimplePopup(*args: Any, **kwargs: Any)

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)

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()

Draw the popup.

show(text=None)

Show the popup with optional new text.

qtile_expanded.extensions.close_all_popups() → int

Close all open popups.

This function can be called from anywhere (e.g., gesture handlers, keybindings) to close all open popups.

Returns:

Number of popups closed

Example:

from qtile_expanded.extensions.base_popup import close_all_popups

# In your Qtile config def close_popups(qtile):

count = close_all_popups() if count > 0:

print(f”Closed {count} popups”)

keys = [

Key([“mod1”], “Escape”, lazy.function(close_popups)),

]

qtile_expanded.extensions.get_open_popups() → list

Get list of all currently open popups.

Returns:

List of open popup instances

qtile_expanded.extensions.is_popup_open() → bool

Check if any popup is currently open.

Returns:

True if at least one popup is open, False otherwise

Example:

from qtile_expanded.extensions.base_popup import is_popup_open

if is_popup_open():

print(“There is a popup open”)

Popup Module

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)

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)

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()

Draw the popup with all notifications.

drawer: Drawer

show(notifications=None)

Show the popup with the given notifications.

update_notifications(notifications)

Update the list of notifications and redraw.

win: Any

class qtile_expanded.extensions.popup.SimplePopup(*args: Any, **kwargs: Any)

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)

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()

Draw the popup.

drawer: Drawer

show(text=None)

Show the popup with optional new text.

win: Any

NotificationPopup

class qtile_expanded.extensions.popup.NotificationPopup(*args: Any, **kwargs: Any)

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)

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()

Draw the popup with all notifications.

drawer: Drawer

show(notifications=None)

Show the popup with the given notifications.

update_notifications(notifications)

Update the list of notifications and redraw.

win: Any

SimplePopup

class qtile_expanded.extensions.popup.SimplePopup(*args: Any, **kwargs: Any)

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)

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()

Draw the popup.

drawer: Drawer

show(text=None)

Show the popup with optional new text.

win: Any

NotificationCenter Module

Notification Center for Qtile Expanded.

This module provides a centralized notification management system that: - Tracks all notifications - Manages notification history - Provides popup display functionality - Integrates with DBus notifications

This allows widgets like NotificationBell to display notifications without having to manage the popup logic themselves.

class qtile_expanded.extensions.notification_center.NotificationCenter(max_notifications: int = 50, storage_namespace: str = 'notification_center', persist_state: bool = True)

Bases: object

Centralized notification management for Qtile.

This class maintains a list of notifications and provides methods to: - Add notifications (from DBus or manually) - Remove notifications - Show notifications in a popup - Persist notifications across reloads

Usage:

from qtile_expanded.extensions.notification_center import NotificationCenter

# Create a notification center center = NotificationCenter()

# Add a notification center.add_notification(

app_name=”Firefox”, summary=”New message”, body=”Hello from Alice!”

)

# Show popup center.show_popup(qtile)

# Clear all center.clear()

Attributes:

notifications: List of notification dicts max_notifications: Maximum notifications to keep

__init__(max_notifications: int = 50, storage_namespace: str = 'notification_center', persist_state: bool = True)

Initialize NotificationCenter.

Args:

max_notifications: Maximum number of notifications to keep in history storage_namespace: Namespace for state storage persist_state: Whether to persist notifications across reloads

add_notification(summary: str = '', body: str = '', app_name: str = '', icon: str | None = None, urgency: int = 1, replaces_id: int = 0, hints: dict | None = None, **kwargs) → dict[str, Any]

Add a notification.

Args:

summary: Notification summary/title body: Notification body text app_name: Application name icon: Icon path urgency: Urgency level (0=low, 1=normal, 2=critical) replaces_id: ID of notification this replaces hints: Additional hints from DBus **kwargs: Additional metadata

Returns:

The created notification dict

clear() → None

Clear all notifications.

dismiss_notification(index: int) → bool

Dismiss a notification by index.

Args:

index: Index of notification to dismiss

Returns:

True if notification was dismissed, False otherwise

get_count() → int

Get the number of notifications.

classmethod get_instance() → NotificationCenter

Get or create the singleton instance.

get_unread_count() → int

Get the number of unread notifications.

hide_popup() → None

Hide the notification popup.

mark_all_as_read() → None

Mark all notifications as read.

show_popup(qtile, **config) → None

Show the notification popup.

Args:

qtile: The Qtile instance **config: Additional configuration for the popup

toggle_popup(qtile, **config) → None

Toggle the notification popup.

Args:

qtile: The Qtile instance **config: Additional configuration for the popup

NotificationCenter

class qtile_expanded.extensions.notification_center.NotificationCenter(max_notifications: int = 50, storage_namespace: str = 'notification_center', persist_state: bool = True)

Bases: object

Centralized notification management for Qtile.

This class maintains a list of notifications and provides methods to: - Add notifications (from DBus or manually) - Remove notifications - Show notifications in a popup - Persist notifications across reloads

Usage:

from qtile_expanded.extensions.notification_center import NotificationCenter

# Create a notification center center = NotificationCenter()

# Add a notification center.add_notification(

app_name=”Firefox”, summary=”New message”, body=”Hello from Alice!”

)

# Show popup center.show_popup(qtile)

# Clear all center.clear()

Attributes:

notifications: List of notification dicts max_notifications: Maximum notifications to keep

__getitem__(index: int) → dict[str, Any]

Get a notification by index.

__init__(max_notifications: int = 50, storage_namespace: str = 'notification_center', persist_state: bool = True)

Initialize NotificationCenter.

Args:

max_notifications: Maximum number of notifications to keep in history storage_namespace: Namespace for state storage persist_state: Whether to persist notifications across reloads

__iter__()

Iterate over notifications.

__len__() → int

Get the number of notifications.

add_notification(summary: str = '', body: str = '', app_name: str = '', icon: str | None = None, urgency: int = 1, replaces_id: int = 0, hints: dict | None = None, **kwargs) → dict[str, Any]

Add a notification.

Args:

summary: Notification summary/title body: Notification body text app_name: Application name icon: Icon path urgency: Urgency level (0=low, 1=normal, 2=critical) replaces_id: ID of notification this replaces hints: Additional hints from DBus **kwargs: Additional metadata

Returns:

The created notification dict

clear() → None

Clear all notifications.

dismiss_notification(index: int) → bool

Dismiss a notification by index.

Args:

index: Index of notification to dismiss

Returns:

True if notification was dismissed, False otherwise

get_count() → int

Get the number of notifications.

classmethod get_instance() → NotificationCenter

Get or create the singleton instance.

get_unread_count() → int

Get the number of unread notifications.

hide_popup() → None

Hide the notification popup.

mark_all_as_read() → None

Mark all notifications as read.

show_popup(qtile, **config) → None

Show the notification popup.

Args:

qtile: The Qtile instance **config: Additional configuration for the popup

toggle_popup(qtile, **config) → None

Toggle the notification popup.

Args:

qtile: The Qtile instance **config: Additional configuration for the popup