Merge pull request #32 from do9core/feat/infinite-rolling

feat: implement roulette infinite scrolling behavior

Author: do9core

CHANGELOG.md

@@ -1,3 +1,8 @@
+# 0.3.2 - 2026/3/10
+
+### New feature
+  * You can now roll the Roulette infinitely with `rollInfinitely` method, until you call `rollTo` or `stop` method. The example is also updated to show how to use it.
+
 ## 0.3.1 - 2026/3/9
 
 ### New feature

README.md

@@ -35,7 +35,7 @@ Add this to your `pubspec.yaml` file:
 
 ```yaml
 dependencies:
-  roulette: ^0.3.1
+  roulette: ^0.3.2
 ```
 
 ## Usage
@@ -166,6 +166,26 @@ await controller.rollTo(
 );
 ```
 
+### Roll infinitely before determine the result (available in 0.3.2)
+
+You can also use `rollInfinitely` to roll infinitely until you call `stop` or `rollTo` method:
+
+```dart
+// Roll infinitely
+controller.rollInfinitely();
+
+// Getting the result value somewhere...
+try {
+  final result = await service.request()
+  final index = values.indexOf(result);
+  // Stop rolling and settle to index
+  controller.rollTo(index, offset: random.nextDouble());
+} catch (e, st) {
+  // Or stop rolling immediately, stop with this method has no animation
+  // controller.stop();
+}
+```
+
 Please refer to API documentation for more details.
 
 For more complete examples, please check the example app.

example/lib/main.dart

@@ -251,7 +251,7 @@ class _HomePageState extends State<HomePage> {
                           switch (_animationMode) {
                             case AnimationMode.curve:
                               config = const CurveAnimationConfig(
-                                curve: Curves.fastOutSlowIn,
+                                curve: Curves.easeOut,
                                 duration: Duration(seconds: 5),
                               );
                             case AnimationMode.physics:
@@ -278,19 +278,28 @@ class _HomePageState extends State<HomePage> {
                             );
                           }
                         },
-                        child: const Text('ROLL'),
+                        child: const Text('Roll'),
+                      ),
+                      FilledButton(
+                        onPressed: () {
+                          _controller.rollInfinitely(
+                            period: const Duration(milliseconds: 200),
+                            clockwise: _clockwise,
+                          );
+                        },
+                        child: Text('Roll Infinitely'),
                       ),
                       FilledButton(
                         onPressed: () {
                           _controller.stop();
                         },
-                        child: const Text('CANCEL'),
+                        child: const Text('Cancel'),
                       ),
                       FilledButton(
                         onPressed: () {
                           _controller.resetAnimation();
                         },
-                        child: const Text('RESET'),
+                        child: const Text('Reset'),
                       ),
                     ],
                   ),

example/pubspec.lock

@@ -198,7 +198,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.3.0"
+    version: "0.3.2"
   shared_preferences:
     dependency: transitive
     description:

lib/src/roulette.dart

@@ -102,6 +102,8 @@ class RouletteState extends State<Roulette>
       _handleStop();
     } else if (event is RouletteResetEvent) {
       _handleReset();
+    } else if (event is InfiniteRollEvent) {
+      _handleInfiniteRoll(event);
     }
   }
 
@@ -156,6 +158,22 @@ class RouletteState extends State<Roulette>
         .catchError((_) => _reportEvent(OnRollCancelledEvent(event)));
   }
 
+  void _handleInfiniteRoll(InfiniteRollEvent event) {
+    if (_animationController.isAnimating) {
+      _animationController.stop();
+    }
+
+    rotateAnimation.value = makeInfiniteRollAnimation(
+      _animationController,
+      clockwise: event.clockwise,
+      curve: event.curve,
+    );
+    _animationController
+        .repeat(period: event.period)
+        .orCancel
+        .catchError((_) => _reportEvent(OnRollCancelledEvent(event)));
+  }
+
   void _handleStop() {
     _animationController.stop();
   }

lib/src/roulette_controller.dart

@@ -79,6 +79,19 @@ class RouletteStopEvent implements RouletteEvent {
   const RouletteStopEvent();
 }
 
+@internal
+class InfiniteRollEvent implements RouletteEvent {
+  const InfiniteRollEvent({
+    required this.clockwise,
+    this.period = defaultPeriod,
+    this.curve,
+  });
+
+  final bool clockwise;
+  final Duration period;
+  final Curve? curve;
+}
+
 @internal
 class RouletteResetEvent implements RouletteEvent {
   const RouletteResetEvent();
@@ -123,7 +136,12 @@ class RouletteController {
     _eventStreamController.add(RouletteResetEvent());
   }
 
-  /// Stop current running animation
+  /// Stop current running animation.
+  /// No animation will be performed, the roulette will
+  /// stop at current position directly.
+  ///
+  /// If you want your roulette to stop with an animation,
+  /// use [rollTo] instead.
   void stop() {
     _eventStreamController.add(RouletteStopEvent());
   }
@@ -176,6 +194,35 @@ class RouletteController {
     return completer.future;
   }
 
+  /// Start rolling the roulette indefinitely until a
+  /// [rollTo], [rollInfinitely] or [stop] is called.
+  /// The [clockwise] determine whether the animator should run in clockwise direction.
+  /// Config [period] to update the roll period for one circle.
+  /// If you want to change the cycle animation behavior, try [curve],
+  /// but it may make the animation look wired.
+  ///
+  /// Returning a [Future], when the animation is completed(cancelled actually)
+  /// the future resolved.
+  Future<void> rollInfinitely({
+    bool clockwise = true,
+    Duration period = defaultPeriod,
+    Curve? curve,
+  }) {
+    final completer = Completer<void>();
+    final event = InfiniteRollEvent(clockwise: clockwise, period: period);
+    _eventStreamController.add(event);
+
+    StreamSubscription? subscription;
+    subscription = _callbackStreamController.stream.listen((e) {
+      if (e is OnRollCancelledEvent && e.event == event) {
+        completer.complete();
+        subscription?.cancel();
+      }
+    });
+
+    return completer.future;
+  }
+
   void dispose() {
     _eventStreamController.close();
     _callbackStreamController.close();

lib/utils/constants.dart

@@ -3,3 +3,6 @@ const int defaultMinRotateCircles = 12;
 
 /// Default rotate animation run time
 const Duration defaultDuration = Duration(seconds: 5);
+
+/// Default infinite roll period
+const Duration defaultPeriod = Duration(seconds: 1);

lib/utils/helpers.dart

@@ -23,6 +23,24 @@ Animation<double> makeAnimation(
   }
 }
 
+/// Make [Animation] from [controller] to begin infinite roll effect.
+Animation<double> makeInfiniteRollAnimation(
+  AnimationController controller, {
+  required bool clockwise,
+  double initialValue = 0,
+  Curve? curve,
+}) {
+  final begin = initialValue % (2 * pi);
+  final end = begin + 2 * pi * (clockwise ? 1 : -1);
+  final tween = Tween(begin: begin, end: end);
+  if (curve != null) {
+    final curved = CurvedAnimation(parent: controller, curve: curve);
+    return curved.drive(tween);
+  } else {
+    return controller.drive(tween);
+  }
+}
+
 /// Calculate the end rotate value by [targetIndex].
 /// The returned value contains the circles to roll.
 /// Make sure when you run this method the [group] has at least one [RouletteUnit].

pubspec.yaml

@@ -1,7 +1,10 @@
 name: roulette
 description: This is a library provide a simple roulette widget which usually used for lottery.
-version: 0.3.1
+version: 0.3.2
 repository: https://github.com/do9core/roulette
+issue_tracker: https://github.com/do9core/roulette/issues
+topics:
+  - widget
 
 environment:
   sdk: ">=2.12.0 <4.0.0"