Documentation / @finchart/tools / DrawingToolsApi
Interface: DrawingToolsApi
Defined in: tools/src/tools.ts:216
Extends
PluginApi
Properties
changes
readonlychanges:Observable<DrawingsChange>
Defined in: tools/src/tools.ts:292
The list changed. via distinguishes direct edits from undo/redo replay.
disposed
readonlydisposed:boolean
Defined in: core/dist/primitives/plugin.d.mts:27
Inherited from
PluginApi.disposed
historyChanges
readonlyhistoryChanges:Observable<DrawingHistoryChange>
Defined in: tools/src/tools.ts:287
Fires when command, boundary, or gesture state changes undo/redo availability.
modeChanges
readonlymodeChanges:Observable<DrawingModeChange>
Defined in: tools/src/tools.ts:239
selectionChanges
readonlyselectionChanges:Observable<DrawingSelectionChange>
Defined in: tools/src/tools.ts:298
The selection changed — every path arrives here: pointer, double-click, right-click, ], [, select, and deselection. This is what an app's properties panel or trash button listens to.
Methods
add()
add(
drawing,options?):DrawingHandle
Defined in: tools/src/tools.ts:222
Mounts it programmatically. Doesn't select by default — a deliberate asymmetry with hand-drawing, which selects on completion (AddDrawingOptions.select).
Parameters
drawing
options?
Returns
applyOptions()
applyOptions(
patch):void
Defined in: tools/src/tools.ts:300
Changes only the fields you give. Re-mounting instead would erase every line already drawn.
Parameters
patch
Partial<DrawingToolsStyleOptions>
Returns
void
begin()
begin(
kind):void
Defined in: tools/src/tools.ts:230
The next input draws this kind. A horizontal line lands at the pressed price; a trend line or Fibonacci works with either click-drag or click-move-click — where you pressed is a, where you release or click again is b. On completion it's selected and the armed state releases itself.
Parameters
kind
"horizontal" | "vertical" | "trend" | "ray" | "extended" | "arrow" | "fib" | "rectangle" | "ellipse" | "priceMeasure" | "barMeasure" | "parallelChannel" | "pitchfork" | "fibExtension"
Returns
void
cancel()
cancel():
void
Defined in: tools/src/tools.ts:236
Discards a draft, or restores an unreleased drag to where it was grabbed, and releases the armed state too — what Esc does. Neither leaves a history command (nothing was committed).
Returns
void
canRedo()
canRedo():
boolean
Defined in: tools/src/tools.ts:285
Whether redo() can replay now; false during a drag or draft. This read remains available after disposal.
Returns
boolean
canUndo()
canUndo():
boolean
Defined in: tools/src/tools.ts:283
Whether undo() would consume a command, drag, or draft. This read remains available after disposal.
Returns
boolean
clear()
clear():
void
Defined in: tools/src/tools.ts:271
Replaces the ledger with empty and clears undo/redo history.
Returns
void
dispose()
dispose():
void
Defined in: core/dist/primitives/plugin.d.mts:26
Returns
void
Inherited from
PluginApi.dispose
handles()
handles():
DrawingHandle[]
Defined in: tools/src/tools.ts:269
Handles in the same order as list().
If only add issued handles, a drawing restored by load after a page refresh couldn't be pointed at or removed individually — only clear() would be left. So this issues handles for the whole list. It's fine to hand out a fresh object every time: the contract is what it points at, not its identity, so select / remove still work.
Returns
list()
list():
Drawing[]
Defined in: tools/src/tools.ts:259
Copies — editing them outside doesn't tell the chart. To actually edit, use a handle or a drag.
Returns
Drawing[]
load()
load(
payload):boolean
Defined in: tools/src/tools.ts:290
Returns false and keeps the existing list/history if it can't be read; success clears history.
Parameters
payload
string
Returns
boolean
mode()
mode():
"horizontal"|"vertical"|"trend"|"ray"|"extended"|"arrow"|"fib"|"rectangle"|"ellipse"|"priceMeasure"|"barMeasure"|"parallelChannel"|"pitchfork"|"fibExtension"|null
Defined in: tools/src/tools.ts:238
The kind currently armed or being drawn. null if none.
Returns
"horizontal" | "vertical" | "trend" | "ray" | "extended" | "arrow" | "fib" | "rectangle" | "ellipse" | "priceMeasure" | "barMeasure" | "parallelChannel" | "pitchfork" | "fibExtension" | null
redo()
redo():
boolean
Defined in: tools/src/tools.ts:281
Reapplies the latest reverted edit. Declines while a draft or drag is in flight.
Returns
boolean
select()
select(
handle):void
Defined in: tools/src/tools.ts:257
Sets the selection programmatically — you can drive it from the keyboard or from the app (a list panel highlighting a chart entry) without a pointer hit.
Point at it with the handle add returned; null deselects. Throws if the handle points at an already-removed drawing — succeeding quietly there would be a failure that only looks like success.
Parameters
handle
DrawingHandle | null
Returns
void
selection()
selection():
Drawing|null
Defined in: tools/src/tools.ts:247
The currently selected drawing — a copy. null if none.
A selection arises from a pointer hit, select, or keyboard cycling (] / [); it's released by clicking empty space or Esc, and removed by Delete/Backspace. It's session state, so it isn't serialized.
Returns
Drawing | null
serialize()
serialize():
string
Defined in: tools/src/tools.ts:288
Returns
string
setSnap()
setSnap(
on):void
Defined in: tools/src/tools.ts:306
Turns snapping on or off — drawing and anchor dragging stick to a bar's values (close, low, high) and the bar's x. Applies to whatever's mid-draw starting from the next pointer event.
Parameters
on
boolean
Returns
void
snapping()
snapping():
boolean
Defined in: tools/src/tools.ts:308
Whether snapping is on — what a toggle button's aria-pressed asks.
Returns
boolean
undo()
undo():
boolean
Defined in: tools/src/tools.ts:279
Reverts the latest committed edit. An unreleased drag is cancelled first; a draft rewinds one confirmed anchor first (the anchors after it trail the cursor again from the next pointer move — the rewind itself has no cursor position). Returns whether it consumed anything, so a host that chains if (!tools.undo()) app.undo() never double-undoes.
Returns
boolean