feat: ✨ Expose onFinish and onDismiss listeners (#561)

Author: memishood

README.md

@@ -344,13 +344,17 @@ subtitle: Text('Try swiping this item'
 
 ## Functions of `ShowCaseView.get()` and `ShowCaseView.getNamed(scopeName)`:
 
-| Function Name | Description                                         |
-|---------------|-----------------------------------------------------|
-| startShowCase | Starting the showcase                               |
-| next          | Starts next showcase                                |
-| previous      | Starts previous showcase                            |
-| dismiss       | Dismisses all showcases                             |
-| unRegister    | UnRegister all showcases and the showcaseView scope |
+| Function Name           | Description                                         |
+|-------------------------|-----------------------------------------------------|
+| startShowCase           | Starting the showcase                               |
+| next                    | Starts next showcase                                |
+| previous                | Starts previous showcase                            |
+| dismiss                 | Dismisses all showcases                             |
+| addOnFinishCallback     | Listener when showcase is finished                  |
+| removeOnFinishCallback  | Clears OnFinishCallback                             |
+| addOnDismissCallback    | Listener when showcase is dismissed                 |
+| removeOnDismissCallback | Clears OnDismissCallback                            |
+| unRegister              | UnRegister all showcases and the showcaseView scope |
 
 ## Main Contributors
 

example/lib/detailscreen.dart

@@ -20,13 +20,29 @@ class _DetailState extends State<Detail> {
     // ShowcaseView then you can register new ShowcaseView
     ShowcaseView.register(scope: scopeName);
     WidgetsBinding.instance.addPostFrameCallback(
-      (_) => ShowcaseView.getNamed(scopeName).startShowCase(
-        [_one],
-        delay: const Duration(milliseconds: 200),
-      ),
+      (_) => ShowcaseView.getNamed(scopeName)
+        ..startShowCase([_one], delay: const Duration(milliseconds: 200))
+        ..addOnFinishCallback(_onShowcaseFinished)
+        ..addOnDismissCallback(_onShowcaseDismissed),
     );
   }
 
+  @override
+  void dispose() {
+    ShowcaseView.getNamed(scopeName)
+      ..removeOnFinishCallback(_onShowcaseFinished)
+      ..removeOnDismissCallback(_onShowcaseDismissed);
+    super.dispose();
+  }
+
+  void _onShowcaseFinished() {
+    debugPrint("Showcase tour finished!");
+  }
+
+  void _onShowcaseDismissed(GlobalKey? dismissedAt) {
+    debugPrint("Showcase dismissed $dismissedAt");
+  }
+
   @override
   Widget build(BuildContext context) {
     return Scaffold(
@@ -51,6 +67,26 @@ class _DetailState extends State<Detail> {
               key: _one,
               title: 'Title',
               description: 'Desc',
+              floatingActionWidget: FloatingActionWidget(
+                left: 16,
+                bottom: 16,
+                child: Padding(
+                  padding: const EdgeInsets.all(16.0),
+                  child: ElevatedButton(
+                    style: ElevatedButton.styleFrom(
+                      backgroundColor: const Color(0xffEE5366),
+                    ),
+                    onPressed: ShowcaseView.getNamed(scopeName).dismiss,
+                    child: const Text(
+                      'Close Showcase',
+                      style: TextStyle(
+                        color: Colors.white,
+                        fontSize: 15,
+                      ),
+                    ),
+                  ),
+                ),
+              ),
               child: InkWell(
                 onTap: () {},
                 child: const Text(

lib/src/showcase/showcase_view.dart

@@ -173,6 +173,12 @@ class ShowcaseView {
   /// Map to store keys for which floating action widget should be hidden.
   late final Map<GlobalKey, bool> _hideFloatingWidgetKeys;
 
+  /// Stores functions to call when a onFinish event occurs.
+  final List<VoidCallback> _onFinishCallbacks = [];
+
+  /// Stores functions to call when a onDismiss event occurs.
+  final List<OnDismissCallback> _onDismissCallbacks = [];
+
   /// Returns whether showcase is completed or not.
   bool get isShowCaseCompleted => _ids == null && _activeWidgetId == null;
 
@@ -258,8 +264,13 @@ class ShowcaseView {
   void dismiss() {
     final idDoesNotExist =
         _activeWidgetId == null || (_ids?.length ?? -1) <= _activeWidgetId!;
+    final dismissedAtKey = idDoesNotExist ? null : _ids?[_activeWidgetId!];
+
+    onDismiss?.call(dismissedAtKey);
+    for (final callback in _onDismissCallbacks) {
+      callback.call(dismissedAtKey);
+    }
 
-    onDismiss?.call(idDoesNotExist ? null : _ids?[_activeWidgetId!]);
     if (!_mounted) return;
 
     _cleanupAfterSteps();
@@ -273,6 +284,9 @@ class ShowcaseView {
     ShowcaseService.instance.unregister(scope: scope);
     _mounted = false;
     _cancelTimer();
+
+    _onFinishCallbacks.clear();
+    _onDismissCallbacks.clear();
   }
 
   /// Updates the overlay to reflect current showcase state.
@@ -301,6 +315,26 @@ class ShowcaseView {
         : globalFloatingActionWidget;
   }
 
+  /// Adds a listener that will be called when the showcase tour is finished.
+  void addOnFinishCallback(VoidCallback listener) {
+    _onFinishCallbacks.add(listener);
+  }
+
+  /// Removes a listener that was previously added via [addOnFinishCallback].
+  void removeOnFinishCallback(VoidCallback listener) {
+    _onFinishCallbacks.remove(listener);
+  }
+
+  /// Adds a listener that will be called when the showcase tour is dismissed.
+  void addOnDismissCallback(OnDismissCallback listener) {
+    _onDismissCallbacks.add(listener);
+  }
+
+  /// Removes a listener that was previously added via [addOnDismissCallback].
+  void removeOnDismissCallback(OnDismissCallback listener) {
+    _onDismissCallbacks.remove(listener);
+  }
+
   void _startShowcase(
     Duration delay,
     List<GlobalKey<State<StatefulWidget>>> widgetIds,
@@ -345,6 +379,9 @@ class ShowcaseView {
         if (_activeWidgetId! >= _ids!.length) {
           _cleanupAfterSteps();
           onFinish?.call();
+          for (final callback in _onFinishCallbacks) {
+            callback.call();
+          }
         } else {
           // Add a short delay before starting the next showcase to ensure proper state update
           // Then start the new showcase