Files

FileSystem provides application directories and asynchronous file operations. FilePicker returns capability-bearing FileReference values instead of assuming every platform exposes a durable filesystem path.

Open a user-selected file

Task<void> OpenText(State<std::string> content) {
  auto picker = UseService<FilePicker>();
  auto picked = co_await picker->OpenFileAsync({
      .name = "Text",
      .extensions = {"txt"},
  });
  if (picked) {
    auto text = co_await picked->ReadStringAsync();
    if (text.Succeeded()) {
      content = std::move(text).Value();
    }
  }
}

An empty optional means the user cancelled the picker. It is not a framework error and should not produce an error message.

Keep provider authority

Use FileReference for user-selected and externally activated files. It carries metadata and platform authority and supports reading, importing, and replacement when writable without pretending that every provider value is a durable local path.

Retain the reference only for as long as its platform contract permits. Import content into application storage when the application needs durable ownership.

Work with application files

File and FileSystem cover application-owned paths. AppDirectories identifies platform-resolved executable (when available), data, cache, and temporary locations according to the current adapter. Obtain the installed services with UseService<FileSystem>() and UseService<FilePicker>().

File offers synchronous operations for code that already runs off the UI thread and Async counterparts for component-owned work. Read, stat, and listing operations return FileResult<T>; mutation methods report success with bool. Inspect Succeeded() before taking Value(), and use FileErrorCode to choose a recoverable application response.

Filter and save

Picker filters describe names, extensions, and MIME intent where supported. They improve the platform picker experience but are not a security boundary; validate content after opening it.

Use the save picker for a new destination and the replacement operations on a writable FileReference when updating an existing user-selected document.

See the File API for exact overloads and result types, and Lifecycle and activation for files delivered when another application opens content with HuxerUI.