filmopen_tree

A snapshot

This specification is a copy of docs/software/packages/filmopen_tree.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 tree pane: the tree view (TreeView, drawing filmopen_state‘s TreeNodes; with a TreeDragDrop its rows can be dragged — it knows places on a row, DropPlace, and shows them, while what may be dragged and what a drop does is ScriptActions’, the one move), the project menu with New project, the sample, Copy to a folder… and the library folder, the new-project dialog (the title first, then the folder for the project — its parent, and its own name, which follows the title until one is typed — with no kind; under them filmopen_sharing’s cloud choice and director block, the director made the username before the project is made, then the record or the cloud set up, a stage that fails after the project exists said with what finishes it; what it creates opens on the new project’s own pj version, on Edit, its first scene waiting in the script), the new-entity dialog (a character, a location or a prop from their category page — a prop’s kind optional, A.3’s ten with None first; a folder or a scene from a row’s menu or a page — it is here because the tree opens it and may not import the pages, which import the tree), RowMenuButton and showRowMenu (the ⋯ of a row and its menu, which a page’s rows use too), and ScriptActions: what a row of the script offers in its menu — Add folder…, Add scene…, Move up, Move down, Move to…, Remove from folder — each calling the one ProjectController method for it; and the move dialog (showMoveDialog, moveDestinations: Script and the folders the viewer may change, read off the tree’s own model, without the moved folder’s branch).

Flutter. 15 files, 4,648 lines under lib/; 50 tests in 8 files. Barrel: lib/filmopen_tree.dart.

Depends on

• filmopen_format — uses Author, ChildEntry, Entity, EntityType, EpochDeclaration, FilmProject, ProjectManifest, ShortName, ShortNameProblem, StaleFileException, VersionStem, characterKinds, childTypes, danglingReason, folderIsOrHolds, folderKinds, folderTagPrefix, nextFolderTag, nextSceneTag, projectKeyOf, projectManifestFileName, propKinds, takenChildTags
• filmopen_store — uses AppLog, EntityExistsException, ProjectFolderIsLinkException, ProjectFolderNotEmptyException, canCreateProjects, createProject, deleteProjectFolder, firstSceneTag, isDeletableProjectFolder, sameFolderPath
• filmopen_state — uses AccountAuthentication, AccountProjects, AccountProjectsRefused, AccountSnapshot, AccountSnapshots, AddedChild, ChildBeside, ChildrenLock, CreatedProject, EntitySelection, EntityTreeIcon, ExitTasks, GlyphTreeIcon, IndexNotPublishedException, MovedChildren, NavIndex, OpenDrafts, OpenRefusedException, PageAccess, ProjectController, ProjectImportException, ProjectNotOpenedException, ProjectRecord, RecentProject, ScriptPlace, Selection, Settings, TreeBuilder, TreeGlyph, TreeIcon and 28 more
• filmopen_ui — uses AppColors, Breakpoints, EmptyState, InfoChip, ShortNameField, iconFor, kLongMessage, showMessage, showMessageOn
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_dictation — uses DictateButton, DictationLook, DictationTarget, dictateShortName
• filmopen_sharing — uses AccountSnapshotBuilder, CloudChoice, CloudOptions, CloudProvider, DirectorChoice, DirectorSource, RecordPullFailure, RecordResult, shareNewProjectOnDrive, sharingModelProvider, showAliasDialog

Third-party: flutter_riverpod, file_selector.

Used by

filmopen_app, filmopen_browser

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

• function Future<void> copySessionToFolder(BuildContext context, WidgetRef ref) — Copy to a folder… (§9.5): keeps a session copy on disk, offered by the project menu and by a page’s red line, so it is one function.

lib/src/import_script_dialog.dart

• variable const importScriptExtensions — What the picker offers, in one Screenplay group: every format the import reads, upper and lower case.
• function Future<VersionStem?> showImportScriptDialog(BuildContext context, {Future<String?> Function()? chooseFile}) — Imports a chosen screenplay file into a new project folder and returns its project version, or null on cancellation.
• function Future<void> showImportScriptDesktopOnly(BuildContext context) — Says that a screenplay is imported in the desktop version only, where no file can be chosen (a phone).

lib/src/move_dialog.dart

• class MoveDestination — Where an entry of the script may go: a row of the move dialog.
  • const MoveDestination({required this.id, required this.container, required this.label, this.detail, required this.depth})
  • final String id — The tree’s id of the row — script, script/fo:f1/fo:f3 — which the dialog’s identifier carries: move.to:<id>.
  • final Entity container — The file whose children takes the entry.
  • final String label — What the row says: the folder’s name, or Script, and what the tree says after it — the kind, the count — where it says anything.
  • final String? detail
  • final int depth — How far the row is indented, as the tree indents it: 0 is Script.
• function ({List<MoveDestination> destinations, int foldersLeftOut, String? scriptLeftOutOf}) moveDestinations(TreeModel model, ScriptPlace moved, { required… — What the move dialog lists for [moved]: Script, and every folder the script draws whose version is the viewer’s own, in the tree’s order.
• function TreeModel viewTreeModel(WidgetRef ref) — The tree of the film as decisions read it (ProjectController.view, §7.5).
• function Future<Entity?> showMoveDialog(BuildContext context, WidgetRef ref, ScriptPlace moved, { required bool Function(Entity) mayChange, bool Function(En… — Asks where [moved] goes, and answers the file chosen — the entry is put at the end of its children — or null when cancelled.

lib/src/new_entity_dialog.dart

• variable const Set<EntityType> addableTypes — The library types a person can add from their category page.
• function Future<VersionStem?> showNewEntityDialog(BuildContext context, EntityType type, {String? initialEpoch, bool forScene = false}) — Asks for the filename, the name, a character’s role or a prop’s kind and — where the project has several — the epoch, then writes the first version of a new character, location or prop as the username in effect, which…
• function Future<AddedChild?> showNewChildDialog(BuildContext context, EntityType type, {required Entity parent}) — Add folder… and Add scene…: one dialog for the two types a script holds, asking the name first and nothing else a person has to think about.

lib/src/new_project_dialog.dart

• function Future<CreatedProject?> showNewProjectDialog(BuildContext context, {Future<String?> Function()? chooseFolder}) — Asks for a new project’s title, then the folder it goes into: the parent folder and the folder’s own name, the short name its files carry (§9.2).

lib/src/row_menu.dart

• class TreeMenuItem — One item of a row’s menu.
  • const TreeMenuItem({ required this.identifier, required this.label, required this.icon, required this.onSelected, this.disabledReason, })
  • final String identifier — The door an agent drives: the same on every row, one menu being open at a time (tree.add-folder, tree.add-scene, tree.remove).
  • final String label — What the item says, and the glyph before it.
  • final IconData icon
  • final VoidCallback onSelected — What it does when it is chosen.
  • final String? disabledReason — Why the item cannot be chosen, as its tooltip; null when it can (CLAUDE.md §6: a disabled control says why).
• function Future<void> showRowMenu(BuildContext context, Offset position, List<TreeMenuItem> items) — Opens [items] as a menu at [position] (global), the way the platform’s own context menu opens where it was asked for, and does what is chosen.
• class RowMenuButton — The ⋯ of a row: a row of the tree’s Script branch, and a row of a folder’s contents on its page.
  • const RowMenuButton({super.key, required this.identifier, required this.items, this.color})
  • final String identifier — The door an agent drives: tree:<node id>.menu, contents:<entry>.menu.
  • final List<TreeMenuItem> Function() items — What the menu holds, built when it is opened.
  • final Color? color

lib/src/script_actions.dart

• class ScriptActions — What a person does to the script from a row’s menu, and from a folder’s contents: Add folder…, Add scene…, Move up, Move down, Move to… and Remove from folder.
  • const ScriptActions(this.ref, {this.onNavigated})
  • final WidgetRef ref
  • final VoidCallback? onNavigated — Called when an action opened a page, as choosing a row does.
  • String? lockReason(BuildContext context, Entity parent) — Why the children of [parent] may not be changed by the viewer, in words, or null when they may.
  • List<TreeMenuItem> menuOf(BuildContext context, TreeNode node) — The menu of a row of the script.
  • List<TreeMenuItem> itemsFor(BuildContext context, ScriptPlace place, {String prefix = 'tree', bool withAdd = true, String? nodeId}) — The items for a row at [place], wherever the row is drawn.
  • Future<void> add(BuildContext context, EntityType type, Entity parent) — Asks for the new folder’s or scene’s name, creates it at the end of [parent]’s children and opens its page.
  • TreeDragDrop dragDrop(BuildContext context) — Dragging in the tree: every drop is the move the menu makes, and nothing else.
  • bool canDrag(BuildContext context, TreeNode node) — A row of the script whose entry names a folder or a scene, out of a list the viewer may change — or out of none, beside the script — and not one that is for inspection only.
  • String? cannotMove(BuildContext context, ScriptPlace? place) — Why the row at [place] cannot be moved, dragged or marked, as a code for the log; null where it can.
  • Map<String, String> notMarkable(BuildContext context, Iterable<(String, ScriptPlace?)> rows) — Each of [rows], by id, that cannot be marked, with why: what the marks are told to leave out (§8.1).
  • Set<DropPlace> placesOn(TreeNode target) — What a drop on [target] can mean: into a row that holds a list — the Script row, a folder drawn with its contents — and before or after a row a list of the script holds.
  • String? dropRefusal(BuildContext context, TreeNode dragged, TreeNode target, DropPlace? where) — Why [dragged] may not land at [where] of [target], or null when it may.
  • bool wouldCycle(String? entry, Entity container) — Whether filing [entry] under [container] would put a folder inside itself or beneath itself.
  • Future<void> drop(BuildContext context, TreeNode dragged, TreeNode target, DropPlace where) — The drop: into a list at its end, or before or after [target] in the list that holds it — beside [target]’s entry as the move’s turn finds that list (§7.5), never at the index the drawn row had.
  • Future<void> moveBy(BuildContext context, ScriptPlace place, int delta) — Move up and Move down: one place earlier or later in the list that holds the row, as the move’s turn finds that list (§7.5) — one write of that list.
  • Future<void> moveTo(BuildContext context, ScriptPlace place, {String? nodeId}) — Move to…: asks where, among Script and the folders the script draws that the viewer may change, and puts the row at the end of the one chosen.
  • Future<void> remove(BuildContext context, ScriptPlace place) — Takes the row out of the list that holds it.

lib/src/tree_drag.dart — only DropPlace, TreeDragDrop

• enum DropPlace — Where a dragged row would land, relative to the row the pointer is over.
  • values: before, into, after
• class TreeDragDrop — A drag’s doors.
  • const TreeDragDrop({required this.canDrag, required this.placesOn, required this.refusal, required this.onDrop, this.onRefused})
  • final bool Function(TreeNode node) canDrag — Whether [node] can be picked up.
  • final Set<DropPlace> Function(TreeNode target) placesOn — The places a drop on [target] can mean; none for a row that is no part of the script.
  • final String? Function(TreeNode dragged, TreeNode target, DropPlace? place) refusal — Why [dragged] may not land at [place] of [target], in words, or null when it may.
  • final void Function(TreeNode dragged, TreeNode target, DropPlace place) onDrop — The drop: [dragged] at [place] of [target], which [refusal] allowed.
  • final void Function(TreeNode dragged, TreeNode target, DropPlace? place, String reason)? onRefused — A drop let go of where [refusal] gave [reason]: once, at the release, never while the drag hovers.

lib/src/tree_icons.dart

• function IconData treeIconData(TreeIcon icon) — The glyph of a row’s [TreeIcon]: the entity types’ icons, and one each for the grouping rows.

lib/src/tree_pane.dart

• class TreePane — The sidebar: project title, actions, filter, and the tree.
  • const TreePane({super.key, this.onNavigated})
  • final VoidCallback? onNavigated — Called when a tap has navigated somewhere — not when one merely opened a branch.

lib/src/tree_view.dart

• class TreeView — A flat, virtualised rendering of a [TreeNode] forest.
  • const TreeView({ super.key, required this.roots, required this.isExpanded, required this.selectedId, required this.filter, required this.onSelect,…
  • static const Duration openOnRest — How long a drag rests on a closed folder before it opens (§3.11).
  • static const double scrollEdge — How near the list’s top or bottom a drag scrolls it (§3.11).
  • final List<TreeNode> roots
  • final bool Function(TreeNode node) isExpanded
  • final String? selectedId
  • final String filter
  • final ValueChanged<TreeNode> onSelect
  • final ValueChanged<TreeNode> onToggle
  • final Set<String> marked — The rows marked for an act that takes more than one, by node id (§8.3): each is tinted, whatever their count.
  • final int markedCount — How many rows a drag of a marked row carries: the marks that resolve to a row.
  • final String? anchorId — The row a shift-click measures its range from.
  • final ValueChanged<TreeNode>? onMarkOnly — A plain click: this row alone is marked, and it becomes the anchor.
  • final ValueChanged<TreeNode>? onMarkToggle — A control- or command-click: this row joins the marks or leaves them.
  • final ValueChanged<List<TreeNode>>? onMarkRange — A shift-click: every row drawn between the anchor and this one, in the order drawn.
  • final List<TreeMenuItem> Function(TreeNode node)? menuOf — What a row’s menu holds; a row with none has no ⋯ button and takes no right click.
  • final TreeDragDrop? dragDrop — Dragging rows of the script; null for a tree whose rows stay where they are.

Internal

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

• lib/src/open_project_dialog.dart: showOpenProjectDialog, OpenProjectDialog, _OpenProjectDialogState, _ComingSoon
• lib/src/tree_drag_widgets.dart: DragFeedback, MouseDraggable, TouchDraggable
• lib/src/tree_row.dart: TreeRow, _TreeRowState, _RowLabel, _Chevron