Relevant source files

The following files were used as context for generating this wiki page: - [main/core/system/notification/NotificationManager.cpp](https://github.com/flxos-labs/flxos/blob/main/main/core/system/notification/NotificationManager.cpp) - [main/core/system/notification/NotificationManager.hpp](https://github.com/flxos-labs/flxos/blob/main/main/core/system/notification/NotificationManager.hpp) - [main/core/ui/desktop/modules/notification_panel/NotificationPanel.cpp](https://github.com/flxos-labs/flxos/blob/main/main/core/ui/desktop/modules/notification_panel/NotificationPanel.cpp) - [main/main.cpp](https://github.com/flxos-labs/flxos/blob/main/main/main.cpp) - [main/CMakeLists.txt](https://github.com/flxos-labs/flxos/blob/main/main/CMakeLists.txt) - [ROADMAP.md](https://github.com/flxos-labs/flxos/blob/main/ROADMAP.md)

# Notification Manager 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. ```mermaid classDiagram class NotificationManager { -vector~Notification~ m_notifications -mutex m_mutex -lv_subject_t m_unread_count_subject -lv_subject_t m_update_subject +getInstance() NotificationManager$ +addNotification(title, message, appName, icon, priority) +removeNotification(id) +markAsRead(id) +getUnreadCount() size_t } class Notification { +string id +string title +string message +string appName +void* icon +int priority +uint32_t timestamp +bool isRead } class NotificationPanel { -lv_obj_t* m_panel -lv_obj_t* m_list +update_list() -on_clear_click(e) } NotificationManager "1" *-- "many" Notification : stores NotificationPanel ..> NotificationManager : observes subjects ``` Sources: [main/core/system/notification/NotificationManager.hpp:17-55](), [main/core/ui/desktop/modules/notification_panel/NotificationPanel.cpp:66-73]() ## 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. ```cpp 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. ```mermaid sequenceDiagram participant App as Application/System participant NM as NotificationManager participant GT as GuiTask participant UI as NotificationPanel App->>NM: addNotification(title, msg, ...) NM->>NM: Generate unique ID NM->>NM: Push to m_notifications NM->>GT: lock() NM->>NM: lv_subject_set_int(m_update_subject) NM->>GT: unlock() GT->>UI: Trigger Observer Callback UI->>NM: getNotifications() UI->>UI: update_list() ``` Sources: [main/core/system/notification/NotificationManager.cpp:106-121](), [main/core/ui/desktop/modules/notification_panel/NotificationPanel.cpp:66-73]() ## 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 `isRead` flag 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 the `m_update_subject` changes. * **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. ```cpp #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.