Merge pull request #15 from llucax/countdown

Add example implementing a paudable countdown

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.0+2
+
+- Add example implementing a pausable countdown.
+
 ## 0.1.0+1
 
 - Add build status and sponsorship badges.

README.md

@@ -12,7 +12,7 @@ A [Dart](https://dart.dev/)
 [timer](https://api.dart.dev/stable/dart-async/Timer/Timer.html) that can be
 paused, resumed and reset.
 
-## Example
+## Example using `start()`, `pause()` and `reset()`
 
 ```dart
 import 'package:pausable_timer/pausable_timer.dart';
@@ -70,3 +70,67 @@ void main() async {
   print('isCancelled: ${timer.isCancelled}');
 }
 ```
+
+## Example pausable countdown implementation
+
+```dart
+import 'package:pausable_timer/pausable_timer.dart';
+
+/// Example on how to implement countdown making a PausableTimer periodic.
+void main() async {
+  PausableTimer timer;
+  var countDown = 5;
+
+  print('Create a periodic timer that fires every 1 second and starts it');
+  timer = PausableTimer(
+    Duration(seconds: 1),
+    () {
+      countDown--;
+      // If we reached 0, we don't reset and restart the time, so it won't fire
+      // again, but it can be reused afterwards if needed. If we cancel the
+      // timer, then it can be reused after the countdown is over.
+      if (countDown > 0) {
+        timer
+          ..reset()
+          ..start();
+      }
+      // This is really what your callback do.
+      print('\t$countDown');
+    },
+  )..start();
+
+  print('And wait 2.1 seconds...');
+  print('(0.1 extra to make sure there is no race between the timer and the '
+      'waiting here)');
+  await Future<void>.delayed(timer.duration * 2.1);
+  print('By now 2 events should have fired: 4, 3\n');
+
+  print('We can pause it now');
+  timer.pause();
+
+  print('And we wait for 2 more seconds...');
+  await Future<void>.delayed(timer.duration * 2);
+  print("But our timer doesn't care while it's paused\n");
+
+  print('So we start it again');
+  timer.start();
+  print('And wait for 3.1 seconds more...');
+  await Future<void>.delayed(timer.duration * 3.1);
+  print('And we are done: 2, 1 and 0 should have been printed');
+
+  print('The timer should be unpaused, inactive, expired and not cancelled');
+  print('isPaused: ${timer.isPaused}');
+  print('isActive: ${timer.isActive}');
+  print('isExpired: ${timer.isExpired}');
+  print('isCancelled: ${timer.isCancelled}');
+
+  print('We can now reset it and start it again, now for 3 seconds');
+  countDown = 3;
+  timer
+    ..reset()
+    ..start();
+  print('And wait for 3.1 seconds...');
+  await Future<void>.delayed(timer.duration * 3.1);
+  print('And it should be done printing: 2, 1 and 0');
+}
+```

example/countdown.dart

@@ -0,0 +1,59 @@
+import 'package:pausable_timer/pausable_timer.dart';
+
+/// Example on how to implement countdown making a PausableTimer periodic.
+void main() async {
+  PausableTimer timer;
+  var countDown = 5;
+
+  print('Create a periodic timer that fires every 1 second and starts it');
+  timer = PausableTimer(
+    Duration(seconds: 1),
+    () {
+      countDown--;
+      // If we reached 0, we don't reset and restart the time, so it won't fire
+      // again, but it can be reused afterwards if needed. If we cancel the
+      // timer, then it can be reused after the countdown is over.
+      if (countDown > 0) {
+        timer
+          ..reset()
+          ..start();
+      }
+      // This is really what your callback do.
+      print('\t$countDown');
+    },
+  )..start();
+
+  print('And wait 2.1 seconds...');
+  print('(0.1 extra to make sure there is no race between the timer and the '
+      'waiting here)');
+  await Future<void>.delayed(timer.duration * 2.1);
+  print('By now 2 events should have fired: 4, 3\n');
+
+  print('We can pause it now');
+  timer.pause();
+
+  print('And we wait for 2 more seconds...');
+  await Future<void>.delayed(timer.duration * 2);
+  print("But our timer doesn't care while it's paused\n");
+
+  print('So we start it again');
+  timer.start();
+  print('And wait for 3.1 seconds more...');
+  await Future<void>.delayed(timer.duration * 3.1);
+  print('And we are done: 2, 1 and 0 should have been printed');
+
+  print('The timer should be unpaused, inactive, expired and not cancelled');
+  print('isPaused: ${timer.isPaused}');
+  print('isActive: ${timer.isActive}');
+  print('isExpired: ${timer.isExpired}');
+  print('isCancelled: ${timer.isCancelled}');
+
+  print('We can now reset it and start it again, now for 3 seconds');
+  countDown = 3;
+  timer
+    ..reset()
+    ..start();
+  print('And wait for 3.1 seconds...');
+  await Future<void>.delayed(timer.duration * 3.1);
+  print('And it should be done printing: 2, 1 and 0');
+}

pubspec.yaml

@@ -3,7 +3,7 @@ description: A timer implementation that can be paused, resumed and reset.
 homepage: https://github.com/llucax/pausable_timer
 repository: https://github.com/llucax/pausable_timer
 
-version: 0.1.0+1
+version: 0.1.0+2
 
 environment:
   sdk: ">=2.7.0 <3.0.0"