Class DrawingController

The space the armed tool places in: 'data' unless it was armed for the viewport.

Add a fully-specified drawing (import, or a host-authored one). One that carries a restriction is the host's, and placing it is not a step the user can take back, so it is not recorded.

Supported numeric levels, independent of whether the queried time lies on the shape.

Apply a linked commit without adding to this chart's local undo history.

Over the series (zIndex 0), out of the series band when it was placed in it. A no-op for a drawing already there.

In front of every other drawing in its slot: its side of the series, or the entry it is placed above.

Abandon whatever is being placed: the anchors so far are dropped and, unless the controller stays in drawing mode, the tool is disarmed too, so one Escape returns the chart to the cursor the way a finished shape would. With nothing pending, an armed tool is simply disarmed. Returns whether anything changed, so a host can let the key fall through when it did nothing.

Roll back an interrupted drag and leave the pre-gesture undo/redo stacks intact.

Delete every drawing the user may, as one undo entry; options.force takes the read-only ones too.

The clipboard behind copy / cut / paste, for a host reporting failures.

Put drawings on the clipboard. Defaults to the selection; pass an id or a list of ids to copy something else. Resolves false when there was nothing to copy, or when the payload could not be stored anywhere.

Group live drawings, replacing any previous membership for those ids. A read-only drawing's group is the host's, so it is left where it is unless options.force is set.

Copy, then delete. The delete happens only after the clipboard write resolves successfully, so a refused write leaves the model exactly as it was rather than destroying a drawing that went nowhere. A read-only drawing cannot be deleted, so it is not cut either: it stays, uncopied.

Hand the step each study input anchor move makes (a handle dragged, a moveInputAnchor) to a timeline of the host's instead of this history, until the returned function gives them back. For a host keeping one undo history for the whole chart that already records the settings patch the move writes, as the widget's ChartHistory does: held here as well, one move would be taken back twice, and a press here would reach a step the other timeline had already taken back. record is called once the patch is written, in the same turn, with the step's own undo and redo (each false once the settings have moved on from it); this history records nothing for it and emits no drawing:change. A move made inside untracked is the host's own and reaches neither. A later call takes the steps from an earlier one. A point written to the settings some other way, which this history otherwise holds as a step of its own, is not handed over: the host's timeline sees that write itself.

Every drawing, in list order, those the interval hides included. That is creation order until a z-order call moves one; the list is the tie-break for equal zIndex, so it is also the paint order within a band.

Clone drawings, offset like a paste so the copies are visibly new, and select the clones. One undo entry. Ids that name nothing are ignored. A clone is the user's own drawing, so it carries no policy.

Whether eraser mode is on.

End a variable-anchor shape (polyline, path) at the anchors placed so far. Those tools declare points: 0, so nothing else can ever complete them; without this they collected vertices forever. Bound to double-click, and public so a host can offer Esc / Enter too. No-op when there is nothing placeable, so a stray double-click costs nothing.

Replace every drawing. Accepts a DrawingsDocument or a 1.9.x bare Drawing[]; both go through the migration, so an old save upgrades on load. Clears the selection and history.

Named drawing sets, returned as detached records.

The ids of the drawings the chart's interval leaves off the chart, in model order. One pass for a caller asking about every drawing, as the object inventory does on each refresh: shownOnInterval per id would look each one up.

The steps each branch holds, oldest first, by the number drawing:change reported them under. For a host that keeps one timeline across drawings and its own edits: a step missing from both branches has been taken away (a reset, a trim, a host edit that left it nothing to do), and pressing undo for it would reach an older step instead. A step still being recorded, a drag in progress, is not listed until its change closes it.

The drawing under the pointer, selected or not, as the chart's hit-test last reported it. What a host passes as hasTarget to the key mapping, and what a context menu opens on.

The chart interval drawings are shown for: the data context's interval when the controller was built, then as each data:context announces it, or null when the host names none (or a blank one), and then every drawing shows. Each drawing's intervals range is read against it.

The snap mode in force, after the boolean form has been folded.

Whether a temporary measure (Shift+click on empty space) is on the chart. draw:measure ({ active }) fires when one starts and when it goes. A host routing Escape to cancel() only while placing passes this too.

Move a study's input anchor (a price input declared with timeKey and anchor: true) to point as the user, the way dragging its handle does: the time snaps to the bar under it, both halves stay inside the bounds the inputs declare, a study the user may not configure refuses it, and the move is one undo step in this history. For a host control that sets the point another way, such as a point pick on the chart, so Undo takes it back like a drag. A point written through the study's settings instead (a settings dialog's Pick point) is one step of this history as well, unless it is written inside untracked or forced on a study the user may not configure, which are the host's own. False when the study has no anchor for key (or the controller was built without input anchors), the study refuses, or it already holds the point.

Move drawings by a screen distance, dx right and dy down in media px, as one undo entry. Pixels rather than data units so an arrow key moves a shape the same visible amount on every pane and scale. Locked and read-only drawings stay put.

Paste whatever is on the clipboard into this chart, offset from the original so the copy is visibly a second object, and select the result. Each pasted drawing is a fresh object with a fresh id, never a second reference to the one copied, so editing the paste cannot alter its source (or the clipboard).

Anything that is not our payload (foreign text, a truncated or hand-edited copy, a newer format) pastes nothing and resolves to an empty array: a paste shortcut must not throw at the host because the user last copied a spreadsheet cell.

Move a drawing directly above or below target in its pane's paint order, as one undo step. Next to another drawing it joins the slot that drawing paints in; above a series-band entry (chart.seriesStack) it is placed on that entry, under the drawings already there; below one it goes on top of the slot under that entry, the drawings behind the series when the entry is the first. A slot's drawings are renumbered, below the series up to -1 and elsewhere from 0. False, with nothing recorded, for a target on another pane, one the host cannot report, or a move that changes nothing. Like reorder, it is outside a drawing's policy.

Remove the last anchor placed on a variable-anchor tool (polyline, path) still being drawn: the Backspace of placement. A fixed-anchor tool has nothing to pop, since its anchors commit the moment the last one lands, and a freehand stroke is one gesture rather than a list. Returns whether an anchor went.

Delete one drawing. A read-only one goes only with options.force.

Remove a group, optionally deleting all its drawings as one edit. One that holds a read-only drawing is the host's, and needs options.force.

Delete several drawings as one undo entry. Unknown ids are ignored, and read-only drawings stay unless options.force is set.

Rename a group. One that holds a read-only drawing is the host's, and needs options.force.

Move one step through the rendered stack, within the slot it paints in: its side of the series, or the entry it is placed above. placeInStack moves it between slots.

Reorder related drawings inside their existing slots, preserving unrelated local order.

The drawing's anchors in container media px, the space timeToCoordinate and priceToCoordinate answer in, whichever space it is anchored in. What a host places an overlay by (an inline editor, a popover). Null for an unknown id, or when the drawing's pane has no place on screen (folded to a strip, or hidden behind a maximized pane).

Replace the selection, or with additive toggle each id into it (the shift-click gesture). Ids that name nothing, or a drawing whose policy says it cannot be selected, are ignored, so the selection only ever holds drawings that are there to act on. Pass null to clear.

The primary selection: the first id picked, or null.

Every selected id, in the order they were picked.

Under the series (zIndex -1), out of the series band when it was placed in it. A no-op for a drawing already there.

Behind every other drawing in its slot: its side of the series, or the entry it is placed above.

Eraser mode: a click on a drawing deletes it, and a drag deletes every drawing it crosses, as one undo step on release. What the user could not delete by selecting it (read-only, locked, unselectable or hidden) stays. While it is on the chart is in placement mode, so a drag erases rather than pans. Turning it on disarms any tool; arming a tool, cancel() and setEraser(false) turn it off. draw:eraser ({ active }) fires on each change.

A linked drag paints over its committed drawing without changing saved state.

Arm a tool for placement, or pass null to return to the cursor. With options.space set to 'viewport' the drawing it places is pinned to the screen; a tool that cannot be (see DrawingTool.viewport) throws.

Whether a drawing is on the chart at the chart's interval: false for an unknown id and for one whose intervals range leaves that interval out. visible is not read; it is the user's own switch.

Serialisable document, the same shape ChartState.drawings carries. Transient drawings (policy.persistent false) are left out, and so is their group membership.

Run fn as the host's own act. An edit it makes records no undo step and leaves both branches as they are, and every step already recorded takes it in, the way a forced call does, so no later undo or redo reverses it. Unlike force it reaches no read-only drawing, and undo or redo inside it still moves along the branches. For a host keeping one timeline across drawings and its own changes, whose own changes are never steps.

Patch one drawing. False when there is no such drawing, or when it is read-only to the user and options.force is not set. A patch that carries policy is the host's, and like a forced one records no step.

Also false when the patch asks for a space the drawing could not be moved to (a tool without viewport support, or a pane with no place on screen, folded or hidden behind a maximized pane): the rest of the patch still applies, and the false tells a host that the drawing is not in the space it asked for, which a control showing that space has to say.

Patch several drawings as one undo entry: a colour change across a multi-selection is one edit to the user, so it is one Ctrl+Z too. Ids that no longer exist are skipped, and so are read-only drawings unless options.force is set; nothing is recorded when nothing is left, or when every patch is the host's (forced, or carrying policy).

Numeric drawing value using the actual pane projection and collapsed time axis.