filmopen_picker

A snapshot

This specification is a copy of docs/software/packages/filmopen_picker.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

The prompt-builder picker: its model — resolved catalogs, deferred pictures, stored choices and prompt lookup through the plug-in seam — and its widgets.

Flutter. 8 files, 973 lines under lib/; 43 tests in 9 files. Barrel: lib/filmopen_picker.dart.

Depends on

• filmopen_l10n — uses nothing by name the digest could see
• filmopen_ui — uses AppColors
• filmopen_state — uses PluginCatalogueView, PluginFileRefused
• filmopen_store — uses AppLog

Third-party: http.

Used by

filmopen_forms

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/catalog.dart

• class PickerChoice — A stored choice identifying an entry across its source’s catalog.
  • const PickerChoice(this.source, this.item) — Stores a source tag and entry id.
  • final String source, item — The plug-in tag and the catalog-wide entry id.
  • String get reference — The persisted reference, without a catalog version.
  • static PickerChoice? parse(String? reference) — Parses exactly two nonempty halves separated by one colon.
• class PickerItem — One entry with resolved words and pictures deferred until requested.
  • const PickerItem(this.id, this.title, this.description, this.prompt, this.alt, this.thumbnail, this.full) — Keeps resolved words and deferred pictures.
  • final String id, title, description, prompt, alt — The safe entry id and resolved display and prompt words.
  • final PickerPicture thumbnail — The package thumbnail, loaded only on demand.
  • final PickerPicture? full — The optional full picture, loaded only on demand.
• class PickerCategory — One category’s resolved words and entries in file order.
  • const PickerCategory(this.id, this.title, this.description, this.items) — Keeps one resolved category in file order.
  • final String id, title, description — The safe category id and resolved display words.
  • final List<PickerItem> items — The entries in their declared order.
• class PickerSource — An enabled builder’s name and resolved catalog.
  • const PickerSource(this.tag, this.name, this.categories) — Keeps a builder summary and its resolved catalog.
  • final String tag, name — The plug-in’s tag and summary name.
  • final List<PickerCategory> categories — The categories in file order.
• class PromptBuilderCatalogRefused — A whole catalog refused at a schema location, without private content.
  • const PromptBuilderCatalogRefused(this.code, this.location, [this.key]) — Identifies a refusal without including the catalog body.
  • final String code, location — The refusal code and structural JSON path.
  • final String? key — The missing string key, where applicable.
• function List<PickerCategory> readPromptBuilderCatalog(Uint8List bytes, {required String tag, required PluginCatalogueView plugins, required String? Functio… — Resolves schema 1 whole, refusing invalid catalogs before any picture is read.

lib/src/field.dart — only PromptBuilderField

• class PromptBuilderField — The closed control of a prompt-builder target: the effective choice’s thumbnail and title, or [emptyLabel].
  • const PromptBuilderField({super.key, required this.target, required this.label, required this.emptyLabel, required this.value, required this.inheri… — A control for [target] showing value ?? inherited.
  • final String target, label, emptyLabel, identifier — The builders’ target, their label, the words of no choice and the agent’s identifier.
  • final String? value, inherited, helper — The raw references as the draft and the inheritance hold them, and the inheritance’s origin words.
  • final ValueChanged<PickerChoice> onChanged — Called with a local pick, never on building, opening or closing.
  • final bool enabled — Whether the control opens the popup; false draws it locked.
  • final http.Client? client — The client for HTTPS pictures, a stand-in in tests.

lib/src/full_view.dart

• function Future<bool> showPromptBuilderFull(BuildContext context, {required PickerSource source, required PickerItem item, Future<Uint8List?>? thumbnail}) — The full view of [item] over the popup: its picture, its prompt read-only, Copy, Use this and Close.

lib/src/picture.dart

• enum PickerPictureKind — The encoded-byte bound to apply before decoding a picture.
  • values: thumbnail, full
• class PickerPicture — A package or HTTPS picture whose bytes are read only on demand.
  • PickerPicture(this.tag, this.category, this.item, this.kind, {required this._plugins, this._client, this.path, this.url}) — Describes a picture without reading it.
  • final String tag, category, item — Safe correlation tokens identifying the picture without its address.
  • final PickerPictureKind kind — Whether the thumbnail or full-picture bound applies.
  • final String? path — The package asset path, when the picture is packaged.
  • final Uri? url — The HTTPS address, when the picture is remote.
  • Future<Uint8List> load() — Reads once, checks encoded bounds/signature and logs without revealing the address.
• class PickerPictureRefused — A safe picture refusal, with its code alone as text.
  • const PickerPictureRefused(this.code) — Stores a transport or encoded-picture refusal code.
  • final String code — The refusal reason, without a URL, path or body.
• function String? pictureRefusal(Uint8List bytes, PickerPictureKind kind) — Checks encoded size and JPEG, PNG or WebP signature before the caller decodes.

lib/src/popup.dart

• function Future<PickerChoice?> showPromptBuilderPopup(BuildContext context, {required List<PickerSource> sources, PickerChoice? chosen, required String targ… — The picker’s popup over [sources]: answers the pick, or null where it closes unchanged.

lib/src/prompt.dart

• function Future<String?> promptBuilderPrompt(PluginCatalogueView plugins, PickerChoice choice, {required String locale}) — Resolves one localized prompt, returning null only for an agreed missing reference.

lib/src/sources.dart

• function Future<List<PickerSource>> promptBuilderSources(PluginCatalogueView plugins, {required String target, String? locale, http.Client? client}) — Reads enabled matching builders sequentially, keeping the rest after a catalog failure.