Resource API

Declared by <huxerui/resource.h>.

Resource identifiers

ResourceId(domain, key) exposes Domain, Key, ToString, and equality. ImageResource, StringResource, and RawResource are distinct final ID types inheriting its constructors.

StringVariant

Retains direct text or a localized template for an API that composes the value after the call returns. Constructors accept empty, std::string, std::string_view, C string, or StringResource values. Format(resource, arguments...) retains positional formatted arguments.

UseString(StringResource, arguments...) resolves immediately to std::string. UseString(const StringVariant&) and UseString(StringVariant&&) resolve a retained value during the consumer’s composition. Prefer Text::Format(resource, ...) for Text, UseString(resource, ...) for an immediate string, and StringVariant::Format only for a parameter whose declared type is StringVariant.

Locale and configuration

Locale::FromLanguageTag, Locale::Default, and LanguageTag represent normalized locale choice. ResourceConfiguration contains locale and logical display_scale.

RawAsset

Factories: FromBytes, CopyBytes, and FromSharedBytes. Metadata: MimeType, HasValue, and equality. ReadBytes(cache = false) and ReadString(cache = false) return owned complete contents. OpenRead() returns InputStream; OpenReadAsync() returns Task<AsyncInputStream>.

ImageAsset

Factories: FromFile, FromEncoded, and CopyEncoded, each with optional scale. Queries: EncodedBytes, Format, MimeType, pixel width/height, Scale, IntrinsicSize, HasValue, and handle equality. ImageFormat is Png or Jpeg; ImageSampling is Nearest or Linear.

Resolution

UseRawResource, UseImage, and UseVectorImage resolve generated IDs through the current resource configuration. PlatformResources is the adapter interface exposing Configuration() and OpenRead(package_path) -> std::optional<InputStream>. The provider can open on a worker and must give each stream independent ownership; missing entries return nullopt, while valid empty entries return a stream that reaches EOF.

Complete resource-consumer example

#include <huxerui/huxerui.h>

using namespace huxerui;

[[huxerui::composable]]
View InboxSummary(int unread_count) {
  const StringResource title("app", "inbox_title");
  const ImageResource cover("app", "inbox_cover");

  return Column {
    Text::Format(title, unread_count),
    Button(UseString(title, unread_count)),
    Image(cover).Fit(ImageFit::Cover),
  }.With(Spacing(12.0F));
}

Text::Format resolves text owned by Text; UseString resolves an immediate string for Button; Image receives its resource ID directly.

Buffer ownership and decoded text

RawAsset::FromBytes accepts owned Bytes, CopyBytes copies a borrowed span, and FromSharedBytes(owner, data, size, mime_type) keeps a supplied owner alive while referencing its immutable byte region. The pointer must remain valid within that owner’s lifetime; shared ownership does not freeze a mutable producer buffer for you.

UseRawResource resolves identity and metadata without reading the package payload. ReadBytes(true) or ReadString(true) retains a complete successful read in a cache shared by asset copies; false does not evict an existing cache. Complete reads can block. OpenRead and OpenReadAsync create independent cursors and do not populate that complete-content cache.

Raw ReadString() preserves arbitrary bytes, BOMs and embedded nulls without encoding validation. Use File::ReadString when UTF-8 validation is intended. Default missing assets return empty complete reads, but opening a missing asset throws. Valid zero-length assets still have HasValue().

Uncached package access requires a connected resource service. Memory-backed/cached data and already opened streams can survive Runtime destruction. Open failures follow the resource exception contract; later stream failures use IoResult. OpenReadAsync() returns Task<AsyncInputStream>, not Task<IoResult<AsyncInputStream>>. Use a scoped task and handle opening exceptions as well as read errors.

ImageAsset::FromFile reads a local encoded raster file, FromEncoded takes owned encoded Bytes, and CopyEncoded copies a span. These are encoded PNG/JPEG data, not raw RGBA pixels. Scale is the logical density: intrinsic DIPs derive from pixel dimensions divided by scale. Resource selection and density handling should remain with ImageResource when using packaged variants.

StringVariant retains string ownership; a string_view constructor is not a promise to borrow the caller’s storage indefinitely. Literal Format and resource formatting serve different consumers. Prefer a generated ID over spelling ResourceId domain/key strings throughout UI, and keep locale-dependent resolution in composition so the owning scope can observe context changes.