screen method
Names the screen as it stands, without performing an action.
Where nothing has moved since the last verb captured — the ordinary
tap then screen pair — this names that capture rather than
photographing the same frame a second time:
await s.tap(Keys.search);
await s.screen('Cases'); // one step, named 'Cases', verb `tap`
So a name costs nothing, and an author never has to weigh writing one
against the picture it would duplicate. "Nothing has moved" is answered
twice: the frame count answers first and free — nothing drawn is the
same picture — and where frames were drawn (extra settling between
the verb and its name, a periodic timer repainting an identical screen)
the render this call was about to pay anyway is compared against the
held one — words, bytes and all — and a proven-identical screen adopts
just the same. Only where the screen actually differs — a pump, a
completer, a rebuild from outside the tree — is there something new to
photograph, and this captures it, which is the whole reason the verb
exists:
await s.tap(Keys.takePicture);
await s.screen('Capturing'); // names the tap's frame
await s.wait(const Duration(seconds: 5));
await s.screen('Captured'); // a new frame: its own step
It settles first, like every other verb — a capture wants a screen that has finished moving, and which verb waits and which does not is exactly the knowledge Settle exists to remove. To photograph a screen mid-flight, say so here, on the name rather than only on the verb before it:
await s.tap(Keys.takePicture, settle: Settle.none);
await s.screen('Capturing', settle: Settle.none);
Both halves, because the wait is per step and the second one would otherwise undo the first. On a screen holding an indefinite animation that is not pedantry: a bounded policy never sees a quiet frame there, so it spends its whole budget, and a spent budget under fake time is a clock that moved — every timer due inside the window fires, and the thing the scenario meant to photograph may have finished. True of any verb that follows, not only of this one.
A name never overwrites a name: two screen calls on one frame stay two
steps. force declines the adoption outright, for a deliberate second
picture of a frame that already has a name on it.
Implementation
Future<void> screen(
String name, {
List<String> tags = const [],
Settle? settle,
bool force = false,
}) => _step(
Shot(name, tags: tags),
settle,
() async {},
verb: 'screen',
adopt: !force,
);