Merge pull request #316 from ramin-deriv/merge_dev_into_master

merge_dev_into_master

.github/workflows/main.yaml

@@ -18,18 +18,18 @@ jobs:
     runs-on: "ubuntu-latest"
     steps:
       - name: 📚 Git Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
 
       - name: 🐦 Setup Flutter
-        uses: subosito/flutter-action@v2
+        uses: subosito/flutter-action@48cafc24713cca54bbe03cdc3a423187d413aafa
         with:
           flutter-version: "3.10.2"
           channel: stable
           cache: true
           cache-key: flutter-:os:-:channel:-:version:-:arch:-:hash:-${{ hashFiles('**/pubspec.lock') }}
 
       - name: 🤫 Set SSH Key
-        uses: webfactory/ssh-agent@v0.8.0
+        uses: webfactory/ssh-agent@fd34b8dee206fe74b288a5e61bc95fba2f1911eb
         with:
           ssh-private-key: ${{secrets.SSH_PRIVATE_KEY}}
 

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.1.0] - TODO: Add release date.
+
+* Add drawing tools.
+* Make the chart compatible with the `flutter_web` platform.
+
 ## [0.0.1] - TODO: Add release date.
 
-* TODO: Describe initial release.
+* TODO: Describe initial release.

README.md

@@ -250,7 +250,8 @@ ChartLocalization.load(locale);
 
 ### DerivChart
 
-A wrapper around the `chart` widget which provides the UI to add/remove indicators and to manage saving/restoring selected ones on storage.
+A wrapper around the `chart` widget provides the functionality to add/remove/update indicators and to manage saving/restoring selected ones on storage.
+To learn more about how we can customize the indicators feature using `DerivChart` check [this documentation](/docs/deriv_chart_widget_usage.md).
 
 #### Usage:
 

docs/deriv_chart_widget_usage.md

@@ -0,0 +1,64 @@
+### How to use DerivChart chart component
+
+`DerivChart` is a wrapper around the `chart` widget that provides the ability to add/remove indicators and manage saving/restoring added ones in storage.
+By default, this widget shows two buttons at the top left to add/remove indicators and drawing tools. This can be used when you don't need to customize the look and functionalities of the menus and dialogs for adding/removing indicators and changing their settings and want to use the chart's default menu interfaces.
+
+We can also implement our own interface to do all the above and integrate it with the `DerivChart` component.
+This can be done by creating an instance of `AddOnsRepository` and passing it to the chart. For example, in the case of indicators, we can create an instance of `AddOnsRepository<IndicatorConfig>` as shown below:
+
+```Dart
+_indicatorsRepo = AddOnsRepository<IndicatorConfig>(
+      // Is called when fetching the saved indicators from the shared preferences.
+      // To handle how an IndicatorConfig object should be created from a saved JSON object.
+      createAddOn: (Map<String, dynamic> map) => IndicatorConfig.fromJson(map),
+      onEditCallback: (int index) {
+       // handle edit of an indicator on index from _indicatorsRepo.items
+      },
+      // A string acts as a key for the set of indicators that are saved. so we can have a separate set of saved indicators per key
+      // For example we can have saved indicators per symbol if we pass the symbol code every time it changes to the indicator repo.
+      sharedPrefKey: 'R_100',
+    );
+```
+
+After creating the instance you can pass it to the DerivChart component.
+
+```Dart
+ DerivChart(
+      indicatorsRepo: _indicatorsRepo,
+      ...
+      ...
+```
+
+To load the saved indicators we should call the below method and pass the instance of SharedPref:
+
+```Dart
+_indicatorsRepo.loadFromPrefs(
+      await SharedPreferences.getInstance(),
+      'R_100',
+);
+```
+
+`AddOnsRepository` is a subtype of `ChangeNotifier` so when we call this method, later `DerivChart` will be informed about the change in the list of indicators.
+
+#### Add/remove/update indicators
+Now that we have the instance of `AddsOnRepository` we can use it to know the current list of added indicators. and use its method to add/remove/update, from our menu interfaces.
+
+To add:
+
+```Dart
+_indicatorRepo.add(MACDIndicatorConfig());
+```
+
+To remove: 
+
+`index` is the index of the indicator item in `_indicatorRepo.items` list.
+
+```Dart
+_indicatorRepo.removeAt(index);
+```
+
+To update:
+
+```Dart
+ repo.updateAt(index, updatedConfig),
+```

docs/drawing_tools.md

@@ -0,0 +1,42 @@
+# Drawing Tools
+
+The process initiates by opening the drawing tools dialog and selecting a preferred drawing tool. Subsequently, the user can add specific taps on the Deriv chart to start drawing with default configurations.
+
+The GestureDetector on the Deriv chart, utilized by the `drawingCreator` captures user input. Within the `onTap` method, every captured input will be added to the list of edgePoints. Simultaneously, the `drawingParts` list is created to store the drawing parts. Both lists are then passed to the `onAddDrawing` callback, which adds the complete drawing to the drawing repository and saves it in shared preferences based on the active Symbol, so the drawing data can be retrieved based on the chart's symbol.
+
+During the addition of drawing parts to the `drawingParts` list, each instance of the drawing is initialized. This initialization triggers the relevant `onPaint` method, allowing each drawing part to be painted to the chart. Since we maintain a list of `drawingParts`, each of which is an instance of a drawing, every drawing part has its own `onPaint` and `hitTest` methods inherited from CustomPaint. Consequently, any modifications in the drawing's position, such as dragging, result in the `repaint` and `hitTest` methods being invoked for each drawing part. For a more detailed explanation, please refer to the sections titled DrawingPainter, EdgePoints, and DraggableEdgePoints.
+
+Any modifications or adjustments to the drawing can be made by the user through the drawing tools dialog, it will end up in triggering an update in the drawing configuration within drawing_tools_dialog widget.
+
+To enable the drawings to be draggable, a distinct gesture is assigned to each drawing added to the chart. This gesture, embedded within the DrawingPainter, identifies any user taps on the drawing and designates the drawing as selected or deselected. The user can then drag the selected drawing across the chart.
+
+To update the position of the dragged drawing, the drawing must be repainted on the chart. This operation is performed by the CustomPaint component within the DrawingPainter.
+
+## Drawing Tool Chart
+
+DrawingToolChart widget is embedded within MainChart, enabling users to sketch particular shapes on DerivChart. This feature comprises two main parts: DrawingToolWidget and DrawingPainter. The DrawingPainter is specifically tasked with painting and repainting the drawings and is invoked for every drawing added to the chart.
+In other words, for each drawing a DrawingPainter widget is added on the DrawingToolChart stack, and DrawingToolWidget is for when any drawing tool is selected.
+
+## DrawingToolWidget
+
+It assigns the task of drawing creation to the respective drawing tool creator. Each creator employs the chart's gestures to detect user inputs and initially adds the drawing to the list by invoking the onAddDrawing callback. Every drawing tool creator extends from the DrawingCreator class.
+
+## DrawingCreator
+
+It is a base class for all drawing tool creators. It is responsible for adding the drawing to the list and invoking the onAddDrawing callback. It also provides the drawing tool creator with the chart's gestures to detect user inputs.
+
+## DrawingPainter
+
+A stateful widget which is responsible for painting and repainting the drawings based on theirs configs using `CustomPaint`. Since the CustomPaint is wrapped within GestureDetector, each drawing created possesses its dedicated gesture, designed specifically for enabling the drawings to be draggable.
+
+In this widget we make drawings selectable by means of gesture and `hitTest` of `CustomPainter`. `hitTest` method checks if the user has clicked on a drawing or not, if yes it will return true. Inside `CustomPaint` we are calling `onPaint` and `hitTest` for each drawingPart.
+
+![plot](drawing_tools.png)
+
+## EdgePoints
+
+EdgePoint is a term we coined to keep the data of points required to create a drawing. For instance, a line necessitates two points, while a channel requires three. Whenever a user taps on Deriv-chart to create a drawing, a new instance of this class is generated within each drawing creator. This instance contains data obtained from Deriv_chart's gesture detector. These EdgePoints are then passed as a list to the onAddDrawing callback for drawing creation.
+
+## DraggableEdgePints
+
+This class extends from EdgePoint. It incorporates functions to compute the edgePoints' positions after they are dragged (utilizing data obtained from the DrawingPainter gestureDetector). These instances will be created as the state of the drawing_painter widget. Subsequently, they will be passed to CustomPaint, where onPaint and hitTest methods utilize them for drawing selection and repainting the drawings on the chart.