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

The SCIHorizontalLineAnnotation

The SCIHorizontalLineAnnotation draws the horizontal line between X1 and X2 coordinates at Y1:

NOTE: You might find it useful to learn about the SCIVerticalLineAnnotation as well since it’s very similar with the Horizontal one.

Horizontal Line Annotation

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

The SCIHorizontalLineAnnotation class is inherited from SCILineAnnotation, and hence, provides the SCILineAnnotationBase.stroke property which is used to define the line annotation color. It expects a SCIPenStyle object. To learn more about Pens and Brushes and how to utilize them, please refer to the SCIPenStyle, SCIBrushStyle and SCIFontStyle article.

NOTE: To learn more about Annotations in general - please see the Common Annotation Features article.

In general case, the position of an SCIHorizontalLineAnnotation can be defined by the ISCIAnnotation.y1 value only, which will lead to full-width horizontal line at Y1 coordinate.

Despite the above, it is possible to specify X1 and X2 coordinates for the line ends, but it will work differently while combined with different SCIAlignment. SCIHorizontalLineAnnotation.horizontalAlignment property can consume the following values:

The X1 and X2 values can be accessed via the ISCIAnnotation.x1 and ISCIAnnotation.x2 properties

NOTE: The xAxisId and yAxisId must be supplied if you have an axis with non-default Axis Ids, e.g. in multi-axis scenario.

Create a HorizontalLine Annotation

A SCIHorizontalLineAnnotation can be added onto a chart using the following code:

// Assume a surface has been created and configured somewhere id<ISCIChartSurface> surface; // Create a HorizontalLine Annotation SCIHorizontalLineAnnotation *horizontalLine = [SCIHorizontalLineAnnotation new]; // Allow to interact with the annotation in run-time horizontalLine.isEditable = YES; // In a multi-axis scenario, specify the XAxisId and YAxisId horizontalLine.xAxisId = TopAxisId; horizontalLine.yAxisId = RightAxisId; // Specify a desired position by setting coordinates and mode horizontalLine.coordinateMode = SCIAnnotationCoordinateMode_RelativeY; horizontalLine.y1 = @(0.1); // Specify the border color for the annotation horizontalLine.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFFC9C29 thickness:2]; // Add the annotation to the Annotations collection of the surface [self.surface.annotations add:horizontalLine];
// Assume a surface has been created and configured somewhere let surface: ISCIChartSurface // Create a HorizontalLine Annotation let horizontalLine = SCIHorizontalLineAnnotation() // Allow to interact with the annotation in run-time horizontalLine.isEditable = true // In a multi-axis scenario, specify the XAxisId and YAxisId horizontalLine.xAxisId = TopAxisId horizontalLine.yAxisId = RightAxisId // Specify a desired position by setting coordinates horizontalLine.coordinateMode = .relativeY horizontalLine.set(y1: 0.1) // Specify the stroke color for the annotation horizontalLine.stroke = SCISolidPenStyle(colorCode: 0xFFFC9C29, thickness: 2) // Add the annotation to the Annotations collection of the surface self.surface.annotations.add(horizontalLine)
// Assume a surface has been created and configured somewhere IISCIChartSurface surface; // Create a HorizontalLine Annotation var horizontalLine = new SCIHorizontalLineAnnotation { // Allow to interact with the annotation in run-time IsEditable = true, // In a multi-axis scenario, specify the XAxisId and YAxisId XAxisId = TopAxisId, YAxisId = RightAxisId, // Specify a desired position by setting coordinates CoordinateMode = SCIAnnotationCoordinateMode.RelativeY, Y1Value = 0.1, // Specify the stroke color for the annotation Stroke = new SCISolidPenStyle(0xFFFC9C29, 2), }; // Add the annotation to the Annotations collection of the surface Surface.Annotations.Add(horizontalLine);

NOTE: To learn more about other Annotation Types, available out of the box in SciChart, please find the comprehensive list in the Annotation APIs article.

The AnnotationLabels collection

By default, the SCIHorizontalLineAnnotation does not show any labels. You can show a label by adding a SCIAnnotationLabel to the SCILineAnnotationWithLabelsBase.annotationLabels collection, like below:

SCIAnnotationLabel *annotationLabel = [SCIAnnotationLabel new]; annotationLabel.labelPlacement = SCILabelPlacement_Axis; [horizontalLine.annotationLabels add:annotationLabel];
let annotationLabel = SCIAnnotationLabel() annotationLabel.labelPlacement = .axis horizontalLine.annotationLabels.add(annotationLabel)
var annotationLabel = new SCIAnnotationLabel(); annotationLabel.LabelPlacement = SCILabelPlacement.Axis; horizontalLine.AnnotationLabels.Add(annotationLabel);

The Label position can be changed by setting the SCIAnnotationLabel.labelPlacement property which expects one of the SCILabelPlacement enumeration.

NOTE: Everything about AnnotationLabels collection and SCIAnnotationLabel can be also applied to the SCIVerticalLineAnnotation

The SCIAnnotationLabel Type

You can change appearance, position, custom value, etcetera for any annotation label which are listed below:

  • borderPen - defines the AnnotationLabel outline.
  • backgroundBrush - defines the AnnotationLabel background.
  • padding - defines the padding around the label
  • rotationAngle - allows to rotate annotation label text, expects degrees
  • text - you can set custom text for your label.
  • attributedText - you can set custom attributed text for your label. In this case, the text property will be ignored.
  • fontStyle - applies the SCIFontStyle object onto the text.

NOTE: By default, SCIAnnotationLabel uses its associated axis Y-value to display a label.

NOTE: To learn more about Pens and Brushes and how to utilize them, please refer to the SCIPenStyle, SCIBrushStyle and SCIFontStyle article.

Also, you can have more than one AnnotationLabel associated with SCIHorizontalLineAnnotation by adding more than one to the SCILineAnnotationWithLabelsBase.annotationLabels collection.

Please see the code below, which showcases the utilization of the above settings:

SCIHorizontalLineAnnotation *horizontalLine = [SCIHorizontalLineAnnotation new]; horizontalLine.x1 = @(10); horizontalLine.y1 = @(34.512); horizontalLine.isEditable = YES; horizontalLine.horizontalAlignment = SCIAlignment_Right; horizontalLine.stroke = [[SCISolidPenStyle alloc] initWithColor:UIColor.redColor thickness:2]; SCIAnnotationLabel *axisAnnotationLabel = [SCIAnnotationLabel new]; axisAnnotationLabel.labelPlacement = SCILabelPlacement_Axis; axisAnnotationLabel.rotationAngle = -10; axisAnnotationLabel.padding = (UIEdgeInsets){ .left = 10 }; SCIAnnotationLabel *annotationLabel = [SCIAnnotationLabel new]; annotationLabel.labelPlacement = SCILabelPlacement_TopLeft; annotationLabel.text = @“Whatever Label”; annotationLabel.fontStyle = [[SCIFontStyle alloc] initWithFontSize:25 andTextColor:UIColor.yellowColor]; [horizontalLine.annotationLabels addAll:annotationLabel, axisAnnotationLabel, nil];
let horizontalLine = SCIHorizontalLineAnnotation() horizontalLine.set(x1: 10) horizontalLine.set(y1: 34.512) horizontalLine.isEditable = true horizontalLine.horizontalAlignment = .right horizontalLine.stroke = SCISolidPenStyle(color: .red, thickness: 2) let axisAnnotationLabel = SCIAnnotationLabel() axisAnnotationLabel.labelPlacement = .axis axisAnnotationLabel.rotationAngle = -10; axisAnnotationLabel.padding = UIEdgeInsets(top: 0, left: -10, bottom: 0, right: 0) let annotationLabel = SCIAnnotationLabel() annotationLabel.labelPlacement = .topLeft annotationLabel.text = “Whatever Label” annotationLabel.fontStyle = SCIFontStyle(fontSize: 25, andTextColor: .yellow) horizontalLine.annotationLabels.add(annotationLabel) horizontalLine.annotationLabels.add(axisAnnotationLabel)
var horizontalLine = new SCIHorizontalLineAnnotation(); horizontalLine.X1Value = 10; horizontalLine.Y1Value = 34.512; horizontalLine.IsEditable = true; horizontalLine.HorizontalAlignment = SCIAlignment.Right; horizontalLine.Stroke = new SCISolidPenStyle(UIColor.Red, 2); var axisAnnotationLabel = new SCIAnnotationLabel(); axisAnnotationLabel.LabelPlacement = SCILabelPlacement.Axis; axisAnnotationLabel.RotationAngle = -10; axisAnnotationLabel.Padding = new UIEdgeInsets(0, -10, 0, 0); var annotationLabel = new SCIAnnotationLabel(); annotationLabel.LabelPlacement = SCILabelPlacement.TopLeft; annotationLabel.Text = “Whatever Label”; annotationLabel.FontStyle = new SCIFontStyle(25, UIColor.Yellow); horizontalLine.AnnotationLabels.Add(annotationLabel); horizontalLine.AnnotationLabels.Add(axisAnnotationLabel);

The result will be the following:

Horizontal Line Annotation With Labels

Annotation Label Value and TextFormatting

By default, the label text is formatted by the ISCIAxisCore.textFormatting property. For more information, refer to the Axis Labels - TextFormatting and CursorTextFormatting article.

But you can also override the default behaviour by providing a custom ISCIFormattedValueProvider for your SCIHorizontalLineAnnotation corresponding property.

Let’s see a short example which shows how to use the above:

// Declare custom ISCIFormattedValueProvider @interface AnnotationValueProvider: NSObject<ISCIFormattedValueProvider> @end @implementation AnnotationValueProvider - (id)formatValueWithAxisInfo:(SCIAxisInfo *)axisInfo { return axisInfo != nil ? [NSString stringWithFormat:@“$ %@ $”, axisInfo.axisFormattedDataValue] : nil; } @end … SCIHorizontalLineAnnotation *horizontalLine = [SCIHorizontalLineAnnotation new]; horizontalLine.x1 = @(10); horizontalLine.y1 = @(34.512); horizontalLine.isEditable = YES; horizontalLine.horizontalAlignment = SCIAlignment_Right; // Provide custom ISCIFormattedValueProvider for the annotation horizontalLine.formattedLabelValueProvider = [AnnotationValueProvider new]; SCIAnnotationLabel *axisAnnotationLabel = [SCIAnnotationLabel new]; axisAnnotationLabel.labelPlacement = SCILabelPlacement_Axis; [horizontalLine.annotationLabels add:axisAnnotationLabel];
// Declare custom ISCIFormattedValueProvider class AnnotationValueProvider: ISCIFormattedValueProvider { func formatValue(with axisInfo: SCIAxisInfo!) -> ISCIString! { return axisInfo != nil ? NSString(string: “$ \(axisInfo.axisFormattedDataValue!) $”) : nil; } } … let horizontalLine = SCIHorizontalLineAnnotation() horizontalLine.set(x1: 10) horizontalLine.set(y1: 34.512) horizontalLine.isEditable = true horizontalLine.horizontalAlignment = .right // Provide custom ISCIFormattedValueProvider for the annotation horizontalLine.formattedLabelValueProvider = AnnotationValueProvider() let axisAnnotationLabel = SCIAnnotationLabel() axisAnnotationLabel.labelPlacement = .axis horizontalLine.annotationLabels.add(axisAnnotationLabel)
// Declare custom ISCIFormattedValueProvider class AnnotationValueProvider : ISCIFormattedValueProvider { public override IISCIString FormatValueWithAxisInfo(SCIAxisInfo axisInfo) { return axisInfo != null ? $“$ {axisInfo.AxisFormattedDataValue} $”.ToSciString() : null; } } … var horizontalLine = new SCIHorizontalLineAnnotation(); horizontalLine.X1Value = 10; horizontalLine.Y1Value = 34.512; horizontalLine.IsEditable = true; horizontalLine.HorizontalAlignment = SCIAlignment.Right; // Provide custom ISCIFormattedValueProvider for the annotation horizontalLine.FormattedLabelValueProvider = new AnnotationValueProvider(); var axisAnnotationLabel = new SCIAnnotationLabel(); axisAnnotationLabel.LabelPlacement = SCILabelPlacement.Axis; horizontalLine.AnnotationLabels.Add(axisAnnotationLabel);

The result will be the following:

Horizontal Line Annotation Label Formatting

NOTE: To learn more about other Annotation Types, available out of the box in SciChart, please find the comprehensive list in the Annotation APIs article.