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

SCIPitchforkCreationModifier

The SCIPitchforkCreationModifier is a custom gesture modifier used for interactive creation of Pitchfork annotations on a SciChart surface. It enables users to define a pitchfork using a two-stage pan gesture workflow, producing a SCIPitchforkAnnotation with real-time visual feedback during construction.

Overview

The modifier manages the full lifecycle of pitchfork creation:

Two-step gesture interaction (A → B → C)
Real-time rendering while dragging points
Automatic annotation finalization after point C is set
Immediate reset for continuous creation of multiple pitchforks

Once completed, the annotation is added to the chart and a completion callback is triggered.

Interaction Behavior

The creation flow is split into two sequential pan gestures.

State Machine

State	Description
`SCIPitchforkCreationStateIdle`	Waiting for first touch input
`SCIPitchforkCreationStateDrawingAB`	Point A is locked, user is dragging to define B
`SCIPitchforkCreationStateWaitingForC`	A and B are locked, waiting for second gesture
`SCIPitchforkCreationStateDrawingC`	User is dragging to define C; pitchfork updates live

Gesture Flow (A → B → C)

1. First Pan Gesture (A → B)

Gesture	Behavior
Touch Down	Locks point A at touch location
Drag	Dynamically updates point B
Touch Up	Finalizes A and B, transitions to waiting state

2. Second Pan Gesture ©

Gesture	Behavior
Touch Down	Begins defining point C
Drag	Pitchfork updates in real time with C movement
Touch Up	Finalizes annotation and completes creation

Completion

After point C is set, a SCIPitchforkAnnotation is created
The SCIAnnotationCreationModifierBase.annotationCreationCompletionListener callback is invoked
The modifier automatically resets to Idle and is ready for the next pitchfork

Retrieving Annotation Data

After completion, the resulting SCIPitchforkAnnotation contains the defining points of the structure.

You can extract its geometry using base data methods exposed by the annotation:

-[ISCITradingAnnotation getBaseDataValues]

Values correspond to chart axis coordinates
Best for storage, analytics, and reconstruction

-[ISCITradingAnnotation getBasePoints]

Values correspond to rendered screen coordinates
Useful for UI overlays and screen-level calculations

API Reference

Field	Description
`SCIPitchforkCreationModifier.halfWidthZoneFill`	Fill colour for the central (middle) polygon section.
`SCIPitchforkCreationModifier.fullWidthZoneFill`	Fill colour for the two outer polygon sections.
`SCIPitchforkCreationModifier.tineStroke`	The pen style used to draw the four tine lines.
`SCIPitchforkCreationModifier.mainStroke`	The pen style used to draw the main pivot line.
`SCIPitchforkCreationModifier.creationState`	Current state of the pitchfork creation lifecycle.
`-[SCIPitchforkCreationModifier reset]`	Cancels any in-progress gesture and returns the modifier to `Idle`.

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

// Create pitchfork creation modifier
SCIPitchforkCreationModifier *modifier = [SCIPitchforkCreationModifier new];

//Styling
modifier.halfWidthZoneFill = [[SCISolidBrushStyle alloc] initWithColorCode:0x401F9FFF];
modifier.fullWidthZoneFill = [[SCISolidBrushStyle alloc] initWithColorCode:0x40F0FA00];
modifier.tineStroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFF007064 thickness:2];
modifier.mainStroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFF007064 thickness:2];

// Handle completion
__weak typeof(self) weakSelf = self;
modifier.annotationCreationCompletionListener = ^(id _Nonnull createdAnnotation, SCIAnnotationCreationType type) {
  __strong typeof(weakSelf) strongSelf = weakSelf;
  if (!strongSelf) return;
            
  NSLog(@“PITCHFORK annotation created: %@ type %@”, createdAnnotation, SCIAnnotationTypeName(type));
            
  if (![createdAnnotation isKindOfClass:[SCIPitchforkAnnotation class]]) return;
  SCIPitchforkAnnotation *annotation = (SCIPitchforkAnnotation*) createdAnnotation;
            
  /// Get data points
  NSArray *arrPoints = [annotation getBaseDataValues];
            
  NSLog(@“Point A: %@”, arrPoints[0]);
  NSLog(@“Point B: %@”, arrPoints[1]);
  NSLog(@“Point C: %@”, arrPoints[2]);
            
};

// Add to chart
[self.surface.chartModifiers add:modifier];

// Create pitchfork creation modifier
let modifier = SCIPitchforkCreationModifier()


modifier.halfWidthZoneFill = SCISolidBrushStyle(color: 0x401F9FFF)
modifier.fullWidthZoneFill  = SCISolidBrushStyle(color: 0x40F0FA00)
modifier.tineStroke = SCISolidPenStyle(color: 0xFF007064, thickness: 2)
modifier.mainStroke = SCISolidPenStyle(color: 0xFF007064, thickness: 2)
            
// Handle completion
modifier.annotationCreationCompletionListener = { [weak self] createdAnnotation, type in
    guard self != nil else { return }
                
    print(“PITCHFORK annotation created: \(createdAnnotation), type: \(SCIAnnotationTypeName(type))”)
                
    if let annotation = createdAnnotation as? SCIPitchforkAnnotation {
        // Get data points
        let points = annotation.getBaseDataValues()
        print(“Point A: \(points[0])”)
        print(“Point B: \(points[1])”)
        print(“Point C: \(points[2])”)
    }
}

// Add to chart
surface.chartModifiers.add(modifier)

Best Practices

Disable conflicting gesture modifiers during pitchfork creation for smoother interaction
Use SCIAnnotationCreationModifierBase.annotationCreationCompletionListener to persist or analyze completed annotations
Call -[SCIPitchforkCreationModifier reset] when switching tools or exiting drawing mode
Use distinct styling for pitchfork annotations to improve chart readability

Notes

Only one pitchfork is created per interaction cycle
The modifier automatically resets after completion
Designed for financial charting tools where trend structure visualization is required