NotificationCenter

The NotificationCenter class provides centralized notification management for Qtile. It maintains a list of all notifications and provides methods to add, remove, and display notifications.

Features

• Centralized state: Single source of truth for all notifications

• DBus integration: Automatically listens to DBus notifications

• Popup display: Built-in support for showing notifications in a popup

• Persistence: Notifications survive across config reloads

• Singleton pattern: Easy to share across multiple widgets

Basic Usage

from qtile_expanded import NotificationCenter

# Get the singleton instance
center = NotificationCenter.get_instance()

# Add a notification
center.add_notification(
    app_name="Firefox",
    summary="New message",
    body="Hello from Alice!"
)

# Show popup
center.show_popup(qtile)

# Clear all notifications
center.clear()

Integration with NotificationBell

The NotificationBell widget can use NotificationCenter for shared notification state:

from qtile_expanded.widgets import NotificationBell

# This bell will use the shared NotificationCenter
bell = NotificationBell(use_notification_center=True)

# Multiple bells can share the same center
bell2 = NotificationBell(use_notification_center=True)

When using NotificationCenter integration: - All widgets share the same notification list - DBus notifications are handled by the center (not each widget) - Popup state is managed centrally - Notifications persist across reloads

Manual Notification Management

from qtile_expanded import NotificationCenter

center = NotificationCenter.get_instance()

# Add notification
notification = center.add_notification(
    summary="New message",
    body="You have a new message",
    app_name="Messages",
    urgency=1,  # 0=low, 1=normal, 2=critical
)

# Dismiss notification by index
center.dismiss_notification(0)

# Get notification count
count = center.get_count()

# Iterate over notifications
for notif in center:
    print(f"{notif['app_name']}: {notif['summary']}")

# Access by index
first = center[0]

# Clear all
center.clear()

Popup Control

center = NotificationCenter.get_instance()

# Show popup
center.show_popup(qtile)

# Hide popup
center.hide_popup()

# Toggle popup
center.toggle_popup(qtile)

# Update popup with new notifications
center.add_notification(summary="New!")
# The popup will automatically update if open

Custom Configuration

from qtile_expanded import NotificationCenter

# Create center with custom configuration
center = NotificationCenter(
    max_notifications=100,      # Max to keep in history
    storage_namespace="my_center",  # For persistence
    persist_state=True,         # Persist across reloads
)

DBus Integration

NotificationCenter automatically listens to DBus notifications via the org.freedesktop.Notifications interface. When a notification is received, it will be automatically added to the center.

Requirements: - dbus-python package installed - A notification daemon running

Notification Replacement

NotificationCenter supports notification replacement (updating an existing notification):

# First notification with ID
center.add_notification(
    summary="Download starting",
    app_name="Downloader",
    replaces_id=123,  # Unique ID for this notification
)

# Later, replace with progress update
center.add_notification(
    summary="Download: 50%",
    app_name="Downloader",
    replaces_id=123,  # Same ID - replaces the first notification
)

API Reference

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