charton API / @chart-on/core / index / DrawingToolDef
Interface: DrawingToolDef
Defined in: packages/core/src/drawing/types.ts:261
Plugin contract for a drawing tool. Register with chart.drawings.register.
Properties
action?
optionalaction?:"zoom"|"erase"
Defined in: packages/core/src/drawing/types.ts:278
Makes the tool act instead of placing a drawing; points, render and hitTest then go unused. 'erase': a press removes the unlocked drawing under it and a drag every one its stroke crosses, as one undo step. 'zoom': a drag zooms the view to the time and price range of the box.
anchoring?
optionalanchoring?:"data"|"screen"
Defined in: packages/core/src/drawing/types.ts:284
'data' (default) pins anchors to time and price. 'screen' pins them to the pane: time and price then hold x and y as fractions (0..1) of the pane width and height, so the drawing stays put while the chart scrolls.
defaultStyle?
optionaldefaultStyle?:DrawingStyle
Defined in: packages/core/src/drawing/types.ts:306
editableText?
optionaleditableText?:boolean|"optional"
Defined in: packages/core/src/drawing/types.ts:305
Prompt for text after placement and on double click. With true the text is required: a new drawing left without text is removed. With 'optional' it stays without text, and an empty entry clears the text of an existing drawing.
fillAlpha?
optionalfillAlpha?:number
Defined in: packages/core/src/drawing/types.ts:328
Opacity of the tint of the drawing's color the tool fills with when the style sets no fill (default 0.14), so a settings UI can show the fill the tool draws. Level tools fill alternate bands at this opacity and half of it, each in its level's color.
group?
optionalgroup?:string
Defined in: packages/core/src/drawing/types.ts:265
Rail group id: one of the built-in 'lines', 'annotate', 'parallels', 'ratios', 'time', 'patterns' and 'measure', or your own; tools of a group share a flyout.
label
label:
string
Defined in: packages/core/src/drawing/types.ts:263
points
points:
number|"free"|"n"
Defined in: packages/core/src/drawing/types.ts:271
Anchor points placed by the user: a count (1 = single click), 'n' to keep adding points until double-click or Enter, or 'free' for a freehand press-drag-release stroke.
settings?
optionalsettings?:DrawingSettingDef[]
Defined in: packages/core/src/drawing/types.ts:330
Extra style fields for the settings UI.
simplify?
optionalsimplify?:number|boolean
Defined in: packages/core/src/drawing/types.ts:298
For 'free' tools: when the stroke ends, drop points that change the drawn line by less than this many css px (true = 1 px), so strokes save compactly. The tolerance applies at the zoom level the stroke ended at.
snap?
optionalsnap?:"time"|"ohlc"
Defined in: packages/core/src/drawing/types.ts:292
How placed and dragged anchors snap. 'ohlc' puts the price on the nearest open, high, low or close of the bar, whatever the magnet; 'time' snaps only the time to the bar and ignores the magnet. Default: time to the bar, and the price to the bar's values while the magnet is on. The price snaps only in the main pane, where the bars are.
styleFields?
optionalstyleFields?: readonlystring[]
Defined in: packages/core/src/drawing/types.ts:321
The DrawingStyle fields (and the tool's own style keys) render honors, most important first, so a style editor offers only those. The first four that hold plain values are the toolbar's quick fields unless registerToolQuickFields sets others. Without it, editors offer color, line width, line style and the settings keys.
themeColor?
optionalthemeColor?:ThemeColorKey| ((drawing) =>ThemeColorKey)
Defined in: packages/core/src/drawing/types.ts:313
Theme color render draws in while the style sets no color (default 'drawing'), for style editors to show as the color, or a function of the drawing for a tool whose color depends on its points. Unlike a defaultStyle color it is not saved with the drawing, so it follows the theme.
type
type:
string
Defined in: packages/core/src/drawing/types.ts:262
Methods
axisMarks()?
optionalaxisMarks(drawing):DrawingAxisMarks|null
Defined in: packages/core/src/drawing/types.ts:375
Prices and times to label on the axes while the drawing is selected or being placed, with the band between the outermost ones highlighted; null labels nothing. Default: every anchor's price and time; for 'free' tools the stroke's extremes; for 'screen' tools nothing.
Parameters
drawing
Returns
DrawingAxisMarks | null
bounds()?
optionalbounds(d,env):Rect|null
Defined in: packages/core/src/drawing/types.ts:358
Screen-space extent of the drawing in pane-local css px, when it reaches beyond its anchors and handles (a circle around its centre). The selection bounds cover this box as well as the anchors and handles.
Parameters
d
env
Returns
Rect | null
constrain()?
optionalconstrain(points,anchor):DrawingPoint[]
Defined in: packages/core/src/drawing/types.ts:335
Adjust points while anchor anchor is placed or dragged, e.g. to keep a channel parallel. Return the full point list.
Parameters
points
anchor
number
Returns
cursor()?
optionalcursor(d,part,p,env):string|undefined
Defined in: packages/core/src/drawing/types.ts:383
CSS cursor while the pointer is over part of the drawing (p in pane-local css px), e.g. 'ns-resize' for a part that only moves up and down. Return nothing for the default: 'move' on anchors and handles, 'pointer' on the drawing. Not asked while the drawing or all drawings are locked, or during a drag.
Parameters
d
part
p
env
Returns
string | undefined
handles()?
optionalhandles(d,env):Point[]
Defined in: packages/core/src/drawing/types.ts:337
Draggable handles that are not anchors, in pane-local css px.
Parameters
d
env
Returns
Point[]
hitTest()
hitTest(
d,p,env):boolean
Defined in: packages/core/src/drawing/types.ts:393
Parameters
d
p
env
Returns
boolean
modelBounds()?
optionalmodelBounds(drawing):DrawingModelBounds
Defined in: packages/core/src/drawing/types.ts:368
Time and price box the drawing covers, for tools whose points do not describe it: lines that reach the pane edge, levels past the anchors. Infinite values leave a side open. The chart neither draws nor hit-tests a drawing whose box is well out of view, so a box that is too small makes the drawing vanish near the edges. Default: the box of the points, open on the sides extendLeft and extendRight extend; a tool with bounds and no modelBounds is checked by its projected anchors and bounds.
Parameters
drawing
Returns
moveHandle()?
optionalmoveHandle(drawing,index,to,at,env):DrawingPoint[] | {points?:DrawingPoint[];style?:DrawingStyle; }
Defined in: packages/core/src/drawing/types.ts:346
The drawing after dragging handle index to to (time and price, snapped like an anchor) or at (the pointer, unsnapped, in pane-local css px; env projects the drawing's points to compare): its new points, or { points, style } with either left out to keep it, e.g. a size or angle in the style. drawing is a copy. Required for handles to be draggable.
Parameters
drawing
index
number
to
at
env
Returns
DrawingPoint[] | { points?: DrawingPoint[]; style?: DrawingStyle; }
pasteImage()?
optionalpasteImage(file):Promise<{height:number;text:string;width:number; } |null>
Defined in: packages/core/src/drawing/types.ts:391
Take an image file pasted on the chart: the reference to keep in the new drawing's text, and the image's size in pixels, which the drawing's box gets (shrunk to fit half the pane); null declines the file. A paste goes to the first registered tool that has this, as a two-point drawing centred on the crosshair.
Parameters
file
Blob
Returns
Promise<{ height: number; text: string; width: number; } | null>
render()
render(
ctx,d,env):void
Defined in: packages/core/src/drawing/types.ts:392
Parameters
ctx
CanvasRenderingContext2D
d
env
Returns
void