Notification Manager
Relevant source files
The following files were used as context for generating this wiki page:
The Notification Manager is a core system component of FlxOS responsible for handling system-wide alerts, app-specific notifications, and toast popups. It provides a centralized service for applications to register notifications, which are then displayed and managed through the desktop environment's user interface.
Sources: ROADMAP.md:89, main/core/system/notification/NotificationManager.cpp:11-14
System Architecture
The Notification Manager operates as a singleton within the System namespace. It maintains an internal registry of notifications and uses the LVGL observer pattern to notify UI components of state changes, such as new notifications or changes in the unread count.
Core Components
| Component | Description |
|---|---|
| NotificationManager | Singleton class managing the lifecycle, storage, and state of all notifications. |
| Notification Structure | Data structure containing notification metadata (ID, title, message, app name, icon, priority, timestamp). |
| NotificationPanel | UI module that displays the list of notifications in the desktop environment. |
| LVGL Subjects | Reactive data sources used to update the UI (unread count and list updates). |
Sources: main/core/system/notification/NotificationManager.hpp:15-40, main/core/ui/desktop/modules/notification_panel/NotificationPanel.cpp:21-25
Class Relationship
The following diagram illustrates the relationship between the management logic and the UI presentation layer.
Notification Lifecycle
Notifications are generated by system services or user applications and flow through the manager to the UI.
1. Creation and ID Generation
When addNotification is called, the system generates a unique ID using the system timer and a static counter. The notification is then inserted at the beginning of the internal vector to ensure a "newest first" display order.
std::string NotificationManager::generateId() {
static int counter = 0;
std::stringstream ss;
ss << "notif_" << esp_timer_get_time() << "_" << counter++;
return ss.str();
}
Sources: main/core/system/notification/NotificationManager.cpp:30-35, main/core/system/notification/NotificationManager.cpp:37-54
2. UI Notification Flow
The Notification Manager uses a thread-safe update mechanism to signal the UI task. It locks the GuiTask mutex before updating LVGL subjects to prevent race conditions during rendering.
Data Management
Notification Structure
Every notification is represented by a Notification struct.
| Field | Type | Description |
|---|---|---|
id | std::string | Unique identifier generated at runtime. |
title | std::string | Header text of the notification. |
message | std::string | Detailed body text. |
appName | std::string | Name of the originating application. |
icon | const void* | Pointer to LVGL image source or symbol. |
priority | int | Importance level. |
timestamp | uint32_t | Creation time in seconds (from esp_timer). |
isRead | bool | Boolean flag for read/unread status. |
Sources: main/core/system/notification/NotificationManager.hpp:17-26, main/core/system/notification/NotificationManager.cpp:46-50
Interaction API
The manager provides several methods for state manipulation:
- removeNotification(id): Removes a specific notification by ID.
- clearAll(): Purges all stored notifications.
- markAsRead(id): Sets the
isReadflag for a specific entry. - markAllAsRead(): Updates all entries to read status.
Sources: main/core/system/notification/NotificationManager.cpp:57-101
UI Implementation: NotificationPanel
The NotificationPanel is a UI module that visualizes the data managed by the singleton. It is excluded from the build when CONFIG_FLXOS_HEADLESS_MODE is enabled.
UI Features
- Glass Effect: Applies a blur effect to the background using
StyleUtils::apply_glass. - Dynamic List: Automatically rebuilds the list using
update_list()when them_update_subjectchanges. - Swipe Indicator: Provides visual cues for gestures.
- Clear All Button: Directly invokes
NotificationManager::clearAll().
Sources: main/core/ui/desktop/modules/notification_panel/NotificationPanel.cpp:32-40, main/core/ui/desktop/modules/notification_panel/NotificationPanel.cpp:66-73, main/CMakeLists.txt:46
Initialization at Boot
The system initializes the Notification Manager during the app_main sequence and typically sends a "Welcome" notification to confirm successful boot.
#if !CONFIG_FLXOS_HEADLESS_MODE
System::NotificationManager::getInstance().init();
Log::info(TAG, "Sending welcome notification");
System::NotificationManager::getInstance().addNotification("Welcome", "FlxOS initialized successfully!", "System", LV_SYMBOL_OK, 1);
#endif
Sources: main/main.cpp:28-32
Conclusion
The Notification Manager provides a robust, thread-safe framework for handling asynchronous alerts in FlxOS. By decoupling the notification storage logic from the LVGL-based UI via the observer pattern, it ensures that both system services and user apps can reliably communicate with the user without interfering with the main GUI rendering cycle.