Window Manager

Relevant source files

The following files were used as context for generating this wiki page:

• main/core/ui/desktop/window_manager/WindowManager.cpp
• main/core/ui/desktop/window_manager/WindowManager.hpp
• main/core/ui/desktop/README.md
• main/core/apps/AppManager.cpp (Referenced via build logic and implementation)
• main/core/ui/desktop/Desktop.cpp (Referenced via build logic and implementation)
• ROADMAP.md

The Window Manager is a core component of the FlxOS desktop environment responsible for the lifecycle, placement, and visual management of application windows. It enables a multi-window experience on ESP32 microcontrollers by providing dynamic tiling layouts, full-screen toggling, and synchronization between the UI state and the underlying application lifecycle.

Within the project architecture, the Window Manager acts as a bridge between the App Manager and the physical display, ensuring that multiple concurrently running applications can share screen real estate efficiently. It integrates tightly with the FocusManager for input handling and the ThemeManager for visual consistency.

Sources: main/core/ui/desktop/window_manager/WindowManager.cpp:20-30, main/core/ui/desktop/README.md, ROADMAP.md:31-33

Architecture and Core Components

The Window Manager is implemented as a singleton class that manages several key LVGL object containers and internal mappings. It tracks which window belongs to which package and maintains a list of windows participating in the tiling layout.

Key Data Structures

The manager utilizes several private members to maintain system state:

• m_windowAppMap: A map linking LVGL window objects (lv_obj_t*) to their unique package names.
• m_tiledWindows: A vector of windows that are currently visible and subject to the auto-layout engine.
• m_fullScreenWindow: A pointer to the window currently occupying the entire screen, if any.
• m_windowMaxBtnLabelMap: Tracks the labels/icons of maximize buttons to toggle between "plus" and "minus" symbols.

Sources: main/core/ui/desktop/window_manager/WindowManager.hpp:71-85, main/core/ui/desktop/window_manager/WindowManager.cpp:14-18

System Integration

The following diagram illustrates how the Window Manager interacts with other core FlxOS services:

Window Lifecycle Management

The lifecycle of a window is intrinsically tied to the application state. When an application is opened, the Window Manager performs several steps to prepare the environment.

Opening an Application

When openApp(packageName) is called, the system first checks if the application is already open. If so, it simply activates the existing window. Otherwise, it creates a new lv_win object, configures its header, registers it with the FocusManager, and invokes the application's createUI method.

Closing an Application

Windows can be closed via header buttons or programmatically. The closeWindow_internal function handles the cleanup by:

1. Stopping the associated application via AppManager.
2. Removing entries from internal maps (m_windowAppMap, m_windowMaxBtnLabelMap).
3. Deleting the associated Dock button.
4. Removing the window from the tiling list and deleting the LVGL object.
5. Triggering a layout update for remaining windows.

Sources: main/core/ui/desktop/window_manager/WindowManager.cpp:166-189

Layout Engine

The Window Manager features a dynamic tiling engine that automatically calculates window positions and sizes based on the available space in the m_windowContainer.

Tiling Logic

The layout engine uses a recursive splitting approach:

1. It identifies all visible windows not in full-screen mode.
2. It starts with the full container area.
3. For each window (except the last), it splits the remaining area either vertically or horizontally.
4. The last window expands to fill all remaining space.

Feature	Behavior
Split Direction	Alternates between vertical and horizontal for each new window.
Gaps	Uses UiConstants::PAD_SMALL as the spacing between windows.
Full Screen	When a window is maximized, the Status Bar and Dock are hidden, and the window takes 100% of the screen parent.
Rotation	Observes DisplayManager rotation subjects to re-trigger layout updates.

Sources: main/core/ui/desktop/window_manager/WindowManager.cpp:227-270, main/core/ui/desktop/window_manager/WindowManager.cpp:271-274

Full Screen Logic Flow

The transition between tiled and full-screen modes involves reparenting the window object:

API Reference

Public Methods

The WindowManager class provides the following primary interface:

Method	Description
getInstance()	Returns the singleton instance of the Window Manager.
init(...)	Initializes the manager with pointers to UI containers (window, app, screen, status bar, dock).
openApp(pkg)	Opens a new application or activates it if already running.
closeApp(pkg)	Terminates an application and destroys its window.
closeWindow(win)	Closes a specific LVGL window object.
toggleFullScreen(win)	Toggles a window between tiled and full-screen modes.
updateLayout()	Manually triggers a recalculation of window positions.

Sources: main/core/ui/desktop/window_manager/WindowManager.hpp:33-55

Event Callbacks

The manager implements several static callbacks to handle LVGL events:

• on_win_minimize: Handles clicking the dock button or minimize icon.
• on_header_minimize: Specifically handles the window header minimize button.
• on_win_close: Invoked when the 'X' button in the header is clicked.
• on_win_maximize: Invoked when the '+' button in the header is clicked.
• on_rotation_change: Reacts to screen orientation changes.

Sources: main/core/ui/desktop/window_manager/WindowManager.cpp:125-164, main/core/ui/desktop/window_manager/WindowManager.cpp:271-274

Summary

The Window Manager is the central orchestrator of the FlxOS user experience. By managing a dynamic tiling layout and synchronizing with the AppManager, it allows the resource-constrained ESP32 to support a sophisticated multi-tasking interface. Its ability to handle display rotations and provide a full-screen mode ensures that applications can adapt to various hardware configurations and user needs.