Focus Management
Relevant source files
The following files were used as context for generating this wiki page:
Focus Management in FlxOS is a centralized system responsible for handling the Z-order, visual state, and interactive priority of windows and UI panels. It ensures that the user interface remains responsive and organized by managing exclusive visibility between different components such as the app launcher, notification panel, and active application windows.
The system is primarily implemented through the FocusManager class, which interacts with the LVGL object tree to bring specific elements to the foreground and dismiss background or inactive panels. It serves as a critical component of the Window Manager and Desktop environment to provide a cohesive multi-window experience on ESP32 hardware.
Sources: main/core/system/focus/FocusManager.hpp:10-15, main/core/README.md
Core Architecture
The FocusManager follows a singleton pattern, providing a centralized point of control for the system's UI hierarchy. It maintains references to major UI containers, including the window container, the root screen, the status bar, and the system dock.
Managed Components
The manager tracks two primary types of UI elements:
- Windows: Application-level containers that can be activated, bringing them to the front of the Z-order.
- Panels: Persistent or transient system UI elements like the launcher, quick access panel, or notification panel.
Focus Logic and Event Handling
Focus Management relies on global event callbacks to detect user interactions. Specifically, it uses on_global_press and on_global_release to monitor touch inputs across the screen. These callbacks allow the system to determine if a user has clicked outside an active panel, triggering a dismissal of transient UI elements.
Activation Flow
When a window or panel is activated, the FocusManager performs several operations:
- Z-Order Adjustment: The target object is moved to the front of its respective container.
- Exclusive Visibility: Activating a panel typically involves hiding other registered panels to prevent UI overlap.
- Visual Feedback: Updating the state of the active window to reflect its focused status.
System Integration
The FocusManager is integrated into the core build process and is only included when headless mode is disabled, as it requires the LVGL graphics stack. It interacts closely with application modules, such as the FilesApp, which may trigger focus changes when dialogs or sub-windows are created.
Key API Methods
| Method | Description |
|---|---|
registerWindow(lv_obj_t* win) | Adds a window to the focus management queue for event tracking. |
activateWindow(lv_obj_t* win) | Brings the specified window to the front and updates its visual state. |
activatePanel(lv_obj_t* panel) | Displays a system panel while dismissing all other open panels. |
togglePanel(lv_obj_t* panel) | Switches the visibility of a panel (e.g., opening/closing the launcher). |
dismissAllPanels() | Immediately hides all registered transient panels. |
Sources: main/core/system/focus/FocusManager.hpp:34-60, main/CMakeLists.txt:30-45
Gesture and Swipe Support
The FocusManager includes private members for tracking swipe gestures, specifically for accessing the notification panel. It tracks the starting Y-coordinate of a touch event (m_swipeStartY) and uses a boolean flag (m_swipeTracking) to manage the state of the gesture during the interaction.
Sources: main/core/system/focus/FocusManager.hpp:81-84
Implementation Constraints
As noted in system reports, the focus management logic involves significant complexity in certain areas:
- Cyclomatic Complexity: Functions like
activateWindowandon_global_presshave high complexity (rating of 17) due to the numerous conditional checks required to handle different UI states and object types. - Nesting Depth: Event handlers for global presses reach a nesting depth of 5, reflecting the deep inspection of the LVGL object tree required to determine interaction targets.
Sources: reports/complexity.txt:20-23, reports/code_quality_report.md:35-40
Conclusion
Focus Management provides the necessary logic to maintain a clean and usable desktop interface in FlxOS. By centralizing the control of Z-order and panel visibility, the system prevents UI conflicts and ensures that user interactions are always directed to the appropriate foreground element.