| uid | annotationsAPIs.AnnotationsAPIs |
|---|
SciChart features a rich Annotations API, that allows you to place different elements over a chart:
Note
Examples of the Annotations usage can be found in the SciChart Android Examples Suite as well as on GitHub:
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 Android Examples Suite which demonstrate them.
The annotations which are available out the box in SciChart are listed below:
| Annotation Type | Description |
|---|---|
| BoxAnnotation | Draws a rectangle at specific X1, X2, Y1, Y2 coordinates. |
| BrushAnnotation | Allows for freehand drawing on the chart. |
| XabcdAnnotation | Draws harmonic patterns (X, A, B, C, D) with automatic Fibonacci-style ratios. |
| PitchforkAnnotation | Draws Andrew's Pitchfork patterns using 3 points (Handle, High, Low). |
| LineAnnotation | Draws a line between [X1, Y1] and [X2, Y2] coordinates. |
| LineArrowAnnotation | Draws an arrow from [X1, Y1] to [X2, Y2] coordinates. |
| HorizontalLineAnnotation | Draws a horizontal line between [X1, Y1] and [X2, Y2] coordinates. |
| VerticalLineAnnotation | Draws a vertical line between [X1, Y1] and [X2, Y2] coordinates. |
| TextAnnotation | Allows to place a piece of text at specific [X1, Y1] coordinates on a chart. |
| AxisLabelAnnotation | Allows to place a piece of text at specific X1 or Y1 coordinate on a chart Axis. |
| AxisMarkerAnnotation | Allows to place markers with custom text onto X or Y axes. By default, shows the axis value at its location. |
| CustomAnnotation | 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.
The xref:com.scichart.charting.visuals.SciChartSurface stores all its annotations in the internal xref:com.scichart.charting.model.AnnotationCollection. It exposes the xref:com.scichart.charting.visuals.ISciChartSurface.getAnnotations() property to access it.
The following code can be used to add the xref:com.scichart.charting.visuals.annotations.LineAnnotation to the chart:
[!code-javaAddLineAnnotation]
[!code-javaAddLineAnnotation]
[!code-swiftAddLineAnnotation]
All the Annotation classes provided by SciChart conforms to the xref:com.scichart.charting.visuals.annotations.IAnnotation protocol and derive from the xref:com.scichart.charting.visuals.annotations.AnnotationBase 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 |
|---|---|
| x1, y1, x2, y2 | [X1, X2, Y1, Y2] coordinates specifies the position of an annotation on a xref:com.scichart.charting.visuals.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. |
| xAxisId, yAxisId | Specifies the ID of X-Axis and Y-Axis that this annotation is measured against. |
| 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 resizingGrip property |
| 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. |
| isHidden | Hides or shows an annotation. |
| dragDirections | Allows to constrain drag directions for an annotation. Accepts a member of the xref:com.scichart.charting.Direction2D enumeration. |
| resizeDirections | Allows to constrain resize directions for an annotation. Accepts a member of the xref:com.scichart.charting.Direction2D enumeration. |
| 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 xref:com.scichart.charting.visuals.annotations.AnnotationCoordinateMode enumeration. |
| resizingGrip | Determines what resizing markers look like. Custom ones have to implement xref:com.scichart.charting.visuals.annotations.IResizingGrip. |
| annotationSurface | Specifies a surface to place an annotation on. Possible options are declared by the xref:com.scichart.charting.visuals.annotations.AnnotationSurfaceEnum 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 |
|---|---|
| xref:com.scichart.charting.visuals.annotations.AnnotationBase.update(com.scichart.charting.visuals.axes.IAxis,com.scichart.charting.visuals.axes.IAxis) | Redraws an annotation without invalidating the parentSurface of the xref:com.scichart.charting.visuals.annotations.IAnnotation instance. |
| xref:com.scichart.charting.visuals.annotations.IAnnotation.moveAnnotation(float,float) | Moves an annotation by the specified X and Y delta in horizontal and vertical directions. |
| xref:com.scichart.charting.visuals.annotations.IAnnotation.setOnAnnotationDragListener(com.scichart.charting.visuals.annotations.OnAnnotationDragListener) | Allows to appoint xref:com.scichart.charting.visuals.annotations.OnAnnotationDragListener to receive notifications about user interactions with an annotation. |
| xref:com.scichart.charting.visuals.annotations.IAnnotation.setOnAnnotationSelectionChangeListener(com.scichart.charting.visuals.annotations.OnAnnotationSelectionChangeListener) | Allows to appoint xref:com.scichart.charting.visuals.annotations.OnAnnotationSelectionChangeListener to receive notifications when the annotation selection has changed |
| xref:com.scichart.charting.visuals.annotations.IAnnotation.setOnAnnotationIsHiddenChangeListener(com.scichart.charting.visuals.annotations.OnAnnotationIsHiddenChangeListener) | Allows to appoint xref:com.scichart.charting.visuals.annotations.OnAnnotationIsHiddenChangeListener to receive notifications when an annotation gets hidden or visible. |
Note
To find out more about a specific Annotation Type, please refer to a corresponding article about this Annotation type.
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 xref:com.scichart.charting.visuals.annotations.AnchorPointAnnotation. It has two properties, which accepts the xref:com.scichart.charting.visuals.annotations.HorizontalAnchorPoint and xref:com.scichart.charting.visuals.annotations.VerticalAnchorPoint enumerations correspondingly:
- xref:com.scichart.charting.visuals.annotations.AnchorPointAnnotation.setHorizontalAnchorPoint(com.scichart.charting.visuals.annotations.HorizontalAnchorPoint)
- xref:com.scichart.charting.visuals.annotations.AnchorPointAnnotation.setVerticalAnchorPoint(com.scichart.charting.visuals.annotations.VerticalAnchorPoint)
The image below illustrates how those works:
The annotation types that derive from AnchorPointAnnotation are the following:
- xref:annotationsAPIs.TextAnnotation
- xref:annotationsAPIs.CustomAnnotation
- xref:annotationsAPIs.AxisMarkerAnnotation
- xref:annotationsAPIs.AxisLabelAnnotation
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.
In SciChart - All Annotation Types are supporting dragging and repositioning via touch. As mentioned above - that's can be controlled via the isEditable.
Note
This is demonstrated in the Interaction with Annotations example which can be found in the SciChart Android Examples Suite as well as on GitHub:
SciChart also provides a set of specialized Chart Modifiers that allow users to create annotations interactively on the chart using touch gestures.
To learn more about available creation modifiers, please refer to the corresponding articles in the Annotation Creation Modifiers section.