Files App

Overview

brookesia_app_files is the built-in file browser app for System Core packages.

Core Responsibilities

Browses mounted storage file systems.
Displays directories and files through GUI resources.
Uses Storage service and System Core app lifecycle hooks.

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_files/include/brookesia/app_files/files_app.hpp

Classes

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

Built-in file manager application for browsing storage volumes and basic file actions.

Public Types

enum class EntryKind

File browser entry category used for rendering icons and supported actions.

Values:

enumerator Volume: Storage volume root entry.

enumerator Directory: Directory entry.

enumerator File: Regular file entry.

enumerator Other: Unknown or unsupported filesystem entry.

enum class Page

Internal page currently shown by the file manager.

Values:

enumerator Browser: Main browser page.

enumerator Operations: Per-entry operation page.

Public Functions

FileManagerApp(): Create a file manager application instance.

~FileManagerApp() override: Destroy the file manager 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_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 FileManagerAppProvider : public esp_brookesia::system::core::IAppProvider 

Public Functions

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

Get the manifest for the built-in file manager app.

Returns: File manager application manifest.

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

Create a file manager application instance.

Returns: Shared application instance.