Skip to content

Application lifecycle

Source:include/fplinux/fplinux-ui.h

The session starts an application from its installed desktop entry. fplinux_ui_open() connects it to the session and receives its initial configuration; fplinux_ui_run() processes events and draws the interface. Start graphical applications from the catalog, not by executing their binary from a shell. CLI help and argument errors must work before opening the runtime.

fplinux_ui_open() does not call application callbacks. If the compositor closes the surface while it is being created, the first fplinux_ui_run() delivers the closing lifecycle notification and final CLOSE after the application has received its UI handle. The runtime borrows the process’s SIGINT and SIGTERM handlers and restores their previous dispositions in fplinux_ui_close(), including cleanup after a failed open.

Create the initial screen promptly. Do not block the UI thread with slow I/O or a long calculation before the first frame. Use short callbacks and the runtime’s file-descriptor watch or application-owned timers for continuing work.

fplinux_ui_watch_fd() borrows one descriptor and requires a callback for a nonnegative fd; use fd=-1 to remove it. A replacement registration receives only readiness observed for that registration. Readiness for a previous descriptor or callback is discarded, including when a new descriptor reuses the same number.

State or event Meaning for the application
FPLINUX_UI_FOREGROUND This is the selected application
FPLINUX_UI_BACKGROUND Its process is retained for later activation through Home or Tasks
FPLINUX_UI_CLOSING The application is leaving
FPLINUX_UI_EVENT_ACTIVATION The user opened the application from the catalog or selected its task
FPLINUX_UI_EVENT_VISIBILITY Its surface became visible or hidden
FPLINUX_UI_EVENT_RESIZE Surface geometry changed; size getters already contain the new values
FPLINUX_UI_EVENT_INPUT_CANCEL Held input from the named source was cancelled

Read fplinux_ui_lifecycle() when handling a lifecycle event. Hiding the display, locking the keypad or covering an application with a system notice changes visibility without necessarily changing its lifecycle. A background application can keep in-memory work, but that does not save it to storage.

Read event->activation on FPLINUX_UI_EVENT_ACTIVATION. FPLINUX_UI_ACTIVATION_OPEN opens the application’s main screen, including when its process is already running. FPLINUX_UI_ACTIVATION_RESUME returns to its current screen with its focus, scroll position and unfinished work. These actions do not depend on how long the application was in the background. Unlocking the phone is not a new activation.

Create the initial view before calling fplinux_ui_run(). The activation callback runs inside that loop before the next frame is submitted. Prepare the main view, the retained view or a necessary save decision in the callback; the runtime confirms its new frame before the session reveals it. An application does not send a frame acknowledgement itself.

Opening the main screen changes navigation, not application data. Keep the note, calculation, terminal process, game and active timers. Use the application’s navigation and cleanup functions to leave child screens. Protect an edited form with its ordinary leave decision, and preserve an existing save error or pending operation. Returning to the main screen must not repeat a mutation or answer a confirmation for the user. A single-screen application’s main view can already be its working document.

The session localizes the default task name from the desktop entry. fplinux_ui_set_title() instead supplies an application-owned window and task title, such as a document name or an unsaved marker. That text is kept literally; it is not translated again when the interface language changes.

Pause drawing and UI-related work when hidden. The runtime pauses its own screen activity and frame submission, but it does not pause every timer the application created. Keep the timer handle and pause, resume and delete it at the appropriate boundary. A software frame can manage a borrowed timer’s visibility policy; see software frames.

The high-level screens handle their pending input and repeat cancellation. Custom gestures must stop on INPUT_CANCEL, which arrives before synthetic key releases. Do not interpret those releases as a completed user gesture. The Input contract owns key sources and repeat behavior.

Use fplinux_ui_back() to request ordinary close to the catalog. fplinux_ui_go_back() does this from the first high-level screen. fplinux_ui_home() backgrounds the application instead. The session owns the red-key Home action and task switching; applications do not intercept it to add their own exit choice.

Register a close handler when leaving may require a decision:

  • FPLINUX_UI_CLOSE_READY permits closing.
  • FPLINUX_UI_CLOSE_CANCEL leaves the application open.
  • FPLINUX_UI_CLOSE_WAIT keeps its decision interface active until fplinux_ui_close_reply() answers Ready or Cancel.

The Application state contract defines saving, retry and discard behavior. Keep the draft until the requested decision is resolved. Repeated ordinary Close keeps the pending decision. Forced termination and session shutdown can still end the application; WAIT does not prevent those paths.

Return the handler’s initial answer. Call fplinux_ui_close_reply() only after the handler has returned WAIT; replying from inside the handler fails with EINVAL. A repeated request reuses the current answer and keeps a WAIT or CANCEL interface interactive without calling the handler again. Calling fplinux_ui_quit() from the handler permits closing and returns normally from the loop.

Document handlers follow the same return-then-reply rule: return the initial result, and use fplinux_ui_document_reply() later if it was WAIT. A reply from inside the handler fails with EINVAL. Calling fplinux_ui_quit() from a document handler answers the request with ERROR and ECANCELED, then ends the loop normally. An invalid handler result is reported as a runtime error.

FPLINUX_UI_EVENT_CLOSE is the final cleanup notification, not a place to open a save dialog or refuse closing. Save important state before reaching it. Connection and rendering failures can also end the event loop. Check fplinux_ui_run()’s result: normal closing returns zero; runtime failure returns a negative value.

The runtime enters its final closing state before delivering CLOSE. It delivers no later ordinary callbacks, runs no further application timers and submits no further frames. fplinux_ui_close() releases runtime resources without application callbacks.

fplinux_ui_quit() stops the loop without generating a CLOSE event. Complete any required saving before calling it, then use the same cleanup after run() returns.

Remove timers and release application-owned resources before closing the runtime. fplinux_ui_close() frees runtime-owned screens and sound streams. Separately allocated software-frame handles still need fplinux_ui_frame_delete(). Preference objects belong to the application and must be closed explicitly. Closing a preferences object does not save it.

The desktop entry chooses the initial integrated or fullscreen mode. fplinux_ui_set_fullscreen() requests a change while running; do not assume the new dimensions immediately after sending it. On RESIZE, use the current width and height. The runtime has already laid out high-level controls, while the application must reposition raw LVGL objects and redraw Canvas content.

Use the same adaptive layout for every phone. Display mode does not change the application’s permissions or its responsibility to pause work while hidden.

Use the shared session log and debugging workflow to distinguish application exit, loss of the session connection and a program that fails to close. A host test of callbacks does not establish physical display or keypad behavior. Keep a native UI test, package build and phone observation distinct when reporting results.