Drawings
API reference for per-symbol drawing persistence, drawing menus, the radial tool wheel, and tooltip cards.
This page documents per-symbol drawing persistence and its storage port, enhanced drawing context menus, the radial tool wheel, and rich chart tooltip cards.
Import symbols on this page from @luxalgo/vela-pro. Related guides: Drawing tools, Drawing persistence.
Feature enablers for this area (enableDrawingMenus, enableRadialWheel, enableRichTooltips, enableSymbolDrawings) are documented on Enablers and options.
Functions
bindSymbolDrawings
Keep chart's drawings per symbol in storage. chartKey names the chart there: a string, or a function read at EVERY save and load, for a host that shows several documents on one chart (tabs, layouts) and wants each to keep its own drawings. Returns the binding; dispose it when the chart leaves the page.
function bindSymbolDrawings(
chart: Chart,
chartKey: string | (() => string),
storage: SymbolDrawingsStorage,
opts?: SymbolDrawingsBindingOptions,
): SymbolDrawingsBinding
// Unexported supporting type referenced above
type Chart = WidgetContext['chart'];See also: SymbolDrawingsBinding, SymbolDrawingsBindingOptions, SymbolDrawingsStorage. From @luxalgo/vela/plugin: WidgetContext.
decorateDrawingMenu
Pro's treatment of one drawing menu. Returns its cleanup.
function decorateDrawingMenu(
menu: HTMLElement,
host: HTMLElement,
opts?: Pick<EnableDrawingMenusOptions, 'searchFrom' | 'cards'>,
): () => voidSee also: EnableDrawingMenusOptions.
defaultSymbolDrawingsChartKey
The default chart name: the shell's container id and the cell id.
function defaultSymbolDrawingsChartKey(chart: { cellId: string; host: HTMLElement }): stringdrawingToolDescription
function drawingToolDescription(name: string): string | nulllabelPosition
Design-space label position for segment index of count (ring rotated by offsetDeg).
function labelPosition(
index: number,
count: number,
offsetDeg?: number,
): { xPct: number; yPct: number }Default: offsetDeg = 0.
radialToolIndex
Resolve a vector into a clockwise radial segment. Segment zero is centred at 12 o'clock plus offsetDeg (the whole ring may be rotated so a pinned entry lands on an exact compass point); the centre dead zone returns null so tapping the trigger never changes tools accidentally.
function radialToolIndex(
dx: number,
dy: number,
deadZone: number,
count: number,
offsetDeg?: number,
): number | nullDefault: offsetDeg = 0.
radialWheelAttachment
Build the radial-wheel attachment (registered by enableRadialWheel).
function radialWheelAttachment(opts?: RadialWheelOptions): WidgetAttachmentSee also: RadialWheelOptions. From @luxalgo/vela/plugin: WidgetAttachment.
registerDrawingToolDescription
Add or replace a tool's description, by the name the toolbar shows. Returns the removal.
function registerDrawingToolDescription(name: string, description: string): () => voidregisterTooltipCard
Add or replace the card for a control, by the name its tooltip shows. Returns the removal.
function registerTooltipCard(title: string, card: TooltipCard): () => voidSee also: TooltipCard.
resolveTimeframes
Resolve timeframe values into wheel entries: one per distinct timeframe, labelled compactly (60 → 1h), the one matching current marked. Spellings of the same duration (60 and 1h) count as one, the first kept.
function resolveTimeframes(
values: readonly string[],
current: string,
label?: (value: string) => string,
max?: number,
): RadialTool[]Defaults: label = (value) => timeframeLabel(value), max = MAX_SEGMENTS.
See also: RadialTool.
resolveTools
Resolve type keys into wheel entries, dropping unregistered types. A non-empty wheel always carries the pinned Cursor entry at the bottom segment: favorites hold only drawing types, so without the pin the way back to select/idle would vanish the moment the user starred anything.
function resolveTools(types: readonly string[], max?: number): RadialTool[]Default: max = MAX_SEGMENTS.
See also: RadialTool.
sectorPath
The d attribute of segment index of count: an annular wedge centred on its direction (ring rotated by offsetDeg).
function sectorPath(index: number, count: number, offsetDeg?: number): stringDefault: offsetDeg = 0.
shortcutKeys
A shortcut's keys as the platform names them.
function shortcutKeys(shortcut: string, mac: boolean): string[]symbolDrawingsName
The name a symbol is saved under by default: its ticker, without the venue in front. A chart reads the same market as BTCUSDT (as its host wrote it) or as binance:BTCUSDT (as a saved state restores it), and which venue serves a bare symbol can differ from one page load to the next, so the venue cannot be part of the name. The cost: the same ticker on two venues shares its drawings.
function symbolDrawingsName(symbol: string): stringtooltipCardFor
The card for a tooltip's text: an exact name, or a name followed by its value (Timeframe — 1h).
function tooltipCardFor(text: string): { title: string; card: TooltipCard } | nullSee also: TooltipCard.
Classes
LocalSymbolDrawingsStorage
The browser's localStorage: one entry per chart and symbol, under prefix.
class LocalSymbolDrawingsStorage implements SymbolDrawingsStorage {
constructor(prefix?: string, store?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null);
load(key: SymbolDrawingsKey): SavedDrawings | null;
save(key: SymbolDrawingsKey, doc: SavedDrawings | null): void;
}| Member | Type | Description |
|---|---|---|
constructor | (prefix?: string, store?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null) | store: The store to write to; the page's localStorage when left out. Defaults: prefix = DEFAULT_SYMBOL_DRAWINGS_KEY, store = pageStorage(). |
load() | (key: SymbolDrawingsKey) => SavedDrawings | null | The document saved for key, or null when there is none. |
save() | (key: SymbolDrawingsKey, doc: SavedDrawings | null) => void | Keep doc for key; null when the chart has no drawing left on that symbol. |
See also: SavedDrawings, SymbolDrawingsKey, SymbolDrawingsStorage.
RadialToolWheel
class RadialToolWheel {
constructor(host: HTMLElement, onSelect: (type: string) => void);
readonly active: boolean;
setTriggerLabel(label: string): void;
setHubAction(action: RadialHubAction | null): void;
pressHub(clientX: number, clientY: number): boolean;
setTools(tools: readonly RadialTool[], rotationDeg?: number, text?: RadialRingText): void;
open(pointer?: { x: number; y: number } | null): boolean;
move(clientX: number, clientY: number): void;
close(commit?: boolean): void;
destroy(): void;
}| Member | Type | Description |
|---|---|---|
constructor | (host: HTMLElement, onSelect: (type: string) => void) | host: the widget root (themed): the wheel is positioned fixed, but living inside the themed host keeps its CSS custom properties resolvable. onSelect: committed tool type (never called on a dead-zone release). |
active | boolean | |
setTriggerLabel() | (label: string) => void | Label of the trigger key shown in the hub (e.g. 'ALT'). |
setHubAction() | (action: RadialHubAction | null) => void | What a click on the hub does (null: nothing, the hub is a pure cancel zone). Shown as the hub's hint while nothing is aimed. |
pressHub() | (clientX: number, clientY: number) => boolean | A primary press at client coords while the wheel is up: inside the hub (the dead zone) it runs the hub action. Returns whether it did: the caller swallows every press while the wheel is up either way. |
setTools() | (tools: readonly RadialTool[], rotationDeg?: number, text?: RadialRingText) => void | Replace the wheel's tools: rebuilds the ring (segment count is data-driven). rotationDeg rotates the whole ring clockwise so a pinned entry can sit on an exact compass point regardless of the segment count; text words the hub for this ring. Swapping rings while the wheel is up fades the new entries in. Default: rotationDeg = 0. |
open() | (pointer?: { x: number; y: number } | null) => boolean | Open the wheel centred on the host. Starts with no segment aimed so a resting pointer away from the centre never pre-selects a tool; pointer only lights up the hub when it already sits inside the dead zone. Default: pointer = null. |
move() | (clientX: number, clientY: number) => void | Aim the wheel from a pointer position (client coords). |
close() | (commit?: boolean) => void | Close; commit arms the aimed tool (a dead-zone release always cancels). Default: commit = false. |
destroy() | () => void |
See also: RadialHubAction, RadialRingText, RadialTool.
Interfaces and types
RadialHubAction
What a click on the hub does. While nothing is aimed the hub shows hint in place of "Release to cancel", so the action is discoverable the moment the wheel opens.
interface RadialHubAction {
hint: string;
label: string;
run(): void;
}| Member | Type | Description |
|---|---|---|
hint | string | Hub hint while nothing is aimed, e.g. 'Click for timeframes'. |
label | string | Accessible name of the action, e.g. 'Show timeframes'. |
run() | () => void |
RadialRingText
The hub's words for one ring: each falls back to the drawing-tool wording.
interface RadialRingText {
menuLabel?: string;
idle?: string;
aimHint?: string;
}| Member | Type | Description |
|---|---|---|
menuLabel? | string | Accessible name of the menu. Default 'Drawing tools'. |
idle? | string | Hub title while nothing is aimed. Default 'Move to choose'. |
aimHint? | string | Hub hint while an entry is aimed. Default 'Release to arm'. |
RadialTool
One entry of the wheel.
interface RadialTool {
type: string;
label: string;
icon?: string;
current?: boolean;
}| Member | Type | Description |
|---|---|---|
type | string | |
label | string | |
icon? | string | Inline SVG markup (from the drawing-type registry). Omitted or empty for a TEXT entry (a timeframe such as 15m), whose label is drawn large in its place. |
current? | boolean | The entry already in effect (the chart's current timeframe): marked with a dot. |
RadialWheelOptions
interface RadialWheelOptions {
triggerKey?: string;
holdMs?: number;
fallbackTools?: readonly string[];
timeframes?: readonly string[];
}| Member | Type | Description |
|---|---|---|
triggerKey? | string | Trigger key (KeyboardEvent.key). Default 'Alt'. |
holdMs? | number | Hold duration (ms) before the wheel appears. Default 200. |
fallbackTools? | readonly string[] | Tool types when the user has no favorites yet. Default: a 9-tool starter set. The Cursor (select/idle) entry is always pinned into the wheel on top of this list. Pass [] to keep the wheel closed until the user stars something. |
timeframes? | readonly string[] | The timeframe ring a click on the hub swaps in (aim, release to switch the active chart's timeframe), clockwise from 12 o'clock. Default: 1m, 5m, 15m, 30m, 1h, 4h, 1D, 1W, 1M. Pass [] to keep the hub a pure cancel zone. |
SavedDrawings
A chart's drawings as Vela serializes them (chart.drawings.toJSON()).
type SavedDrawings = ReturnType<WidgetContext['chart']['drawings']['toJSON']>;From @luxalgo/vela/plugin: WidgetContext.
SymbolDrawingsBinding
interface SymbolDrawingsBinding {
flush(): void;
dispose(): void;
}| Member | Type | Description |
|---|---|---|
flush() | () => void | Write what is waiting to be saved, now. |
dispose() | () => void | Flush, stop following the chart, and give it back its own setting. |
SymbolDrawingsBindingOptions
interface SymbolDrawingsBindingOptions {
symbolKey?: (symbol: string) => string;
delayMs?: number;
}| Member | Type | Description |
|---|---|---|
symbolKey? | (symbol: string) => string | The name a symbol is saved under. Default: symbolDrawingsName. |
delayMs? | number | How long a change waits before it is written, in milliseconds. |
SymbolDrawingsKey
Whose drawings: one chart of the page, on one symbol.
interface SymbolDrawingsKey {
chart: string;
symbol: string;
}| Member | Type | Description |
|---|---|---|
chart | string | The chart's name: see chartKey in the enabler's options. |
symbol | string |
SymbolDrawingsStorage
Keeps one drawings document per chart and symbol. Both methods may answer later.
interface SymbolDrawingsStorage {
load(key: SymbolDrawingsKey): SavedDrawings | null | Promise<SavedDrawings | null>;
save(key: SymbolDrawingsKey, doc: SavedDrawings | null): void | Promise<void>;
}| Member | Type | Description |
|---|---|---|
load() | (key: SymbolDrawingsKey) => SavedDrawings | null | Promise<SavedDrawings | null> | The document saved for key, or null when there is none. |
save() | (key: SymbolDrawingsKey, doc: SavedDrawings | null) => void | Promise<void> | Keep doc for key; null when the chart has no drawing left on that symbol. |
See also: SavedDrawings, SymbolDrawingsKey.
TooltipCard
interface TooltipCard {
description: string;
shortcut?: string;
}| Member | Type | Description |
|---|---|---|
description | string | One line on what the control does. |
shortcut? | string | Its keyboard shortcut, +-joined (Mod reads ⌘ on a Mac, Ctrl elsewhere). |
Constants
DEFAULT_SYMBOL_DRAWINGS_KEY
const DEFAULT_SYMBOL_DRAWINGS_KEY: 'vela-pro.drawings';