API Reference

This section contains the complete API reference for qtile-expanded.

Main Package

Qtile Expanded - Additional extensions to expand Qtile into more like a desktop environment.

This package provides additional widgets and utilities for Qtile window manager.

Features:

• StateStorage: Persistent state across config reloads

• NotificationBell: Bell icon widget with popup notifications

• NotificationPopup: Full-screen popup for displaying notifications

• NotificationCenter: Centralized notification management

• SimplePopup: General-purpose popup dialogs

Repository:

https://g.arns.lt/zordsdavini/qtile-expanded

Contact:

@zordsdavini@s.arns.lt

License:

MIT

class qtile_expanded.NotificationBell(*args: Any, **kwargs: Any)

Bases: _TextBox

A bell icon widget that indicates notification status.

The icon is gray (no notifications) or red (with count) when notifications exist.

Usage in config:

from qtile_expanded.widgets import NotificationBell

widget_list = [

NotificationBell(), # … other widgets

]

Attributes:

notifications_count: Current count of notifications (default: 0) notifications: List of notification dicts (default: []) icon_no_notifications: Icon to display when no notifications (default: bell outline) icon_with_notifications: Icon to display when notifications exist (default: bell outline) color_no_notifications: Color when no notifications (default: “#888888”) color_with_notifications: Color when notifications exist (default: “#ff0000”) show_count: Whether to show notification count badge (default: True) count_format: Format string for count display (default: “{count}”) popup_enabled: Whether clicking opens a popup (default: True) use_notification_center: Use shared NotificationCenter (default: False)

__init__(**config)

Initialize the NotificationBell widget.

add_notification(summary='', body='', app_name='', **kwargs)

Manually add a notification. Useful when DBus is not available.

Args:

summary: Notification summary/title body: Notification body text app_name: Application name **kwargs: Additional notification data (icon, urgency, etc.)

button_press(x, y, button)

Handle button press events.

calculate_length()

Calculate the length of the widget text.

clear_notifications()

Clear all notifications.

defaults: list[tuple[str, Any, str]] = [('notifications_count', 0, 'Current count of notifications.'), ('notifications', [], 'List of notification dicts.'), ('icon_no_notifications', '⏺', 'Icon when no notifications (FA bell outline).'), ('icon_with_notifications', '⏺', 'Icon when notifications exist (FA bell outline).'), ('color_no_notifications', '#888888', 'Color when no notifications.'), ('color_with_notifications', '#ff0000', 'Color when notifications exist.'), ('show_count', True, 'Whether to show notification count badge.'), ('count_format', '{count}', 'Format string for count display.'), ('font', 'FontAwesome', 'Font to use for icons.'), ('fontsize', 14, 'Font size.'), ('padding', 3, 'Padding around the icon.'), ('persist_state', True, 'Whether to persist notifications across reloads.'), ('storage_namespace', 'notification_bell', 'Namespace for state storage.'), ('popup_enabled', True, 'Whether clicking opens a popup.'), ('popup_background', '#1a1a2e', 'Popup background color.'), ('popup_foreground', '#eeeeee', 'Popup text color.'), ('popup_max_notifications', 10, 'Max notifications to show in popup.'), ('click_behavior', 'toggle', "Click behavior: 'toggle' or 'open'. 'toggle' opens/closes popup, 'open' always opens."), ('use_notification_center', False, 'Use shared NotificationCenter instance instead of own state.')]

dismiss_notification(index)

Dismiss a specific notification by index.

Args:

index: Index of notification to dismiss

info()

Return info about the widget for debugging.

set_notifications(notifications)

Set the notifications list directly.

Args:

notifications: List of notification dicts

update_text()

Update the displayed text based on notification count.

class qtile_expanded.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.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.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

class qtile_expanded.StateStorage(namespace: str, cache_dir: str | Path | None = None, auto_save: bool = True)

Bases: object

Persistent key-value storage for Qtile that survives config reloads.

Data is stored as JSON in ~/.cache/qtile/qtile_expanded/{namespace}.json

Args:

namespace: Unique identifier for this storage (e.g., “my_widget”) cache_dir: Override the Qtile cache directory (default: ~/.cache/qtile) auto_save: Whether to automatically save after each write (default: True)

Attributes:

data: The loaded state dictionary

__init__(namespace: str, cache_dir: str | Path | None = None, auto_save: bool = True)

Initialize StateStorage with a namespace.

clear() → None

Clear all data from the storage.

decrement(key: str, amount: int = 1) → int

Decrement a numeric value in the storage.

Args:

key: The key to decrement amount: The amount to decrement by (default: 1)

Returns:

The new value

delete(key: str) → bool

Delete a value from the storage.

Args:

key: The key to delete

Returns:

True if the key existed and was deleted, False otherwise

get(key: str, default: Any | None = None) → Any

Get a value from the storage.

Args:

key: The key to retrieve default: Default value if key doesn’t exist

Returns:

The stored value, or default if not found

classmethod get_instance(namespace: str, **kwargs) → StateStorage

Get or create a StateStorage instance with the given namespace.

This ensures only one instance per namespace exists.

Args:

namespace: The storage namespace **kwargs: Additional arguments passed to StateStorage constructor

Returns:

The StateStorage instance

has(key: str) → bool

Check if a key exists in the storage.

increment(key: str, amount: int = 1) → int

Increment a numeric value in the storage.

Args:

key: The key to increment amount: The amount to increment by (default: 1)

Returns:

The new value

items() → list[tuple[str, Any]]

Get all key-value pairs in the storage.

keys() → list[str]

Get all keys in the storage.

save() → None

Save state to the JSON file.

classmethod save_all() → None

Save all registered StateStorage instances.

set(key: str, value: Any) → None

Set a value in the storage.

Args:

key: The key to store the value under value: The value to store (must be JSON-serializable)

toggle(key: str, default: bool = False) → bool

Toggle a boolean value in the storage.

Args:

key: The key to toggle default: Default value if key doesn’t exist

Returns:

The new value

update(other: dict[str, Any]) → None

Update the storage with multiple key-value pairs.

Args:

other: Dictionary of key-value pairs to update

values() → list[Any]

Get all values in the storage.

qtile_expanded.setup_qtile_hooks(qtile) → None

Set up Qtile hooks to automatically save state before reload/shutdown.

This function should be called from your Qtile config:

from qtile_expanded.storage import setup_qtile_hooks

def main(q):

setup_qtile_hooks(q) # … rest of your config

Args:

qtile: The Qtile instance (usually ‘q’ in config.py)

Submodules

• StateStorage API
  • StateStorage
  • setup_qtile_hooks()
  • Classes
  • Functions
• Extensions API
  • BasePopup
  • NotificationCenter
  • NotificationPopup
  • PopupRegistry
  • SimplePopup
  • close_all_popups()
  • get_open_popups()
  • is_popup_open()
  • Popup Module
  • NotificationCenter Module
• Widgets API
  • NotificationBell
  • NotificationBell