bumped to version 3.0.1

nixrajput · Sep 10, 2024 · aeced03 · aeced03
1 parent 97762f9
commit aeced03
Show file tree

Hide file tree

Showing 18 changed files with 134 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.0.1
+
+- **Improvement**: Added comments to the classes, controllers, states, options, and enums.
+- **Improvement**: Formatted the code to pass static analysis.
+- **Documentation**: Removed demo `gif` to reduce package size.
+
 ## 3.0.0
 
 - **Breaking Change**: New `FlutterCarouselOptions` introduced for `FlutterCarousel`.

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # flutter_carousel_widget
 
-A customizable carousel slider widget for Flutter, offering features such as infinite scrolling, auto-scrolling, custom child widgets, custom animations, pre-built indicators, expandable carousel widgets, and auto-sized child support.
+A customizable carousel widget for Flutter, offering features such as infinite scrolling, auto-scrolling, custom child widgets, pre-built indicators, expandable child widgets, auto-sized child support, and enlarged center page.
 
 [![pub package](https://img.shields.io/pub/v/flutter_carousel_widget.svg?label=Version&style=flat)][pub]
 [![Stars](https://img.shields.io/github/stars/nixrajput/flutter_carousel_widget?label=Stars&style=flat)][repo]
@@ -56,7 +56,7 @@ A customizable carousel slider widget for Flutter, offering features such as inf
 - **Auto-sized Child Support:** Automatically adjust the size of the carousel items to fit their content.
 - **Enlarge Center Page:** The focused item can be enlarged.
 
-## Breaking Changes for v3.0.0
+## Breaking Changes for the version ^3.0.0
 
 In version 3.0.0 of the package, the following breaking changes have been introduced:
 
@@ -87,8 +87,6 @@ If you have been using CarouselOptions, CarouselController, and CarouselState fo
 
 ## Demo
 
-![Demo](https://raw.githubusercontent.com/nixrajput/flutter_carousel_widget/master/screenshots/flutter_carousel_widget_demo.gif)
-
 ### [Click here to experience the demo in a Web App](https://nixrajput.github.io/flutter_carousel_widget)
 
 ## Installation

diff --git a/lib/flutter_carousel_widget.dart b/lib/flutter_carousel_widget.dart
@@ -1,3 +1,11 @@
+library flutter_carousel_widget;
+
+/// Export statements to expose internal files and classes
+/// from the [flutter_carousel_widget] package.
+///
+/// These exports allow other files or packages to access and
+/// use the classes, controllers, states, options, enums, and indicators.
+
 export 'package:flutter_carousel_widget/src/_expandable_carousel_widget.dart';
 export 'package:flutter_carousel_widget/src/_flutter_carousel_widget.dart';
 export 'package:flutter_carousel_widget/src/carousel_controller/expandable_carousel_controller.dart';

diff --git a/lib/src/carousel_controller/expandable_carousel_controller.dart b/lib/src/carousel_controller/expandable_carousel_controller.dart
@@ -6,26 +6,37 @@ import '../carousel_state/expandable_carousel_state.dart';
 import '../enums/carousel_page_changed_reason.dart';
 import '../utils/flutter_carousel_utils.dart';
 
+/// Abstract controller class to handle carousel interactions like navigation and auto-play.
 abstract class ExpandableCarouselController {
+  /// Factory constructor that returns an implementation of the controller.
   factory ExpandableCarouselController() => ExpandableCarouselControllerImpl();
 
+  /// Indicates if the controller is ready.
   bool get ready;
 
+  /// Future that completes when the controller is ready.
   Future<void> get onReady;
 
+  /// Navigates to the next page in the carousel.
   void nextPage({Duration? duration, Curve? curve});
 
+  /// Navigates to the previous page in the carousel.
   void previousPage({Duration? duration, Curve? curve});
 
+  /// Jumps to a specific page in the carousel without animation.
   void jumpToPage(int page);
 
+  /// Animates the carousel to a specific page.
   void animateToPage(int page, {Duration? duration, Curve? curve});
 
+  /// Starts the auto-play functionality of the carousel.
   void startAutoPlay();
 
+  /// Stops the auto-play functionality of the carousel.
   void stopAutoPlay();
 }
 
+/// Implementation of the ExpandableCarouselController interface.
 class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
   final Completer<void> _readyCompleter = Completer<void>();
   ExpandableCarouselState? _state;
@@ -34,19 +45,23 @@ class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
   /// The animation lasts for the given duration and follows the given curve.
   /// The returned [Future] resolves when the animation completes.
   @override
-  void animateToPage(int page,
-      {Duration? duration = const Duration(milliseconds: 300),
-      Curve? curve = Curves.linear}) async {
+  void animateToPage(
+    int page, {
+    Duration? duration = const Duration(milliseconds: 300),
+    Curve? curve = Curves.linear,
+  }) async {
     final isNeedResetTimer = _state!.options.pauseAutoPlayOnManualNavigate;
 
     if (isNeedResetTimer) {
       _state!.onResetTimer();
     }
 
+    // Calculate the real index to animate to.
     final index = getRealIndex(_state!.pageController?.page!.toInt() ?? 0,
         _state!.realPage - _state!.initialPage, _state!.itemCount);
     _setModeController();
 
+    // Animate to the target page.
     await _state!.pageController!.animateToPage(
         (_state!.pageController?.page!.toInt() ?? 0) + page - index,
         duration: duration!,
@@ -67,6 +82,7 @@ class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
 
     _setModeController();
 
+    // Jump directly to the target page.
     return _state!.pageController?.jumpToPage(
         (_state!.pageController?.page!.toInt() ?? 0) + page - index);
   }
@@ -75,9 +91,10 @@ class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
   /// The animation lasts for the given duration and follows the given curve.
   /// The returned [Future] resolves when the animation completes.
   @override
-  void nextPage(
-      {Duration? duration = const Duration(milliseconds: 300),
-      Curve? curve = Curves.linear}) async {
+  void nextPage({
+    Duration? duration = const Duration(milliseconds: 300),
+    Curve? curve = Curves.linear,
+  }) async {
     final isNeedResetTimer = _state!.options.pauseAutoPlayOnManualNavigate;
 
     if (isNeedResetTimer) {
@@ -86,23 +103,26 @@ class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
 
     _setModeController();
 
+    // Navigate to the next page.
     await _state!.pageController?.nextPage(duration: duration!, curve: curve!);
 
     if (isNeedResetTimer) {
       _state!.onResumeTimer();
     }
   }
 
+  /// Future that completes when the controller is ready.
   @override
   Future<void> get onReady => _readyCompleter.future;
 
   /// Animates the controlled [ExpandableCarousel] to the previous page.
   /// The animation lasts for the given duration and follows the given curve.
   /// The returned [Future] resolves when the animation completes.
   @override
-  void previousPage(
-      {Duration? duration = const Duration(milliseconds: 300),
-      Curve? curve = Curves.linear}) async {
+  void previousPage({
+    Duration? duration = const Duration(milliseconds: 300),
+    Curve? curve = Curves.linear,
+  }) async {
     final isNeedResetTimer = _state!.options.pauseAutoPlayOnManualNavigate;
 
     if (isNeedResetTimer) {
@@ -111,6 +131,7 @@ class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
 
     _setModeController();
 
+    // Navigate to the previous page.
     await _state!.pageController
         ?.previousPage(duration: duration!, curve: curve!);
 
@@ -119,6 +140,7 @@ class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
     }
   }
 
+  /// Checks if the controller is ready to interact with the carousel.
   @override
   bool get ready => _state != null;
 
@@ -138,13 +160,15 @@ class ExpandableCarouselControllerImpl implements ExpandableCarouselController {
     _state!.onResetTimer();
   }
 
+  /// Sets the current state of the carousel.
   set state(ExpandableCarouselState? state) {
     _state = state;
     if (!_readyCompleter.isCompleted) {
       _readyCompleter.complete();
     }
   }
 
+  /// Sets the carousel change mode to controller-based.
   void _setModeController() =>
       _state!.changeMode(CarouselPageChangedReason.controller);
 }
diff --git a/lib/src/carousel_controller/flutter_carousel_controller.dart b/lib/src/carousel_controller/flutter_carousel_controller.dart
@@ -7,22 +7,31 @@ import '../enums/carousel_page_changed_reason.dart';
 import '../utils/flutter_carousel_utils.dart';
 
 abstract class FlutterCarouselController {
+  /// Factory constructor that returns an implementation of the controller.
   factory FlutterCarouselController() => FlutterCarouselControllerImpl();
 
+  /// Indicates if the controller is ready.
   bool get ready;
 
+  /// Future that completes when the controller is ready.
   Future<void> get onReady;
 
+  /// Navigates to the next page in the carousel.
   void nextPage({Duration? duration, Curve? curve});
 
+  /// Navigates to the previous page in the carousel.
   void previousPage({Duration? duration, Curve? curve});
 
+  /// Jumps to a specific page in the carousel without animation.
   void jumpToPage(int page);
 
+  /// Animates the carousel to a specific page.
   void animateToPage(int page, {Duration? duration, Curve? curve});
 
+  /// Starts the auto-play functionality of the carousel.
   void startAutoPlay();
 
+  /// Stops the auto-play functionality of the carousel.
   void stopAutoPlay();
 }
 
@@ -34,19 +43,24 @@ class FlutterCarouselControllerImpl implements FlutterCarouselController {
   /// The animation lasts for the given duration and follows the given curve.
   /// The returned [Future] resolves when the animation completes.
   @override
-  void animateToPage(int page,
-      {Duration? duration = const Duration(milliseconds: 300),
-      Curve? curve = Curves.linear}) async {
+  void animateToPage(
+    int page, {
+    Duration? duration = const Duration(milliseconds: 300),
+    Curve? curve = Curves.linear,
+  }) async {
     final isNeedResetTimer = _state!.options.pauseAutoPlayOnManualNavigate;
 
     if (isNeedResetTimer) {
       _state!.onResetTimer();
     }
+
+    // Calculate the real index to animate to.
     final index = getRealIndex(_state!.pageController?.page!.toInt() ?? 0,
         _state!.realPage - _state!.initialPage, _state!.itemCount);
 
     _setModeController();
 
+    // Animate to the target page.
     await _state!.pageController!.animateToPage(
         (_state!.pageController?.page!.toInt() ?? 0) + page - index,
         duration: duration!,
@@ -67,6 +81,7 @@ class FlutterCarouselControllerImpl implements FlutterCarouselController {
 
     _setModeController();
 
+    // Jump directly to the target page.
     return _state!.pageController?.jumpToPage(
         (_state!.pageController?.page!.toInt() ?? 0) + page - index);
   }
@@ -75,9 +90,10 @@ class FlutterCarouselControllerImpl implements FlutterCarouselController {
   /// The animation lasts for the given duration and follows the given curve.
   /// The returned [Future] resolves when the animation completes.
   @override
-  void nextPage(
-      {Duration? duration = const Duration(milliseconds: 300),
-      Curve? curve = Curves.linear}) async {
+  void nextPage({
+    Duration? duration = const Duration(milliseconds: 300),
+    Curve? curve = Curves.linear,
+  }) async {
     final isNeedResetTimer = _state!.options.pauseAutoPlayOnManualNavigate;
 
     if (isNeedResetTimer) {
@@ -86,23 +102,26 @@ class FlutterCarouselControllerImpl implements FlutterCarouselController {
 
     _setModeController();
 
+    // Navigate to the next page.
     await _state!.pageController?.nextPage(duration: duration!, curve: curve!);
 
     if (isNeedResetTimer) {
       _state!.onResumeTimer();
     }
   }
 
+  /// Future that completes when the controller is ready.
   @override
   Future<void> get onReady => _readyCompleter.future;
 
   /// Animates the controlled [FlutterCarousel] to the previous page.
   /// The animation lasts for the given duration and follows the given curve.
   /// The returned [Future] resolves when the animation completes.
   @override
-  void previousPage(
-      {Duration? duration = const Duration(milliseconds: 300),
-      Curve? curve = Curves.linear}) async {
+  void previousPage({
+    Duration? duration = const Duration(milliseconds: 300),
+    Curve? curve = Curves.linear,
+  }) async {
     final isNeedResetTimer = _state!.options.pauseAutoPlayOnManualNavigate;
 
     if (isNeedResetTimer) {
@@ -111,6 +130,7 @@ class FlutterCarouselControllerImpl implements FlutterCarouselController {
 
     _setModeController();
 
+    // Navigate to the previous page.
     await _state!.pageController!
         .previousPage(duration: duration!, curve: curve!);
 
@@ -119,6 +139,7 @@ class FlutterCarouselControllerImpl implements FlutterCarouselController {
     }
   }
 
+  /// Checks if the controller is ready to interact with the carousel.
   @override
   bool get ready => _state != null;
 
@@ -138,13 +159,15 @@ class FlutterCarouselControllerImpl implements FlutterCarouselController {
     _state!.onResetTimer();
   }
 
+  /// Sets the current state of the carousel.
   set state(FlutterCarouselState? state) {
     _state = state;
     if (!_readyCompleter.isCompleted) {
       _readyCompleter.complete();
     }
   }
 
+  /// Sets the carousel change mode to controller-based.
   void _setModeController() =>
       _state!.changeMode(CarouselPageChangedReason.controller);
 }
diff --git a/lib/src/carousel_options/base_carousel_options.dart b/lib/src/carousel_options/base_carousel_options.dart
@@ -5,6 +5,8 @@ import '../enums/carousel_page_changed_reason.dart';
 import '../enums/center_page_enlarge_strategy.dart';
 import '../indicators/slide_indicator.dart';
 
+/// Abstract class for carousel options, defining base configuration parameters.
+/// This class can be extended to create more specific carousel options for different carousel types.
 abstract class BaseCarouselOptions {
   BaseCarouselOptions({
     this.aspectRatio,

diff --git a/lib/src/carousel_options/expandable_carousel_options.dart b/lib/src/carousel_options/expandable_carousel_options.dart
@@ -7,6 +7,8 @@ import '../enums/center_page_enlarge_strategy.dart';
 import '../indicators/slide_indicator.dart';
 import 'base_carousel_options.dart';
 
+/// The [ExpandableCarouselOptions] class extends [BaseCarouselOptions] and
+/// adds more configuration options specific to the [ExpandableCarousel] widget.
 class ExpandableCarouselOptions extends BaseCarouselOptions {
   ExpandableCarouselOptions({
     this.controller,
@@ -91,6 +93,8 @@ class ExpandableCarouselOptions extends BaseCarouselOptions {
 
   /// Copy With Constructor
   ExpandableCarouselOptions copyWith({
+    ExpandableCarouselController? controller,
+    double? estimatedPageSize,
     double? aspectRatio,
     double? viewportFraction,
     int? initialPage,
@@ -101,7 +105,6 @@ class ExpandableCarouselOptions extends BaseCarouselOptions {
     Duration? autoPlayAnimationDuration,
     Curve? autoPlayCurve,
     Axis? scrollDirection,
-    ExpandableCarouselController? carouselController,
     Function(int index, CarouselPageChangedReason reason)? onPageChanged,
     ValueChanged<double?>? onScrolled,
     ScrollPhysics? physics,
@@ -125,9 +128,9 @@ class ExpandableCarouselOptions extends BaseCarouselOptions {
     double? enlargeFactor,
     CenterPageEnlargeStrategy? enlargeStrategy,
     bool? disableCenter,
-    double? estimatedPageSize,
   }) {
     return ExpandableCarouselOptions(
+      controller: controller ?? this.controller,
       aspectRatio: aspectRatio ?? this.aspectRatio,
       viewportFraction: viewportFraction ?? this.viewportFraction,
       initialPage: initialPage ?? this.initialPage,