Settings App

Overview

brookesia_app_settings provides device and system settings screens for products built with System Super.

Core Responsibilities

Organizes settings by screens such as home, Wi-Fi, sound, display, language, time zone, and more.
Uses service helpers for Wi-Fi, device, audio, display, and storage state.
Loads localized names and messages from app package i18n resources.

Integration Position

This component is an independent ESP-Brookesia release component. It can be integrated through ESP-IDF component dependencies and combined with peer framework components as needed.

API Reference

Header File

app/brookesia_app_settings/include/brookesia/app_settings/settings_app.hpp

Classes

class SettingsApp : public esp_brookesia::system::core::IApp 

Built-in settings application for device, display, sound, Wi-Fi, language, and theme controls.

Public Functions

SettingsApp(): Create a settings application instance.

~SettingsApp() override: Destroy the settings application instance.

virtual system::core::AppManifest get_manifest() const override

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

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

virtual system::core::AppGuiDescriptor get_gui_descriptor() const override

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(system::core::AppContext &context) override

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(system::core::AppContext &context) override

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(system::core::AppContext &context) override

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_stop(system::core::AppContext &context) override

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(system::core::AppContext &context, std::string_view action) override

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(system::core::AppContext &context, system::core::TimerId timer_id, std::string_view name) override

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 SettingsAppProvider : public esp_brookesia::system::core::IAppProvider 

Public Functions

virtual system::core::AppManifest get_manifest() const override

Get the manifest for the built-in settings app.

Returns: Settings application manifest.

virtual std::shared_ptr<system::core::IApp> create_app() override

Create a settings application instance.

Returns: Shared application instance.