Keyboard Layouts & Management
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/kotlin/dev/patrickgold/florisboard/ime/keyboard/KeyboardManager.kt
- app/src/main/kotlin/dev/patrickgold/florisboard/ime/keyboard/LayoutManager.kt
- app/src/main/kotlin/dev/patrickgold/florisboard/app/ext/ExtensionEditScreen.kt
- app/src/test/kotlin/dev/patrickgold/florisboard/ime/keyboard/CharactersModifierLayoutTest.kt
- VOXTRAL_KEYBOARD_PLAN.md
- ROADMAP.md
Keyboard Layouts & Management represents the core engine of Ownkey Keyboard, responsible for orchestrating how keys are defined, rendered, and processed. It manages the transition between different input modes (characters, symbols, numeric), handles language-specific subtypes, and provides the infrastructure for customizable extensions that define keyboard arrangements.
The system is designed to be highly modular, allowing for dynamic updates to the keyboard state based on user input, editor context, and active preferences. It integrates with the AI-driven features of the project, such as Voxtral ASR and LLM rewrite, ensuring that these advanced capabilities are accessible through standard keyboard interactions.
Sources: VOXTRAL_KEYBOARD_PLAN.md, KeyboardManager.kt:43-65
Architecture & Components
The keyboard management system follows a layered architecture where the Input Method Editor (IME) app layer handles orchestration, and specialized managers handle data and state.
Core Classes
KeyboardManager: The central coordinator that implementsInputKeyEventReceiver. It manages theactiveState, handles key events (down/up/repeat), and maintains the activeComputingEvaluator.LayoutManager: Responsible for the asynchronous computation of keyboard layouts based on the current mode and subtype.ComputingEvaluator: An interface used to evaluate the visibility, enabled state, and data (like currency slots) of individual keys during the layout computation process.TextKeyboardCache: A caching mechanism used byKeyboardManagerto store computed keyboards, preventing redundant expensive computations when switching modes.
Sources: KeyboardManager.kt:66-105, LayoutManager.kt
State Management
The activeState (an ObservableKeyboardState) tracks the current configuration of the keyboard UI. It includes properties for keyboardMode, imeUiMode, and various flags like isIncognitoMode or isManualSelectionMode.
The diagram shows how changes in the active state trigger a re-evaluation of the keyboard layout, leading to a new active evaluator.
Sources: KeyboardManager.kt:156-180
Keyboard Modes & Subtypes
Ownkey supports multiple keyboard modes, allowing users to switch between different sets of characters and symbols.
Supported Keyboard Modes
| Mode | Description |
|---|---|
CHARACTERS | The primary alphabetic layout (e.g., QWERTY). |
SYMBOLS / SYMBOLS2 | Primary and secondary punctuation and special character layouts. |
NUMERIC / NUMERIC_ADVANCED | Standard and expanded numeric keypads. |
PHONE / PHONE2 | Layouts optimized for telephone number entry. |
Sources: KeyboardManager.kt:700-706, CharactersModifierLayoutTest.kt:33-40
Subtype Management
A Subtype represents a combination of a locale and a specific layout arrangement. KeyboardManager monitors the subtypeManager for changes to the active subtype, which triggers a re-evaluation of the input shift state and a reset of suggestions.
Sources: KeyboardManager.kt:135-145
Key Event Processing
The KeyboardManager handles the lifecycle of key events through its implementation of the InputKeyEventReceiver interface.
Logical Flow of a Key Press
onInputKeyDown: Begins mass selection if an arrow/move key is pressed; handles initial shift down logic.onInputKeyUp: The primary logic for key execution. It handles system-level keys (CLIPBOARD_COPY, SETTINGS, etc.), mode switching (VIEW_SYMBOLS, etc.), and character commitment.onInputKeyRepeat: Triggers input feedback and repeats the action (e.g., for backspace or arrows).
The sequence diagram illustrates the flow from a physical/touch interaction to the commitment of text or change in keyboard state.
Sources: KeyboardManager.kt:530-670
Extension & Layout Management
Layouts in Ownkey are defined via extensions. This allows for a flexible system where new arrangements can be imported and edited.
Extension Components
Extensions are composed of various components that define keyboard behavior:
- Layouts: JSON files defining the arrangement of keys (e.g.,
charactersMod/default.json). - Composers: Define how multi-character sequences are combined.
- Currency Sets: Define locale-specific currency symbols for slots.
- Popup Mappings: Define the character popups that appear on long-press.
Sources: ExtensionEditScreen.kt:412-450, CharactersModifierLayoutTest.kt:45-60
Extension Editor Workflow
The ExtensionEditScreen provides a UI for managing these extensions. It uses a CacheManager.ExtEditorWorkspace to handle unsaved changes and filesystem operations during the editing process.
The flowchart outlines the process of modifying a keyboard extension, from metadata management to building the final archive.
Sources: ExtensionEditScreen.kt:115-150, ExtensionEditScreen.kt:185-230
Future Development
The project roadmap indicates several major enhancements planned for the keyboard layout engine:
- Unicode Keyboard v3: Implementation of a new layout engine based on the upcoming standard.
- Tablet Mode: Optimizations for landscape input using the new layout engine.
- Floating Keyboard: A mode allowing the keyboard to be moved freely across the screen.
- Layout Editor: An on-board visual editor allowing users to create layouts without manually editing JSON files.
Sources: ROADMAP.md:33-41, ROADMAP.md:46-55
Conclusion
Keyboard Layouts & Management in Ownkey Keyboard provides a robust, extensible framework for mobile text entry. By separating the logical state of the keyboard from the physical layout definitions stored in extensions, the system achieves a high degree of flexibility while maintaining the performance required for a primary input method. The integration of AI features directly into this management layer ensures that advanced dictation and rewriting capabilities remain as responsive and intuitive as traditional typing.