Build one APK that adapts to its surface. Do not select a layout by phone model or create a separate package for each display. The runtime chooses a screen profile and supplies its metrics, theme and fonts. Physical display support remains a property of the selected phone.
Use the space you receive
Section titled “Use the space you receive”The profiles cover 128×128, 128×160, 176×220, 240×320 and landscape 320×240. The runtime selects the largest profile that fits; layout still uses the actual surface dimensions. Read fplinux_ui_width() and fplinux_ui_height(), and use fplinux_ui_metrics() for spacing and component sizes. Do not use the profile enum as a numeric size or copy a table of pixel values into the application.
Profile dimensions and semantic palettes are owned by lib/fplinux/fplinux-ui-profile.json. Use focus_width for an outline, frame_padding inside a framed control and divider_width for a separator. A one-pixel caret, an image’s aspect ratio and a game’s logical grid remain properties of that content; they do not need a separate token for every number.
An integrated application occupies the space between the session’s status and soft-key bars. It must not draw another copy of those bars. A fullscreen application receives the whole display. A titled high-level screen reserves its own title area; use fplinux_ui_screen_get_content_size() for custom content within it.
Prefer Lists, Forms and TextBoxes for ordinary content. They already handle the profile, scrolling, focus, menus and translated labels. Use Canvas for a game board or other content that needs custom drawing.
List rows fill the viewport. Content that overflows reserves a four-pixel channel on the right, filled with the theme’s border colour over the viewport’s visible height: a two-pixel scroll indicator with one pixel of the channel on each side. The channel adds no line of its own; it runs from the line above the viewport to the line below it. Content that fits has no channel and uses the full width. Moving the selection does not change the width; changes to the content or viewport recalculate it. There is no outer padding above the first row or below the last; text and icons keep their inner padding. Dividers span the row; the last logical item has no divider. A list ends on the line below it, such as the soft-key bar’s, which stands in for the divider of the row ending there: that row counts as whole, and neither a second line nor a background line separates it or its selection from the bar. The indicator stays visible while content overflows. At the start of the content the indicator reaches the top of the channel; at the end it reaches the bottom. In a bordered viewport the channel and indicator lie inside the border.
Scrolling text and forms keep their ordinary inner spacing on both sides. For a raw LVGL viewport, set its border and ordinary content padding, then apply fplinux_ui_style_scrollbar(). The shared viewport reserves scrollbar_space only when needed, before drawing; do not add that space to every child. Reapplying the helper is safe. A viewport with its scrollbar mode set to OFF reserves no indicator area.
Up and Down move scrolling text by whole lines. A remaining fragment shorter than a line is included in the same press, in either direction. Left and Right move a page of whole lines with one line of overlap, stopping at the content edge. A scrolling alert message shows only whole lines. fplinux_ui_scroll_key() supplies this text navigation for a raw viewport. Forms retain their normal navigation step and finish a partly clipped end line using its text bounds and inner spacing. List selection has a separate rule: a remaining distance shorter than a quarter of the row step is included in that press. After another row scroll, such as lv_obj_scroll_to_view() of a focused child, fplinux_ui_scroll_settle() applies that list rule to the ends.
System action menus form a compact window directly above the soft-key bar. Left and right menus touch their respective surface edges; a centre menu is centred. The runtime measures all translated item labels, the shared icon column and an optional title, then adds one icon size of space on the right. The window is at least three rows wide. When less than one icon size of the surface would remain beside it, the window takes the full surface width. Internal text padding remains. Height fits whole rows, the bottom one ending on the soft-key bar’s line, and leaves at least a title band’s height of the surface above the menu uncovered, also on a screen without a title. When that would show fewer than three rows, or fewer than all items of a shorter menu, the menu instead fills the surface’s whole height, still below its brand edge line; a menu title stays. Only an overflowing menu includes the scroll-indicator area. Width stays constant as the selection moves. Long labels keep the shared single-line ellipsis and focused-text scrolling behavior. The application supplies the opening side through the menu API; the runtime owns sizing and resize. The underlying screen keeps its geometry and remains visible under a scrim.
The shared symbol grid is centred in the application’s modal area. Its position does not follow a field, caret or scroll offset. Integrated surfaces already exclude the system bars; fullscreen surfaces leave room for the modal soft-key bar. The application title remains under the scrim and does not reduce this area. Use the same picker for a custom input consumer; ordinary text fields provide it themselves.
After RESIZE, recalculate raw object geometry from the new dimensions. For software frames, resize the buffer, obtain its new pixels and redraw the complete frame. Do not rotate portrait coordinates to approximate a landscape layout.
Typography and color
Section titled “Typography and color”Read fonts and semantic colors from fplinux_ui_theme(). Use the body font for ordinary text, the large font for emphasis and the clock font only for its supported numeric characters. The terminal’s monospaced cell font is separate from these interface fonts.
Use control_border for an unfocused interactive frame and focus for its focused state. Keep border for decorative dividers and tracks. The brand color is a decorative accent; use the theme’s brand_foreground for readable brand-coloured text and clock hands.
A focused Form control uses the accent background and accent_text for its value. The edited text range or date/time segment uses surface and foreground within it, so the current field and the selected part remain distinguishable. Use the shared field APIs to keep focus styling, cursor visibility and key handling together.
Measure translated text with the selected font. Character counts do not predict its width. Allow a control to scroll or wrap where that control supports it; use an ellipsis for a single-line summary and provide a way to read the full value. Do not reduce every label to fit a fixed width chosen for one phone.
Single-line runtime text that does not fit, such as a title, list row, form value or soft-key legend, shows the longest start that fits followed by three dots of the same font on its baseline; text that fits is never shortened. A focused element’s text scrolls to show the rest. A raw one-line LVGL label with LV_LABEL_LONG_MODE_DOTS shortens the same way.
Use theme roles such as foreground, surface, accent, warning and danger. A selected row, warning and unavailable control must remain understandable in both themes and without relying only on color. Keep the active focus visible. The runtime owns theme and metric pointers; do not free or copy those structures.
Icons and images
Section titled “Icons and images”Use fplinux_ui_glyph() for a shared meaning such as Back, Save or Delete, with the size role appropriate to the location. The returned image belongs to the runtime. High-level commands provide standard glyphs for their built-in types; supply a row-sized glyph for an application-specific action or an override whose meaning differs from its type. List rows and low-level menu items receive their images explicitly. The command contract describes the defaults.
An application’s catalog icon is package-owned; the desktop-entry guide describes its files. Pass an application tile to a List with FPLINUX_UI_LIST_ICON_APP_TILE; the shared row draws its selection ring. Use FPLINUX_UI_LIST_ICON_IMAGE for a glyph or an ordinary picture, which has no tile ring. Images inside the application must remain readable in light and dark themes. Give an image an intentional background or provide theme-specific variants. Avoid making an image the only explanation of an action.
fplinux_ui_image_load() returns a drawing buffer that the application owns. Release it with lv_draw_buf_destroy() when its last consumer is finished. Do not delete a borrowed glyph with that function.
Commands and custom legend bars
Section titled “Commands and custom legend bars”High-level screens choose the soft keys from command types and priority. Give commands short, translated action words, then let the runtime assign and fit their legends. A label is not a second keyboard handler.
For a raw fullscreen screen, fplinux_ui_softkey_bar_create() and fplinux_ui_softkey_bar_set() draw a standard legend bar. They do not handle keys or send session legends. Reserve its height, update it after resize and keep its labels consistent with the actions your handler accepts. Built-in modal screens provide their own legends when used over fullscreen content.
Keep drawing and memory bounded
Section titled “Keep drawing and memory bounded”The shared UI draws with LVGL into RGB565 surfaces. Use one UI thread and the runtime event loop; do not initialize a second LVGL display or run another lv_timer_handler() loop.
Update objects whose content changed instead of rebuilding a whole screen for every key. Pause application timers while their work is not needed. Allocate large images deliberately and release them when their screen closes. Request fplinux_ui_keep_screen_on() only while visible content needs to keep the screen awake, and release it when that work ends.
The shared GUI contract does not require a GPU. A phone’s GPU support for separate rendering tools does not establish GPU rendering for a GUI application. Use the software-frame API for application-owned RGB565 content within the UI.
Check the interface
Section titled “Check the interface”Check compact, portrait and landscape layouts, both themes, long translated labels, focused and unavailable controls, menu return, and resize. The same APK should use the space available in each case. Native screenshots can establish layout; they do not establish physical panel colors, input timing or frame rate on a phone. Keep those phone support results separate.