Widgets API

Widgets for Qtile Expanded.

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

NotificationBell

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.

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.