NotificationBell Widget

The NotificationBell widget displays a bell icon that changes color based on notification status. It provides an easy way to track and view notifications in your Qtile bar.

Basic Usage

from qtile_expanded.widgets import NotificationBell

widget_list = [
    NotificationBell(),
]

This adds a bell icon to your Qtile bar that:

• Shows as gray (#888888) when there are no notifications

• Turns red (#ff0000) with a count badge when notifications arrive

• Opens a full-screen popup showing all notifications when clicked

• Includes a trash bin icon to clear all notifications

Configuration Options

Customize the appearance and behavior:

widget_list = [
    NotificationBell(
        # Icon appearance
        icon_no_notifications="\u23fa",  # Unicode bell outline
        icon_with_notifications="\u23fa",
        color_no_notifications="#888888",
        color_with_notifications="#ff0000",

        # Count display
        show_count=True,
        count_format="{count}",  # e.g., "{count}" or "[{count}]"

        # Styling
        font="FontAwesome",
        fontsize=14,
        padding=3,

        # Persistence
        persist_state=True,
        storage_namespace="notification_bell",

        # Popup
        popup_enabled=True,
        popup_background="#1a1a2e",
        popup_foreground="#eeeeee",
        popup_max_notifications=10,

        # Click behavior
        click_behavior="toggle",  # "toggle" or "open"

        # NotificationCenter integration
        use_notification_center=False,
    ),
]

Notification Popup

When you click on the bell icon (if popup_enabled=True), a full-screen popup opens showing all notifications:

Popup Features:

• Lists all notifications with their app name, summary, and body

• Shows timestamp for each notification

• Trash bin icon in the top-right to clear all notifications

• Click on a notification to dismiss it individually

• Click outside the popup to close it

• Customizable colors, fonts, and sizes

Click Behavior:

• Left click: Opens/closes popup (if notifications exist and popup enabled)

• Right click: Clears all notifications

• Trash icon in popup: Clears all notifications

• Click on notification: Dismisses that specific notification

Configuration:

# Disable popup
NotificationBell(popup_enabled=False)

# Custom popup styling
NotificationBell(
    popup_background="#1a1a2e",
    popup_foreground="#ffffff",
    popup_max_notifications=20,
)

# Click behavior
NotificationBell(click_behavior="toggle")  # Toggle popup on click (default)
NotificationBell(click_behavior="open")    # Always open popup on click

Persistent State

By default, NotificationBell persists the full notification list across config reloads using StateStorage:

# Disable persistence
NotificationBell(persist_state=False)

# Use custom namespace for storage
NotificationBell(storage_namespace="my_notification_widget")

This means your notifications will survive even if you reload your Qtile config.

NotificationCenter Integration

For advanced usage with multiple widgets sharing notification state, use NotificationCenter:

from qtile_expanded import NotificationCenter

# Create a shared notification center
center = NotificationCenter.get_instance()

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

# Both will show the same notifications

This is useful when you want to have multiple notification displays or coordinate notification state across different parts of your config.

Manual Control

You can also control notifications manually:

from qtile_expanded.widgets import NotificationBell

bell = NotificationBell()

# Add a notification manually
bell.add_notification(
    summary="New message",
    body="You have a new message from Alice",
    app_name="Messages"
)

# Set notifications directly
bell.set_notifications([
    {"app_name": "App1", "summary": "Hello", "body": "World"},
    {"app_name": "App2", "summary": "Test", "body": "Notification"},
])

# Dismiss specific notification by index
bell.dismiss_notification(0)  # Remove first notification

# Clear all notifications
bell.clear_notifications()

DBus Integration

NotificationBell automatically listens to DBus notifications via the org.freedesktop.Notifications interface. This means it will automatically pick up notifications from applications that send notifications via DBus.

Requirements: - dbus-python package installed - A notification daemon running (e.g., dunst, notify-osd)

Notification Data Structure

Each notification is stored as a dictionary with the following fields:

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

API Reference

Notification Bell Widget for Qtile.

A widget that displays a bell icon which changes color based on notification status: - Gray when there are no notifications - Red with a count badge when there are notifications

This widget listens to DBus notifications to track notification count. Optionally persists notification count across config reloads using StateStorage. Clicking the bell opens a full-screen popup showing all notifications with a trash bin to clear them.

The widget can use a shared NotificationCenter instance or manage its own notifications.

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