Document slide indicators in the readme

DavidDWiser · DavidDWiser · commit 2ecea4a419fe · 2023-12-07T11:31:40.000+01:00
diff --git a/README.md b/README.md
@@ -33,6 +33,7 @@ A customizable carousel slider widget in Flutter which supports infinite scrolli
       - [`.previousPage({Duration duration, Curve curve})`](#previouspageduration-duration-curve-curve)
       - [`.jumpToPage(int page)`](#jumptopageint-page)
       - [`.animateToPage(int page, {Duration duration, Curve curve})`](#animatetopageint-page-duration-duration-curve-curve)
+  - [Slide indicators](#slide-indicators)
   - [Contributing](#contributing)
   - [License](#license)
   - [Sponsor Me](#sponsor-me)
@@ -68,7 +69,7 @@ Add `flutter_carousel_widget` as a dependency in your `pubspec.yaml` file:
 
 ```dart
 dependencies:
-  flutter_carousel_widget: ^latest_version
+flutter_carousel_widget: ^latest_version
 ```
 
 And import it:
@@ -85,25 +86,25 @@ Flutter Carousel is a carousel widget which supports infinite scrolling, auto sc
 
 ```dart
 FlutterCarousel(
-  options: CarouselOptions(
-    height: 400.0, 
-    showIndicator: true,
-    slideIndicator: CircularSlideIndicator(),
-  ),
-  items: [1,2,3,4,5].map((i) {
-    return Builder(
-      builder: (BuildContext context) {
-        return Container(
-          width: MediaQuery.of(context).size.width,
-          margin: EdgeInsets.symmetric(horizontal: 5.0),
-          decoration: BoxDecoration(
-            color: Colors.amber
-          ),
-          child: Text('text $i', style: TextStyle(fontSize: 16.0),)
-        );
-      },
-    );
-  }).toList(),
+options: CarouselOptions(
+height: 400.0,
+showIndicator: true,
+slideIndicator: CircularSlideIndicator(),
+),
+items: [1,2,3,4,5].map((i) {
+return Builder(
+builder: (BuildContext context) {
+return Container(
+width: MediaQuery.of(context).size.width,
+margin: EdgeInsets.symmetric(horizontal: 5.0),
+decoration: BoxDecoration(
+color: Colors.amber
+),
+child: Text('text $i', style: TextStyle(fontSize: 16.0),)
+);
+},
+);
+}).toList(),
 )
 ```
 
@@ -113,57 +114,57 @@ Expandable Carousel is a carousel widget which automatically expands to the size
 
 ```dart
 ExpandableCarousel(
-  options: CarouselOptions(
-    autoPlay: true,
-    autoPlayInterval: const Duration(seconds: 2),
-  ),
-  items: [1,2,3,4,5].map((i) {
-    return Builder(
-      builder: (BuildContext context) {
-        return Container(
-          width: MediaQuery.of(context).size.width,
-          margin: EdgeInsets.symmetric(horizontal: 5.0),
-          decoration: BoxDecoration(
-            color: Colors.amber
-          ),
-          child: Text('text $i', style: TextStyle(fontSize: 16.0),)
-        );
-      },
-    );
-  }).toList(),
+options: CarouselOptions(
+autoPlay: true,
+autoPlayInterval: const Duration(seconds: 2),
+),
+items: [1,2,3,4,5].map((i) {
+return Builder(
+builder: (BuildContext context) {
+return Container(
+width: MediaQuery.of(context).size.width,
+margin: EdgeInsets.symmetric(horizontal: 5.0),
+decoration: BoxDecoration(
+color: Colors.amber
+),
+child: Text('text $i', style: TextStyle(fontSize: 16.0),)
+);
+},
+);
+}).toList(),
 )
 ```
 
 ### Option Customization
 
 ```dart
 FlutterCarousel(
-  items: items,
-  options: CarouselOptions(
-    height: 400.0,
-    aspectRatio: 16 / 9,
-    viewportFraction: 1.0,
-    initialPage: 0,
-    enableInfiniteScroll: true,
-    reverse: false,
-    autoPlay: false,
-    autoPlayInterval: const Duration(seconds: 2),
-    autoPlayAnimationDuration: const Duration(milliseconds: 800),
-    autoPlayCurve: Curves.fastOutSlowIn,
-    enlargeCenterPage: false,
-    controller: CarouselController(),
-    onPageChanged: callbackFunction,
-    pageSnapping: true,
-    scrollDirection: Axis.horizontal,
-    pauseAutoPlayOnTouch: true,
-    pauseAutoPlayOnManualNavigate: true,
-    pauseAutoPlayInFiniteScroll: false,
-    enlargeStrategy: CenterPageEnlargeStrategy.scale,
-    disableCenter: false,
-    showIndicator: true,
-    floatingIndicator = true,
-    slideIndicator: CircularSlideIndicator(),
-  )
+items: items,
+options: CarouselOptions(
+height: 400.0,
+aspectRatio: 16 / 9,
+viewportFraction: 1.0,
+initialPage: 0,
+enableInfiniteScroll: true,
+reverse: false,
+autoPlay: false,
+autoPlayInterval: const Duration(seconds: 2),
+autoPlayAnimationDuration: const Duration(milliseconds: 800),
+autoPlayCurve: Curves.fastOutSlowIn,
+enlargeCenterPage: false,
+controller: CarouselController(),
+onPageChanged: callbackFunction,
+pageSnapping: true,
+scrollDirection: Axis.horizontal,
+pauseAutoPlayOnTouch: true,
+pauseAutoPlayOnManualNavigate: true,
+pauseAutoPlayInFiniteScroll: false,
+enlargeStrategy: CenterPageEnlargeStrategy.scale,
+disableCenter: false,
+showIndicator: true,
+floatingIndicator = true,
+slideIndicator: CircularSlideIndicator(),
+)
 )
 ```
 
@@ -173,21 +174,21 @@ This method will save memory by building items once it becomes necessary. This w
 
 ```dart
 FlutterCarousel.builder(
-  itemCount: 15,
-  itemBuilder: (BuildContext context, int itemIndex, int pageViewIndex) =>
-  Container(
-    child: Text(itemIndex.toString()),
-  ),
+itemCount: 15,
+itemBuilder: (BuildContext context, int itemIndex, int pageViewIndex) =>
+Container(
+child: Text(itemIndex.toString()),
+),
 )
 ```
 
 ```dart
 ExpandableCarousel.builder(
-  itemCount: 15,
-  itemBuilder: (BuildContext context, int itemIndex, int pageViewIndex) =>
-  Container(
-    child: Text(itemIndex.toString()),
-  ),
+itemCount: 15,
+itemBuilder: (BuildContext context, int itemIndex, int pageViewIndex) =>
+Container(
+child: Text(itemIndex.toString()),
+),
 )
 ```
 
@@ -199,26 +200,26 @@ In order to manually control the pageview's position, you can create your own `C
 class CarouselDemo extends StatelessWidget {
   CarouselController buttonCarouselController = CarouselController();
 
- @override
+  @override
   Widget build(BuildContext context) => Column(
-    children: [
-      FlutterCarousel(
-        items: child,
-        options: CarouselOptions(
-          autoPlay: false,
-          controller: buttonCarouselController,
-          enlargeCenterPage: true,
-          viewportFraction: 0.9,
-          aspectRatio: 2.0,
-          initialPage: 2,
-        ),
-      ),
-      RaisedButton(
-        onPressed: () => buttonCarouselController.nextPage(
-            duration: Duration(milliseconds: 300), curve: Curves.linear),
-        child: Text('→'),
-      )
-    ]
+          children: [
+            FlutterCarousel(
+              items: child,
+              options: CarouselOptions(
+                autoPlay: false,
+                controller: buttonCarouselController,
+                enlargeCenterPage: true,
+                viewportFraction: 0.9,
+                aspectRatio: 2.0,
+                initialPage: 2,
+              ),
+            ),
+            RaisedButton(
+              onPressed: () => buttonCarouselController.nextPage(
+                      duration: Duration(milliseconds: 300), curve: Curves.linear),
+              child: Text('→'),
+            )
+          ]
   );
 }
 ```
@@ -241,6 +242,47 @@ Jump to the given page.
 
 Animate to the given page.
 
+## Slide indicators
+
+The `flutter_carousel_widget` package comes with a few [predefined slide indicators](https://github.com/nixrajput/flutter_carousel_widget/tree/master/lib/src/indicators) with their own unique behaviors. This helps drastically and brings focus towards the actual implementation of your carousel widget.
+
+However, there might be cases where you want to control the look or behavior of the slide indicator or implement a totally new one. You can do that by implementing the `SlideIndicator` contract.
+
+The following example implements an indicator which tells the percentage of the slide the user is on:
+```dart
+class SlidePercentageIndicator implements SlideIndicator {
+  SlidePercentageIndicator({
+    this.decimalPlaces = 0,
+    this.style,
+  });
+
+  /// The number of decimal places to show in the output
+  final int decimalPlaces;
+
+  /// The text style to be used by the percentage text
+  final TextStyle? style;
+
+  @override
+  Widget build(int currentPage, double pageDelta, int itemCount) {
+    if (itemCount < 2) return const SizedBox.shrink();
+
+    final step = 100 / (itemCount - 1);
+    final percentage = step * (pageDelta + currentPage);
+
+    return Center(
+      child: Text(
+        '${percentage.toStringAsFixed(decimalPlaces)}%',
+        style: style ??
+            const TextStyle(
+              fontSize: 24,
+              fontWeight: FontWeight.w600,
+            ),
+      ),
+    );
+  }
+}
+```
+
 ## Contributing
 
 If you would like to contribute to this project, feel free to fork the repository, make your changes, and submit a pull request. Please follow the guidelines in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
