Common UI Components
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Common UI Components in FlxOS constitute the reusable building blocks and standardized interfaces used across various system applications such as the Files App, Settings, and System Info. These components leverage the LVGL 9 graphics library and LovyanGFX to provide a responsive, modern desktop-like experience on ESP32 microcontrollers.
The architecture focuses on consistency through the use of shared layout constants, unified property systems, and reactive data binding via the lv_observer pattern. This ensures that UI elements like headers, lists, and modal dialogs maintain a uniform look and feel while reducing code duplication across the modular application architecture.
Sources: README.md:16-25, LVGL_Features.md:6-15
Core UI Infrastructure
Layout and Theming Constants
FlxOS utilizes centralized constants to maintain visual consistency. These constants define spacing, padding, and sizing for various UI elements.
| Category | Constant Group | Purpose |
|---|---|---|
| Sizing | UiConstants | Defines tab bar size, bar heights, and common widget dimensions. |
| Padding | UiConstants | Standardizes PAD_SMALL, PAD_DEFAULT, and PAD_LARGE for consistent spacing. |
| Layout | LayoutConstants | Manages relative sizing (percentages) for modals, progress bars, and dialogs. |
Sources: main/core/apps/system_info/SystemInfoApp.cpp:78-83, main/core/apps/files/FilesApp.cpp:44-48, main/core/ui/theming/ui_constants/UiConstants.hpp, main/core/ui/theming/layout_constants/LayoutConstants.hpp
Application Layout Engines
The UI components are positioned using CSS-compliant layout engines:
- Flexbox: Used for 1D responsive rows and columns, frequently seen in system info tabs and file lists.
- Grid: Employed for complex 2D cell-based arrangements.
Sources: LVGL_Features.md:23-26, main/core/apps/system_info/SystemInfoApp.cpp:115-117
Standardized Application Components
Headers and Page Containers
Applications typically utilize a standardized header and container structure provided by SettingsCommon.
The header often includes navigation controls (Back, Home) and context-specific actions (Add Folder, Paste).
Sources: main/core/apps/files/FilesApp.cpp:52-64, main/core/apps/settings/SettingsCommon.hpp:25
Interactive Lists and Navigation
The lv_list component is a primary navigation tool, enhanced with specific FlxOS styling.
- List Buttons: Standardized buttons created via
lv_list_add_button. - Context Menus: Implemented using
lv_dropdownattached to list items, allowing for actions like Copy, Rename, or Delete. - Tab Views: Used in complex apps (e.g., System Info) to categorize data into sections like "System", "Memory", and "Network".
Sources: main/core/apps/files/FilesApp.cpp:192-205, main/core/apps/system_info/SystemInfoApp.cpp:80-87
Feedback and Modal Components
Modal Dialogs and Message Boxes
FlxOS uses lv_msgbox for user interaction requiring confirmation or input.
- Message Box: Displays information or errors with a title and close button.
- Input Dialog: Contains an
lv_textareafor user text input (e.g., naming a folder). - Confirmation Box: A specialized modal with "Yes/No" or "OK/Cancel" footers.
Sources: main/core/apps/files/FilesApp.cpp:43-50, main/core/apps/files/FilesApp.cpp:278-295
Progress Tracking
Long-running operations (like file copying) utilize a modal progress dialog.
The progress component consists of an lv_label for path/status text and an lv_bar for visual percentage representation.
Sources: main/core/apps/files/FilesApp.cpp:138-163
Data Visualization Components
Gauges and Bars
System metrics such as CPU load, memory usage, and storage capacity are represented using lv_bar.
| Metric Type | Component Used | Logic |
|---|---|---|
| CPU Load | lv_bar | Mapped 0-100% per core. |
| Heap Memory | lv_bar | usagePercent calculated from total vs used. |
| Storage | lv_bar | Calculated from partition bytes. |
Sources: main/core/apps/system_info/SystemInfoApp.cpp:142-152, main/core/apps/system_info/SystemInfoApp.cpp:325-330
Tables
Complex data lists, such as the task monitor, use the lv_table component to display multi-column information including Task Name, CPU%, State, and Priority.
Sources: main/core/apps/system_info/SystemInfoApp.cpp:218-235
Summary
The Common UI Components in FlxOS provide a robust framework for building consistent embedded applications. By standardizing on LVGL 9 widgets and a centralized set of layout/ui constants, the system ensures that complex applications like the Files App and System Info App share a unified interface logic. This architecture supports both high-level user interactions via modals and menus, as well as low-level system monitoring through standardized visualization components.
Sources: main/core/apps/files/FilesApp.cpp, main/core/apps/system_info/SystemInfoApp.cpp, LVGL_Features.md