Skip to content
BarchartBarchart HTML5 Chart

AnnotationManipulation action

Use chart.change({ id: "AnnotationManipulation", context }) to read selection and stacking positions, select drawings, or reorder them. Execute this action on its own, not in a batch with other actions.

Host opt-in

Set annotationManipulation: true in the configuration passed to initFeed to enable enhanced annotation interactions. This optional runtime flag is not part of the saved chart definition. Omitted or false preserves legacy interaction behavior.

Without opt-in, context-menu requests clear selection, ordinary annotation updates deselect, body hit-testing chooses the topmost drawing on the pointer’s axis, and long-pressing locked drawings enters crosshair mode. With opt-in, selection persists, selected bodies take priority, overlaps can be offered to a chooser, selected handles render above other bodies, and locked drawings support context-menu long-press.

The new API and additive notification fields remain available in either mode. Undo correctness fixes also apply in both modes. Hosts using the enhanced chooser should opt in before creating their charts.

Context

  • id?: Get or Update (default).
  • uid?: annotation UID. Required when selecting a drawing or changing its position.
  • selected? (Update): select the UID with true; deselect matching drawings with false.
  • preview? (Update): with true, keep the UID at normal opacity and dim other user drawings in its pane. Requires a UID. With false, clear preview (optionally only for the given UID). Independent of selection.
  • position? (Update): Front, Back, or a non-negative integer. Positions run back to front within the drawing’s own axis; oversized positions clamp to the front.

A UID resolves anywhere in the chart. Unknown UIDs are no-ops. Pane and axis indices are output-only metadata and are not accepted in action contexts. Position changes and selection can be combined. Omitted fields leave that state unchanged.

Get

Returns an array of { uid, paneIndex, axisIndex, position, selected, preview } for matching user annotations, in pane/axis/back-to-front order. With no UID, returns all user annotations. paneIndex is the zero-based pane index; axisIndex is zero-based within that pane. These result fields explain where the drawing belongs and how to interpret its axis-local position. Study-generated drawings are excluded. Hidden drawings remain in this list and in the stacking order.

const drawings = chart.change({
    id: "AnnotationManipulation",
    context: { id: "Get" },
});

Update

// Select a drawing without changing its stacking order.
chart.change({ id: "AnnotationManipulation", context: { uid, selected: true } });


// Bring that drawing above other user drawings on its axis.
chart.change({ id: "AnnotationManipulation", context: { uid, position: "Front" } });


// Send it to the back, or to a specific slot.
chart.change({ id: "AnnotationManipulation", context: { uid, position: "Back" } });
chart.change({ id: "AnnotationManipulation", context: { uid, position: 1 } });


// Clear the current selection (optionally target a specific UID).
chart.change({ id: "AnnotationManipulation", context: { selected: false } });

For a chooser hover, combine { uid, selected: true, preview: true }. Clear with { preview: false } when the pointer leaves or the chooser closes, including error cleanup. Preview changes only rendering opacity, preserves stacking order, and leaves plots and study-generated drawings unchanged. It is never saved, synchronized, or recorded in undo. Runtime rebuilds clear it; hidden or removed preview targets cause no dimming.

With annotationManipulation: true, selection persists through ordinary edits and context-menu requests. Selection is transient, chart-wide, and never saved or recorded in undo history. Hidden drawings cannot be selected. Locked drawings can be selected but remain locked against dragging. With opt-in, the selected drawing’s body takes priority for editing and handles render above drawing bodies without changing saved order. Handle ownership is respected in both modes. Selection clears when the chart runtime is rebuilt.

Ordering emits CH_ANNOTATIONCHANGED, CH_DEFINITION_CHANGED, and CH_ANNMODIFIEDBYTOOL (toolChange: "Reordered"; undo/redo use "Undo"/"Redo"). Ordering is saved in the annotation array, survives save/load, and is undoable on interactive charts. Reordering at an already-reached position is a no-op. Ordinary edits do not reorder drawings; undoing deletion restores the original axis and position. Ordering applies within an axis, not across axes or against study-generated drawings.

Headless charts

Get and position updates operate on the chart definition without a canvas. Selection is unavailable: Get reports selected: false and preview: false, and selection/preview updates are ignored. Headless charts have no undo history, consistent with other annotation actions.

Overlap selection in host applications

CH_ANNNEEDSCONTEXTMENU includes a candidates array, front to back, for user drawings hit at the pointer across axes in the pane. Each candidate includes the usual annotation notification fields (UID, type id, traits, points, visibility, locking, extras, chart) plus paneIndex, axisIndex, position, and canFlip.

For hosts opting in with annotationManipulation: true, the notification includes wasSelected, captured before the gesture changes selection. Show the toolbar when this is true or there is only one candidate. Otherwise, show a chooser using the type and line/fill colors from traits, then call AnnotationManipulation/Update with the chosen UID and selected: true. After choosing, close the chooser and leave the drawing selected without opening the toolbar. A subsequent right-click on that selected drawing opens its toolbar. This lets the user edit an obscured drawing without rearranging it. The library supplies data and selection behavior; the host supplies the chooser and toolbar.

Compatibility notes for hosts

With annotationManipulation: true, annotations retain selection when a context menu is requested and after ordinary property updates. Hiding the selected drawing clears selection. A selected drawing’s body and handles take hit-test priority within overlaps, allowing an obscured drawing to remain editable. Hosts that require deselection when their toolbar or editor closes can explicitly send { selected: false }.

Ordering introduces toolChange: "Reordered" and orderOnly: true notifications; ordering undo/redo also carry orderOnly: true. Hosts synchronizing annotations must exclude these from ordinary drawing updates because each chart may have a different local stack.

With input validation enabled, the existing annotation action ID must match Annotation exactly; names merely containing that word are not accepted.

Opted-in touch hosts can use the same chooser rules for long-press. The initial tap may select the topmost drawing for dragging; when an unselected overlap is long-pressed, the context-menu request restores the selection from before the gesture and reports wasSelected: false. Long-pressing a drawing that was already selected opens its toolbar.

Annotation undo history follows surviving drawing owners through pane/axis rebuilds. If the original owner has been removed, undoing a deletion restores the drawing on the main axis instead of discarding it. This ownership tracking is runtime-only and adds no saved-definition fields.