diff --git a/.jazzy.yaml b/.jazzy.yaml index cd39ab1..2f2bca6 100644 --- a/.jazzy.yaml +++ b/.jazzy.yaml @@ -139,6 +139,10 @@ custom_categories: - Interactivity - SCISeriesSelectionModifier - Legend Modifier - Series Value Modifier + - Trading Annotation - SCIExtendedLineCreationModifier + - Trading Annotation - SCIPitchforkCreationModifier + - Trading Annotation - SCIXabcdCreationModifier + - Trading Annotation - SCIFreehandDrawingModifier - name: Annotations APIs children: @@ -154,6 +158,11 @@ custom_categories: - AxisMarkerCustomAnnotation - CustomAnnotation - CustomGrip + - CompositeAnnotation + - ExtendedLineAnnotation + - PitchforkAnnotation + - XabcdAnnotation + - FreehandDrawingAnnotation # - name: Advanced 2D chart Topics # children: @@ -445,6 +454,7 @@ custom_categories: - SCIExecuteOn - SCIModifierGroup - SCIPlacement + - SCIAnnotationCreationType - SCISelectionMode - SCIShiftTooltipHelper - SCISourceMode @@ -473,6 +483,13 @@ custom_categories: - SCIXAxisDragModifier - SCIYAxisDragModifier + # Gesture Modifiers + - SCIAnnotationCreationModifierBase + - SCIExtendedLineCreationModifier + - SCIPitchforkCreationModifier + - SCIXabcdCreationModifier + - SCIFreehandDrawingModifier + # Series Value Modifier - ISCISeriesValueMarker - ISCISeriesValueMarkerFactory @@ -684,6 +701,18 @@ custom_categories: - SCIAxisMarkerAnnotation - SCIAxisMarkerCustomAnnotation + # Trading Annotations + - ISCITradingAnnotation + - SCITradingAnnotationBase + - SCIElliotWaveAnnotationBase + - ISCIPolyLineAnnotation + - SCIPolyLineAnnotation + - SCICompositeAnnotation + - SCIXabcdAnnotation + - SCIExtendedLineAnnotation + - SCIPitchforkAnnotation + - SCIFreehandDrawingAnnotation + - ISCIAnnotationDragListener - SCIAnnotationIsHiddenChangedListener - SCIAnnotationSelectionChangedListener diff --git a/guides/Annotations API/CompositeAnnotation.md b/guides/Annotations API/CompositeAnnotation.md new file mode 100644 index 0000000..2994643 --- /dev/null +++ b/guides/Annotations API/CompositeAnnotation.md @@ -0,0 +1,173 @@ +# The CompositeAnnotation +A `SCICompositeAnnotation` is a container annotation specific `X1, X2, Y1, Y2` coordinates that allows you to group multiple child annotations and render them as a single logical unit on an SCIChartSurface. Each child annotation can use relative coordinate space (0–1) within the composite bounds, enabling scalable and reusable annotation layouts. +It inherits from SCIBoxAnnotation, meaning it also provides a resizable, draggable rectangular boundary that defines the coordinate space for its children. + +![Composite Annotation](img/annotations/composite-annotation.png) + +> **_NOTE:_** Examples of the **`Annotations`** usage can be found in the [SciChart iOS Examples Suite](https://www.scichart.com/examples/ios-chart/) as well as on [GitHub](https://github.com/ABTSoftware/SciChart.iOS.Examples): +> +> - Composite Annotation - [Obj-C/Swift](https://www.scichart.com/example/ios-chart-chart-composite-annotations-example/) ̰ + +The `SCICompositeAnnotation` class provides the `SCICompositeAnnotation.borderPen` and `SCICompositeAnnotation.fillBrush` properties, which are used for the annotation outline and background and expects the `SCIPenStyle` and `SCIBrushStyle` correspondingly. +To learn more about **Pens** and **Brushes** and how to utilize them, please refer to the [SCIPenStyle, SCIBrushStyle and SCIFontStyle](scipenstyle-scibrushstyle-and-scifontstyle.html) article. + +> **_NOTE:_** To learn more about **Annotations** in general - please see the [Common Annotation Features](Annotations APIs.html#common-annotations-features) article. + +A `SCICompositeAnnotation` is placed on a chart at the position determined by its `[X1, Y1]` and `[X2, Y2]` coordinates, which correspond to the **top-left** and **bottom-right** corners of the drawn rectangle. +Those can be accessed via the following properties: +- `ISCIAnnotation.x1` +- `ISCIAnnotation.y1` +- `ISCIAnnotation.x2` +- `ISCIAnnotation.y2` + +> **_NOTE:_** The **xAxisId** and **yAxisId** must be supplied if you have axis with **non-default** Axis Ids, e.g. in **multi-axis** scenario. + +## Create a CompositeAnnotation +A `SCICompositeAnnotation` can be added onto a chart using the following code: + +
+ + +
+
+// Assume a surface has been created and configured somewhere +id surface; + +// Create a CompositeAnnotation +SCICompositeAnnotation *compositeAnnotation = [SCICompositeAnnotation new]; + +// Allow interaction at runtime +compositeAnnotation.isEditable = YES; + +// In multi-axis scenario, specify axis IDs +compositeAnnotation.xAxisId = TopAxisId; +compositeAnnotation.yAxisId = LeftAxisId; + +// Parent bounding box (chart coordinates) +// Defines the area where all child annotations live +[compositeAnnotation setX1:@(185.0)]; +[compositeAnnotation setY1:@(12300.0)]; +[compositeAnnotation setX2:@(210.0)]; +[compositeAnnotation setY2:@(11100.0)]; + +// Fill color for composite background +compositeAnnotation.fillBrush = [[SCISolidBrushStyle alloc] initWithColorCode:0x33FF69BD]; + +// Optional: border styling (inherits from SCIBoxAnnotation) +compositeAnnotation.borderPen = [[SCISolidPenStyle alloc] initWithColorCode:0x99FF69BD thickness:2]; + + +// Child Annotations (RELATIVE SPACE) + +// Center Text Annotation +SCITextAnnotation *textAnnotationCenter = [SCITextAnnotation new]; + +// IMPORTANT: relative coordinate system (0 → 1 inside composite) +textAnnotationCenter.coordinateMode = SCIAnnotationCoordinateMode_Relative; + +// Position at center of composite +[textAnnotationCenter setX1:@(0.5)]; +[textAnnotationCenter setY1:@(0.5)]; + +textAnnotationCenter.text = @"Center\n(0.5, 0.5)"; +textAnnotationCenter.fontStyle = [[SCIFontStyle alloc] initWithFontSize:14 andTextColor:SCIColor.whiteColor]; + + +// Diagonal Line Annotation +SCILineAnnotation *lineAnnotation = [SCILineAnnotation new]; + +// Relative coordinates inside composite bounds +lineAnnotation.coordinateMode = SCIAnnotationCoordinateMode_Relative; + +// Draw diagonal line +[lineAnnotation setX1:@(0.2)]; +[lineAnnotation setY1:@(0.2)]; +[lineAnnotation setX2:@(0.8)]; +[lineAnnotation setY2:@(0.8)]; + +lineAnnotation.stroke = + [[SCISolidPenStyle alloc] initWithColor:SCIColor.whiteColor thickness:2]; + + +// Add child annotations to composite +compositeAnnotation.annotations = + [[SCIAnnotationCollection alloc] initWithCollection:@[ + textAnnotationCenter, + lineAnnotation + ]]; + + +// Add composite annotation to surface +[self.surface.annotations add:compositeAnnotation]; +
+
+// Assume a surface has been created and configured somewhere +let surface: ISCIChartSurface + +// Create a CompositeAnnotation +let compositeAnnotation = SCICompositeAnnotation() + +// Allow to interact with the annotation in run-time +compositeAnnotation.isEditable = true + +// In a multi-axis scenario, specify the XAxisId and YAxisId +compositeAnnotation.xAxisId = "TopAxisId" +compositeAnnotation.yAxisId = "LeftAxisId" + +// Specify a desired position by setting coordinates (parent bounding box) +// This defines the area in chart coordinates where all child annotations will live +compositeAnnotation.set(x1: 185.0) +compositeAnnotation.set(y1: 12300.0) +compositeAnnotation.set(x2: 210.0) +compositeAnnotation.set(y2: 11100.0) + +// Specify the fill color for the composite container (background box) +compositeAnnotation.fillBrush = SCISolidBrushStyle(color: 0x33FF69BD) + +// Optionally: border styling (since it inherits from SCIBoxAnnotation) +compositeAnnotation.borderPen = SCISolidPenStyle(color: 0x99FF69BD, thickness: 2) + + +// Child Annotations (ALL use relative coordinate space) + +// Center Text Annotation +let textAnnotationCenter = SCITextAnnotation() + +// IMPORTANT: child annotations use relative coordinates (0 → 1) +textAnnotationCenter.coordinateMode = .relative + +// Position inside composite (center) +textAnnotationCenter.set(x1: 0.5) +textAnnotationCenter.set(y1: 0.5) + +textAnnotationCenter.text = "Center\n(0.5, 0.5)" +textAnnotationCenter.fontStyle = SCIFontStyle(fontSize: 14, andTextColor: SCIColor.white) + + +// Diagonal Line Annotation +let lineAnnotation = SCILineAnnotation() + +// Relative coordinates inside composite bounds +lineAnnotation.coordinateMode = .relative + +// Draw a diagonal line across the composite area +lineAnnotation.set(x1: 0.2) +lineAnnotation.set(y1: 0.2) +lineAnnotation.set(x2: 0.8) +lineAnnotation.set(y2: 0.8) + +lineAnnotation.stroke = SCISolidPenStyle(color: SCIColor.white, thickness: 2) + + +// Add child annotations to composite +compositeAnnotation.annotations = + SCIAnnotationCollection(collection: [ + textAnnotationCenter, + lineAnnotation +]) + + +// Add composite to surface +self.surface.annotations.add(items: compositeAnnotation) +
+> **_NOTE:_** To learn more about other **Annotation Types**, available out of the box in SciChart, please find the comprehensive list in the [Annotation APIs](Annotations APIs.html) article. diff --git a/guides/Annotations API/ExtendedLineAnnotation.md b/guides/Annotations API/ExtendedLineAnnotation.md new file mode 100644 index 0000000..05bfa3e --- /dev/null +++ b/guides/Annotations API/ExtendedLineAnnotation.md @@ -0,0 +1,153 @@ +# The SCIExtendedLineAnnotation +The `SCIExtendedLineAnnotation` is a specialized line annotation for iOS charts that can extend infinitely in one or both directions beyond its defined endpoints. It is commonly used in trading and technical analysis to project trendlines, support/resistance levels, or extended guides across the chart surface. + +![Extended Line Annotation](img/annotations/extended-line-annotation.png) + +> **_NOTE:_** Examples of the **`Annotations`** usage can be found in the [SciChart iOS Examples Suite](https://www.scichart.com/examples/ios-chart/) as well as on [GitHub](https://github.com/ABTSoftware/SciChart.iOS.Examples): +> + +## Structure and Points +The SCIExtendedLineAnnotation is defined by two anchor points: +- Point 1 (Start): The starting anchor of the line. +- Point 2 (End): The ending anchor of the line. + +## Behavior +- The line is drawn between Point 1 and Point 2. +- Depending on the extendStart and extendEnd flags, the line may be projected infinitely beyond either or both anchor points. +- The four extension modes are summarized in the table below: + +| extendStart | extendEnd | Behavior | +| ----------- | --------- | ---------------------------------------------------------------- | +| YES | YES | Line extends infinitely in both directions. | +| NO | YES | Line extends infinitely forward from the end point only. | +| YES | NO | Line extends infinitely backward from the start point only. | +| NO | NO | Line is drawn only between the two anchor points (default line). | + +The SCIExtendedLineAnnotation can be configured using the properties listed in the table below: + +| **Field** | **Description** | +| --------------------------------------- | --------------------------------------------------------------------------- | +| `SCIExtendedLineAnnotation.extendStart` | When YES, the line is projected infinitely backward beyond the start point. | +| `SCIExtendedLineAnnotation.extendEnd` | When YES, the line is projected infinitely forward beyond the end point. | | + + +Points for a SCIExtendedLineAnnotation are defined using the set(x1:), set(y1:), set(x2:), set(y2:) methods inherited from SCILineAnnotationBase. The extension direction is then controlled independently via the extendStart and extendEnd flags. + +> **_NOTE:_** To learn more about **Annotations** in general - please see the [Common Annotation Features](Annotations APIs.html#common-annotations-features) article. + +## Create an ExtendedLineAnnotation +A `SCIExtendedLineAnnotation` can be added onto a chart using the following code: + +
+ + +
+
+// Assume a surface has been created and configured somewhere +id surface; + +// Infinite Line: extends in both directions across the entire chart +SCIExtendedLineAnnotation *extendedLine = [SCIExtendedLineAnnotation new]; +[extendedLine setX1:@10]; +[extendedLine setY1:@11600]; +[extendedLine setX2:@100]; +[extendedLine setY2:@12400]; + +// Extend in both directions +extendedLine.extendStart = YES; +extendedLine.extendEnd = YES; + +// Enable interaction +extendedLine.isEditable = YES; +extendedLine.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFFFFFFF thickness:3.0]; + +// Forward Ray: extends the line beyond the end point only +SCIExtendedLineAnnotation *forwardLine = [SCIExtendedLineAnnotation new]; +[forwardLine setX1:@64]; +[forwardLine setY1:@12000]; +[forwardLine setX2:@70]; +[forwardLine setY2:@11600]; + +// Extend forward beyond x2 only +forwardLine.extendStart = NO; +forwardLine.extendEnd = YES; + +// Enable interaction +forwardLine.isEditable = YES; +forwardLine.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFFFFFFF thickness:3.0]; + +// Backward Ray: extends the line behind the start point only +SCIExtendedLineAnnotation *backwardLine = [SCIExtendedLineAnnotation new]; +[backwardLine setX1:@30]; +[backwardLine setY1:@12200]; +[backwardLine setX2:@64]; +[backwardLine setY2:@12100]; + +// Extend backward behind x1, do not extend forward +backwardLine.extendStart = YES; +backwardLine.extendEnd = NO; + +// Enable interaction +backwardLine.isEditable = YES; +backwardLine.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFFFFFFF thickness:3.0]; + +// Add to chart surface +[self.surface.annotations addAll:extendedLine, backwardLine, forwardLine, nil]; +
+
+// Assume a surface has been created and configured somewhere +let surface: ISCIChartSurface + +// Infinite Line: extends in both directions across the entire chart +let extendedLine = SCIExtendedLineAnnotation() +extendedLine.set(x1: 10) +extendedLine.set(y1: 11600) +extendedLine.set(x2: 100) +extendedLine.set(y2: 12400) + +// Extend in both directions +extendedLine.extendStart = true +extendedLine.extendEnd = true + +// Enable interaction +extendedLine.isEditable = true +extendedLine.stroke = SCISolidPenStyle(color: 0xFFFFFFFF, thickness: 3) + +// Forward Ray: extends the line beyond the end point only +let forwardLine = SCIExtendedLineAnnotation() +forwardLine.set(x1: 64) +forwardLine.set(y1: 12000) +forwardLine.set(x2: 70) +forwardLine.set(y2: 11600) + +// Extend forward beyond x2 only +forwardLine.extendStart = false +forwardLine.extendEnd = true + +// Enable interaction +forwardLine.isEditable = true +forwardLine.stroke = SCISolidPenStyle(color: 0xFFFFFFFF, thickness: 3) + +// Backward Ray: extends the line behind the start point only +let backwardLine = SCIExtendedLineAnnotation() +backwardLine.set(x1: 30) +backwardLine.set(y1: 12200) +backwardLine.set(x2: 64) +backwardLine.set(y2: 12100) + +// Extend backward behind x1, do not extend forward +backwardLine.extendStart = true +backwardLine.extendEnd = false + +// Enable interaction +backwardLine.isEditable = true +backwardLine.stroke = SCISolidPenStyle(color: 0xFFFFFFFF, thickness: 3) + +// Add to chart surface +self.surface.annotations.add(items: extendedLine, backwardLine, forwardLine) + +
+ +> **_NOTE:_** For interactive creation of `SCIExtendedLineAnnotation`, use the corresponding annotation creation modifier [SCIExtendedLineCreationModifier](trading-annotation---sciextendedlinecreationmodifier.html) available in SciChart iOS. + +> **_NOTE:_** To learn more about other **Annotation Types**, available out of the box in SciChart, please find the comprehensive list in the [Annotation APIs](Annotations APIs.html) article. diff --git a/guides/Annotations API/FreehandDrawingAnnotation.md b/guides/Annotations API/FreehandDrawingAnnotation.md new file mode 100644 index 0000000..9ab5e0c --- /dev/null +++ b/guides/Annotations API/FreehandDrawingAnnotation.md @@ -0,0 +1,82 @@ +# The SCIFreehandDrawingAnnotation +he `SCIFreehandDrawingAnnotation` allows for freehand drawing directly on the chart surface by capturing a sequence of points that form a continuous brush stroke. + +![Freehand Drawing Annotation](img/annotations/freehand-drawing-annotation.png) + +> **_NOTE:_** Examples of the **`Annotations`** usage can be found in the [SciChart iOS Examples Suite](https://www.scichart.com/examples/ios-chart/) as well as on [GitHub](https://github.com/ABTSoftware/SciChart.iOS.Examples): +> +> - Freehand Drawing Annotation - [Obj-C/Swift](https://www.scichart.com/example/ios-chart-chart-freehand-drawing-annotations-example/) ̰ + +A `SCIFreehandDrawingAnnotation` is a multi-point annotation that stores a collection of points to represent a freehand path drawn by the user. + +The SCIFreehandDrawingAnnotation can be configured using the properties and method listed in the table below: + +| **Field** | **Description** | +| ---------------------------------------------- | ---------------------------------------------------------- | +| `SCIFreehandDrawingAnnotation.stroke` | Defines the stroke style (color and thickness) of the pen. | +| `SCIFreehandDrawingAnnotation.drawId` | A unique identifier for the annotation instance. | +| `SCIFreehandDrawingAnnotation.selectionOffset` | Extra padding applied around the selection bounds. | + +To learn more about **Pens** and **Brushes** and how to utilize them, please refer to the [SCIPenStyle, SCIBrushStyle](scipenstyle-scibrushstyle-and-scifontstyle.html) article. + +> **_NOTE:_** To learn more about **Annotations** in general - please see the [Common Annotation Features](Annotations APIs.html#common-annotations-features) article. + +## Adding Points +Points for a `SCIFreehandDrawingAnnotation` are defined sequentially using the `[appendPointWithX:y:]` method, which appends each new coordinate to the existing path to form a continuous freehand stroke. +The `clearPoints` method can be used to remove all previously added points, resetting the annotation so that it no longer renders until new points are appended. + +> **_NOTE:_** The **xAxisId** and **yAxisId** must be supplied if you have axis with **non-default** Axis Ids, e.g. in **multi-axis** scenario. + +## Create a FreehandDrawingAnnotation +A `SCIFreehandDrawingAnnotation` can be added onto a chart using the following code: + +
+ + +
+
+// Assume a surface has been created and configured somewhere +id surface; + +SCIFreehandDrawingAnnotation *freehandDrawing = [SCIFreehandDrawingAnnotation new]; + +// Append points for the path +[freehandDrawing appendPointWithX:@(224) y:@(11000)]; +[freehandDrawing appendPointWithX:@(250) y:@(12000)]; +[freehandDrawing appendPointWithX:@(220) y:@(11400)]; +[freehandDrawing appendPointWithX:@(224) y:@(11000)]; + +// Customize appearance +freehandDrawing.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFFF0000 thickness:3]; + +// Enable interaction +freehandDrawing.isEditable = YES; + +// Add to chart surface +[surface.annotations add: freehandDrawing]; +
+
+// Assume a surface has been created and configured somewhere +let surface: ISCIChartSurface + +let freehandDrawing = SCIFreehandDrawingAnnotation() + +// Append points for the path +freehandDrawing.appendPointWith(x: NSNumber(value: 224), y: NSNumber(value: 11000)) +freehandDrawing.appendPointWith(x: NSNumber(value: 250), y: NSNumber(value: 12000)) +freehandDrawing.appendPointWith(x: NSNumber(value: 220), y: NSNumber(value: 11400)) +freehandDrawing.appendPointWith(x: NSNumber(value: 224), y: NSNumber(value: 11000)) + +// Customize appearance +freehandDrawing.stroke = SCISolidPenStyle(color: SCIColor.red, thickness: 3) + +// Enable interaction +freehandDrawing.isEditable = true + +// Add to chart surface +surface.annotations.add(freehandDrawing) +
+ +> **_NOTE:_** For interactive creation of SCIFreehandDrawingAnnotation, use the corresponding annotation creation modifier [SCIFreehandDrawingModifier](trading-annotation---sciFreehandDrawingModifier.html) available in SciChart iOS. + +> **_NOTE:_** To learn more about other **Annotation Types**, available out of the box in SciChart, please find the comprehensive list in the [Annotation APIs](Annotations APIs.html) article. diff --git a/guides/Annotations API/PitchforkAnnotation.md b/guides/Annotations API/PitchforkAnnotation.md new file mode 100644 index 0000000..c6b8acf --- /dev/null +++ b/guides/Annotations API/PitchforkAnnotation.md @@ -0,0 +1,90 @@ +# The SCIPitchforkAnnotation +The `SCIPitchforkAnnotation` (also known as Andrew’s Pitchfork) is a specialized trading annotation for iOS charts that uses three points to visualize potential support and resistance levels. It consists of a median line and two parallel outer lines (tines), forming a "pitchfork" shape. It supports interactive grips for dragging, polygon fills for highlighting regions, and customizable stroke/fill styles. + +![Pitchfork Annotation](img/annotations/pitchfork-annotation.png) + +> **_NOTE:_** Examples of the **`Annotations`** usage can be found in the [SciChart iOS Examples Suite](https://www.scichart.com/examples/ios-chart/) as well as on [GitHub](https://github.com/ABTSoftware/SciChart.iOS.Examples): +> +> - Composite Annotation - [Obj-C/Swift](https://www.scichart.com/example/ios-chart-chart-composite-annotations-example/) ̰ + +## Structure and Points +The SCIPitchforkAnnotation is defined by three base points: +- Point 0 (Handle / Pivot): The starting point of the median line. +- Point 1 (Upper): The first point defining the outer boundary. +- Point 2 (Lower): The second point defining the outer boundary. + +## Behavior +- The median line begins at Point 0 and passes through the midpoint between Point 1 and Point 2. +- Two additional lines (tines) are drawn parallel to the median line, originating from Point 1 and Point 2. +- The space between these lines can be filled to highlight trading zones. + +The SCIPitchforkAnnotation can be configured using the properties and method listed in the table below: + +| **Field** | **Description** | +| ------------------------------------------ | --------------------------------------------------------------------------------- | +| `SCIPitchforkAnnotation.tineStroke` | Defines the SCIPenStyle used to draw the pitchfork lines (outer 4 tines). | +| `SCIPitchforkAnnotation.halfWidthZoneFill` | Defines the SCIBrushStyle used to fill the central region around the median line. | +| `SCIPitchforkAnnotation.fullWidthZoneFill` | Defines the SCIBrushStyle used to fill the outer regions on either side. | + + +To learn more about **Pens** and **Brushes** and how to utilize them, please refer to the [SCIPenStyle, SCIBrushStyle](scipenstyle-scibrushstyle-and-scifontstyle.html) article. + +> **_NOTE:_** To learn more about **Annotations** in general - please see the [Common Annotation Features](Annotations APIs.html#common-annotations-features) article. + +Points for a `SCIPitchforkAnnotation` are defined sequentially using the setBasePointWithX(:y) method. The median line is drawn from the first point through the midpoint between the second and third points. Two additional parallel lines (tines) extend from the second and third points, forming the characteristic pitchfork structure. + +> **_NOTE:_** The **xAxisId** and **yAxisId** must be supplied if you have axis with **non-default** Axis Ids, e.g. in **multi-axis** scenario. + +## Create a PitchforkAnnotation +A `SCIPitchforkAnnotation` can be added onto a chart using the following code: + +
+ + +
+
+// Assume a surface has been created and configured somewhere +id surface; + +SCIPitchforkAnnotation *pitchfork = [[SCIPitchforkAnnotation alloc] init]; + +// Define base points (pivot, upper, lower) +[pitchfork setBasePointWithX:@224 y:@11000]; +[pitchfork setBasePointWithX:@250 y:@11300]; +[pitchfork setBasePointWithX:@228 y:@11600]; + +// Customize appearance +pitchfork.halfWidthZoneFill = [[SCISolidBrushStyle alloc] initWithColorCode:0x401E90FF]; +pitchfork.fullWidthZoneFill = [[SCISolidBrushStyle alloc] initWithColorCode:0x4000AA00]; + +// Enable interaction +pitchfork.isEditable = YES; + +// Add to chart surface +[surface.annotations add: pitchfork]; +
+
+// Assume a surface has been created and configured somewhere +let surface: ISCIChartSurface + +let pitchfork = SCIPitchforkAnnotation() + +// Define base points (pivot, upper, lower) +pitchfork.setBasePointWithX(NSNumber(value: 224), y: NSNumber(value: 11000)) +pitchfork.setBasePointWithX(NSNumber(value: 250), y: NSNumber(value: 11300)) +pitchfork.setBasePointWithX(NSNumber(value: 228), y: NSNumber(value: 11600)) + +// Customize appearance +pitchfork.halfWidthZoneFill = SCISolidBrushStyle(color: 0x401E90FF) +pitchfork.fullWidthZoneFill = SCISolidBrushStyle(color: 0x4000AA00) + +// Enable interaction +pitchfork.isEditable = true + +// Add to chart surface +surface.annotations.add(pitchfork) +
+ +> **_NOTE:_** For interactive creation of SCIPitchforkAnnotation, use the corresponding annotation creation modifier [SCIPitchforkCreationModifier](trading-annotation---scipitchforkcreationmodifier.html) available in SciChart iOS. + +> **_NOTE:_** To learn more about other **Annotation Types**, available out of the box in SciChart, please find the comprehensive list in the [Annotation APIs](Annotations APIs.html) article. diff --git a/guides/Annotations API/XabcdAnnotation.md b/guides/Annotations API/XabcdAnnotation.md new file mode 100644 index 0000000..02dd99e --- /dev/null +++ b/guides/Annotations API/XabcdAnnotation.md @@ -0,0 +1,103 @@ +# The SCIXabcdAnnotation +The SCIXabcdAnnotation is a specialized multi-point trading annotation used to draw harmonic patterns such as Gartley, Butterfly, Bat, and Crab. These patterns consist of five key points: X, A, B, C, and D, which help identify potential reversal zones in financial charts. + +![Xabcd Annotation](img/annotations/xabcd-annotation.png) + +> **_NOTE:_** Examples of the **`Annotations`** usage can be found in the [SciChart iOS Examples Suite](https://www.scichart.com/examples/ios-chart/) as well as on [GitHub](https://github.com/ABTSoftware/SciChart.iOS.Examples): +> +> - Xabcd Annotation - [Obj-C/Swift](https://www.scichart.com/example/ios-chart-chart-trading-annotations-example/) ̰ + +The `SCICompositeAnnotation` class provides the `SCICompositeAnnotation.borderPen` and `SCICompositeAnnotation.fillBrush` properties, which are used for the annotation outline and background and expects the `SCIPenStyle` and `SCIBrushStyle` correspondingly. +To learn more about **Pens** and **Brushes** and how to utilize them, please refer to the [SCIPenStyle, SCIBrushStyle and SCIFontStyle](scipenstyle-scibrushstyle-and-scifontstyle.html) article. + +> **_NOTE:_** To learn more about **Annotations** in general - please see the [Common Annotation Features](Annotations APIs.html#common-annotations-features) article. + +## Structure and Points +The SCIXabcdAnnotation is defined by five base points, added sequentially using the setBasePointWithX(:y) method: +- Point 0 (X): Starting point of the pattern +- Point 1 (A): First leg of the pattern +- Point 2 (B): Retracement from A +- Point 3 (C): Extension from B +- Point 4 (D): Final point completing the harmonic structure +kDPointIndex = 4 indicates the index of the final D point. + +## Behavior +- Lines are drawn between XA, AB, BC, and CD. +- Additional helper (often dashed) lines may connect XB, AC, BD, and XD. +- Two filled regions are typically formed: + * Triangle XAB + * Triangle BCD + +The SCIXabcdAnnotation can be configured using the properties and method listed in the table below: + +| **Field** | **Description** | +| ------------------------------- | ------------------------------------------------------------------------- | +| `SCIXabcdAnnotation.showRatios` | Determines whether calculated harmonic ratios are displayed on the chart. | + + +## Define Points +Points are added sequentially using `[annotation setBasePointWithX: y:];`. Each call adds the next point in order (X → A → B → C → D). +The annotation is fully formed once all five points are provided. + + +> **_NOTE:_** The **xAxisId** and **yAxisId** must be supplied if you have axis with **non-default** Axis Ids, e.g. in **multi-axis** scenario. + +## Create a XabcdAnnotation +A `SCIXabcdAnnotation` can be added onto a chart using the following code: + +
+ + +
+
+// Assume a surface has been created and configured somewhere +id surface; + +SCIXabcdAnnotation *xAbcdAnn = [[SCIXabcdAnnotation alloc] init]; + +// Define points (X, A, B, C, D) +[xAbcdAnn setBasePointWithX:@224 y:@7]; // X +[xAbcdAnn setBasePointWithX:@230 y:@4]; // A +[xAbcdAnn setBasePointWithX:@235 y:@5]; // B +[xAbcdAnn setBasePointWithX:@240 y:@6]; // C +[xAbcdAnn setBasePointWithX:@245 y:@7]; // D + +// Customize appearance +xAbcdAnn.fillBrush = [[SCISolidBrushStyle alloc] initWithColorCode:0x55AAAA00]; +xAbcdAnn.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFe97064 thickness:2.0]; + +// Enable interaction and ratios +xAbcdAnn.isEditable = YES; +xAbcdAnn.showRatios = YES; + +// Add to chart surface +[self.surface.annotations add:xAbcdAnn]; +
+
+// Assume a surface has been created and configured somewhere +let surface: ISCIChartSurface + +let xAbcdAnn = SCIXabcdAnnotation() + +// Add points +xAbcdAnn.setBasePointWithX(NSNumber(value: 224), y: NSNumber(value: 7)) // X +xAbcdAnn.setBasePointWithX(NSNumber(value: 230), y: NSNumber(value: 4)) // A +xAbcdAnn.setBasePointWithX(NSNumber(value: 235), y: NSNumber(value: 5)) // B +xAbcdAnn.setBasePointWithX(NSNumber(value: 240), y: NSNumber(value: 6)) // C +xAbcdAnn.setBasePointWithX(NSNumber(value: 245), y: NSNumber(value: 7)) // D + +// Customize appearance +xAbcdAnn.fillBrush = SCISolidBrushStyle(color: 0x55AAAA00) +xAbcdAnn.stroke = SCISolidPenStyle(color: 0xFFe97064, thickness: 2) + +// Enable interaction and ratios +xAbcdAnn.isEditable = true +xAbcdAnn.showRatios = true + +// Add to chart surface +self.surface.annotations.add(items: xAbcdAnn) +
+ +> **_NOTE:_** For interactive creation of SCIXabcdAnnotation, use the corresponding annotation creation modifier [SCIXabcdCreationModifier](trading-annotation---scixabcdcreationmodifier.html) available in SciChart iOS. + +> **_NOTE:_** To learn more about other **Annotation Types**, available out of the box in SciChart, please find the comprehensive list in the [Annotation APIs](Annotations APIs.html) article. diff --git a/guides/Chart Modifier API/Trading Annotation - SCIExtendedLineCreationModifier.md b/guides/Chart Modifier API/Trading Annotation - SCIExtendedLineCreationModifier.md new file mode 100644 index 0000000..34417be --- /dev/null +++ b/guides/Chart Modifier API/Trading Annotation - SCIExtendedLineCreationModifier.md @@ -0,0 +1,132 @@ +# SCIExtendedLineCreationModifier +The `SCIExtendedLineCreationModifier` is a custom gesture modifier used for interactive creation of Extended Line annotations on a SciChart surface. It enables users to define a line with two anchor points using a pan gesture workflow, with options to extend the line forward, backward, or both directions beyond its anchors. + +## Overview +The modifier manages the full lifecycle of extended line creation: + +- Two-step gesture interaction (A → B) +- Real-time rendering while dragging points +- Automatic annotation finalization after point B is set +- Immediate reset for continuous creation of multiple extended lines +- Configurable line extension behavior (both directions, forward, backward, or none) + +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. + +### Gesture Flow (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 | + +### Completion + +- After point **B** is set, a `SCIExtendedLineAnnotation` is created +- The `annotationCreationCompletionListener` callback is invoked +- The modifier automatically resets to Idle and is ready for the next line + +## Retrieving Annotation Data + +After completion, the resulting `SCIExtendedLineAnnotation` provides direct access to its defining anchor points in data space. + +### Point Accessors +getX1() / getY1() and getX2() / getY2() +Returns the first anchor point (A) and the second anchor point (B) in data coordinates. +Values correspond to the chart’s X‑Axis and Y‑Axis units. + +## API Reference + +| **Field** | **Description** | +| ------------------------------------------------------------------------ | ------------------------------------------------------------------- | +| `SCIExtendedLineCreationModifier.stroke` | Pen style used to draw the extended line. | +| `SCIExtendedLineCreationModifier.extendStart` | Boolean flag controlling backward extension of the line. | +| `SCIExtendedLineCreationModifier.extendEnd` | Boolean flag controlling forward extension of the line. | +| `SCIExtendedLineCreationModifier.reset()` | Cancels any in‑progress gesture and returns the modifier to Idle. | +| `SCIAnnotationCreationModifierBase.xAxisId` | ID of the X‑Axis the annotation is draw against. | +| `SCIAnnotationCreationModifierBase.yAxisId`. | ID of the Y‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.tag` | Custom tag identifier for the modifier. | +| `SCIAnnotationCreationModifierBase.annotationCreationCompletionListener` | Callback invoked when a full extended line annotation is completed. | + + +## Usage Example + +
+ + +
+ +
+ +// Create extended line creation modifier +SCIExtendedLineCreationModifier *modifier = [SCIExtendedLineCreationModifier new]; + +// Configure extension behavior +modifier.extendStart = YES; +modifier.extendEnd = YES; + +// Set the stroke style +modifier.stroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFE97064 thickness:2]; + +// Handle completion +modifier.annotationCreationCompletionListener = ^(id _Nonnull createdAnnotation, SCIAnnotationCreationType type) { + __strong typeof(weakSelf) strongSelf = weakSelf; + if (!strongSelf) return; + + NSLog(@"ExtendedLine annotation created: %@ type %@", createdAnnotation, SCIAnnotationTypeName(type)); + + if (![createdAnnotation isKindOfClass:[SCIExtendedLineAnnotation class]]) return; + SCIExtendedLineAnnotation *annotation = (SCIExtendedLineAnnotation *)createdAnnotation; + + double x1Point = annotation.x1.toDouble; + double x2Point = annotation.x2.toDouble; + double y1Point = annotation.y1.toDouble; + double y2Point = annotation.y1.toDouble; + NSLog(@"Point A: %f, %f", x1Point, y1Point); + NSLog(@"Point B: %f, %f", x2Point, y2Point); +}; + +// Add to chart +[self.surface.chartModifiers add:modifier]; + +
+ +
+ +// Create extended line creation modifier +let modifier = SCIExtendedLineCreationModifier() + +// Configure extension behavior +modifier.extendStart = true +modifier.extendEnd = true + +// Set the stroke style +modifier.stroke = SCISolidPenStyle(color: 0xFFE97064, thickness: 2) + +// Handle completion +modifier.annotationCreationCompletionListener = { [weak self] createdAnnotation, type in + guard self != nil else { return } + + print("Annotation created: \(createdAnnotation), type: \(SCIAnnotationTypeName(type))") + + guard let annotation = createdAnnotation as? SCIExtendedLineAnnotation else { return } + let x1Point: Double = annotation.getX1() + let y1Point: Double = annotation.getY1() + let x2Point: Double = annotation.getX2() + let y2Point: Double = annotation.getY2() + + print("point =\(x1Point) \(x2Point)") + print("point =\(y1Point) \(y2Point)") +} + +
+ +## Best Practices + +- Disable conflicting gesture modifiers during extended line creation for smoother interaction +- Use `annotationCreationCompletionListener` to persist or analyze completed annotations +- Call `reset()` when switching tools or exiting drawing mode +- Configure extendStart and extendEnd to match the desired line extension behavior \ No newline at end of file diff --git a/guides/Chart Modifier API/Trading Annotation - SCIFreehandDrawingModifier.md b/guides/Chart Modifier API/Trading Annotation - SCIFreehandDrawingModifier.md new file mode 100644 index 0000000..0e9299b --- /dev/null +++ b/guides/Chart Modifier API/Trading Annotation - SCIFreehandDrawingModifier.md @@ -0,0 +1,100 @@ +# The SCIFreehandDrawingModifier +The `SCIFreehandDrawingModifier` is a gesture modifier that enables freehand drawing directly on a SciChartSurface. + +![Freehand Drawing Modifier](img/annotations/freehand-drawing-modifier.png) + +> **_NOTE:_** Examples of the **`Annotations`** usage can be found in the [SciChart iOS Examples Suite](https://www.scichart.com/examples/ios-chart/) as well as on [GitHub](https://github.com/ABTSoftware/SciChart.iOS.Examples): +> +> - Freehand Drawing Modifier - [Obj-C/Swift](https://www.scichart.com/example/ios-chart-chart-freehand-drawing-modifier-example/) ̰ + +## 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. | +| `SCIAnnotationCreationModifierBase.xAxisId` | ID of the X‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.yAxisId` | ID of the Y‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.tag` | Custom tag identifier for the modifier. | +| `SCIAnnotationCreationModifierBase.annotationCreationCompletionListener` | A callback invoked when a drawing annotation is completed. | + + +To learn more about **Pens** and **Brushes** and how to utilize them, please refer to the [SCIPenStyle, SCIBrushStyle and SCIFontStyle](scipenstyle-scibrushstyle-and-scifontstyle.html) article. + +> **_NOTE:_** To learn more about **Annotations** in general - please see the [Common Annotation Features](Annotations APIs.html#common-annotations-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); +}; + +// 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)") + } +} + +// 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](Annotations APIs.html) article. diff --git a/guides/Chart Modifier API/Trading Annotation - SCIPitchforkCreationModifier.md b/guides/Chart Modifier API/Trading Annotation - SCIPitchforkCreationModifier.md new file mode 100644 index 0000000..54af3a6 --- /dev/null +++ b/guides/Chart Modifier API/Trading Annotation - SCIPitchforkCreationModifier.md @@ -0,0 +1,168 @@ +# 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 (C) + +| 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 `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: + +### getBaseDataValues() + +- Returns pitchfork anchor points in **data space** +- Values correspond to chart axis coordinates +- Best for storage, analytics, and reconstruction + +### getBasePoints() + +- Returns pitchfork points in **pixel space** +- 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`. | +| `SCIAnnotationCreationModifierBase.xAxisId` | ID of the X‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.yAxisId` | ID of the Y‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.tag` | Custom tag identifier for the modifier. | +| `SCIAnnotationCreationModifierBase.annotationCreationCompletionListener` | A callback invoked when a full pitchfork annotation is completed. | + +## 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 `annotationCreationCompletionListener` to persist or analyze completed annotations +- Call `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 diff --git a/guides/Chart Modifier API/Trading Annotation - SCIXabcdCreationModifier.md b/guides/Chart Modifier API/Trading Annotation - SCIXabcdCreationModifier.md new file mode 100644 index 0000000..aa693e4 --- /dev/null +++ b/guides/Chart Modifier API/Trading Annotation - SCIXabcdCreationModifier.md @@ -0,0 +1,146 @@ +# SCIXabcdCreationModifier +The `SCIXabcdCreationModifier` is a custom gesture modifier used for interactive creation of **XABCD annotations** on a SciChart surface. + +It enables users to place five key points (X → A → B → C → D) using touch gestures, with real-time visual feedback during placement. + +## Overview +The modifier handles the full lifecycle of XABCD annotation creation: + +- Sequential point placement via touch interaction +- Real-time dragging feedback for each point +- Automatic completion after the final point (D) +- Immediate reset for continuous drawing + +Once completed, the annotation remains on the chart and a callback is triggered. + +## Interaction Behavior + +The creation flow follows a structured sequence: + +### Per Point Interaction (X → A → B → C → D) + +| Gesture | Behavior | +| -------------- | ---------------------------------------------- | +| **Touch Down** | Places the current point at the touch location | +| **Drag** | Moves the point dynamically in real-time | +| **Touch Up** | Locks the point and advances to the next one | + +### Completion + +- After placing point **D**, the annotation is finalized +- The `annotationCreationCompletionListener` callback is invoked +- The modifier resets immediately, ready for a new annotation + +![Xabcd Annotation](img/annotations/xabcd-annotation.png) + +## Retrieving Annotation Points After Drawing Completion +After an annotation drawing is completed, you can retrieve its underlying points using: +getBaseDataValues() +getBasePoints() +Both methods return the annotation’s defining points, but in different coordinate spaces. + +### getBaseDataValues() +- Returns the annotation points in data space (axis values). +- X and Y values correspond to the chart’s actual data coordinates +- Independent of pixel resolution or screen scaling +- Useful for storing, analysis, or reloading annotations + +### getBasePoints() +- Returns annotation points in pixel space (rendered screen coordinates). +- X and Y values correspond to screen pixels +- Useful for rendering overlays or UI alignment + +## Usage Example +
+ + +
+
+// Create a new XABCD creation modifier instance +SCIXabcdCreationModifier *modifier = [SCIXabcdCreationModifier new]; + +// Set the stroke (outline) style for the XABCD annotation lines +modifier.annotationStroke = [[SCISolidPenStyle alloc] initWithColorCode:0xFFE97064 thickness:2]; + +// Set the fill style for the annotation +modifier.annotationFill = [[SCISolidBrushStyle alloc] initWithColorCode:0x55AAAA00]; + +// Callback triggered when the user completes placing all 5 points (X, A, B, C, D) +// Provides access to the fully created annotation object +__weak typeof(self) weakSelf = self; +modifier.annotationCreationCompletionListener = ^(id _Nonnull createdAnnotation, SCIAnnotationCreationType type) { + __strong typeof(weakSelf) strongSelf = weakSelf; + if (!strongSelf) return; + + NSLog(@"XABCD annotation created: %@ type %@", createdAnnotation, SCIAnnotationTypeName(type)); + + if (![createdAnnotation isKindOfClass:[SCIXabcdAnnotation class]]) return; + + SCIXabcdAnnotation *xabcd = (SCIXabcdAnnotation *)createdAnnotation; + NSArray *points = [xabcd getBaseDataValues]; + + // Get data points + // Index mapping: 0 = X, 1 = A, 2 = B, 3 = C, 4 = D + NSLog(@"[XABCD] X: date=%@ price=%@", points[0].x, points[0].y); + NSLog(@"[XABCD] A: date=%@ price=%@", points[1].x, points[1].y); +}; + +// Add the modifier to the chart surface +[self.surface.chartModifiers add:modifier]; +
+
+// Create a new XABCD creation modifier instance +let modifier = SCIXabcdCreationModifier() + +// Set the stroke (outline) style for the XABCD annotation lines +modifier.annotationStroke = SCISolidPenStyle(color: 0xFFE97064, thickness: 2) + +// Set the fill style for the annotation +modifier.annotationFill = SCISolidBrushStyle(color: 0x55AAAA00) + +// Callback triggered when all points (X, A, B, C, D) are placed +// Gives access to the completed annotation object +modifier.annotationCreationCompletionListener = { [weak self] createdAnnotation, type in + guard self != nil else { return } + + print("Annotation created: \(createdAnnotation), type: \(SCIAnnotationTypeName(type))") + + guard let xabcd = createdAnnotation as? SCIXabcdAnnotation else { return } + let arrPoints = xabcd.getBaseDataValues() + + // Get data points + // Index mapping: 0 = X, 1 = A, 2 = B, 3 = C, 4 = D + print("XABCD point X: \(arrPoints[0].x), \(arrPoints[0].y)") + print("XABCD point A: \(arrPoints[1].x), \(arrPoints[1].y)") +} + +// Add the modifier to the chart surface +surface.chartModifiers.add(modifier) +
+ + +The SCIXabcdCreationModifier can be configured using the properties and method listed in the table below: + +| **Field** | **Description** | +| ------------------------------------------------------------------------ | ------------------------------------------------------------- | +| `SCIXabcdCreationModifier.annotationStroke` | Defines the stroke style for newly created annotations. | +| `SCIXabcdCreationModifier.annotationFill` | Defines the fill style for newly created annotations. | +| `SCIXabcdCreationModifier.isDragging` | Indicates whether the user is actively dragging a point. | +| `SCIXabcdCreationModifier.activePointIndex` | Represents the index of the point currently being placed. | +| `SCIXabcdCreationModifier.reset()` | Cancels and removes any in-progress annotation. | +| `SCIAnnotationCreationModifierBase.xAxisId` | ID of the X‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.yAxisId` | ID of the Y‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.tag` | Custom tag identifier for the modifier. | +| `SCIAnnotationCreationModifierBase.annotationCreationCompletionListener` | A callback invoked when a full XABCD annotation is completed. | + +## Best Practices +- Disable conflicting gesture modifiers during drawing for better UX +- Use CompletionListener to validate or store annotations +- Call `reset()` when switching tools or exiting drawing mode +- Customize stroke/fill for better visual distinction +- Call cancel when switching tools or modes + +## Notes +- The modifier automatically resets after completing point D +- Only one annotation is created per interaction cycle +- Designed for real-time financial charting and harmonic pattern visualization diff --git a/scichart-theme/assets/img/annotations/composite-annotation.png b/scichart-theme/assets/img/annotations/composite-annotation.png new file mode 100644 index 0000000..9db40a9 Binary files /dev/null and b/scichart-theme/assets/img/annotations/composite-annotation.png differ diff --git a/scichart-theme/assets/img/annotations/extended-line-annotation.png b/scichart-theme/assets/img/annotations/extended-line-annotation.png new file mode 100644 index 0000000..de6023b Binary files /dev/null and b/scichart-theme/assets/img/annotations/extended-line-annotation.png differ diff --git a/scichart-theme/assets/img/annotations/freehand-drawing-annotation.png b/scichart-theme/assets/img/annotations/freehand-drawing-annotation.png new file mode 100644 index 0000000..a5d0bc4 Binary files /dev/null and b/scichart-theme/assets/img/annotations/freehand-drawing-annotation.png differ diff --git a/scichart-theme/assets/img/annotations/freehand-drawing-modifier.png b/scichart-theme/assets/img/annotations/freehand-drawing-modifier.png new file mode 100644 index 0000000..7c41ade Binary files /dev/null and b/scichart-theme/assets/img/annotations/freehand-drawing-modifier.png differ diff --git a/scichart-theme/assets/img/annotations/pitchfork-annotation.png b/scichart-theme/assets/img/annotations/pitchfork-annotation.png new file mode 100644 index 0000000..1299363 Binary files /dev/null and b/scichart-theme/assets/img/annotations/pitchfork-annotation.png differ diff --git a/scichart-theme/assets/img/annotations/xabcd-annotation.png b/scichart-theme/assets/img/annotations/xabcd-annotation.png new file mode 100644 index 0000000..0b601bd Binary files /dev/null and b/scichart-theme/assets/img/annotations/xabcd-annotation.png differ diff --git a/sections/Annotations APIs.md b/sections/Annotations APIs.md index d9886ab..5af8e46 100644 --- a/sections/Annotations APIs.md +++ b/sections/Annotations APIs.md @@ -12,19 +12,23 @@ This article is concerned with simply giving **an overview of the annotations** The annotations which are available out the box in SciChart are listed below: -| **Annotation Type** | **Description** | -| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| [SCIBoxAnnotation](boxannotation.html) | Draws a **rectangle** at specific `X1, X2, Y1, Y2` coordinates. | -| [SCILineAnnotation](lineannotation.html) | Draws a **line** between `[X1, Y1]` and `[X2, Y2]` coordinates. | -| [SCILineArrowAnnotation](linearrowannotation.html) | Draws an **arrow** from `[X1, Y1]` to `[X2, Y2]` coordinates. | -| [SCIHorizontalLineAnnotation](horizontallineannotation.html) | Draws a **horizontal line** between `[X1, Y1]` and `[X2, Y2]` coordinates. | -| [SCIVerticalLineAnnotation](verticallineannotation.html) | Draws a **vertical line** between `[X1, Y1]` and `[X2, Y2]` coordinates. | -| [SCITextAnnotation](textannotation.html) | Allows to place a piece of **text** at specific `[X1, Y1]` coordinates on a chart. | -| [SCIImageAnnotation](imageannotation.html) | Allows to place a **image** at specific `[X1, Y1]` coordinates on a chart or use it as a background image for a chart. | -| [SCIAxisLabelAnnotation](axislabelannotation.html) | Allows to place a piece of **text** at specific `X1` or `Y1` coordinate on a chart **Axis**. | -| [SCIAxisMarkerAnnotation](axismarkerannotation.html) | Allows to place **markers** with custom text onto `X or Y axes`. By default, shows the axis **value at its location**. | -| [SCIAxisMarkerCustomAnnotation](axismarkercustomannotation.html) | Allows to place **markers** with custom `UIView` onto `X or Y axes`. |  -| [SCICustomAnnotation](customannotation.html) | Allows to place any `UIView` at a specific `[X1, Y1]` coordinates on a chart. | +| **Annotation Type** | **Description** | +| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| [SCIBoxAnnotation](boxannotation.html) | Draws a **rectangle** at specific `X1, X2, Y1, Y2` coordinates. | +| [SCILineAnnotation](lineannotation.html) | Draws a **line** between `[X1, Y1]` and `[X2, Y2]` coordinates. | +| [SCILineArrowAnnotation](linearrowannotation.html) | Draws an **arrow** from `[X1, Y1]` to `[X2, Y2]` coordinates. | +| [SCIHorizontalLineAnnotation](horizontallineannotation.html) | Draws a **horizontal line** between `[X1, Y1]` and `[X2, Y2]` coordinates. | +| [SCIVerticalLineAnnotation](verticallineannotation.html) | Draws a **vertical line** between `[X1, Y1]` and `[X2, Y2]` coordinates. | +| [SCITextAnnotation](textannotation.html) | Allows to place a piece of **text** at specific `[X1, Y1]` coordinates on a chart. | +| [SCIImageAnnotation](imageannotation.html) | Allows to place a **image** at specific `[X1, Y1]` coordinates on a chart or use it as a background image for a chart. | +| [SCIAxisLabelAnnotation](axislabelannotation.html) | Allows to place a piece of **text** at specific `X1` or `Y1` coordinate on a chart **Axis**. | +| [SCIAxisMarkerAnnotation](axismarkerannotation.html) | Allows to place **markers** with custom text onto `X or Y axes`. By default, shows the axis **value at its location**. | +| [SCIAxisMarkerCustomAnnotation](axismarkercustomannotation.html) | Allows to place **markers** with custom `UIView` onto `X or Y axes`. | +| [SCICustomAnnotation](customannotation.html) | Allows to place any `UIView` at a specific `[X1, Y1]` coordinates on a chart. | +| [SCIXabcdAnnotation](xabcdannotation.html) | Allows to draw XABCD pattern by connecting five points [X, A, B, C, D] points. | +| [SCIPitchforkAnnotation](pitchforkannotation.html) | Allows to draw an Andrew's Pitchfork from a pivot point A through two crossbar points B, C projecting three parallel trend channels. | +| [SCIExtendedLineAnnotation](extendedlineannotation.html) | Allows to draws a line between [X1, Y1] and [X2, Y2] coordinates that can optionally extend beyond either endpoint to the chart edge. | +| [SCIFreehandDrawingAnnotation](freehanddrawingannotation.html) | Allows to draws a freehand path by recording a continuous sequence of touch points across the chart surface. | > **_NOTE:_** To learn more about **Annotation API**, please read the [Common Annotations Features](#common-annotations-features) section. > To find out more about a **specific** Annotation Type, please refer to a corresponding article about this **Annotation type**. @@ -96,31 +100,31 @@ These provide an API which allows to put them onto a chart and interact with the Please see the list of common features below: -| **Feature** | **Description** | -| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `ISCIAnnotation.x1`, `ISCIAnnotation.y1`, `ISCIAnnotation.x2`, `ISCIAnnotation.y2` | [X1, X2, Y1, Y2] coordinates specifies the position of an annotation on a `SCIChartSurface`. These are chart coordinates, not device (screen or pixel) coordinates. To find out about coordinate transformation in SciChart, please refer to the [Convert Pixels to Data Coordinates article](axis-apis---convert-pixel-to-data-coordinates.html). | -| `ISCIAnnotation.xAxisId`, `ISCIAnnotation.yAxisId` | Specifies the ID of **X-Axis** and **Y-Axis** that this annotation is measured against. | -| `ISCIAnnotation.isSelected` | Defines whether the annotation is **Selected**. When Selected - round **resizing markers** appears at the ends or corners of the annotation which can be used to resize it. Resizing markers can be accessed via the `SCIAnnotationBase.resizingGrip` property | -| `ISCIAnnotation.isEditable` | Specifies whether an annotation is **available for interaction**. When Editable, the annotation can be **Selected**, **Moved** and **Resized** by a user with a touch interaction. | -| `ISCIAnnotation.isHidden` | **Hides** or **shows** an annotation. | -| `ISCIAnnotation.dragDirections` | Allows to **constrain drag directions** for an annotation. Accepts a member of the `SCIDirection2D` enumeration. | -| `ISCIAnnotation.resizeDirections` | Allows to **constrain resize directions** for an annotation. Accepts a member of the `SCIDirection2D` enumeration. | +| **Feature** | **Description** | +| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ISCIAnnotation.x1`, `ISCIAnnotation.y1`, `ISCIAnnotation.x2`, `ISCIAnnotation.y2` | [X1, X2, Y1, Y2] coordinates specifies the position of an annotation on a `SCIChartSurface`. These are chart coordinates, not device (screen or pixel) coordinates. To find out about coordinate transformation in SciChart, please refer to the [Convert Pixels to Data Coordinates article](axis-apis---convert-pixel-to-data-coordinates.html). | +| `ISCIAnnotation.xAxisId`, `ISCIAnnotation.yAxisId` | Specifies the ID of **X-Axis** and **Y-Axis** that this annotation is measured against. | +| `ISCIAnnotation.isSelected` | Defines whether the annotation is **Selected**. When Selected - round **resizing markers** appears at the ends or corners of the annotation which can be used to resize it. Resizing markers can be accessed via the `SCIAnnotationBase.resizingGrip` property | +| `ISCIAnnotation.isEditable` | Specifies whether an annotation is **available for interaction**. When Editable, the annotation can be **Selected**, **Moved** and **Resized** by a user with a touch interaction. | +| `ISCIAnnotation.isHidden` | **Hides** or **shows** an annotation. | +| `ISCIAnnotation.dragDirections` | Allows to **constrain drag directions** for an annotation. Accepts a member of the `SCIDirection2D` enumeration. | +| `ISCIAnnotation.resizeDirections` | Allows to **constrain resize directions** for an annotation. Accepts a member of the `SCIDirection2D` enumeration. | | `SCIAnnotationBase.coordinateMode` | Determines whether [X1, X2, Y1, Y2] coordinates are **in chart** coordinates or in **relative** screen coordinates. **Relative** coordinates range from **[0 to 1]**, where 1 refers to the full Width or Height of the canvas. **Absolute** coordinates are the **data-values** which must correspond to the [Axis Type](Axis APIs.html). Defined by the `SCIAnnotationCoordinateMode` enumeration. | -| `SCIAnnotationBase.resizingGrip` | Determines what **resizing markers** look like. Custom ones have to implement `ISCIResizingGrip`. | -| `ISCIAnnotation.annotationSurface` | Specifies a **surface** to place an annotation on. Possible options are declared by the `SCIAnnotationSurfaceEnum` enumeration. | +| `SCIAnnotationBase.resizingGrip` | Determines what **resizing markers** look like. Custom ones have to implement `ISCIResizingGrip`. | +| `ISCIAnnotation.annotationSurface` | Specifies a **surface** to place an annotation on. Possible options are declared by the `SCIAnnotationSurfaceEnum` enumeration. | > **_NOTE:_** The **xAxisId** and **yAxisId** must be supplied if you have axis with **non-default** Axis Ids. Below is the list of some methods and listeners: -| **Feature** | **Description** | -| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `-[ISCIAnnotation updateWithXAxis:yAxis:]` | **Redraws** an annotation without invalidating the `parentSurface` of the `ISCIAnnotation` instance. | -| `-[ISCIAnnotation moveAnnotationByXDelta:yDelta:]` | **Moves** an annotation by the specified X and Y **delta** in horizontal and vertical directions. | -| | | -| `ISCIAnnotation.annotationDragListener` | Allows to appoint `SCIAnnotationDragListener` to receive notifications about **user interactions** with an annotation. | -| `ISCIAnnotation.annotationSelectionChangedListener` | Allows to appoint `SCIAnnotationSelectionChangedListener` to receive notifications when the annotation **selection has changed** | -| `ISCIAnnotation.annotationIsHiddenChangedListener` | Allows to appoint `SCIAnnotationIsHiddenChangedListener` to receive notifications when an annotation **gets hidden or visible**. | +| **Feature** | **Description** | +| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `-[ISCIAnnotation updateWithXAxis:yAxis:]` | **Redraws** an annotation without invalidating the `parentSurface` of the `ISCIAnnotation` instance. | +| `-[ISCIAnnotation moveAnnotationByXDelta:yDelta:]` | **Moves** an annotation by the specified X and Y **delta** in horizontal and vertical directions. | +| | | +| `ISCIAnnotation.annotationDragListener` | Allows to appoint `SCIAnnotationDragListener` to receive notifications about **user interactions** with an annotation. | +| `ISCIAnnotation.annotationSelectionChangedListener` | Allows to appoint `SCIAnnotationSelectionChangedListener` to receive notifications when the annotation **selection has changed** | +| `ISCIAnnotation.annotationIsHiddenChangedListener` | Allows to appoint `SCIAnnotationIsHiddenChangedListener` to receive notifications when an annotation **gets hidden or visible**. | > To find out more about a **specific** Annotation Type, please refer to a corresponding article about this **Annotation type**. diff --git a/sections/Chart Modifier APIs.md b/sections/Chart Modifier APIs.md index 1941d38..cd66339 100644 --- a/sections/Chart Modifier APIs.md +++ b/sections/Chart Modifier APIs.md @@ -13,32 +13,42 @@ Those could be grouped like the following: #### Zoom and Pan Modifiers The following modifiers can be used if you want to add scrolling or zooming behavior to a chart: -| **Modifier Name** | **Description** | -| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Modifier Name** | **Description** | +| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [SCIZoomExtentsModifier](zoom-and-pan---scizoomextentsmodifier.html) | **Resets the zoom** to the data extents via double-tapping. Available almost everywhere, e.g. see the [Sync Multi Chart](https://www.scichart.com/example/ios-chart/ios-chart-example-sync-mutiple-charts/) example. | -| [SCIPinchZoomModifier](zoom-and-pan---scipinchzoommodifier.html) | **Zooms** a chart in and out via the pinch and spread gestures correspondingly. Available almost everywhere, e.g. see the [Multiple X-Axes](https://www.scichart.com/example/ios-multiple-axis-demo/) example. | -| [SCIZoomPanModifier](zoom-and-pan---scizoompanmodifier.html) | **Pans** the chart in X, Y or both directions with inertia via finger sliding. Available almost everywhere, e,g. see the [Multiple X-Axes](https://www.scichart.com/example/ios-multiple-axis-demo/) example. | -| [SCIXAxisDragModifier](zoom-and-pan---scixaxisdragmodifier.html) | **Scales** or **pans an X Axis** via finger drag. See [Drag Axis to Scale a Chart](https://www.scichart.com/example/ios-chart-chart-drag-axis-to-scale-example/) example. | -| [SCIYAxisDragModifier](zoom-and-pan---sciyaxisdragmodifier.html) | **Scales** or **pans an Y Axis** via finger drag. See [Drag Axis to Scale a Chart](https://www.scichart.com/example/ios-chart-chart-drag-axis-to-scale-example/) example. | +| [SCIPinchZoomModifier](zoom-and-pan---scipinchzoommodifier.html) | **Zooms** a chart in and out via the pinch and spread gestures correspondingly. Available almost everywhere, e.g. see the [Multiple X-Axes](https://www.scichart.com/example/ios-multiple-axis-demo/) example. | +| [SCIZoomPanModifier](zoom-and-pan---scizoompanmodifier.html) | **Pans** the chart in X, Y or both directions with inertia via finger sliding. Available almost everywhere, e,g. see the [Multiple X-Axes](https://www.scichart.com/example/ios-multiple-axis-demo/) example. | +| [SCIXAxisDragModifier](zoom-and-pan---scixaxisdragmodifier.html) | **Scales** or **pans an X Axis** via finger drag. See [Drag Axis to Scale a Chart](https://www.scichart.com/example/ios-chart-chart-drag-axis-to-scale-example/) example. | +| [SCIYAxisDragModifier](zoom-and-pan---sciyaxisdragmodifier.html) | **Scales** or **pans an Y Axis** via finger drag. See [Drag Axis to Scale a Chart](https://www.scichart.com/example/ios-chart-chart-drag-axis-to-scale-example/) example. | #### Interactivity Modifiers These modifiers allow to interact with chart series or inspect them: -| **Modifier Name** | **Description** | -| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [SCISeriesSelectionModifier](interactivity---sciseriesselectionmodifier.html) | Provides **selection** of a series via tapping on it. See the [Series Selection](https://www.scichart.com/example/ios-chart/ios-series-selection/) example. | -| [SCITooltipModifier](interactivity---scitooltipmodifier.html) | Provides a **tooltip** for the nearest point on a series under the finger. See the [Using TooltipModifier](https://www.scichart.com/example/ios-chart/ios-using-tooltip-modifier/) example. | +| **Modifier Name** | **Description** | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [SCISeriesSelectionModifier](interactivity---sciseriesselectionmodifier.html) | Provides **selection** of a series via tapping on it. See the [Series Selection](https://www.scichart.com/example/ios-chart/ios-series-selection/) example. | +| [SCITooltipModifier](interactivity---scitooltipmodifier.html) | Provides a **tooltip** for the nearest point on a series under the finger. See the [Using TooltipModifier](https://www.scichart.com/example/ios-chart/ios-using-tooltip-modifier/) example. | | [SCIRolloverModifier](interactivity---scirollovermodifier.html) | Provides a **vertical slice** cursor **with tooltips** and markers rolling over a series. See the [Using RolloverModifier](https://www.scichart.com/example/ios-chart-tooltips-using-rollovermodifier/) example. | -| [SCICursorModifier](interactivity---scicursormodifier.html) | Provides a **crosshairs** with a tooltip and axis labels. See [Using CursorModifier](https://www.scichart.com/example/ios-using-cursor-modifier/) example. | +| [SCICursorModifier](interactivity---scicursormodifier.html) | Provides a **crosshairs** with a tooltip and axis labels. See [Using CursorModifier](https://www.scichart.com/example/ios-using-cursor-modifier/) example. | #### Miscellaneous Modifiers Modifiers below are used as helpers and can be a useful addition to a chart: -| **Modifier Name** | **Description** | -| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [SCIModifierGroup](#scimodifiergroup-features) | Can be used to **group** chart modifiers together. This can useful in **multi-chart** scenarios, to unite ModifierGroups into one **EventGroup** of modifiers. If an **Event** occurs on a chart, it will be propagated to modifiers from other charts that are in the same **EventGroup**. See the [Multi-Panel Stock Chart](https://www.scichart.com/example/ios-multi-pane-stock-chart/) example. | -| [SCILegendModifier](legend-modifier.html) | Allows to creates and configure a **Legend** for a chart. See the [Legend Chart](https://www.scichart.com/example/ios-chart/ios-chart-legends-api-example/) example. | -| [SCISeriesValueModifier](series-value-modifier.html) | A custom ChartModifier which places an `SCISeriesValueMarkerAnnotation` on the YAxis for each RenderableSeries in the chart, showing the current `ISCIRenderableSeries` latest Y-value. E.g. for each series, place one axis-marker with the latest Y-value of the series. See the [SeriesValueModifier Chart](https://www.scichart.com/example/ios-chart/ios-chart-legends-api-example/) example. | +| **Modifier Name** | **Description** | +| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [SCIModifierGroup](#scimodifiergroup-features) | Can be used to **group** chart modifiers together. This can useful in **multi-chart** scenarios, to unite ModifierGroups into one **EventGroup** of modifiers. If an **Event** occurs on a chart, it will be propagated to modifiers from other charts that are in the same **EventGroup**. See the [Multi-Panel Stock Chart](https://www.scichart.com/example/ios-multi-pane-stock-chart/) example. | +| [SCILegendModifier](legend-modifier.html) | Allows to creates and configure a **Legend** for a chart. See the [Legend Chart](https://www.scichart.com/example/ios-chart/ios-chart-legends-api-example/) example. | +| [SCISeriesValueModifier](series-value-modifier.html) | A custom ChartModifier which places an `SCISeriesValueMarkerAnnotation` on the YAxis for each RenderableSeries in the chart, showing the current `ISCIRenderableSeries` latest Y-value. E.g. for each series, place one axis-marker with the latest Y-value of the series. See the [SeriesValueModifier Chart](https://www.scichart.com/example/ios-chart/ios-chart-legends-api-example/) example. | + +#### Creation Modifiers +These modifiers allow interactive drawing of annotations directly on the chart surface: + +| **Modifier Name** | **Description** | +| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [SCIXabcdCreationModifier](trading-annotation---scixabcdcreationmodifier.html) | Provides interactive placement of an XABCD harmonic pattern by tapping/dragging to define five sequential points [X, A, B, C, D]. Commonly used in trading analysis for pattern recognition. See the [Trading Annotation](https://www.scichart.com/example/ios-chart/ios-trading-annotation/) example. | +| [SCIPitchforkCreationModifier](trading-annotation---scipitchforkcreationmodifier.html) | Enables interactive creation of a pitchfork tool by selecting three anchor points. Automatically draws three parallel trend lines for support/resistance analysis. See the [Trading Annotation](https://www.scichart.com/example/ios-chart/ios-trading-annotation/) example. | +| [SCIExtendedLineCreationModifier](trading-annotation---sciextendedlinecreationmodifier.html) | Allows interactive placement of an extended line through two points [X1, Y1], [X2, Y2]. The line extends infinitely across the chart viewport for trend visualization. | +| [SCIFreehandDrawingModifier](trading-annotation---scifreehanddrawingmodifier.html) | Provides a **crosshairs** with a tooltip and axis labels. See [Freehand Drawing Annotation](https://www.scichart.com/example/ios-freehand-drawing-annotation/) example. | > **_NOTE:_** To learn more about **ChartModifiers API**, please read the [Common ChartModifiers Features](#common-chart-modifier-features) section. > To find out more about a **specific** ChartModifier, please refer to a corresponding article about this Modifier type. @@ -81,13 +91,13 @@ It is a must that Custom Modifiers implement `ISCIChartModifier`, and hence we r Please see the list of common features below: -| **Feature** | **Description** | -| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `ISCIChartSurfaceProvider.parentSurface` | Provides the `ISCIChartSurface` which the modifier is attached to. See the `ISCIAttachable.isAttached` method below. | -| `ISCIChartModifierCore.modifierSurface` | Returns the **ModifierSurface** from the parental `SCIChartSurface`. It is used to place Views like tooltips, etc. onto it. | +| **Feature** | **Description** | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ISCIChartSurfaceProvider.parentSurface` | Provides the `ISCIChartSurface` which the modifier is attached to. See the `ISCIAttachable.isAttached` method below. | +| `ISCIChartModifierCore.modifierSurface` | Returns the **ModifierSurface** from the parental `SCIChartSurface`. It is used to place Views like tooltips, etc. onto it. | | `ISCIAttachable.isAttached` | Value which indicates whether a modifier is attached to a `SCIChartSurface` or not. If it is - `ISCIChartSurfaceProvider.parentSurface` property will return the corresponding instance of `SCIChartSurface`. | -| `ISCIChartModifierCore.isEnabled` | Allows to specify if a modifier should be **available** for interaction **or not**. | -| `ISCIReceiveEvents.receiveHandledEvents` | Allows to specify whether a modifier should receive events handled by another modifier. | +| `ISCIChartModifierCore.isEnabled` | Allows to specify if a modifier should be **available** for interaction **or not**. | +| `ISCIReceiveEvents.receiveHandledEvents` | Allows to specify whether a modifier should receive events handled by another modifier. | #### SCIModifierGroup Features The `SCIModifierGroup` allows **grouping** of modifiers. This can be useful if modifiers create a logical group within which they are handled together. @@ -100,4 +110,16 @@ This can be done by setting `SCIModifierGroup.eventGroup` to be the same for **M | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `SCIModifierGroup.eventGroup` | Allows to specify which **EventGroup** this modifier goes in. It is used to share events between modifiers that belong to different surfaces. | | `ISCIReceiveEventGroup.eventsSource` | Returns the **ModifierSurface** which is the source of the events. | -| `SCIModifierGroup.childModifiers` | Assigns a collection of modifiers to a **ModifierGroup**. Also a collection can be passed into the class constructor during creation. | \ No newline at end of file +| `SCIModifierGroup.childModifiers` | Assigns a collection of modifiers to a **ModifierGroup**. Also a collection can be passed into the class constructor during creation. | + +## Common Creation Modifier Features +All the **CreationModifiers** provided by SciChart derive from the `SCIAnnotationCreationModifierBase` class. + +Please see the list of common features below: + +| **Feature** | **Description** | +| ------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `SCIAnnotationCreationModifierBase.xAxisId` | ID of the X‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.yAxisId` | ID of the Y‑Axis the annotation is measured against. | +| `SCIAnnotationCreationModifierBase.tag` | Custom tag identifier for the modifier. | +| `SCIAnnotationCreationModifierBase.annotationCreationCompletionListener` | A callback invoked when a full annotation creation is completed. | \ No newline at end of file