# Drawings (/vela-pro/api/drawings)



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](/vela-pro/charts/drawings/tools), [Drawing persistence](/vela-pro/persistence/stores/drawings).

Feature enablers for this area ([`enableDrawingMenus`](/vela-pro/api/enablers#enabledrawingmenus), [`enableRadialWheel`](/vela-pro/api/enablers#enableradialwheel), [`enableRichTooltips`](/vela-pro/api/enablers#enablerichtooltips), [`enableSymbolDrawings`](/vela-pro/api/enablers#enablesymboldrawings)) are documented on [Enablers and options](/vela-pro/api/enablers).

## Functions [#functions]

### `bindSymbolDrawings` [#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.

```typescript
function bindSymbolDrawings(
    chart: Chart,
    chartKey: string | (() => string),
    storage: SymbolDrawingsStorage,
    opts?: SymbolDrawingsBindingOptions,
): SymbolDrawingsBinding

// Unexported supporting type referenced above
type Chart = WidgetContext['chart'];
```

See also: [`SymbolDrawingsBinding`](/vela-pro/api/drawings#symboldrawingsbinding), [`SymbolDrawingsBindingOptions`](/vela-pro/api/drawings#symboldrawingsbindingoptions), [`SymbolDrawingsStorage`](/vela-pro/api/drawings#symboldrawingsstorage). From `@luxalgo/vela/plugin`: `WidgetContext`.

### `decorateDrawingMenu` [#decoratedrawingmenu]

Pro's treatment of one drawing menu. Returns its cleanup.

```typescript
function decorateDrawingMenu(
    menu: HTMLElement,
    host: HTMLElement,
    opts?: Pick<EnableDrawingMenusOptions, 'searchFrom' | 'cards'>,
): () => void
```

See also: [`EnableDrawingMenusOptions`](/vela-pro/api/enablers#enabledrawingmenusoptions).

### `defaultSymbolDrawingsChartKey` [#defaultsymboldrawingschartkey]

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

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

### `drawingToolDescription` [#drawingtooldescription]

```typescript
function drawingToolDescription(name: string): string | null
```

### `labelPosition` [#labelposition]

Design-space label position for segment `index` of `count` (ring rotated by `offsetDeg`).

```typescript
function labelPosition(
    index: number,
    count: number,
    offsetDeg?: number,
): { xPct: number; yPct: number }
```

Default: `offsetDeg = 0`.

### `radialToolIndex` [#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.

```typescript
function radialToolIndex(
    dx: number,
    dy: number,
    deadZone: number,
    count: number,
    offsetDeg?: number,
): number | null
```

Default: `offsetDeg = 0`.

### `radialWheelAttachment` [#radialwheelattachment]

Build the radial-wheel attachment (registered by [`enableRadialWheel`](/vela-pro/api/enablers#enableradialwheel)).

```typescript
function radialWheelAttachment(opts?: RadialWheelOptions): WidgetAttachment
```

See also: [`RadialWheelOptions`](/vela-pro/api/drawings#radialwheeloptions). From `@luxalgo/vela/plugin`: `WidgetAttachment`.

### `registerDrawingToolDescription` [#registerdrawingtooldescription]

Add or replace a tool's description, by the name the toolbar shows. Returns the removal.

```typescript
function registerDrawingToolDescription(name: string, description: string): () => void
```

### `registerTooltipCard` [#registertooltipcard]

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

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

See also: [`TooltipCard`](/vela-pro/api/drawings#tooltipcard).

### `resolveTimeframes` [#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.

```typescript
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`](/vela-pro/api/drawings#radialtool).

### `resolveTools` [#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.

```typescript
function resolveTools(types: readonly string[], max?: number): RadialTool[]
```

Default: `max = MAX_SEGMENTS`.

See also: [`RadialTool`](/vela-pro/api/drawings#radialtool).

### `sectorPath` [#sectorpath]

The `d` attribute of segment `index` of `count`: an annular wedge centred on its direction (ring rotated by `offsetDeg`).

```typescript
function sectorPath(index: number, count: number, offsetDeg?: number): string
```

Default: `offsetDeg = 0`.

### `shortcutKeys` [#shortcutkeys]

A shortcut's keys as the platform names them.

```typescript
function shortcutKeys(shortcut: string, mac: boolean): string[]
```

### `symbolDrawingsName` [#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.

```typescript
function symbolDrawingsName(symbol: string): string
```

### `tooltipCardFor` [#tooltipcardfor]

The card for a tooltip's text: an exact name, or a name followed by its value (`Timeframe — 1h`).

```typescript
function tooltipCardFor(text: string): { title: string; card: TooltipCard } | null
```

See also: [`TooltipCard`](/vela-pro/api/drawings#tooltipcard).

## Classes [#classes]

### `LocalSymbolDrawingsStorage` [#localsymboldrawingsstorage]

The browser's localStorage: one entry per chart and symbol, under `prefix`.

```typescript
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`](/vela-pro/api/drawings#saveddrawings), [`SymbolDrawingsKey`](/vela-pro/api/drawings#symboldrawingskey), [`SymbolDrawingsStorage`](/vela-pro/api/drawings#symboldrawingsstorage).

### `RadialToolWheel` [#radialtoolwheel]

```typescript
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`](/vela-pro/api/drawings#radialhubaction), [`RadialRingText`](/vela-pro/api/drawings#radialringtext), [`RadialTool`](/vela-pro/api/drawings#radialtool).

## Interfaces and types [#interfaces-and-types]

### `RadialHubAction` [#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.

```typescript
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` [#radialringtext]

The hub's words for one ring: each falls back to the drawing-tool wording.

```typescript
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` [#radialtool]

One entry of the wheel.

```typescript
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` [#radialwheeloptions]

```typescript
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` [#saveddrawings]

A chart's drawings as Vela serializes them (`chart.drawings.toJSON()`).

```typescript
type SavedDrawings = ReturnType<WidgetContext['chart']['drawings']['toJSON']>;
```

From `@luxalgo/vela/plugin`: `WidgetContext`.

### `SymbolDrawingsBinding` [#symboldrawingsbinding]

```typescript
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` [#symboldrawingsbindingoptions]

```typescript
interface SymbolDrawingsBindingOptions {
    symbolKey?: (symbol: string) => string;
    delayMs?: number;
}
```

| Member       | Type                         | Description                                                                                                   |
| ------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `symbolKey?` | `(symbol: string) => string` | The name a symbol is saved under. Default: [`symbolDrawingsName`](/vela-pro/api/drawings#symboldrawingsname). |
| `delayMs?`   | `number`                     | How long a change waits before it is written, in milliseconds.                                                |

### `SymbolDrawingsKey` [#symboldrawingskey]

Whose drawings: one chart of the page, on one symbol.

```typescript
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` [#symboldrawingsstorage]

Keeps one drawings document per chart and symbol. Both methods may answer later.

```typescript
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`](/vela-pro/api/drawings#saveddrawings), [`SymbolDrawingsKey`](/vela-pro/api/drawings#symboldrawingskey).

### `TooltipCard` [#tooltipcard]

```typescript
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 [#constants]

### `DEFAULT_SYMBOL_DRAWINGS_KEY` [#default_symbol_drawings_key]

```typescript
const DEFAULT_SYMBOL_DRAWINGS_KEY: 'vela-pro.drawings';
```
