Feat(iOS): Documentation for Trading annotation and creation modifiers

.jazzy.yaml

@@ -139,6 +139,9 @@ custom_categories:
       - Interactivity - SCISeriesSelectionModifier
       - Legend Modifier
       - Series Value Modifier
+      - Trading Annotation - SCIPitchforkCreationModifier
+      - Trading Annotation - SCIXabcdCreationModifier
+      - Trading Annotation - SCIFreehandDrawingModifier
 
   - name: Annotations APIs
     children:
@@ -154,6 +157,10 @@ custom_categories:
       - AxisMarkerCustomAnnotation
       - CustomAnnotation
       - CustomGrip
+      - CompositeAnnotation
+      - PitchforkAnnotation
+      - XabcdAnnotation
+      - FreehandDrawingAnnotation
 
   # - name: Advanced 2D chart Topics
   # children:
@@ -472,6 +479,9 @@ custom_categories:
       - SCIAxisDragModifierBase
       - SCIXAxisDragModifier
       - SCIYAxisDragModifier
+      - SCIPitchforkCreationModifier
+      - SCIXabcdCreationModifier
+      - SCIFreehandDrawingModifier
 
       # Series Value Modifier
       - ISCISeriesValueMarker
@@ -684,6 +694,17 @@ custom_categories:
       - SCIAxisMarkerAnnotation
       - SCIAxisMarkerCustomAnnotation
 
+      # Trading Annotations
+      - ISCITradingAnnotation
+      - SCITradingAnnotationBase
+      - SCIElliotWaveAnnotationBase
+      - ISCIPolyLineAnnotation
+      - SCIPolyLineAnnotation
+      - SCICompositeAnnotation
+      - SCIXabcdAnnotation
+      - SCIPitchforkAnnotation
+      - SCIFreehandDrawingAnnotation
+
       - ISCIAnnotationDragListener
       - SCIAnnotationIsHiddenChangedListener
       - SCIAnnotationSelectionChangedListener

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:
+
+<div class="code-snippet-tabs">
+  <button class="code-snippet-tab" onclick="showCodeFor(event, 'objectivec')">OBJECTIVE-C</button>
+  <button class="code-snippet-tab" onclick="showCodeFor(event, 'swift')">SWIFT</button>
+</div>
+<div class="code-snippet" id="objectivec">
+    // Assume a surface has been created and configured somewhere
+id<SCIChartSurface> surface = self.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];
+</div>
+<div class="code-snippet" id="swift">
+// 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)
+</div>
+> **_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.

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:
+
+<div class="code-snippet-tabs">
+  <button class="code-snippet-tab" onclick="showCodeFor(event, 'objectivec')">OBJECTIVE-C</button>
+  <button class="code-snippet-tab" onclick="showCodeFor(event, 'swift')">SWIFT</button>
+</div>
+<div class="code-snippet" id="objectivec">
+// Assume a surface has been created and configured somewhere
+id<ISCIChartSurface> 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];
+</div>
+<div class="code-snippet" id="swift">
+// 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)
+</div>
+
+> **_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.

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:
+
+<div class="code-snippet-tabs">
+  <button class="code-snippet-tab" onclick="showCodeFor(event, 'objectivec')">OBJECTIVE-C</button>
+  <button class="code-snippet-tab" onclick="showCodeFor(event, 'swift')">SWIFT</button>
+</div>
+<div class="code-snippet" id="objectivec">
+// Assume a surface has been created and configured somewhere
+id<ISCIChartSurface> 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];
+</div>
+<div class="code-snippet" id="swift">
+// 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)
+</div>
+
+> **_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.