DrawingControl – amCharts 5 Documentation

Type class

A StockToolbar control that turns drawing mode on, with a row of controls for picking the tool and its colors, lines and fonts.

Click here for more info

Sources

DrawingControl can be used (imported) via one of the following packages.

// Import DrawingControl
import * as am5stock from "@amcharts/amcharts5/stock";

// Create DrawingControl
am5stock.DrawingControl.new(root, {
  // ... config if applicable
});

<!-- Load DrawingControl -->
<script src="stock.js"></script>

<script>
// Create DrawingControl
am5stock.DrawingControl.new(root, {
  // ... config if applicable
});
</script>

Inheritance

DrawingControl extends StockControl.

DrawingControl is not extended by any other symbol.

Settings

Set these settings on a DrawingControl object using its set() and setAll() methods.

Read about settings concept.

active #	Type `undefined` \| `false` \| `true` Default `false` Inherited from `IStockControlSettings` Turns the control on; its button shows as active.
align #	Type `"left"` \| `"right"` Default `"left"` Inherited from `IStockControlSettings` Side of the toolbar the control is placed on.
animations #	Type `Array` Inherited from `IEntitySettings` Animations the element plays on its own, described as data - so they can be set from a JSON config and saved with it. Each one animates a setting of the element (or, with `target: "dataItem"`, a value of its data item - a map point's `positionOnLine`, say). They start when the setting is applied, restart when it changes, and stop when the element is disposed. A saved config keeps what was configured, never a value caught half way through an animation. sprite.set("animations", [ { key: "rotation", to: 360, duration: 4000, loops: 0 }, { key: "scale", from: 1, to: 1.3, duration: 800, loops: 0, yoyo: true, easing: "sine" } ]); @since 5.20.8
colors #	Type `ColorSet` Colors to offer in the color pickers. Click here for more info
description #	Type `undefined` \| `string` Inherited from `IStockControlSettings` What the control does, shown as the button's tooltip. Falls back to `name`.
drawingIcon #	Type `IIcon` Icon that the icon tool draws.
drawingIcons #	Type `IIcon[]` Icons to choose from for the icon tool.
fillColor #	Type `Color` Fill color of new drawings.
fillOpacity #	Type `undefined` \| `number` Fill opacity of new drawings, from `0` to `1`.
forceHidden #	Type `undefined` \| `false` \| `true` Default `false` Inherited from `IStockControlSettings` Keeps the control hidden, even when `show()` is called. @since 5.8.5
icon #	Type `HTMLElement` \| `SVGElement` \| `"none"` Inherited from `IStockControlSettings` Icon element of the button, or `"none"` for no icon. Each control has its own default icon.
id #	Type `undefined` \| `string` Inherited from `IEntitySettings` A unique ID for looking the element up in `root.entitiesById`. Setting an ID that another element already has throws an error.
ignoreThemes #	Type `undefined` \| `false` \| `true` Default `false` Inherited from `IEntitySettings` Ignores themes: no theme rule applies to the element, not even one of the default theme. @since 5.15.6
labelFill #	Type `Color` Text color of new labels and callouts.
labelFontFamilies #	Type `string[]` Font families to choose from.
labelFontFamily #	Type `undefined` \| `string` Font family of new labels and callouts. `"inherit"` uses the computed font of the chart's container (since `5.17.3`).
labelFontSize #	Type `number` \| `string` \| `undefined` Font size of new labels and callouts.
labelFontSizes #	Type `Array` Font sizes to choose from.
labelFontStyle #	Type `"normal"` \| `"italic"` \| `"oblique"` Font style of new labels and callouts.
labelFontWeight #	Type `"normal"` \| `"bold"` \| `"bolder"` \| `"lighter"` \| `"100"` \| `"200"` \| `"300"` \| `"400"` \| `"500"` \| `"600"` \| `"700"` \| `"800"` \| `"900"` Font weight of new labels and callouts.
name #	Type `undefined` \| `string` Inherited from `IStockControlSettings` Label text of the control's button.
scrollable #	Type `undefined` \| `false` \| `true` Limits the tool list's height to the chart's height minus 100 pixels, scrolling the rest. @since 5.9.5
series #	Type `XYSeries[]` Series to attach drawings to. Each panel's main series (`stockSeries` on its panel, the first series on others) is added automatically.
showExtension #	Type `undefined` \| `false` \| `true` Default `true` Extends new lines with a dotted line beyond both ends.
snapToData #	Type `undefined` \| `false` \| `true` Default `false` Snaps the points of new drawings to the values of the nearest data items.
stateAnimationDuration #	Type `undefined` \| `number` Default `0` Inherited from `IEntitySettings` How long, in milliseconds, a switch from one state to another animates. `0` switches at once.
stateAnimationEasing #	Type `$ease.Easing` Default `out(cubic)` Inherited from `IEntitySettings` Easing of the animated switch from one state to another.
stockChart #	Type `StockChart` Inherited from `IStockControlSettings` The `StockChart` the control acts on.
strokeColor #	Type `Color` Line color of new drawings; changing it also restyles the selected ones.
strokeDasharray #	Type `number[]` Dash pattern of new drawings' lines, such as `[2, 2]`, or `[]` for a solid line.
strokeDasharrays #	Type `number[]` Dash patterns to choose from.
strokeOpacity #	Type `undefined` \| `number` Line opacity of new drawings, from `0` to `1`.
strokeWidth #	Type `undefined` \| `number` Line width of new drawings, in pixels.
strokeWidths #	Type `number[]` Line widths to choose from, in pixels.
themeTags #	Type `Array` Inherited from `IEntitySettings` Tags that theme rules can target. They also count for the element's children, so a rule can match a child by a tag of its parent. Click here for more info
themeTagsSelf #	Type `Array` Inherited from `IEntitySettings` Tags that theme rules can target, like `themeTags`, but only for this element, not its children. Click here for more info
themes #	Type `Array` Inherited from `IEntitySettings` Themes applied to the element and everything inside it.
togglable #	Type `undefined` \| `false` \| `true` Default `true` Inherited from `IStockControlSettings` A click on the button toggles `active`.
tool #	Type `DrawingTools` Default `"Line"` The tool in use; the one set at the start is the default.
toolSettings #	Type `undefined` \| `object` Settings for the drawing series of each tool, keyed by tool name. @since 5.5.2 Click here for more info
tools #	Type `DrawingTools[]` Tools to list in the tool dropdown. Click here for more info
userData #	Type `any` Inherited from `IEntitySettings` Any data of your own to keep with the element.
visible #	Type `undefined` \| `false` \| `true` Default `true` Inherited from `IStockControlSettings` Shows the control's button; `false` hides it.
There are 18 inherited items currently hidden from this list.

Private settings

These are read-only settings accessible from a DrawingControl object using its getPrivate() method.

Read about private settings.

boldControl #	Read only Type `StockControl`
button #	Read only Type `HTMLDivElement` Inherited from `IStockControlPrivate`
clearControl #	Read only Type `StockControl`
eraserControl #	Read only Type `StockControl`
extensionControl #	Read only Type `StockControl`
fillControl #	Read only Type `ColorControl`
icon #	Read only Type `HTMLElement` Inherited from `IStockControlPrivate`
iconControl #	Read only Type `IconControl`
italicControl #	Read only Type `StockControl`
label #	Read only Type `HTMLDivElement` Inherited from `IStockControlPrivate`
labelFillControl #	Read only Type `ColorControl`
labelFontFamilyControl #	Read only Type `DropdownListControl`
labelFontSizeControl #	Read only Type `DropdownListControl`
selectControl #	Read only Type `StockControl` The control that turns drawing selection on and off. @since 5.9.1
snapControl #	Read only Type `StockControl`
strokeControl #	Read only Type `ColorControl`
strokeDasharrayControl #	Read only Type `DropdownListControl`
strokeWidthControl #	Read only Type `DropdownListControl`
toolControl #	Read only Type `DrawingToolControl`
toolTemplates #	Read only Type `undefined` \| `object`
toolbar #	Read only Type `StockToolbar` Inherited from `IStockControlPrivate`
toolsContainer #	Read only Type `HTMLDivElement`
There are 4 inherited items currently hidden from this list.

Properties

adapters #	Type `Adapters` Default `new Adapters(this)` Inherited from `Entity`
className #	Static Type `string` Default `"DrawingControl"`
classNames #	Static Type `Array` Default `"DrawingControl", "StockControl", "Entity"`
drawingSeries #	Type `object` The drawing series of each tool, keyed by tool name. @since 5.8.0 @readonly
enableDispose #	Type `boolean` Default `true` Inherited from `Settings` Set to `false` to make `dispose()` do nothing.
events #	Type `EventDispatcher` Default `this._createEvents()` Inherited from `Entity`
root #	Type `Root` Inherited from `Entity` The `Root` the object belongs to. @readonly @since 5.0.6
states #	Type `States` Default `new States(this)` Inherited from `Entity`
template #	Type `Template` \| `undefined` Inherited from `Entity` A `Template` applied to the object. Its settings apply where the object has none set of its own.
uid #	Type `number` Default `++counter` Inherited from `Settings` A unique number, given to each object as it is created.
There are 7 inherited items currently hidden from this list.

Methods

addLine( tool: `"Horizontal Line"` \| `"Horizontal Ray"` \| `"Vertical Line"`, panel: `StockPanel`, point: `IPoint` ) #	Returns `void` Adds a horizontal line, horizontal ray or vertical line drawing through a point, without the pointer. @since 5.10.2
animate( options: `AnimationOptions` ) #	Returns `Animation` Inherited from `Settings` Animates a setting from its current value (or `from`) to `to`. The setting jumps to `from` at once. With `duration` `0`, or no value to start from, it is set to `to` at once and the returned animation is already stopped. Click here for more info
clearDrawings() #	Returns `void` Deletes all drawings made with the control's tools. @since 5.3.9
dispose() #	Returns `void` Inherited from `Settings` Disposes the object, freeing everything it holds. A disposed object can't be used again.
get( key: `Key`, fallback: `F` ) #	Returns `NonNullable` \| `F` Inherited from `Entity` Returns the value of setting `key`, run through any adapters, or `fallback` if it is not set. Click here for more info
has( key: `Key` ) #	Returns `boolean` Inherited from `Settings` Returns `true` if setting `key` is set. Click here for more info
hide() #	Returns `void` Inherited from `StockControl` Hides the control's button.
isAccessible() #	Returns `boolean` Inherited from `StockControl`
isDisposed() #	Returns `boolean` Inherited from `Settings` Returns `true` if the object has been disposed.
isType( type: `string` ) #	Returns `this` Inherited from `Entity` Returns `true` if the object is of class `type` or extends it.
new( root: `Root`, settings: `ITSettings`, template?: `Template` ) #	Static Returns `T` Inherited from `Entity` Creates an instance of the class. Use it instead of `new Class()`. Click here for more info
off( key: `Key`, callback?: `undefined` \| ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `void` Inherited from `Settings` Removes a callback added with `on()`. Without `callback`, removes all of them for `key`. Click here for more info @since 5.9.2
offDebounced( key: `Key`, callback?: `undefined` \| ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `void` Inherited from `Settings` Removes a callback added with `onDebounced()`. Without `callback`, removes all of them for `key`. Click here for more info
offDebouncedPrivate( key: `Key`, callback?: `undefined` \| ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `void` Inherited from `Settings` Removes a callback added with `onPrivateDebounced()`. Without `callback`, removes all of them for `key`. Click here for more info
offPrivate( key: `Key`, callback?: `undefined` \| ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `void` Inherited from `Settings` Removes a callback added with `onPrivate()`. Without `callback`, removes all of them for `key`. Click here for more info @since 5.9.2
on( key: `Key`, callback: ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `IDisposer` Inherited from `Settings` Calls `callback` each time the value of setting `key` changes or is removed. Setting the same value again does not call it. Click here for more info
onDebounced( key: `Key`, callback: ( value: `[""]`, target: `this`, key: `Key`) => `void`, debounceDelay: `number` ) #	Returns `IDisposer` Inherited from `Settings` Like `on()`, but waits until setting `key` has not changed for `debounceDelay` milliseconds, then calls `callback` once with the latest value. Click here for more info
onPrivate( key: `Key`, callback: ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `IDisposer` Inherited from `Settings` Calls `callback` each time the value of private setting `key` changes. Click here for more info
onPrivateDebounced( key: `Key`, callback: ( value: `[""]`, target: `this`, key: `Key`) => `void`, debounceDelay: `number` ) #	Returns `IDisposer` Inherited from `Settings` Like `onPrivate()`, but waits until private setting `key` has not changed for `debounceDelay` milliseconds, then calls `callback` once with the latest value. Click here for more info
once( key: `Key`, callback: ( value: `[""]`, target: `this`, key: `Key`) => `void` ) #	Returns `IDisposer` Inherited from `Settings` Like `on()`, but the callback is removed after it is called once. Click here for more info @since 5.20.4
onceDebounced( key: `Key`, callback: ( value: `[""]`, target: `this`, key: `Key`) => `void`, debounceDelay: `number` ) #	Returns `IDisposer` Inherited from `Settings` Like `onDebounced()`, but the callback is removed after it is called once. Click here for more info @since 5.20.4
remove( key: `Key` ) #	Returns `void` Inherited from `Entity` Removes the value set for setting `key`. The setting goes back to the value from a theme or template, if one has it. Click here for more info
removeAll() #	Returns `void` Inherited from `Settings` Removes all settings, as `remove()` does for each one. Click here for more info
serializeDrawings( output: `"object"` \| `"string"`, indent?: `undefined` \| `string` ) #	Returns `Array` \| `string` Serializes all drawings of the chart into an array of objects (`output: "object"`) or into JSON (`"string"`, the default). Click here for more info @since 5.3.0
set( key: `Key`, value: `Value` ) #	Returns `Value` Inherited from `Entity` Sets setting `key` to `value` and returns `value`. A value set this way overrides themes and templates, and stops any animation of the setting. Click here for more info
setAll( settings: `Partial` ) #	Returns `void` Inherited from `Settings` Sets several settings at once, from an object of key-value pairs. Click here for more info
setEraser( active: `boolean` ) #	Returns `void` Turns erasing on or off: while on, a click on a drawing deletes it. @since 5.3.9
setTimeout( fn: () => `void`, delay: `number` ) #	Returns `IDisposer` Inherited from `Entity` Calls `fn` after `delay` milliseconds, unless the object is disposed first. Disposing the returned disposer cancels it.
show() #	Returns `void` Inherited from `StockControl` Shows the control's button, unless `forceHidden` is set.
unserializeDrawings( data: `string` \| `Array` ) #	Returns `void` Adds drawings to the chart from data made by `serializeDrawings()`. Click here for more info @since 5.3.0
There are 25 inherited items currently hidden from this list.

addLine(

tool: "Horizontal Line" | "Horizontal Ray" | "Vertical Line",
panel: StockPanel,
point: IPoint

)

Returns void

Adds a horizontal line, horizontal ray or vertical line drawing through a point, without the pointer.

@since 5.10.2

animate(

options: AnimationOptions

)

Returns Animation

Inherited from Settings

Animates a setting from its current value (or from) to to. The setting jumps to from at once. With duration 0, or no value to start from, it is set to to at once and the returned animation is already stopped.

Click here for more info

clearDrawings()

Returns void

Deletes all drawings made with the control's tools.

@since 5.3.9

dispose()

Returns void

Inherited from Settings

Disposes the object, freeing everything it holds. A disposed object can't be used again.

get(

key: Key,
fallback: F

)

Returns NonNullable | F

Inherited from Entity

Returns the value of setting key, run through any adapters, or fallback if it is not set.

Click here for more info

has(

key: Key

)

Returns boolean

Inherited from Settings

Returns true if setting key is set.

Click here for more info

hide()

Returns void

Inherited from StockControl

Hides the control's button.

isAccessible()

Returns boolean

Inherited from StockControl

isDisposed()

Returns boolean

Inherited from Settings

Returns true if the object has been disposed.

isType(

type: string

)

Returns this

Inherited from Entity

Returns true if the object is of class type or extends it.

new(

root: Root,
settings: ITSettings,
template?: Template

)

Static

Returns T

Inherited from Entity

Creates an instance of the class. Use it instead of new Class().

Click here for more info

off(

key: Key,
callback?: undefined | ( value: [""], target: this, key: Key) => void

)

Returns void

Inherited from Settings

Removes a callback added with on(). Without callback, removes all of them for key.

Click here for more info
@since 5.9.2

offDebounced(

key: Key,
callback?: undefined | ( value: [""], target: this, key: Key) => void

)

Returns void

Inherited from Settings

Removes a callback added with onDebounced(). Without callback, removes all of them for key.

Click here for more info

offDebouncedPrivate(

key: Key,
callback?: undefined | ( value: [""], target: this, key: Key) => void

)

Returns void

Inherited from Settings

Removes a callback added with onPrivateDebounced(). Without callback, removes all of them for key.

Click here for more info

offPrivate(

key: Key,
callback?: undefined | ( value: [""], target: this, key: Key) => void

)

Returns void

Inherited from Settings

Removes a callback added with onPrivate(). Without callback, removes all of them for key.

Click here for more info
@since 5.9.2

on(

key: Key,
callback: ( value: [""], target: this, key: Key) => void

)

Returns IDisposer

Inherited from Settings

Calls callback each time the value of setting key changes or is removed. Setting the same value again does not call it.

Click here for more info

onDebounced(

key: Key,
callback: ( value: [""], target: this, key: Key) => void,
debounceDelay: number

)

Returns IDisposer

Inherited from Settings

Like on(), but waits until setting key has not changed for debounceDelay milliseconds, then calls callback once with the latest value.

Click here for more info

onPrivate(

key: Key,
callback: ( value: [""], target: this, key: Key) => void

)

Returns IDisposer

Inherited from Settings

Calls callback each time the value of private setting key changes.

Click here for more info

onPrivateDebounced(

key: Key,
callback: ( value: [""], target: this, key: Key) => void,
debounceDelay: number

)

Returns IDisposer

Inherited from Settings

Like onPrivate(), but waits until private setting key has not changed for debounceDelay milliseconds, then calls callback once with the latest value.

Click here for more info

once(

key: Key,
callback: ( value: [""], target: this, key: Key) => void

)

Returns IDisposer

Inherited from Settings

Like on(), but the callback is removed after it is called once.

Click here for more info
@since 5.20.4

onceDebounced(

key: Key,
callback: ( value: [""], target: this, key: Key) => void,
debounceDelay: number

)

Returns IDisposer

Inherited from Settings

Like onDebounced(), but the callback is removed after it is called once.

Click here for more info
@since 5.20.4

remove(

key: Key

)

Returns void

Inherited from Entity

Removes the value set for setting key. The setting goes back to the value from a theme or template, if one has it.

Click here for more info

removeAll()

Returns void

Inherited from Settings

Removes all settings, as remove() does for each one.

Click here for more info

serializeDrawings(

output: "object" | "string",
indent?: undefined | string

)

Returns Array | string

Serializes all drawings of the chart into an array of objects (output: "object") or into JSON ("string", the default).

Click here for more info
@since 5.3.0

set(

key: Key,
value: Value

)

Returns Value

Inherited from Entity

Sets setting key to value and returns value. A value set this way overrides themes and templates, and stops any animation of the setting.

Click here for more info

setAll(

settings: Partial

)

Returns void

Inherited from Settings

Sets several settings at once, from an object of key-value pairs.

Click here for more info

setEraser(

active: boolean

)

Returns void

Turns erasing on or off: while on, a click on a drawing deletes it.

@since 5.3.9

setTimeout(

fn: () => void,
delay: number

)

Returns IDisposer

Inherited from Entity

Calls fn after delay milliseconds, unless the object is disposed first. Disposing the returned disposer cancels it.

show()

Returns void

Inherited from StockControl

Shows the control's button, unless forceHidden is set.

unserializeDrawings(

data: string | Array

)

Returns void

Adds drawings to the chart from data made by serializeDrawings().

Click here for more info
@since 5.3.0

There are 25 inherited items currently hidden from this list.

Events

Add event handlers to DrawingControl object using its events.on() method.

Read about adding event handlers.

#click	Param { originalEvent: `IPointerEvent`, type: `"click"`, target: `this` } Inherited from `IStockControlEvents` The control's button was clicked.
There is 1 inherited item currently hidden from this list.

#click

Param { originalEvent: IPointerEvent,
type: "click",
target: this }

Inherited from IStockControlEvents

The control's button was clicked.

There is 1 inherited item currently hidden from this list.