filmopen_insertion_ui

A snapshot

This specification is a copy of docs/software/packages/filmopen_insertion_ui.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 media place: one element for every place a film keeps media (Software Specification §9.3).

Flutter. 13 files, 2,510 lines under lib/; 149 tests in 7 files. Barrel: lib/filmopen_insertion_ui.dart.

Depends on

• filmopen_format — uses Author, EntityType, FileNameParser, FilmProject, MediaEntry, MediaInsertionResult, MediaKind, MediaSpans, MediaStage, Pick, SpansShape, TakeName, acceptsFile, arrivedAfter, blockIdsOf, blockLineOf, blockMediaGroups, blocksOf, coverageFrom, documentsNamingTake, entriesIn, entryNaming, isViewersTake, mediaContainerKey, mediaKindOf, projectKeyOf, spansAllowed, takeNamed, withEntriesReordered, withEntryAttributes
• filmopen_state — uses AutomationHost, BatchSelection, MediaEntryAction, MediaEntryActionAvailability, MediaEntryActionAvailable, MediaEntryActionContext, MediaEntryActionReason, MediaEntryActionUnavailable, MediaEntryActions, MediaEntryProviderUnavailable, PageAccess, browserProvider, catalogueProvider, insertionServiceProvider, jobViewsProvider, mediaStoreProvider, projectClosedProvider, projectProvider, settingsProvider
• filmopen_insertion — uses BlockPlace, FilesSource, Function, InsertionService, InsertionSource, InsertionTarget, MediaImportException, SlotPlace, producerFailureOf, producerJobKind
• filmopen_jobs — uses JobAction, JobActionAck, JobPhase, JobUnavailable, JobView, describeJobError
• filmopen_media — uses MediaInput, MediaProvenance, MediaRef, MediaStore, ProjectMedia
• filmopen_media_ui — uses Function, MediaBatchFrame, MediaState, MediaTile, MediaTileButton, canChooseFiles, chooseMediaFiles, factLines, mediaStateOf, mediaTileEdge, mediaTileEdgeFor, mediaTileGap, provenanceLines, provenanceText, showMediaViewer
• filmopen_ui — uses AppColors, EmptyState, scopedId, showMessage
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_store — uses AppLog, LogLevel
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: flutter_riverpod, desktop_drop.

Used by

filmopen_app, filmopen_browser, filmopen_forms, filmopen_prompt_ui, filmopen_render_ui

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/file_drop_stub.dart

• variable const bool canDropFiles — Whether files can be dropped here: on Windows, Linux, macOS and Android, never on the web.
• function Widget fileDropTarget({ required Widget child, required void Function(List<String> paths) onDrop, void Function(bool over)? onOver, }) — [child] as a drop target wherever a pointer at the drop would touch it, [onDrop] getting the paths in order.
• function void settleFileDrops() — Called once at start: answers the drop package’s web half with nothing, so a drag over the page is ignored.

lib/src/insertion_actions.dart

• class ActionAvailability — Whether an action may run at a place: yes, or no with the sentence its button’s tooltip says.
  • const ActionAvailability()
• class ActionAvailable — The action may run.
  • const ActionAvailable()
• class ActionUnavailable — The action may not run, and [reason] says why, in the person’s language.
  • const ActionUnavailable(this.reason)
  • final String reason — Why, for the disabled button’s tooltip.
• class InsertionAction — A button of the add tile: what it is called and drawn with, the kinds it makes, whether it may run at a place, and what it runs — an [InsertionSource] for the place’s service to insert, or nothing.
  • const InsertionAction()
  • String get id — The last segment of the button’s identifier, media:<stem>:<group>.action.<id>.
  • String label(AppLocalizations l10n) — The button’s word, in the person’s language.
  • IconData get icon — The button’s icon, which it keeps where its word does not fit.
  • Set<MediaKind> get kinds — The kinds of media the action makes; a place that takes none of them does not draw its button.
  • bool appliesTo(InsertionTarget target) — Whether the action belongs at [target] at all; a place where it does not draws no button for it, where one that may not run now keeps its place, disabled.
  • ActionAvailability availableFor(BuildContext context, InsertionTarget target) — Whether the action may run for [target] now; a button that may not keeps its place, disabled.
  • Future<InsertionSource?> run(BuildContext context, InsertionTarget target) — Runs the action for [target] — a sheet, a dialog — and answers what to insert, or null for nothing.
  • Future<InsertionSource?> continueFrom(BuildContext context, InsertionTarget target, MediaEntry take, {MediaStage? stage}) — Runs the action for [target] continuing [take], a render’s take of the place (Render from this take), and answers what to insert; null, the default, for an action that continues nothing.
• class UploadAction — Upload: a file on this machine or an address, through the upload sheet, of the kinds the place takes.
  • const UploadAction()
• class InsertionActions — The actions every add tile offers: [UploadAction] first, then those [register]ed, in that order.
  • static List<InsertionAction> get all — Every action, Upload first.
  • static void Function() register(InsertionAction action) — Adds [action] after those registered before it; answers what takes it back.

lib/src/job_tile.dart

• function String jobSentence(AppLocalizations l10n, JobView job) — What [job] is doing, in the words its tile says.
• class JobTile — One job as a tile: the mark of its phase, its sentence, a bar where its progress is a number, and a small button per action it offers (job:<id>:<action>).
  • const JobTile({ super.key, required this.job, required this.identifier, required this.onAction, this.edge = mediaTileEdge, this.onDetails, })
  • final JobView job — The job as its service shows it.
  • final String identifier — media:<stem>:<group>:job:<n>, the n-th job of the place, newest first.
  • final void Function(JobAction action) onAction — Called with the action a button of the tile was pressed for; the caller sends it to the job’s service.
  • final VoidCallback? onDetails — What Details does, beside the job’s actions; no button where it is null (§6.15).
  • final double edge — The edge of the place’s tiles: a job is two tiles wide and at least one tall.

lib/src/media_place.dart

• class MediaPlace — One place of a page’s media: the add tile first, then this place’s jobs newest first, then its entries.
  • const MediaPlace({ super.key, required this.target, required this.document, required this.onDocument, required this.editable, required this.title,…
  • final InsertionTarget target — Where an insertion goes: the entity’s version, and a [SlotPlace] naming a group of its media or a [BlockPlace] naming a group of a block’s.
  • final Map<String, dynamic> document — The document the page is about to write: its draft, or the file on a version it may not write.
  • final void Function(void Function(Map<String, dynamic> draft) apply) onDocument — The page’s door for every edit of the entries: a change applied to its draft, as a keystroke is.
  • final bool editable — Whether the version may be written: the add tile, the drop and the menu items that edit entries exist only then.
  • final String title — The place’s title, above its tiles.
  • final Widget? header — Drawn under the title and above the tiles: what the place’s renders start from (its Prompt card, §9.3); null draws nothing.
  • final DateTime? newSince — The instant a take is new after (§13.4 visited); null marks nothing.
  • final Future<void> Function(MediaEntry entry)? onDelete — The page’s door once an entry’s deleted is written: it settles the draft, then asks the state.
  • final void Function(MediaEntry entry)? onOpened — Told as the person opens an entry in the viewer, by its tile or its menu’s Open: the page’s look (§13.4).
  • String get group — The group [target] names; a [MediaPlace] is only ever given a group’s place.
  • String? get block — The block whose group this is, or null for the entity’s own.

lib/src/media_upload_sheet.dart

• function Future<List<String>> Function(BuildContext context, Set<MediaKind> kinds)? debugChooseMediaFiles — The file dialog the sheet opens, given the kinds it offers.
• function Future<List<MediaInput>> showMediaUploadSheet(BuildContext context, { required bool sessionCopy, required Set<MediaKind> kinds, Future<List<String>… — Asks what to import into a place that takes [kinds] and answers it, or nothing when the person changes their mind.

lib/src/place_selection.dart

• class PlaceSelection — The checked places of a list, by InsertionTarget.placeKey, and the places that may be checked at all.
  • const PlaceSelection({super.key, required ValueNotifier<Set<String>> checked, required this.generate, required this.offered, required super.child}) — The selection [checked] over [offered], for the places under [child].
  • final ValueNotifier<Map<String, bool>> generate — What the person chose on the Prompt cards’ Generate boxes, by <placeKey>:<kind>; a box with no entry reads its prompt’s state (§9.3).
  • final Set<String> offered — The places that may be checked: shown and editable.
  • ValueNotifier<Set<String>> get checked
  • static PlaceSelection? maybeOf(BuildContext context) — The nearest selection above [context], which the place is redrawn with; null where there is none.
  • void toggle(String placeKey, {required String place, required String stem, required String group}) — Checks [placeKey] or unchecks it, and logs the choice: the place’s [place] identifier, [stem] and [group].
  • void toggleGenerate(String key, {required String place, required String stem, required String kind, required bool shown, required bool byDefault}) — Turns the Generate box [key] the other way from what it [shown], and logs the choice.

Internal

Files under lib/ the barrel does not reach; nothing outside the package may import them.

• lib/src/add_tile.dart: AddTile, _ActionButton
• lib/src/entry_dialogs.dart: _primaryButton, showEntryNoteDialog, _NoteDialog, _NoteDialogState, DeleteFate, FileGoes, NotATake, FileAbsent, TakeOfAnother, KeptElsewhere, deleteFateOf, _spellsTake, +1
• lib/src/file_drop_io.dart: canDropFiles, fileDropTarget, settleFileDrops, _DropGate, _DropGateState
• lib/src/place_kinds.dart: placeTakes
• lib/src/spans_chooser.dart: SpansChoice, _Extent, _laterBlocks, _positionOf, spansChooserAsks, spansLine, showSpansChooser, _SpansChooser, _SpansChooserState