API Reference

[中文]

This page collects the API reference generated from the System Core public headers.

System

Public header: #include "brookesia/system_core/system/system.hpp"

Header File

system/brookesia_system_core/include/brookesia/system_core/system/system.hpp

Classes

class System

Core Brookesia system runtime that owns apps, GUI access, timers, storage, and services.

System coordinates native and runtime applications, mounts their GUI resources, dispatches app lifecycle callbacks, and exposes storage, GUI, keyboard, dialog, and timer facilities through AppContext and service APIs.

Subclassed by esp_brookesia::system::super::System

Public Functions

System(): Create a core system runtime.

std::expected<void, std::string> init(Config config)

Initialize the system runtime with explicit configuration.

Parameters: config -- Runtime configuration. Ownership of gui_backend is transferred into the system.
Returns: Empty result on success, or an error string.

std::expected<void, std::string> start()

Start services, install configured apps, and enter the running state.

Returns: Empty result on success, or an error string.

void stop(): Stop running apps and services.

void deinit(): Release runtime resources after the system has stopped.

void process_timers(): Process pending timer events from the host event loop.

struct AppStartOptions

struct Config

Configuration used to initialize the core system runtime.

Public Members

std::unique_ptr<gui::IBackend> gui_backend: GUI backend implementation used by the system runtime.

gui::Environment environment: GUI and platform environment exposed to apps.

StorageConfig storage = {}: Storage roots and install target policy.

StartupOverlay startup_overlay = {}: Optional startup overlay configuration.

AppLaunchTransition app_launch_transition = {}: Optional app launch transition configuration.

std::string system_type = BROOKESIA_SYSTEM_CORE_DEFAULT_SYSTEM_TYPE: System type string exposed to services and applications.

bool start_service_manager = true: Whether the service manager should be started by System::start().

bool install_registered_apps = true: Whether statically registered native app providers should be installed.

bool install_package_apps = true: Whether package apps should be discovered from configured package roots.

bool enable_gui_view_debug = false: Whether GUI view debug metadata should be enabled at startup.

bool enable_gui_live_preview = false: Whether GUI live preview should be enabled at startup.

gui::LivePreviewOptions gui_live_preview_options = {}: Live preview options applied when startup live preview is enabled.

int32_t gui_live_preview_poll_interval_ms = 100: Poll interval used by startup live preview in milliseconds.

struct AppLaunchTransition

Optional launch transition shown when an app surface is being opened.

Public Members

bool enabled = false: Whether app launch transition rendering is enabled.

std::string root_path: GUI resource root containing the launch transition document.

std::string screen_path = "/app_launch": Absolute screen path inside the launch transition document.

std::string surface_path = "/app_launch/surface": Path of the app surface placeholder used by the transition.

std::string icon_path = "/app_launch/icon_box/icon_image": Path of the app icon image in the transition document.

std::string fallback_label_path = "/app_launch/icon_box/fallback_label": Path of the fallback label when an icon is not available.

gui::MountTarget target: GUI mount target used for the launch transition.

int32_t duration_ms = 220: Transition animation duration in milliseconds.

int32_t timeout_ms = 500: Maximum time to wait for app surface readiness.

int32_t final_icon_size = 96: Final app icon size in pixels.

struct StartupOverlay

Optional startup overlay shown while the system is preparing the shell.

Public Members

bool enabled = false: Whether startup overlay mounting is enabled.

std::string root_path: GUI resource root containing the startup overlay document.

std::string screen_path = "/startup": Absolute screen path inside the startup overlay document.

gui::MountTarget target: GUI mount target used for the overlay.

int32_t min_present_ms = 16: Minimum duration in milliseconds before the overlay can be dismissed.

Application Interface

Public header: #include "brookesia/system_core/app/iapp.hpp"

Header File

system/brookesia_system_core/include/brookesia/system_core/app/iapp.hpp

Classes

class IApp

Base interface implemented by native applications hosted by Brookesia System.

Applications provide a manifest, optionally expose a GUI descriptor, and receive lifecycle, action, and timer callbacks from the system runtime.

Subclassed by esp_brookesia::app::app_store::AppStoreApp, esp_brookesia::app::files::FileManagerApp, esp_brookesia::app::settings::SettingsApp

Public Functions

virtual AppManifest get_manifest() const = 0

Get the static metadata used to identify and present the application.

Returns: Application manifest containing id, name, version, and launch metadata.

virtual AppGuiDescriptor get_gui_descriptor() const

Get the optional GUI resource descriptor for applications with a visual surface.

Returns: GUI descriptor; the default descriptor is empty for non-visual apps.

virtual std::expected<void, std::string> on_install(AppContext &context)

Called when the application package is installed into the system.

Parameters: context -- System context for package storage and service access.
Returns: Empty result on success, or an error string.

virtual void on_uninstall(AppContext &context)

Called before the application package is removed from the system.

Parameters: context -- System context for cleanup operations.

virtual std::expected<void, std::string> on_start(AppContext &context)

Called when the application is started.

Parameters: context -- Runtime context for GUI, timers, storage, and services.
Returns: Empty result on success, or an error string that aborts startup.

virtual std::expected<void, std::string> on_pause(AppContext &context)

Called when the application should suspend active work.

Parameters: context -- Runtime context for the running application.
Returns: Empty result on success, or an error string.

virtual std::expected<void, std::string> on_resume(AppContext &context)

Called when the application should resume after a pause.

Parameters: context -- Runtime context for the running application.
Returns: Empty result on success, or an error string.

virtual std::expected<void, std::string> on_stop(AppContext &context)

Called when the application is stopped.

Parameters: context -- Runtime context for releasing app resources.
Returns: Empty result on success, or an error string.

virtual std::expected<void, std::string> on_action(AppContext &context, std::string_view action)

Handle an action emitted by the application GUI or shell.

Parameters

context -- Runtime context for the running application.
action -- Action identifier registered by the application GUI.

Returns

Empty result on success, or an error string.

virtual std::expected<void, std::string> on_timer(AppContext &context, TimerId timer_id, std::string_view name)

Handle a timer event previously scheduled through the app context.

Parameters

context -- Runtime context for the running application.
timer_id -- Runtime timer identifier.
name -- Application-defined timer name.

Returns

Empty result on success, or an error string.

class IAppProvider

Factory interface registered by built-in or dynamically loaded application packages.

Subclassed by esp_brookesia::app::app_store::AppStoreAppProvider, esp_brookesia::app::files::FileManagerAppProvider, esp_brookesia::app::settings::SettingsAppProvider

Public Functions

virtual AppManifest get_manifest() const = 0

Get the manifest of the application created by this provider.

Returns: Application manifest used for discovery and installation.

virtual std::shared_ptr<IApp> create_app()

Create an application instance.

Returns: Shared application instance, or nullptr when the provider cannot instantiate it.

Macros

BROOKESIA_SYSTEM_CORE_APP_PROVIDER_REGISTER_WITH_SYMBOL(ProviderType, name, symbol_name)

Register an application provider with a stable plugin symbol.

Parameters

ProviderType -- Concrete provider type derived from IAppProvider.
name -- Provider name used by the plugin registry.
symbol_name -- Exported symbol name used for dynamic provider lookup.