Skip to content

Use the shared text field whenever the application asks for text. It owns multi-tap input, the pending character, cursor movement, symbol selection, Clear and external-keyboard text. This keeps input consistent between Notes, Settings and other applications.

A Form’s text item is appropriate for a name, short value or numeric entry. A TextBox provides a full-screen multiline editor. These high-level screens route keys, draw the field and assign its commands. The application handles changes and decides when to accept or save the value.

Choose the field type for the value being edited. Numeric, decimal, phone and password fields have different accepted input and display behavior; use the types declared in fplinux-ui-text.h. A password field masks committed characters but leaves the pending multi-tap character visible until it is committed. It does not provide protected storage or an application sandbox. Validate application-specific meaning when accepting a value, such as the valid range of a counter.

Specify a character limit that matches the task. Read the value through the screen’s getter, which includes pending text. Returned text is borrowed; copy it before retaining it beyond a field change or screen removal. A change callback reports an edit, not a successful save.

The input mode stays visible while editing. A limited field adds its character count when it reaches 90% of the limit and removes it again below that threshold. A change callback may normalize the text with a setter; that edit is applied without a nested or deferred duplicate notification. Do not delete the field from its own change callback.

Add FPLINUX_UI_TEXT_UNEDITABLE for a readable field without editing controls. In a multiline field, Up and Down move by one complete line; Left and Right move by whole lines with overlap between pages. A small bottom inset keeps the last line readable when the view height is not a multiple of the line spacing.

The runtime handles repeated digit presses, holding a digit, mode switching, symbols and Clear. The user guide owns the ordinary key instructions. Use the existing field instead of duplicating those gestures in a command callback.

High-level screens manage field focus and activity. Opening Options, covering a screen or leaving it cancels held repeat and unfinished keypad gestures; returning requires a new press. Clear, digits, star and pound have their own field gestures. Do not start another key-repeat timer around the shared editor.

Phone key roles and external keyboard input are distinct. The Input contract defines their sources, reserved keys and repeat policies. Test a key’s source as well as its code when writing custom input; an external F13 key is not the phone’s left soft key.

The interface language controls translations and formatting. The keypad input language selects the initial text-entry language independently. Use fplinux_ui_locale() and fplinux_ui_input_locale() for those different purposes. Installed language data supplies the multi-tap characters; do not copy a language’s key tables into an application.

External keyboards use the compositor’s XKB layout. That is another input mechanism, not an application’s keypad table. The language guide explains translations and language packages.

Create a raw field with the functions in fplinux-ui-text.h only when a Form or TextBox cannot represent the layout. Position it using the current surface and theme, pass its accepted keys to fplinux_ui_text_key(), and set its focus with fplinux_ui_text_set_focused() when the owning screen changes. The raw field participates in shared navigation repeat when it receives the runtime’s keys.

The low-level field does not choose the application’s Save/Back actions. Make those actions reachable while Clear is active. High-level screens already keep a displaced Back action in Options; a custom screen must deliberately provide its equivalent navigation.

Cancel application-owned held gestures on FPLINUX_UI_EVENT_INPUT_CANCEL, before the synthetic releases arrive. Use lifecycle and visibility to stop input-related work when the screen is hidden. Do not submit an unfinished user action just because focus was lost.

Keep a draft separate from the last confirmed value when the screen offers Save and Cancel. Cancelling returns to that value. Saving follows the Application state contract: retain the draft after failure, distinguish an unpublished write from unconfirmed synchronization, and allow the user to decide before ordinary closing.