The HorizontalLineAnnotation

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

Note

You might find it useful to learn about the VerticalLineAnnotation 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 Android Examples Suite as well as on GitHub:

The HorizontalLineAnnotation class is inherited from LineAnnotation, and hence, provides the stroke property which is used to define the line annotation color. It expects a PenStyle object. To learn more about Pens and Brushes and how to utilize them, please refer to the PenStyle, BrushStyle and FontStyle article.

Note

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

In general case, the position of an HorizontalLineAnnotation can be defined by the 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 Gravity. horizontalGravity property can consume the following values:

  • Gravity.LEFT - the X1 coordinate will be applied to the right end of a line. The line appears pinned to the left side.
  • Gravity.RIGHT - the X1 coordinate will be applied to the left end of a line. The line appears pinned to the right side.
  • Gravity.CENTER_HORIZONTAL - both X1 and X2 coordinates will be applied.
  • Gravity.FILL_HORIZONTAL - both X1 and X2 coordinates are ignored. The line appears horizontally stretched. This is the default value.

The X1 and X2 values can be accessed via the x1 and 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 HorizontalLineAnnotation can be added onto a chart using the following code:

// Assume a surface has been created and configured somewhere
// Create a HorizontalLine Annotation
final HorizontalLineAnnotation horizontalLine = new HorizontalLineAnnotation(getContext());

// Allow to interact with the annotation in run-time
horizontalLine.setIsEditable(true);

// In a multi-axis scenario, specify the XAxisId and YAxisId
horizontalLine.setXAxisId("TopAxisId");
horizontalLine.setYAxisId("RightAxisId");

// Specify a desired position by setting coordinates and mode
horizontalLine.setCoordinateMode(AnnotationCoordinateMode.RelativeY);
horizontalLine.setY1(0.1);

// Specify the border color for the annotation
horizontalLine.setStroke(new SolidPenStyle(0xFFFC9C29, true, 2f, null));

// Add the annotation to the Annotations collection of the surface
surface.getAnnotations().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 HorizontalLineAnnotation does not show any labels. You can show a label by adding a AnnotationLabel to the annotationLabels collection, like below:

final AnnotationLabel annotationLabel = new AnnotationLabel(getContext());
annotationLabel.setText("Label text");
annotationLabel.setLabelPlacement(LabelPlacement.Axis);
horizontalLine.annotationLabels.add(annotationLabel);

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

Note

Everything about AnnotationLabels collection and AnnotationLabel can be also applied to the VerticalLineAnnotation

The AnnotationLabel Type

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

Note

By default, AnnotationLabel uses its associated axis Y-value to display a label. To learn more about Pens and Brushes and how to utilize them, please refer to the PenStyle, BrushStyle and FontStyle article.

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

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

final HorizontalLineAnnotation horizontalLine = new HorizontalLineAnnotation(getContext());
horizontalLine.setX1(10.0d);
horizontalLine.setY1(34.512d);
horizontalLine.setIsEditable(true);
horizontalLine.setHorizontalGravity(Gravity.END);
horizontalLine.setStroke(new SolidPenStyle(Color.RED, true, 2f, null));

AnnotationLabel axisAnnotationLabel = new AnnotationLabel(getContext());
axisAnnotationLabel.setLabelPlacement(LabelPlacement.Axis);
axisAnnotationLabel.setRotationAngle(-10);
axisAnnotationLabel.setPadding(10, 0, 0, 0);

AnnotationLabel annotationLabel = new AnnotationLabel(getContext());
annotationLabel.setLabelPlacement(LabelPlacement.TopLeft);
annotationLabel.setText("Whatever Label");
annotationLabel.setFontStyle(new FontStyle(25, Color.YELLOW));

Collections.addAll(horizontalLine.annotationLabels, annotationLabel, 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 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 IFormattedValueProvider for your HorizontalLineAnnotation corresponding property.

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

class AnnotationValueProvider implements IFormattedValueProvider {
    @Override
    public CharSequence formatValue(AxisInfo axisInfo) {
        return axisInfo != null ? String.format(" $ %s $", axisInfo.axisFormattedDataValue) : null;
    }
}

final HorizontalLineAnnotation horizontalLine = new HorizontalLineAnnotation(getContext());
horizontalLine.setX1(10.0d);
horizontalLine.setY1(34.512d);
horizontalLine.setIsEditable(true);
horizontalLine.setHorizontalGravity(Gravity.END);
// Provide custom IFormattedValueProvider for the annotation
horizontalLine.setFormattedLabelValueProvider(new AnnotationValueProvider());

AnnotationLabel axisAnnotationLabel = new AnnotationLabel(getContext());
axisAnnotationLabel.setLabelPlacement(LabelPlacement.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.