The MeasureAnnotationCreationModifier

The MeasureAnnotationCreationModifier is a chart modifier that allows for interactive creation of MeasureAnnotation instances using either a 2-tap or a single-drag workflow.

Overview

When this modifier is enabled, users can place the 2 required anchor points - the start and the end of the move being measured - in one of two ways:

Tap to place: Each tap confirms the position of the next anchor point. A "rubber-band" dashed line provides a preview of the segment between the last confirmed point and the current touch position.
Single drag: If the finger moves more than 10 pixels before the first touch-up, the gesture is classified as a drag - both anchor points are placed from the start and end of that drag, and the annotation is finalized on touch-up.

Once both points are placed, the annotation is finalized, the rubber-band preview is removed, and the modifier automatically resets to create the next one.

Snapping to Data Points

If a renderable series is assigned to snapSeries, the modifier passes it to every MeasureAnnotation it creates, so both anchor points snap to the nearest rendered data point while being placed.

Note

The snap-distance threshold logic lives on the MeasureAnnotation itself rather than on the modifier. This means snapping keeps working for vertex and body drags performed after creation, and it is configured through the annotation's own properties. See the MeasureAnnotation article for details.

Assigning snapSeries also affects the bar count reported by the annotation's label, since the series' X values are used to resolve the indices of the two anchor points on a value axis.

Properties

The following properties can be used to configure the MeasureAnnotationCreationModifier:

Property	Description
snapSeries	Sets the renderable series that the created annotations should snap to. Pass `null` to disable snapping. Assigning it also updates the annotation currently being created.
xAxisId	Sets the ID of the X-Axis that the created annotations should be measured against.
yAxisId	Sets the ID of the Y-Axis that the created annotations should be measured against.
rubberBandStroke	Sets the pen style for the preview line shown during creation. Must not be `null`.

The following read-only properties allow to inspect the creation progress, e.g. from a custom subclass:

Property	Description
currentAnnotation	The annotation currently being created, or `null` if no creation is in progress.
currentPointIndex	The index of the next anchor point to be placed - `0` for the start, `1` for the end.
rubberBandAnnotation	The rubber-band preview annotation, or `null` if it is not currently shown.

Event Listeners

You can receive a notification when an annotation is fully created by setting an OnAnnotationCreatedListener:

setAnnotationCreationListener(OnAnnotationCreatedListener listener): Passes the newly created annotation instance to the listener.

Using MeasureAnnotationCreationModifier

The following code demonstrates how to add and configure a MeasureAnnotationCreationModifier:

Java
Kotlin

// Create a MeasureAnnotationCreationModifier
final MeasureAnnotationCreationModifier measureCreationModifier = new MeasureAnnotationCreationModifier();

// Optional: Snap the anchor points of every created annotation to the closest data point
// of an OHLC series. The series is also used to resolve the bar count reported by the label
// measureCreationModifier.setSnapSeries(candlestickSeries);

// Optional: Customize the rubber-band preview line shown while placing the points
measureCreationModifier.setRubberBandStroke(new SolidPenStyle(Color.WHITE, true, 1.5f, new float[]{5, 5}));

// Optional: Set a listener to be notified when an annotation is created
measureCreationModifier.setAnnotationCreationListener(newAnnotation -> {
    // Configure the newly created annotation if needed
    newAnnotation.setIsEditable(true);
});

// Add the modifier to the surface
surface.getChartModifiers().add(measureCreationModifier);

// Create a MeasureAnnotationCreationModifier
val measureCreationModifier = MeasureAnnotationCreationModifier().apply {
    // Optional: Snap the anchor points of every created annotation to the closest data point
    // of an OHLC series. The series is also used to resolve the bar count reported by the label
    // snapSeries = candlestickSeries

    // Optional: Customize the rubber-band preview line shown while placing the points
    rubberBandStroke = SolidPenStyle(Color.WHITE, true, 1.5f, floatArrayOf(5f, 5f))

    // Optional: Set a listener to be notified when an annotation is created
    setAnnotationCreationListener { newAnnotation ->
        // Configure the newly created annotation if needed
        newAnnotation.setIsEditable(true)
    }
}

// Add the modifier to the surface
surface.chartModifiers.add(measureCreationModifier)

Customizing the Modifier

The MeasureAnnotationCreationModifier is designed for extensibility. You can customize its behavior by extending it and overriding its protected methods:

Method	Description
`createAnnotation(Context)`	Replace the annotation type, or apply custom default styling to every created annotation.
`createRubberBandAnnotation(Context)`	Replace the rubber-band preview annotation type.
`configureRubberBandAnnotation(IAnnotation)`	Configure the rubber-band annotation after creation.
`updateRubberBandEndPoint(PointF)`	Change how the rubber-band tracks the finger.
`removeRubberBandAnnotation()`	Clean up the rubber-band annotation.
`onAnnotationCreated(IAnnotation)`	React to annotation completion.

Java
Kotlin

// Define a custom MeasureAnnotationCreationModifier
private static class CustomMeasureAnnotationCreationModifier extends MeasureAnnotationCreationModifier {
    @Override
    protected MeasureAnnotation createAnnotation(Context context) {
        final MeasureAnnotation annotation = super.createAnnotation(context);

        // Apply custom default styling to every annotation created by this modifier
        annotation.setGrowingColor(Color.CYAN);
        annotation.setDecliningColor(Color.MAGENTA);
        annotation.setYValueScaleFactor(10000d);

        return annotation;
    }

    @Override
    protected void configureRubberBandAnnotation(IAnnotation annotation) {
        super.configureRubberBandAnnotation(annotation);

        // Customize the rubber-band styling
        if (annotation instanceof LineAnnotation) {
            ((LineAnnotation) annotation).setStroke(new SolidPenStyle(Color.YELLOW, true, 2f, new float[]{10, 5}));
        }
    }

    @Override
    protected void onAnnotationCreated(IAnnotation newAnnotation) {
        super.onAnnotationCreated(newAnnotation);

        // Custom logic after annotation is fully created
        newAnnotation.setIsEditable(true);
    }
}

void useCustomMeasureAnnotationCreationModifier(@NonNull SciChartSurface surface) {
    // Use the custom modifier
    final CustomMeasureAnnotationCreationModifier customModifier = new CustomMeasureAnnotationCreationModifier();

    surface.getChartModifiers().add(customModifier);
}

// Define a custom MeasureAnnotationCreationModifier
private class CustomMeasureAnnotationCreationModifier : MeasureAnnotationCreationModifier() {
    override fun createAnnotation(context: Context): MeasureAnnotation {
        val annotation = super.createAnnotation(context)

        // Apply custom default styling to every annotation created by this modifier
        annotation.growingColor = Color.CYAN
        annotation.decliningColor = Color.MAGENTA
        annotation.yValueScaleFactor = 10000.0

        return annotation
    }

    override fun configureRubberBandAnnotation(annotation: IAnnotation) {
        super.configureRubberBandAnnotation(annotation)

        // Customize the rubber-band styling
        if (annotation is LineAnnotation) {
            annotation.stroke = SolidPenStyle(Color.YELLOW, true, 2f, floatArrayOf(10f, 5f))
        }
    }

    override fun onAnnotationCreated(newAnnotation: IAnnotation) {
        super.onAnnotationCreated(newAnnotation)

        // Custom logic after annotation is fully created
        newAnnotation.setIsEditable(true)
    }
}

fun useCustomMeasureAnnotationCreationModifier(surface: SciChartSurface) {
    // Use the custom modifier
    val customModifier = CustomMeasureAnnotationCreationModifier()

    surface.chartModifiers.add(customModifier)
}

Note

The snapSeries assigned on the modifier is applied when the annotation is added to the surface, after createAnnotation returns. Assign it on the modifier rather than inside an overridden createAnnotation.

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.