Page History

...

How-to Guides → Solution Examples → Feature Examples → User Interactions Examples → TrendChart Annotations Example → Trend Annotations Reference (10.1.5 draft)

...

Version

...

10.1.5

...

+

...

Overview

Annotations are timestamped operator-authored or AI-authored notes overlaid on a TrendChart pen. Use them to mark events, capture commentary on a value at a moment in time, or surface AI-generated explanations next to the data they refer to.

The annotation surface in 10.1.5 is intentionally scoped to the two time-series chart controls: the TrendChart and the DrillingChart. Other chart types (BarChart, PieChart, GanttChart, etc.) have no annotation surface by design.

Quick start (zero-config)

The simplest pattern uses the platform-default behavior: the auto-created Annotations SQL table inside the TagHistorian database, plus the chart's built-in operator UX.

...

No customer-side Script.Class is required for this default path.

AnnotationsSource (per-chart)

The AnnotationsSource field on each TrendChart and DrillingChart names the Dataset.Table object that backs the annotation overlay for that chart.

...

The value is per-chart on purpose. Different charts can be wired to different annotation tables, and a single solution can mix the platform-default Annotations table with one or more customer-managed tables on different charts.

AnnotationsEnabled (operator-safety opt-out)

Each chart has a runtime tag at Client.TrendChart.AnnotationsEnabled and Client.DrillingChart.AnnotationsEnabled. Both default to true.

...

Setting either tag to false hides the four annotation context-menu items and suppresses the read-back overlay on that chart kind. This is the recommended switch for kiosk, regulated, or view-only deployments where operators must not author annotations — no scripting required.

Customer-extension *Method tags

Each TrendChart and DrillingChart exposes four optional override hooks. When set, they redirect the corresponding chart action to a customer Script.Class method, replacing the platform default for that action only. When empty, the platform-default zero-config behavior takes over.

AddNoteMethod

// Full AddNoteMethod method name in "Script.Class" with Client domain.
// Ex: Script.Class.ClientMain.MyAddNoteMethod.
// Prototype:
//   public void AddNote(TTrendChart trend, string tagName, object xValue, double yValue);
// Note: tagName can be null.

AddRangeEventMethod

// Full AddRangeEventMethod method name in "Script.Class" with Client domain.
// Ex: Script.Class.ClientMain.MyAddRangeEventMethod.
// Prototype:
//   public void AddRangeEventMethod(TTrendChart trend, string[] tagNames,
//                                    DateTime start, TimeSpan duration);

GetAnnotationTableMethod

// Full GetAnnotationTableMethod method name in "Script.Class" with Client domain.
// Ex: Script.Class.ClientMain.MyGetAnnotationTable.
// Prototype:
//   public DataTable GetAnnotationTableMethod(TTrendChart trend, string[] tagNames,
//                                              object xMinValue, object xMaxValue,
//                                              bool showTagNotes, bool showTimeNotes,
//                                              bool showXValueNotes, bool showRangeEvents);

MouseClickAnnotationMethod

// Full MouseClickAnnotationMethod method name in "Script.Class" with Client domain.
// Ex: Script.Class.ClientMain.MyMouseClickAnnotationMethod.
// Prototype:
//   public void MouseClickAnnotationMethod(MouseButtonEventArgs e, bool isEvent,
//                                           string identification, string title,
//                                           string contents, string color,
//                                           object xValue, double yValue,
//                                           double duration);

Built-in zero-config default behavior

When AnnotationsSource is non-empty AND the four *Method tags are empty, the chart uses the platform-default add and read paths:

...

You can override either path independently. Setting AddNoteMethod alone gives you a custom add UX while keeping the platform-default read. Setting GetAnnotationTableMethod alone gives you a custom read query while keeping the platform-default add. Mix and match as the deployment requires.

By-design scope: TrendChart and DrillingChart only

The 10.1.5 annotation API surface applies to time-series charts — specifically the TrendChart and DrillingChart controls. Other chart kinds (BarChart, PieChart, GanttChart, scatter plots, etc.) have no annotation overlay, no AnnotationsSource field, and no AnnotationsEnabled tag. This is by design: the time-axis semantics that make annotation pinning meaningful exist only on these two chart kinds.

If you need annotation-like commentary on a non-time-series chart, the Dataset.Table the annotations live in is plain SQL — you can author your own visualization on top of it.

Annotations SQL table schema

The platform auto-creates an Annotations table inside the TagHistorian SQLite database the first time the Historian module starts. The table has 26 columns covering the full annotation feature set:

...

The remaining 9 columns (ID, SourceID, Font, PopupText, DataContext, Attribute, GroupName, ChartStart, ChartDuration) take their SQL defaults on insert; the server reconciles the INSERT shape against the target schema by name and silently drops any column the target table does not expose. Customers managing their own annotation table need only the 17-column subset for ingest compatibility, but should provision the full 26-column shape if they want full feature coverage (event ranges, custom fonts, popup customization, chart-zoom-derived timestamps, etc.).

Customer-managed annotation tables

To use your own annotation table instead of the auto-created one:

1. Create a Dataset.Table object in your solution pointing to a SQL table with at least the 17-column ingest shape above.
2. Set AnnotationsSource on each chart that should use it to the Dataset.Table object name (e.g., "MyAnnotations").
3. The chart will read from and write to the named table; the platform does NOT auto-create customer-named tables. Provision the table yourself.

Code example

The minimum wiring — on a fresh solution, with no scripts:

...

For headless server-side annotation creation (AI-generated, batch import, report-time generation), see the TK Annotation Helpers Reference page.

...

In this section...