Update readme.md

Author: Kamil Klyta

CHANGELOG.md

@@ -1,46 +1,64 @@
-## [1.0.0]
+## [0.8.0] - April 12, 2020
+
 ## BREAKING API CHANGES
-* Feedback improvements (thank you for emails!):
-  * Changed long identifier names:
-    * `CustomRefreshIndicatorData` => `IndicatorData`
-    * `CustomRefreshIndicatorState` => `IndicatorState`
-    * `CustomIndicatorBuilder` => `IndicatorBuilder`
-* Changed `indicatorState` key contained in `IndicatorData` to => `state`
-* ## `indicatorBuilder` function is no longer called on every `IndicatorData` change!
-
-To animate indicator based on `IndicatorData` you can use `AnimationBuilder` widget and pass `IndicatorData` object as `animation` argument. Because of that you can implement your own widget rebuild system what can improve your custom indicator performance (instead of building indicator eg. 300 times you can decide when you want to do it). Example:
+
+- Feedback improvements (thank you for your emails!):
+  - Changed long identifier names:
+    - `CustomRefreshIndicatorData` => `IndicatorController`
+    - `CustomRefreshIndicatorState` => `IndicatorState`
+- Update example app
+- ## `indicatorBuilder` argument is no longer present. Instead use `builder` argument which has some significant changes.
+
+To animate indicator based on `IndicatorControler` you can use `AnimationBuilder` widget and pass `IndicatorData` object as `animation` argument. Because of that you can implement your own widget rebuild system what can improve your custom indicator performance (instead of building indicator eg. 300 times you can decide when you want to do it). Example:
+
 ```dart
 return CustomRefreshIndicator(
     child: ListView(children: <Widget>[/* ... */]),
-    indicatorBuilder: (BuildContext context, IndicatorData data) {
+    builder: (
+      BuildContext context,
+      /// Subtree that contains scrollable widget and was passed
+      /// to child argument
+      Widget child,
+      /// Now all your data will be stored in controller.
+      /// To get controller outside of this function
+      /// 1. Create controller in parent widget and pass it to CustomRefreshIndicator
+      /// 2. Assign [GlobalKey] to CustomRefreshIndicator and access `key.currentState.controller`.
+      IndicatorController controller
+    ) {
       return AnimatedBuilder(
         // IndicatorData extends ChangeNotifier class so it is possible to
-        // assign it to an AnimationBuilder and take advantage of subtree rebuild
-        animation: data,
+        // assign it to an AnimationBuilder widget and take advantage of subtree rebuild
+        animation: controller,
         child: MyPrebuildWidget(),
+        child: child,
         builder: (BuildContext context, Widget child) {
-          return MyCustomIndicator(child: child);
+          /// TODO: Implement your custom refresh indicator
         },
       );
     },
     onRefresh: myAsyncMethod,
   );
 ```
+
 ## [0.2.1]
-* Upgrade example to AndroidX
-* Improved README
+
+- Upgrade example to AndroidX
+- Improved README
+
 ## [0.2.0] - Added support for BouncingScrollPhysics.
-* Added support for `BouncingScrollPhysics` - ios default sroll physics
-* Improved readme
+
+- Added support for `BouncingScrollPhysics` - ios default sroll physics
+- Improved readme
+
 ## [0.1.1]
-* Extracted inbox example to [`letter_refresh_indicator`](https://pub.dev/packages/letter_refresh_indicator) package
-## [0.1.0] - Initial version.
-* Added basic `CustomRefreshIndicator` widget with `CustomRefreshIndicatorData` class.
-* Added `SimpleIndicatorContainer` widget which simulate default `RefreshIndicator` container
-* Added examples:
-  * inbox
-  * simple
-  * blur
 
+- Extracted inbox example to [`letter_refresh_indicator`](https://pub.dev/packages/letter_refresh_indicator) package
 
+## [0.1.0] - Initial version.
 
+- Added basic `CustomRefreshIndicator` widget with `CustomRefreshIndicatorData` class.
+- Added `SimpleIndicatorContainer` widget which simulate default `RefreshIndicator` container
+- Added examples:
+  - inbox
+  - simple
+  - blur

README.md

@@ -1,95 +1,137 @@
 # Flutter Custom Refresh Indicator
 
-This package provides `CustomRefreshIndicator` widget that make it easy to implement your own custom refresh indicator.
+This package provides `CustomRefreshIndicator` widget that make it easy to implement your own custom refresh indicator. It listens for scroll events from scroll widget passed to child argument and parsing it to data easy for custom refresh indicator implementation. Indicator data is provided by IndicatorController (third argument of builder method). Long story short... thats it!
+
+If there is something that can be improved, fixed or you just have some great idea feel free to open github issue [HERE](https://github.com/gonuit/flutter-custom-refresh-indicator/issues) or open a pull request [HERE](https://github.com/gonuit/flutter-custom-refresh-indicator/pulls).
+
+If you implemented your own custom refresh indicator with this library and you want it to be mentioned here or provided as an example to the eample app, just open a pull request [HERE](https://github.com/gonuit/flutter-custom-refresh-indicator/pulls).
+
+## QUICK START
+
+### Code
 
-## Usage
 ```dart
 CustomRefreshIndicator(
-  // Your custom indicator builder
-  indicatorBuilder: (context, data) => SimpleIndicatorContainer(
-    data: data,
-    child: SimpleIndicatorContent(data: data),
-  ),
-  onRefresh: myAsyncRefreshMethod,
-  // Your child scroll widget 
+  /// Scrollable widget
   child: ListView.separated(
     itemBuilder: (BuildContext context, int index) => const SizedBox(
       height: 100,
     ),
     separatorBuilder: (BuildContext context, int index) =>
         const SizedBox(height: 20),
   ),
+  /// Custom indicator builder function
+  builder: (
+    BuildContext context,
+    Widget child,
+    IndicatorController controller,
+    ) {
+      /// TODO: Implement your own refresh indicator
+      return Stack(
+        children: <Widget>[
+          AnimatedBuilder(
+            animation: controller,
+            builder: (BuildContext context, _) {
+              /// This part will be rebuild on every controller change
+              return MyIndicator();
+            },
+          ),
+          /// Scrollable widget that was provided as [child] argument
+          ///
+          /// TIP:
+          /// You can also wrap [child] with [Transform] widget to also a animate list transform (see example app)
+          child,
+        ],
+      );
+    }
+  /// A function that's called when the user has dragged the refresh indicator
+  /// far enough to demonstrate that they want the app to refresh.
+  /// Should return [Future].
+  onRefresh: myAsyncRefreshMethod,
 )
 ```
 
-## Getting started
+### How the controller data change
+
+The best way to understand how the "CustomRefreshIndicator" widget changes its controller data is to see the example 😉.
+![Controller_Data](readme/controller_data.gif)
 
 ## Examples
-### Use of `SimpleIndicatorContainer` with `Icon` as child [LINK](example/lib/indicators/simple_indicator.dart)  
-![simple_indicator](readme/simple_container.gif)
 
-### Envelope indicator
-![letter_indicator](readme/letter_indicator.gif)
+Almost all of these examples are available in the example application.
 
+### Plane indicator [[SOURCE CODE](example/lib/indicators/plane_indicator.dart)]
 
+![plane_indicator](readme/plane_indicator.gif)
 
-### `CustomRefreshIndicator`
-`CustomRefreshIndicator` has an absolute minimum functionality that allows you to create and set your own custom indicators.
+### Ice cream indicator [[SOURCE CODE](example/lib/indicators/ice_cream_indicator.dart)]
 
-#### Arguments
-| Argument                            | Type                                                            | Default value                  | Required          |    
-| :---------------------------------- | :-------------------------------------------------------------- | :----------------------------- | :---------------- |
-| child                               | `Widget`                                                        | none                           | true              |
-| onRefresh                           | `Future<void> Function()`                                       | none                           | true              |
-| indicatorBuilder                    | `Widget Function(BuildContext, CustomRefreshIndicatorData)  `   | none                           | true              |
-| dragingToIdleDuration               | `Duration`                                                      | `Duration(milliseconds: 300)`  | false             |
-| armedToLoadingDuration              | `Duration`                                                      | `Duration(milliseconds: 200)`  | false             |
-| loadingToIdleDuration               | `Duration`                                                      | `Duration(milliseconds: 100)`  | false             |
-| leadingGlowVisible                  | `bool`                                                          | `false`                        | false             |
-| trailingGlowVisible                 | `bool`                                                          | `true`                         | false             |
+![ice_cream_indicator](readme/ice_cream_indicator.gif)
 
+### Simple indicator made with `PositionedIndicatorContainer` [[SOURCE CODE](example/lib/indicators/simple_indicator.dart)]
 
-### `CustomRefreshIndicatorData`
-Contains data provided by `CustomRefreshIndicator` that could be usefull for your custom indicator implementation.
+![simple_indicator](readme/simple_with_opacity.gif)
 
-### Arguments
+### Envelope indicator
+
+![letter_indicator](readme/letter_indicator.gif)
+
+### Emoji indicator [[SOURCE CODE](example/lib/indicators/emoji_indicator.dart)]
+
+You can create any indicator you want!
 
-| argument           | type                          |
-| :----------------- | :---------------------------- |
-| value              | `double`                      |
-| direction          | `AxisDirection`               |
-| scrollingDirection | `ScrollDirection`             |
-| indicatorState     | `IndicatorState` |
+![letter_indicator](readme/emoji_indicator.gif)
 
-#### value
+## CustomRefreshIndicator widget
 
-### `IndicatorState`
-Enum which describes state of CustomRefreshIndicator.
+`CustomRefreshIndicator` widget provides an absolute minimum functionality that allows you to create and set your own custom indicators.
+
+## IndicatorState
+
+Enum which describes state of CustomRefreshIndicator. It is provided by IndicatorController.
 
 #### `idle`
-  `CustomRefreshIndicator` is idle (There is no action)
-  
-  (`CustomRefreshIndicatorData.value == 0`)
+
+CustomRefreshIndicator is idle (There is no action)
+
+```dart
+controller.value == 0.0
+```
 
 #### `draging`
-  Whether user is draging `CustomRefreshIndicator` ending the scroll **WILL NOT** result in `onRefresh` call  
-  
-  (`CustomRefreshIndicatorData.value < 1`)
+
+Whether the user is dragging a scrollable widget.  
+Ending the scroll **WILL NOT** result in `onRefresh` function call
+
+```dart
+controller.value < 1.0
+```
 
 #### `armed`
-  `CustomRefreshIndicator` is armed ending the scroll **WILL** result in:
-  - `CustomRefreshIndicator.onRefresh` call
-  - change of status to `loading`
-  - decreasing `CustomRefreshIndicatorData.value` to `1` in duration specified by `CustomRefreshIndicator.armedToLoadingDuration`)
-  
-  (`CustomRefreshIndicatorData.value >= 1`)
+
+CustomRefreshIndicator is armed ending the scroll **WILL** result in:
+
+- `onRefresh` function call
+- change of indicator status to `loading`
+- decreasing controller.value to `1.0` in duration specified by `armedToLoadingDuration` CustomRefreshIndicator widget argument
+
+```dart
+controller.value >= 1.0
+```
 
 #### `hiding`
-  CustomRefreshIndicator is hiding indicator when `onRefresh` future is resolved or indicator was canceled (scroll ended when [IndicatorState] was equal to `dragging` so `value` was less than `1` or the user started scrolling through the list)
-  
-  (`CustomRefreshIndicatorData.value` decreases to `0` in duration specified by `CustomRefreshIndicator.dragingToIdleDuration`)
+
+CustomRefreshIndicator is hiding its indicator. After the future returned from `onRefresh` function is completed or scroll ended when the state was equal to `dragging` or the user started scrolling through the list.
+controller value decreases to `0.0` in duration specified by `dragingToIdleDuration` CustomRefreshIndicator widget argument.
+
+```dart
+controller.value <= 1.0
+```
 
 #### `loading`
-  `CustomRefreshIndicator` is awaiting on `onRefresh` call result. When `onRefresh` will resolve `CustomRefreshIndicator` will change state from `loading` to `hiding` and decrease `CustomRefreshIndicatorData.value` from `1` to `0` in duration specified by `CustomRefreshIndicator.loadingToIdleDuration`
-  
-  (`CustomRefreshIndicatorData.value == 1`)
+
+CustomRefreshIndicator widget is awaiting on future returned from `onRefresh` function. After future completed state will be change into `hiding` and controller value will decrease from `1.0` to `0.0` in duration specified by `loadingToIdleDuration` CustomRefreshIndicator widget argument.
+
+```dart
+controller.value == 1.0
+```

example/lib/indicators/plane_indicator.dart

@@ -30,7 +30,6 @@ class _Cloud {
   });
 }
 
-/// Desgin by Katarzyna Klyta kasia@klyta.it
 class PlaneIndicator extends StatefulWidget {
   final Widget child;
   const PlaneIndicator({

example/lib/screens/presentation_screen.dart

@@ -1,5 +1,4 @@
 import 'package:custom_refresh_indicator/custom_refresh_indicator.dart';
-import 'package:example/indicators/custom_indicator.dart';
 import 'package:example/widgets/example_app_bar.dart';
 import 'package:flutter/material.dart';
 

example/pubspec.lock

@@ -77,7 +77,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.2.1"
+    version: "0.8.0"
   flutter:
     dependency: "direct main"
     description: flutter

pubspec.yaml

@@ -1,6 +1,6 @@
 name: custom_refresh_indicator
 description: Flutter Widget that make it easy to implement custom refresh indicator.
-version: 0.2.1
+version: 0.8.0
 repository: https://github.com/gonuit/flutter-custom-refresh-indicator
 issue_tracker: https://github.com/gonuit/flutter-custom-refresh-indicator/issues
 homepage: https://github.com/gonuit/flutter-custom-refresh-indicator