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

.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

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<ISCIChartSurface> 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/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:
+
+<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;
+
+// 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];
+</div>
+<div class="code-snippet" id="swift">
+// 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)
+
+</div>
+
+> **_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.