Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo

Drawings

API reference for per-symbol drawing persistence, drawing menus, the radial tool wheel, and tooltip cards.

View as Markdown

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'>,
): () => void

See also: EnableDrawingMenusOptions.

defaultSymbolDrawingsChartKey

The default chart name: the shell's container id and the cell id.

function defaultSymbolDrawingsChartKey(chart: { cellId: string; host: HTMLElement }): string

drawingToolDescription

function drawingToolDescription(name: string): string | null

labelPosition

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 | null

Default: offsetDeg = 0.

radialWheelAttachment

Build the radial-wheel attachment (registered by enableRadialWheel).

function radialWheelAttachment(opts?: RadialWheelOptions): WidgetAttachment

See 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): () => void

registerTooltipCard

Add or replace the card for a control, by the name its tooltip shows. Returns the removal.

function registerTooltipCard(title: string, card: TooltipCard): () => void

See 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): string

Default: 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): string

tooltipCardFor

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 } | null

See 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;
}
MemberTypeDescription
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 | nullThe document saved for key, or null when there is none.
save()(key: SymbolDrawingsKey, doc: SavedDrawings | null) => voidKeep 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;
}
MemberTypeDescription
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).
activeboolean
setTriggerLabel()(label: string) => voidLabel of the trigger key shown in the hub (e.g. 'ALT').
setHubAction()(action: RadialHubAction | null) => voidWhat 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) => booleanA 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) => voidReplace 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) => booleanOpen 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) => voidAim the wheel from a pointer position (client coords).
close()(commit?: boolean) => voidClose; 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;
}
MemberTypeDescription
hintstringHub hint while nothing is aimed, e.g. 'Click for timeframes'.
labelstringAccessible 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;
}
MemberTypeDescription
menuLabel?stringAccessible name of the menu. Default 'Drawing tools'.
idle?stringHub title while nothing is aimed. Default 'Move to choose'.
aimHint?stringHub 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;
}
MemberTypeDescription
typestring
labelstring
icon?stringInline 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?booleanThe 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[];
}
MemberTypeDescription
triggerKey?stringTrigger key (KeyboardEvent.key). Default 'Alt'.
holdMs?numberHold 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;
}
MemberTypeDescription
flush()() => voidWrite what is waiting to be saved, now.
dispose()() => voidFlush, stop following the chart, and give it back its own setting.

SymbolDrawingsBindingOptions

interface SymbolDrawingsBindingOptions {
    symbolKey?: (symbol: string) => string;
    delayMs?: number;
}
MemberTypeDescription
symbolKey?(symbol: string) => stringThe name a symbol is saved under. Default: symbolDrawingsName.
delayMs?numberHow 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;
}
MemberTypeDescription
chartstringThe chart's name: see chartKey in the enabler's options.
symbolstring

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>;
}
MemberTypeDescription
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;
}
MemberTypeDescription
descriptionstringOne line on what the control does.
shortcut?stringIts keyboard shortcut, +-joined (Mod reads ⌘ on a Mac, Ctrl elsewhere).

Constants

DEFAULT_SYMBOL_DRAWINGS_KEY

const DEFAULT_SYMBOL_DRAWINGS_KEY: 'vela-pro.drawings';

On this page