Input
The graphical session receives the phone keypad, keyboards and mice through Weston and libinput. Wayland applications receive input from the compositor; direct-display tools use the raw input session described below. This page defines both boundaries and the keyboard layout package contract. See Phone interface for user controls and Terminal for shell input.
Devices
Section titled “Devices”The phone keypad, keyboards forwarded by the USB keyboard bridge, and Bluetooth keyboards and mice appear as Linux evdev devices. The phone keypad has the evdev phys string fplinux/keypad0 on every phone.
Phone keys
Section titled “Phone keys”The keypad sends standard Linux input codes. include/fplinux/fplinux-keypad.h names their phone roles.
| Phone key | Linux code |
|---|---|
| Digits 0 to 9 | KEY_NUMERIC_0 to KEY_NUMERIC_9 |
| * and # | KEY_NUMERIC_STAR, KEY_NUMERIC_POUND |
| D-pad | KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT |
| Centre | KEY_OK |
| Left soft and Right soft | KEY_F13, KEY_F14 |
| Dial | KEY_PICKUP_PHONE |
| Power (Red key) | KEY_POWER |
A code has its phone role only on the device whose phys string is fplinux/keypad0. On an external keyboard, F13 and F14 remain function keys. A key code alone never identifies a phone action: check the source too.
Holding the power key for five seconds requests power-off even while an application holds the keypad; see Power.
Wayland applications
Section titled “Wayland applications”Graphical applications use ordinary Wayland keyboard input. The shared UI runtime in include/fplinux/fplinux-ui.h handles the compositor’s keymap, focus changes and key releases and distinguishes phone keypad events from external keyboard events. It also supplies the multi-tap editor used by Notes and Settings. Applications must not open or grab evdev devices while the graphical session owns input.
The compositor reserves the short red-key action and Ctrl+Esc for session controls. Screen blanking and keyguard handling belong to the session, so a waking key press or a locked key must not reach an application. The session guide owns the user-facing controls.
The shared runtime repeats accepted navigation and text editing in Lists, Forms, TextBoxes, Alerts and Options menus. Raw text fields also participate when the application passes the received key to fplinux_ui_text_key(). The phone repeats only its four D-pad keys: the first step is immediate, the first repeat follows after 500 ms, and subsequent repeats follow at 200 ms intervals without acceleration or catch-up bursts. External keyboard input uses the compositor’s delay, rate and XKB repeatability. A disabled compositor repeat setting disables both sources. Command activation stays a single action. Losing input focus, opening a menu or covering the current screen cancels the held repeat; returning requires a new press. Text fields keep their own Clear, held-digit and text-mode gestures.
A Canvas selects its repeat policy with fplinux_ui_canvas_set_key_repeat(): FPLINUX_UI_CANVAS_REPEAT_NONE is the default; FPLINUX_UI_CANVAS_REPEAT_NAVIGATION repeats arrow keys without Ctrl or Alt; FPLINUX_UI_CANVAS_REPEAT_KEYMAP also allows repeatable keyboard text, as Terminal needs. A catalog uses navigation-only repetition so holding Enter cannot first open it and then launch an application. Leave repetition disabled for a physical-key tester or a drawing control that needs only the original presses and releases.
Use fplinux_ui_navigate() to open a child page from a high-level Options command. The shared screen stack retains the originating menu’s selection and scroll position. fplinux_ui_go_back() returns to that menu; fplinux_ui_pop() completes an action without reopening it. Ordinary fplinux_ui_push() does not create this return path, so an action’s error alert returns to the application. The low-level fplinux_ui_menu_open() API displays one popup at a time and closes it before its callback; it does not create a page history.
Direct-display input sessions
Section titled “Direct-display input sessions”Direct-display applications read input through include/fplinux/fplinux-input-session.h, with the graphical session stopped. It classifies each device by the keypad phys string and by its capabilities, never by its bus:
| Source | Device |
|---|---|
| Keypad | The phone keypad |
| Keyboard | Any other device with an Enter key, even if it also moves a pointer |
| Pointer | Otherwise, a device with relative X and Y motion and a left button |
A mouse that also publishes a separate key-only device contributes that device as a keyboard if it reports Enter.
An application chooses which sources it accepts. The session then guarantees:
- Grab. Every accepted device is grabbed for the life of the session, so its keys do not reach the local console or another application.
- Hotplug. A device that connects later is added. A device that disconnects is removed, and all of its pressed keys are released before the removal is reported.
- No autorepeat. The session delivers presses and releases only. An application that needs key repeat generates it itself.
- Suspend. Before an application hands the display and input to another terminal or application, it suspends its session: all grabs are released and releases and device removals are queued. Drain
fplinux_input_session_next()before handing over ownership, so no pressed key remains in the application. On resume, the current devices are grabbed again and reported as new devices.
Keyboard layout packages
Section titled “Keyboard layout packages”Keyboard layouts are XKB source files under /usr/share/fplinux/xkb. The fplinux-xkb package, part of every system, provides the US layout and the files that all layouts share.
Each further layout is a separate optional APK that:
- installs
symbols/<layout>and an empty registration filelayouts/<layout>; - installs no other XKB files, while retaining its required license notices;
- depends on
fplinux-xkb.
fplinux-xkb-ru, which adds Russian, is the reference example.
XKB allows four groups, so at most three layouts can be registered beside US. A registration name may contain only lowercase letters, digits and _. With more layouts or an invalid name, an application refuses to start and names the problem.
The graphical session selects US and up to three registered XKB layouts named by installed input-language packages when it starts. Its clients use that compositor-provided keymap. Restart the session after adding keyboard language packages; the keypad input language can be changed in Settings without changing the interface language.