Virtual Keyboard
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Virtual Keyboard is a core UI component of FlxOS that provides on-screen text input capabilities for applications. It is built using the LVGL library and is designed to automatically appear when a text input area, such as a lv_textarea, gains focus. This component ensures that embedded devices without physical keyboards can still perform data entry for network configuration, file renaming, and other system tasks.
The keyboard is integrated into the system-wide UI framework and follows the global theme settings. It is managed as a singleton instance, ensuring consistent behavior across different applications like the Files App and Settings.
Sources: main/core/ui/keyboard/VirtualKeyboard.cpp:15-28, ROADMAP.md:73
Architecture and Integration
The Virtual Keyboard is implemented as a singleton class, VirtualKeyboard. It interfaces directly with LVGL's top layer to ensure that the keyboard always appears above other UI elements when active.
Lifecycle and Initialization
The keyboard is initialized on-demand or during system startup. In non-headless modes, it is included in the core source list and compiled into the FlxOS binary.
Automatic Input Registration
FlxOS uses a theme-based registration system to automatically link text areas to the virtual keyboard. When a theme is applied globally, any object identified as a text area is registered with the VirtualKeyboard instance.
| Function | Description | Source |
|---|---|---|
register_input_area(lv_obj_t* obj) | Adds on_ta_event callbacks to a text area to trigger keyboard visibility. | VirtualKeyboard.cpp:54-60 |
Themes::ApplyGlobal(...) | Detects lv_textarea_class objects and registers them with the keyboard. | Themes.cpp:55-61 |
Functional Logic
The Virtual Keyboard operates based on event triggers from text areas (input sources) and the keyboard widget itself (control actions).
Input Focus Flow
When a user clicks or focuses on a registered text area, the keyboard is moved to the foreground and the specific text area is assigned as its target.
Dismissal Logic
The keyboard is dismissed under three primary conditions:
- Defocus: The text area loses focus.
- Ready/Cancel: The user presses the "Check" (Ready) or "Close" (Cancel) button on the keyboard layout.
- Deletion: The target text area is deleted from memory.
Implementation Details
The keyboard's dimensions and placement are governed by system-wide layout constants to ensure consistent proportions across different display resolutions.
- Size: The keyboard typically occupies a percentage of the screen height defined by
LayoutConstants::KEYBOARD_HEIGHT_PCT. - Alignment: It is strictly aligned to the bottom middle (
LV_ALIGN_BOTTOM_MID) of the screen. - Layering: It resides on
lv_layer_top()to prevent being obscured by application windows or modals.
Example Application Usage: Files App
The FilesApp utilizes the virtual keyboard for renaming files and creating new folders. It creates a message box with a text area, which automatically triggers the keyboard due to the focus events managed by the VirtualKeyboard singleton.
// Example of a Text Area triggering the keyboard in FilesApp
lv_obj_t* ta = lv_textarea_create(lv_msgbox_get_content(mbox));
lv_obj_set_width(ta, lv_pct(100));
lv_textarea_set_one_line(ta, true);
lv_obj_add_state(ta, LV_STATE_FOCUSED); // Triggers VirtualKeyboard::on_ta_event
Sources: main/core/apps/files/FilesApp.cpp:322-327, main/core/ui/keyboard/VirtualKeyboard.cpp:42-45
Conclusion
The Virtual Keyboard is an essential utility for interactive applications within FlxOS. By leveraging LVGL's event system and a singleton architecture, it provides a low-overhead, automatic input solution that integrates seamlessly with the system's theming and window management layers.
Sources: main/core/ui/keyboard/VirtualKeyboard.cpp, main/core/ui/theming/themes/Themes.cpp