Skip to content

Screens and commands

Source:include/fplinux/fplinux-ui-screen.h

Use the high-level screens in fplinux/fplinux-ui-screen.h for ordinary application interfaces. The runtime supplies layout, focus, scrolling, text editing, icons and soft-key assignments. The application supplies content and handles commands. Your first application shows a complete form.

Screen Use it for
List Open an item, choose one value, or mark several values
Form Combine text, editable fields, choices, gauges, dates and images
TextBox Edit a multiline document with the shared text input
Alert Ask for a decision or show a notice, error or progress
Canvas Draw custom content while retaining screen commands and navigation

Use an implicit List for navigation, an exclusive List for one selected value, and a multiple List for independent selections. Forms already provide field editors; do not create a second keypad editor inside them. Text entry explains field types and pending input.

Form images keep their proportions inside the available width, including space for the scroll indicator. Their height leaves room for the complete multiline caption and any link or button frame. The runtime fits them again when the view changes size; the application can release the source after appending the image.

Forms own navigation between interactive fields and the reading of plain content between them. Ordinary paragraphs and logos do not acquire an editing focus. At a text boundary, a navigation press completes the partly hidden end line; applications do not need to correct the scroll position. A focused field has an accent background, with the edited segment or text range distinguished inside it.

For settings-style rows, call fplinux_ui_list_set_value_details() on an empty stored List before adding rows, then supply each current value as its detail. The runtime uses a shared right-aligned value column on landscape profiles and a second line on the other profiles. Ordinary descriptive details keep their usual layout. Calling it after adding rows returns EBUSY; another screen kind or a virtual List returns EINVAL.

Stored rows can emphasize their primary text with fplinux_ui_list_set_emphasis() and show a status image at the right with fplinux_ui_list_set_trailing_icon(). The latter borrows its image until replaced or the row is deleted; a runtime-owned glyph remains valid until the UI closes. Use these row properties for a time and its status rather than drawing a separate list in the application.

For a right-aligned value, use fplinux_ui_list_set_trailing_value(). For an adjustable level, use fplinux_ui_list_set_level() with its minimum, maximum and current value; the list shows the number below the caption and arrows on the focused row. The range must be nonempty, its span at most INT32_MAX, and the value within it. An icon, value and level share one trailing slot: setting one replaces the previous content, and a null value clears it. These operations apply to stored rows.

Lists can also use a virtual data source when creating every row would waste memory. The runtime passes a full zeroed fplinux_ui_virtual_row; the synchronous provider fills its fields. Keep its context alive and notify the list when its data changes. Strings and icons must remain valid after the provider returns, until another row request or application callback; a local array is too short-lived. Providers only supply data: they must not mutate lists, delete objects or close the runtime, and navigation returns EBUSY while they run. API Demos includes ordinary and virtual lists, forms and item commands.

Use fplinux_ui_list_set_focus_listener() to follow the row the user reaches with navigation keys. It is separate from the screen’s change listener, which reports value changes such as marking a choice. Moving focus programmatically does not call either listener.

For a page-relative shortcut, fplinux_ui_list_get_first_visible() returns the first fully visible row, or the first intersecting row when a row is taller than the viewport; an empty list returns SIZE_MAX. Keep row navigation with the List rather than calculating its scroll position in the application.

To show a rebuilt list where the old one stood, set its focus first and then fplinux_ui_list_set_first_visible() with the old first row. The list scrolls only as far as its content allows and keeps the focused row in view; a virtual list that has not been shown yet applies the row when it appears.

Add struct fplinux_ui_command values with application-owned IDs, a command type and a full translated label. The runtime chooses their placement:

  • The right soft key takes the first Back, Cancel, Exit or Stop action by priority.
  • Centre activates the focused control, such as a list row or editable field, then falls back to the screen’s OK command.
  • Remaining actions use the left soft key or Options. Help goes into Options.

Lower priority numbers choose keys first; equal priorities retain insertion order. A command attached to the focused item wins a tie with a screen command. Inside Options, Back comes last; the other commands keep their priority order. Back appears there when another action occupies its key, such as Clear in a nonempty text field. A screen with Back already on a soft key does not need another Back row. Reusing an ID on the same screen replaces that command. Labels are copied; callback context remains yours.

An optional short_label gives a command a compact soft-key legend. The runtime first tries full labels, then the supplied short labels, then the ordinary Options assignment. Options keeps the full label. Both strings are copied; shortening does not change the command ID, priority or keep_visible behavior.

Use fplinux_ui_list_set_select_label() to name the centre action of an IMPLICIT or EXCLUSIVE List. Passing null restores the standard Select label. A MULTIPLE List keeps its Mark or Unmark action. The label does not disable input or change the selection policy; the application must handle any operation already in progress.

Use a null label for the standard translated word of a Back, Cancel, Exit, Stop, OK or Help command. These types also get a standard glyph when no image is supplied. Item and Screen commands need their own labels and action glyphs. Supply an explicit system glyph for a different meaning, such as Search on an OK command or Clear on a Cancel command. An unavailable image does not remove the action.

A command’s type does not open a screen. Its listener performs the action or chooses the navigation function. Do not use Linux key codes to reproduce the runtime’s soft-key assignment.

Options opens a compact menu touching the left edge above the soft-key bar, without a generic title. It uses the shared menu layout. While the menu is open, it owns input and legends: OK chooses an action, and the right soft key or Escape closes it. Closing restores the covered screen’s commands.

Operation Result
fplinux_ui_push() Show a screen above the current one
fplinux_ui_navigate() Open a child; from an Options callback, retain that menu for Back
fplinux_ui_go_back() Return to the parent, restoring its Options selection when appropriate; from the first screen, request application close
fplinux_ui_pop() Finish an action and remove the top screen without reopening Options; returns false for the only screen
fplinux_ui_pop_to() Remove every screen above a retained application screen
fplinux_ui_replace() Replace the current screen and discard it

Use navigate() for an Options item that opens Help or another page. Use go_back() for its Back action. Use pop() after a completed action such as Send or Done. This gives the user the same return path across applications without an application-owned menu stack.

Constructors register screens with the runtime, including screens not yet pushed; fplinux_ui_close() frees them. Navigation changes their position. push(), navigate() and replace() return a boolean: EINVAL means a null argument, ENOENT means the target does not belong to this runtime, and EBUSY means the target is already shown or navigation is in progress. A virtual row provider also makes navigation busy. Failure leaves the stack and runtime choice intact; a constructed screen remains owned by the runtime and may be used in a later navigation. pop_to() returns ENOENT when its target is absent from the application stack. pop() returns ENOENT when there is no parent. Do not free a screen yourself or use its pointer after it has been popped or replaced. Keep application context alive until all screens and callbacks that borrow it are gone. Text getters return borrowed text; copy it before keeping it across changes to the field or removal of the screen.

Form choices and Open with occupy a private runtime slot above the application stack. fplinux_ui_current() returns the application screen under that choice. Input, focus and legends follow the choice; successful application navigation cancels it before changing the stack. Cancelling a Form choice retains its previous value without a change callback, and deleting its field closes it. Hiding the application preserves a choice for Resume; Open follows the application’s ordinary initial navigation.

Handle opening and restoring an application through the same application-owned navigation. Before removing a child screen, release its timers, watches and other borrowed resources and clear retained pointers. A TextBox can cancel its symbol grid with fplinux_ui_text_box_cancel_picker() without replacing the field or changing its text, caret or input mode. Use fplinux_ui_menu_close() for an ordinary Options menu; a save decision remains owned by its application.

An Alert displays over the previous screen and temporarily prevents interaction with it. On a command, the runtime removes the Alert from the stack before calling its listener, then deletes it after the listener returns. The listener may read the Alert during that call, but must not pop it, update it or retain its pointer. It may open a new screen.

A timed notice closes without calling the command listener. For a busy or progress Alert, cancellation is an ordinary command with the same lifetime rule. Cancelling the Alert does not cancel application work by itself; the listener must stop the operation it owns.

The title occupies one line above a divider. A title that does not fit scrolls once when the Alert becomes active, then rests with three dots. A long message scrolls while the title, progress indicator and footer stay visible. Use fplinux_ui_alert_set_text() when the message changes; replacing it starts reading from the top, while setting the same text keeps its position. Update a progress caption separately with fplinux_ui_alert_set_footer() to preserve that reading position. A zero maximum in fplinux_ui_alert_set_progress() shows a spinner; a positive maximum shows determinate progress. Keep the numerical caption accurate even when a very small nonzero amount needs a minimum visible segment.

Use the common storage-error and close-decision contract for unsaved data. Do not invent a separate meaning for Retry, Stay or Discard.

Use fplinux_ui_wait_begin() for work that usually ends quickly but may take longer, such as reading a folder. The current screen stays as it is, keeps the soft-key legends it had when the wait began, even if the application removes its commands meanwhile, and ignores keys; Back calls the cancel callback once, or is ignored without one. Only work that lasts longer than half a second shows a busy Alert with the given title and text, and a shown Alert stays at least half a second. Until the wait ends, the application may update the returned Alert’s title, text, footer and progress, but must not add commands to it or navigate to it.

fplinux_ui_wait_end() calls its callback later from the runtime’s loop, with the original screen current again: push the next screen, replace the original one or push an error Alert there, and the result appears in one step. A question the application pushed meanwhile, such as a close decision, stays until it is answered, and the callback waits for it. Navigation that removes the original screen ends the wait without either callback.

Create custom LVGL objects inside the object returned by fplinux_ui_canvas_object(). Use fplinux_ui_screen_get_content_size() for the drawable area; a titled Canvas does not own the title band. Recalculate custom geometry after resize.

A titled screen can show a short status on the right through fplinux_ui_screen_set_header_status(). Supply the full text and its compact form; the runtime chooses the form that fits and shortens the title when needed. The application owns the meaning of the text, while the runtime owns its font, spacing and alignment. Updating the status does not change the content area’s size. Clear it with an empty status to restore the ordinary title. The status belongs to that screen, so updating a covered screen does not replace a child screen’s header.

The Canvas key handler receives keys not consumed by its commands. Any high-level screen can use fplinux_ui_screen_set_key_filter() to consume an application-specific key before ordinary command handling. Leave standard navigation and soft keys to the screen. Enable external-keyboard key handling only when the embedded content needs ordinary Enter or Escape, as a terminal does; phone commands remain available.

Canvas key repeat defaults to none. Choose navigation repeat for a long readable surface, or keymap repeat for content that accepts keyboard text. Use the existing policies described in Input, rather than a second repeat timer.

Register fplinux_ui_canvas_set_active_listener() before pushing a Canvas to follow its actual activation and suspension by visibility, menus and covering screens. The callback runs after the active state changes and can pause or rearm application timers and adjust child objects. It must not navigate, delete the Canvas or close the runtime. Registration and final runtime cleanup do not call it.

Use the raw LVGL screen only when the high-level screens cannot represent the interface. In that case the application owns key routing, focus, legends and layout; layout and appearance and the runtime reference describe those responsibilities.