iOS & macOS Charting Documentation - SciChart iOS & macOS Charts SDK v4.x

Annotations APIs

SciChart features a rich Annotations API, that allows you to place different elements over a chart:

Annotations are Easy Example

NOTE: Examples of the Annotations usage can be found in the SciChart iOS Examples Suite as well as on GitHub:

Obj-C/Swift Example

Xamarin Example

There are many different Annotations provided by SciChart and each one deserves an article by itself! This article is concerned with simply giving an overview of the annotations and where you can find the examples in our SciChart iOS Examples Suite which demonstrate them.

The annotations which are available out the box in SciChart are listed below:

Annotation Type	Description
SCIBoxAnnotation	Draws a rectangle at specific `X1, X2, Y1, Y2` coordinates.
SCILineAnnotation	Draws a line between `[X1, Y1]` and `[X2, Y2]` coordinates.
SCILineArrowAnnotation	Draws an arrow from `[X1, Y1]` to `[X2, Y2]` coordinates.
SCIHorizontalLineAnnotation	Draws a horizontal line between `[X1, Y1]` and `[X2, Y2]` coordinates.
SCIVerticalLineAnnotation	Draws a vertical line between `[X1, Y1]` and `[X2, Y2]` coordinates.
SCITextAnnotation	Allows to place a piece of text at specific `[X1, Y1]` coordinates on a chart.
SCIAxisLabelAnnotation	Allows to place a piece of text at specific `X1` or `Y1` coordinate on a chart Axis.
SCIAxisMarkerAnnotation	Allows to place markers with custom text onto `X or Y axes`. By default, shows the axis value at its location.
SCICustomAnnotation	Allows to place any `UIView` at a specific `[X1, Y1]` coordinates on a chart.

NOTE: To learn more about Annotation API, please read the Common Annotations Features section. To find out more about a specific Annotation Type, please refer to a corresponding article about this Annotation type.

Adding an Annotation Onto a Chart

The SCIChartSurface stores all its annotations in the internal SCIAnnotationCollection. It exposes the ISCIChartSurface.annotations property to access it.

The following code can be used to add the SCILineAnnotation to the chart:

// Assume a surface has been created and configured somewhere
id<ISCIChartSurface> surface;
// Create and configure the Line Annotation
SCILineAnnotation *lineAnnotation = [SCILineAnnotation new];
lineAnnotation.x1 = @(1.0);
lineAnnotation.y1 = @(4.0);
lineAnnotation.x2 = @(2.0);
lineAnnotation.y2 = @(6.0);
lineAnnotation.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFF555555 thickness:2];
// Add the annotation to the SCIAnnotationsCollection of a surface
[self.surface.annotations add:lineAnnotation];

// Assume a surface has been created and configured somewhere
let surface: ISCIChartSurface
// Create and configure the Line Annotation
let lineAnnotation = SCILineAnnotation()
lineAnnotation.set(x1: 1.0)
lineAnnotation.set(y1: 4.0)
lineAnnotation.set(x2: 2.0)
lineAnnotation.set(y2: 6.0)
lineAnnotation.stroke = SCISolidPenStyle(colorCode: 0xFF555555, thickness: 2)
// Add the annotation to the SCIAnnotationsCollection of a surface
surface.annotations.add(lineAnnotation)

// Assume a surface has been created and configured somewhere
IISCIChartSurface surface;
// Create and configure the Line Annotation
var lineAnnotation = new SCILineAnnotation
{
X1Value = 1.0,
Y1Value = 4.0,
X2Value = 2.0,
Y2Value = 6.0,
Stroke = new SCISolidPenStyle(0xFF555555, 2f),
};
// Add the annotation to the SCIAnnotationsCollection of a surface
Surface.Annotations.Add(lineAnnotation);

Common Annotations Features

All the Annotation classes provided by SciChart conforms to the ISCIAnnotation protocol and derive from the SCIAnnotationBase class. These provide an API which allows to put them onto a chart and interact with them.

NOTE: Please refer to the beginning of this article for the complete list of all the Annotation types available out of the box in SciChart.

Please see the list of common features below:

Feature	Description
`ISCIAnnotation.x1`, `ISCIAnnotation.y1`, `ISCIAnnotation.x2`, `ISCIAnnotation.y2`	[X1, X2, Y1, Y2] coordinates specifies the position of an annotation on a `SCIChartSurface`. These are chart coordinates, not device (screen or pixel) coordinates. To find out about coordinate transformation in SciChart, please refer to the Convert Pixels to Data Coordinates article.
`ISCIAnnotation.xAxisId`, `ISCIAnnotation.yAxisId`	Specifies the ID of X-Axis and Y-Axis that this annotation is measured against.
`ISCIAnnotation.isSelected`	Defines whether the annotation is Selected. When Selected - round resizing markers appears at the ends or corners of the annotation which can be used to resize it. Resizing markers can be accessed via the `SCIAnnotationBase.resizingGrip` property
`ISCIAnnotation.isEditable`	Specifies whether an annotation is available for interaction. When Editable, the annotation can be Selected, Moved and Resized by a user with a touch interaction.
`ISCIAnnotation.isHidden`	Hides or shows an annotation.
`ISCIAnnotation.dragDirections`	Allows to constrain drag directions for an annotation. Accepts a member of the `SCIDirection2D` enumeration.
`ISCIAnnotation.resizeDirections`	Allows to constrain resize directions for an annotation. Accepts a member of the `SCIDirection2D` enumeration.
`SCIAnnotationBase.coordinateMode`	Determines whether [X1, X2, Y1, Y2] coordinates are in chart coordinates or in relative screen coordinates. Relative coordinates range from [0 to 1], where 1 refers to the full Width or Height of the canvas. Absolute coordinates are the data-values which must correspond to the Axis Type. Defined by the `SCIAnnotationCoordinateMode` enumeration.
`SCIAnnotationBase.resizingGrip`	Determines what resizing markers look like. Custom ones have to implement `ISCIResizingGrip`.
`ISCIAnnotation.annotationSurface`	Specifies a surface to place an annotation on. Possible options are declared by the `SCIAnnotationSurfaceEnum` enumeration.

NOTE: The xAxisId and yAxisId must be supplied if you have axis with non-default Axis Ids.

Below is the list of some methods and listeners:

Feature	Description
`-[ISCIAnnotation updateWithXAxis:yAxis:]`	Redraws an annotation without invalidating the `parentSurface` of the `ISCIAnnotation` instance.
`-[ISCIAnnotation moveAnnotationByXDelta:yDelta:]`	Moves an annotation by the specified X and Y delta in horizontal and vertical directions.

`ISCIAnnotation.annotationDragListener`	Allows to appoint `SCIAnnotationDragListener` to receive notifications about user interactions with an annotation.
`ISCIAnnotation.annotationSelectionChangedListener`	Allows to appoint `SCIAnnotationSelectionChangedListener` to receive notifications when the annotation selection has changed
`ISCIAnnotation.annotationIsHiddenChangedListener`	Allows to appoint `SCIAnnotationIsHiddenChangedListener` to receive notifications when an annotation gets hidden or visible.

To find out more about a specific Annotation Type, please refer to a corresponding article about this Annotation type.

Annotation Alignment (Anchor Points)

There is the subset of classes among all the annotation types that allows their instances to be aligned relative to the [X1, Y1] control point. The base class responsible for this behavior is called SCIAnchorPointAnnotation. It has two properties, which accepts the SCIHorizontalAnchorPoint and SCIVerticalAnchorPoint enumerations correspondingly:

The image below illustrates how those works:

Annotations Anchor Points

The annotation types that derive from AnchorPointAnnotation are the following:

As the information above implies, annotations of these types are controlled by the [X1, Y1] coordinates only. The [X2, Y2] coordinates have no impact on placement and are simply ignored.

Editing Annotations via User Drag

In SciChart - All Annotation Types are supporting dragging and repositioning via touch. As mentioned above - that’s can be controlled via the ISCIAnnotation.isEditable.

This is demonstrated in the Interaction with Annotations example which can be found in the SciChart iOS Examples Suite as well as on GitHub: