feat: ✨ Add dynamic onStart callback registration with addOnStartCallback and removeOnStartCallback methods (#624)

Author: aditya-chavda

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Feature [#600](https://github.com/SimformSolutionsPvtLtd/showcaseview/issues/600) - Added dynamic onComplete callback registration with `addOnCompleteCallback` and `removeOnCompleteCallback` methods
 - Fixed [#577](https://github.com/SimformSolutionsPvtLtd/showcaseview/issues/577) - Resolve issue where long tooltip text was rendered outside the screen bounds
 - Feature [#586](https://github.com/SimformSolutionsPvtLtd/showcaseview/issues/586): Enhance tooltip accessibility using Semantics live region
+- Feature [#624](https://github.com/SimformSolutionsPvtLtd/showcaseview/pull/624): Added dynamic onStart callback registration with `addOnStartCallback` and `removeOnStartCallback` methods
 
 ## [5.0.1]
 

doc/documentation.md

@@ -575,6 +575,29 @@ ShowcaseView.register(
 
 You can also add and remove event callbacks dynamically at runtime. This is particularly useful when you need to register callbacks from widgets deeper in the tree or when using named scopes.
 
+#### OnStart Callback
+
+Add or remove callbacks that trigger when each showcase step starts:
+
+```dart
+// Add a callback for when each showcase step completes
+ShowcaseView.get().addOnstartCallback((index, key) {
+  print('Showcase step $index started with key: $key');
+  // Perform custom actions here
+});
+
+// Remove a previously added callback
+ShowcaseView.get().removeOnstartCallback(callbackFunction);
+```
+
+**Example with named scope:**
+
+```dart
+ShowcaseView.getNamed('profile').addOnstartCallback((index, key) {
+  print('Profile showcase started at step $index');
+});
+```
+
 #### OnComplete Callback
 
 Add or remove callbacks that trigger when each showcase step completes:

lib/src/showcase/showcase_view.dart

@@ -192,6 +192,9 @@ class ShowcaseView {
   /// Stores functions to call when a onComplete event occurs.
   final List<OnShowcaseCallback> _onCompleteCallbacks = [];
 
+  /// Stores functions to call when a onStart event occurs.
+  final List<OnShowcaseCallback> _onStartCallbacks = [];
+
   /// Returns whether showcase is completed or not.
   bool get isShowCaseCompleted => _ids == null && _activeWidgetId == null;
 
@@ -301,6 +304,7 @@ class ShowcaseView {
     _onFinishCallbacks.clear();
     _onDismissCallbacks.clear();
     _onCompleteCallbacks.clear();
+    _onStartCallbacks.clear();
   }
 
   /// Updates the overlay to reflect current showcase state.
@@ -359,6 +363,16 @@ class ShowcaseView {
     _onCompleteCallbacks.remove(listener);
   }
 
+  /// Adds a listener that will be called when the showcase tour is started.
+  void addOnStartCallback(OnShowcaseCallback listener) {
+    _onStartCallbacks.add(listener);
+  }
+
+  /// Removes a listener that was previously added via [addOnStartCallback].
+  void removeOnStartCallback(OnShowcaseCallback listener) {
+    _onStartCallbacks.remove(listener);
+  }
+
   void _startShowcase(
     Duration delay,
     List<GlobalKey<State<StatefulWidget>>> widgetIds,
@@ -467,6 +481,11 @@ class ShowcaseView {
     _activeWidgetId ??= 0;
     if (_activeWidgetId! < _ids!.length) {
       onStart?.call(_activeWidgetId, _ids![_activeWidgetId!]);
+      // Call all registered onStart callbacks
+      for (final callback in _onStartCallbacks) {
+        callback.call(_activeWidgetId, _ids![_activeWidgetId!]);
+      }
+
       final controllers = _getCurrentActiveControllers;
       final controllerLength = controllers.length;
       final firstController = controllers.firstOrNull;
@@ -486,7 +505,6 @@ class ShowcaseView {
     }
 
     // Cancel any existing timer before setting up a new one
-
     if (autoPlay) {
       _cancelTimer();
       final config = _getCurrentActiveControllers.firstOrNull?.config;