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

The SCIFreehandDrawingModifier

The SCIFreehandDrawingModifier is a gesture modifier that enables freehand drawing directly on a SciChartSurface.

Freehand Drawing Modifier

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

Freehand Drawing Modifier - Obj-C/Swift ̰

Overview

When this modifier is attached to a SciChartSurface, users can draw freehand strokes on the chart using touch gestures. As the user drags across the surface, a freehand drawing annotation is dynamically created and populated with a series of points representing the path of the gesture.

This is useful for scenarios such as:

Marking regions of interest
Freeform technical analysis
Drawing custom overlays on charts

API Reference

Field	Description
`SCIFreehandDrawingModifier.stroke`	The pen style used to draw the annotation
`SCIFreehandDrawingModifier.selectionOffset`	Specifies extra padding around the selection bounds of the annotation..
`SCIFreehandDrawingModifier.deleteSelectedAnnotations()`	Removes all currently selected freehand drawing annotations from the chart surface.
`-[ISCITradingAnnotation getBaseDataValues]`	Returns the collection of base data values.
`-[ISCITradingAnnotation getBasePoints]`	Returns the collection of screen-space points which represent the current freehand path drawn by the modifier.

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

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.

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

Usage Example

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

// Assume a surface has been created and configured somewhere
id surface = self.surface;

SCIFreehandDrawingModifier *freehandModifier = [SCIFreehandDrawingModifier new];

// Set the stroke style
freehandModifier.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFFF0000 thickness:2];

// Call completion block
__weak typeof(self) weakSelf = self;
  freehandModifier.annotationCreationCompletionListener = ^(id _Nonnull createdAnnotation, SCIAnnotationCreationType type) {
    __strong typeof(weakSelf) strongSelf = weakSelf;
    if (!strongSelf) return;
        
    NSLog(@“FREEHAND annotation created: %@ type %@”, createdAnnotation, SCIAnnotationTypeName(type));
        
    if (![createdAnnotation isKindOfClass:[SCIFreehandDrawingAnnotation class]]) return;
    SCIFreehandDrawingAnnotation *annotation = (SCIFreehandDrawingAnnotation*) createdAnnotation;
        
    NSLog(@“draw id: %@”, annotation.drawId);  
    NSLog(@“Points: %@”, [annotation getBaseDataValues]);      
};

// Add to chart modifiers collection
[surface.chartModifiers add:freehandModifier];

// Assume a surface has been created and configured somewhere
let surface: ISCIChartSurface

let freehandModifier = SCIFreehandDrawingModifier()

// Set the stroke style
freehandModifier.stroke = SCISolidPenStyle(color: SCIColor.red, thickness: 2.0)

// Call completion block
freehandModifier.annotationCreationCompletionListener = { [weak self] createdAnnotation, type in
  guard self != nil else { return }
            
  print(“FREEHAND drawing annotation created: \(createdAnnotation), type: \(SCIAnnotationTypeName(type))”)
            
  if let annotation = createdAnnotation as? SCIFreehandDrawingAnnotation {
      print(“draw id: \(annotation.drawId)”)
      print(“Points: \(annotation.getBaseDataValues())”)
  }
}

// Add to chart modifiers collection
surface.chartModifiers.add(freehandModifier)

Behavior

Touch down begins a new freehand drawing annotation.
Moving the finger continuously adds points to the annotation path.
Releasing the touch finalizes the annotation.
Annotations can be selected and removed using deleteSelectedAnnotations().

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.