wijjit.core.notification_manager.NotificationManager

class wijjit.core.notification_manager.NotificationManager(overlay_manager, terminal_width, terminal_height, position='top-right', spacing=1, margin=2, max_stack=5)

Manager for notification stack and lifecycle.

This class manages multiple active notifications, handling their positioning in a stack, auto-dismissal based on timeouts, and integration with the overlay manager.

Parameters:

• overlay_manager (OverlayManager) – Overlay manager instance for displaying notifications

• terminal_width (int) – Current terminal width

• terminal_height (int) – Current terminal height

• position (str, optional) – Stack position: “top-right”, “top-left”, “bottom-right”, “bottom-left” (default: “top-right”)

• spacing (int, optional) – Vertical spacing between stacked notifications (default: 1)

• margin (int, optional) – Margin from screen edges (default: 2)

• max_stack (int or None, optional) – Maximum number of concurrent notifications. When limit is reached, oldest notifications are automatically dismissed. None = unlimited (default: 5)

Variables:

• overlay_manager (OverlayManager) – Overlay manager reference

• terminal_width (int) – Terminal width

• terminal_height (int) – Terminal height

• position (str) – Stack position

• spacing (int) – Spacing between notifications

• margin (int) – Edge margin

• max_stack (int or None) – Maximum stack size

• notifications (list) – List of active notifications (oldest first)

• _lock (threading.Lock) – Thread lock for protecting notification list access

Notes

All notification list access is protected by a threading.Lock to ensure thread safety when notifications are added, removed, or checked from multiple threads or async tasks.

__init__(overlay_manager, terminal_width, terminal_height, position='top-right', spacing=1, margin=2, max_stack=5)

Parameters:

• overlay_manager (OverlayManager)

• terminal_width (int)

• terminal_height (int)

• position (str)

• spacing (int)

• margin (int)

• max_stack (int | None)

Return type:

None

Methods

__init__(overlay_manager, terminal_width, ...)
add(element[, duration, on_close])	Add a notification to the stack.
check_expired()	Check for expired notifications and remove them (synchronous).
check_expired_async()	Check for expired notifications and remove them (asynchronous).
clear()	Remove all notifications.
dismiss_oldest()	Dismiss the oldest notification.
dismiss_topmost()	Dismiss the topmost (most recent) notification.
is_empty()	Check if there are any active notifications (thread-safe).
remove(notification_id)	Remove a notification from the stack.
update_positions()	Update positions of all notifications in the stack.
update_terminal_size(width, height)	Update terminal size and reposition notifications.

add(element, duration=3.0, on_close=None)

Add a notification to the stack.

If max_stack is set and the stack is full, the oldest notification will be automatically dismissed before adding the new one.

Parameters:

• element (NotificationElement) – Notification element to display

• duration (float or None, optional) – Duration in seconds before auto-dismiss (default: 3.0) Set to None for no auto-dismiss

• on_close (callable, optional) – Callback when notification is dismissed

Returns:

Notification ID for manual dismissal

Return type:

str

remove(notification_id)

Remove a notification from the stack.

Parameters:

notification_id (str) – ID of notification to remove

Returns:

True if notification was removed, False if not found

Return type:

bool

check_expired()

Check for expired notifications and remove them (synchronous).

Returns:

True if any notifications were removed, False otherwise

Return type:

bool

async check_expired_async()

Check for expired notifications and remove them (asynchronous).

This async version allows the event loop to process other tasks while checking and removing expired notifications.

Returns:

True if any notifications were removed, False otherwise

Return type:

bool

update_positions()

Update positions of all notifications in the stack.

This should be called after adding/removing notifications or when terminal size changes.

Return type:

None

update_terminal_size(width, height)

Update terminal size and reposition notifications.

Parameters:

• width (int) – New terminal width

• height (int) – New terminal height

Return type:

None

clear()

Remove all notifications.

Returns:

Number of notifications removed

Return type:

int

dismiss_oldest()

Dismiss the oldest notification.

Returns:

True if a notification was dismissed, False if none exist

Return type:

bool

dismiss_topmost()

Dismiss the topmost (most recent) notification.

Returns:

True if a notification was dismissed, False if none exist

Return type:

bool

is_empty()

Check if there are any active notifications (thread-safe).

Returns:

True if no notifications are active, False otherwise

Return type:

bool