Skip to content

Commit 9012595

Browse files
gonuitgonuit
authored
Merge pull request #2 from gonuit/v0.8.0
V0.8.0
2 parents 7c2a4a7 + 36a898f commit 9012595

File tree

63 files changed

+1678
-468
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+1678
-468
lines changed

‎CHANGELOG.md‎

Lines changed: 58 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,64 @@
1+
## [0.8.0] - April 12, 2020
2+
3+
## BREAKING API CHANGES
4+
5+
- Feedback improvements (thank you for your emails!):
6+
- Changed long identifier names:
7+
- `CustomRefreshIndicatorData` => `IndicatorController`
8+
- `CustomRefreshIndicatorState` => `IndicatorState`
9+
- Update example app
10+
- ## `indicatorBuilder` argument is no longer present. Instead use `builder` argument which has some significant changes.
11+
12+
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:
13+
14+
```dart
15+
return CustomRefreshIndicator(
16+
child: ListView(children: <Widget>[/* ... */]),
17+
builder: (
18+
BuildContext context,
19+
/// Subtree that contains scrollable widget and was passed
20+
/// to child argument
21+
Widget child,
22+
/// Now all your data will be stored in controller.
23+
/// To get controller outside of this function
24+
/// 1. Create controller in parent widget and pass it to CustomRefreshIndicator
25+
/// 2. Assign [GlobalKey] to CustomRefreshIndicator and access `key.currentState.controller`.
26+
IndicatorController controller
27+
) {
28+
return AnimatedBuilder(
29+
// IndicatorData extends ChangeNotifier class so it is possible to
30+
// assign it to an AnimationBuilder widget and take advantage of subtree rebuild
31+
animation: controller,
32+
child: MyPrebuildWidget(),
33+
child: child,
34+
builder: (BuildContext context, Widget child) {
35+
/// TODO: Implement your custom refresh indicator
36+
},
37+
);
38+
},
39+
onRefresh: myAsyncMethod,
40+
);
41+
```
42+
143
## [0.2.1]
2-
* Upgrade example to AndroidX
3-
* Improved README
44+
45+
- Upgrade example to AndroidX
46+
- Improved README
47+
448
## [0.2.0] - Added support for BouncingScrollPhysics.
5-
* Added support for `BouncingScrollPhysics` - ios default sroll physics
6-
* Improved readme
49+
50+
- Added support for `BouncingScrollPhysics` - ios default sroll physics
51+
- Improved readme
52+
753
## [0.1.1]
8-
* Extracted inbox example to [`letter_refresh_indicator`](https://pub.dev/packages/letter_refresh_indicator) package
9-
## [0.1.0] - Initial version.
10-
* Added basic `CustomRefreshIndicator` widget with `CustomRefreshIndicatorData` class.
11-
* Added `SimpleIndicatorContainer` widget which simulate default `RefreshIndicator` container
12-
* Added examples:
13-
* inbox
14-
* simple
15-
* blur
1654

55+
- Extracted inbox example to [`letter_refresh_indicator`](https://pub.dev/packages/letter_refresh_indicator) package
1756

57+
## [0.1.0] - Initial version.
1858

59+
- Added basic `CustomRefreshIndicator` widget with `CustomRefreshIndicatorData` class.
60+
- Added `SimpleIndicatorContainer` widget which simulate default `RefreshIndicator` container
61+
- Added examples:
62+
- inbox
63+
- simple
64+
- blur

‎README.md‎

Lines changed: 101 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,137 @@
11
# Flutter Custom Refresh Indicator
22

3-
This package adds `CustomRefreshIndicator` widget that make it easy to implement your own custom refresh indicator.
3+
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!
4+
5+
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).
6+
7+
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).
8+
9+
## QUICK START
10+
11+
### Code
412

5-
## Example use:
613
```dart
714
CustomRefreshIndicator(
8-
// Your custom indicator builder
9-
indicatorBuilder: (context, data) => SimpleIndicatorContainer(
10-
data: data,
11-
child: SimpleIndicatorContent(data: data),
12-
),
13-
onRefresh: myAsyncRefreshMethod,
14-
// Your child scroll widget
15+
/// Scrollable widget
1516
child: ListView.separated(
1617
itemBuilder: (BuildContext context, int index) => const SizedBox(
1718
height: 100,
1819
),
1920
separatorBuilder: (BuildContext context, int index) =>
2021
const SizedBox(height: 20),
2122
),
23+
/// Custom indicator builder function
24+
builder: (
25+
BuildContext context,
26+
Widget child,
27+
IndicatorController controller,
28+
) {
29+
/// TODO: Implement your own refresh indicator
30+
return Stack(
31+
children: <Widget>[
32+
AnimatedBuilder(
33+
animation: controller,
34+
builder: (BuildContext context, _) {
35+
/// This part will be rebuild on every controller change
36+
return MyIndicator();
37+
},
38+
),
39+
/// Scrollable widget that was provided as [child] argument
40+
///
41+
/// TIP:
42+
/// You can also wrap [child] with [Transform] widget to also a animate list transform (see example app)
43+
child,
44+
],
45+
);
46+
}
47+
/// A function that's called when the user has dragged the refresh indicator
48+
/// far enough to demonstrate that they want the app to refresh.
49+
/// Should return [Future].
50+
onRefresh: myAsyncRefreshMethod,
2251
)
2352
```
2453

25-
## Working examples:
54+
### How the controller data change
55+
56+
The best way to understand how the "CustomRefreshIndicator" widget changes its controller data is to see the example 😉.
57+
![Controller_Data](readme/controller_data.gif)
58+
59+
## Examples
60+
61+
Almost all of these examples are available in the example application.
2662

27-
### Use of `SimpleIndicatorContainer` with `Icon` as child [LINK](example/lib/indicators/simple_indicator.dart)
28-
![simple_indicator](readme/simple_container.gif)
63+
### Plane indicator [[SOURCE CODE](example/lib/indicators/plane_indicator.dart)]
64+
65+
![plane_indicator](readme/plane_indicator.gif)
66+
67+
### Ice cream indicator [[SOURCE CODE](example/lib/indicators/ice_cream_indicator.dart)]
68+
69+
![ice_cream_indicator](readme/ice_cream_indicator.gif)
70+
71+
### Simple indicator made with `PositionedIndicatorContainer` [[SOURCE CODE](example/lib/indicators/simple_indicator.dart)]
72+
73+
![simple_indicator](readme/simple_with_opacity.gif)
2974

3075
### Envelope indicator
31-
![letter_indicator](readme/letter_indicator.gif)
3276

33-
## Getting started
77+
![letter_indicator](readme/letter_indicator.gif)
3478

35-
### `CustomRefreshIndicator`
36-
`CustomRefreshIndicator` has an absolute minimum functionality that allows you to create and set your own custom indicators.
79+
### Emoji indicator [[SOURCE CODE](example/lib/indicators/emoji_indicator.dart)]
3780

38-
#### Arguments
39-
| Argument | Type | Default value | Required |
40-
| :---------------------------------- | :-------------------------------------------------------------- | :----------------------------- | :---------------- |
41-
| child | `Widget` | none | true |
42-
| onRefresh | `Future<void> Function()` | none | true |
43-
| indicatorBuilder | `Widget Function(BuildContext, CustomRefreshIndicatorData) ` | none | true |
44-
| dragingToIdleDuration | `Duration` | `Duration(milliseconds: 300)` | false |
45-
| armedToLoadingDuration | `Duration` | `Duration(milliseconds: 200)` | false |
46-
| loadingToIdleDuration      | `Duration` | `Duration(milliseconds: 100)` | false |
47-
| leadingGlowVisible          | `bool` | `false` | false |
48-
| trailingGlowVisible          | `bool` | `true` | false |
81+
You can create any indicator you want!
4982

83+
![letter_indicator](readme/emoji_indicator.gif)
5084

51-
### `CustomRefreshIndicatorData`
52-
Object containig data provided by `CustomRefreshIndicator`.
85+
## CustomRefreshIndicator widget
5386

54-
#### Props
87+
`CustomRefreshIndicator` widget provides an absolute minimum functionality that allows you to create and set your own custom indicators.
5588

56-
| prop | type |
57-
| :----------------- | :---------------------------- |
58-
| value | `double` |
59-
| direction | `AxisDirection` |
60-
| scrollingDirection | `ScrollDirection` |
61-
| indicatorState | `CustomRefreshIndicatorState` |
89+
## IndicatorState
6290

63-
### `CustomRefreshIndicatorState`
64-
Enum which describes state of CustomRefreshIndicator.
91+
Enum which describes state of CustomRefreshIndicator. It is provided by IndicatorController.
6592

6693
#### `idle`
67-
`CustomRefreshIndicator` is idle (There is no action)
68-
69-
(`CustomRefreshIndicatorData.value == 0`)
94+
95+
CustomRefreshIndicator is idle (There is no action)
96+
97+
```dart
98+
controller.value == 0.0
99+
```
70100

71101
#### `draging`
72-
Whether user is draging `CustomRefreshIndicator` ending the scroll **WILL NOT** result in `onRefresh` call
73-
74-
(`CustomRefreshIndicatorData.value < 1`)
102+
103+
Whether the user is dragging a scrollable widget.
104+
Ending the scroll **WILL NOT** result in `onRefresh` function call
105+
106+
```dart
107+
controller.value < 1.0
108+
```
75109

76110
#### `armed`
77-
`CustomRefreshIndicator` is armed ending the scroll **WILL** result in:
78-
- `CustomRefreshIndicator.onRefresh` call
79-
- change of status to `loading`
80-
- decreasing `CustomRefreshIndicatorData.value` to `1` in duration specified by `CustomRefreshIndicator.armedToLoadingDuration`)
81-
82-
(`CustomRefreshIndicatorData.value >= 1`)
111+
112+
CustomRefreshIndicator is armed ending the scroll **WILL** result in:
113+
114+
- `onRefresh` function call
115+
- change of indicator status to `loading`
116+
- decreasing controller.value to `1.0` in duration specified by `armedToLoadingDuration` CustomRefreshIndicator widget argument
117+
118+
```dart
119+
controller.value >= 1.0
120+
```
83121

84122
#### `hiding`
85-
CustomRefreshIndicator is hiding indicator when `onRefresh` future is resolved or indicator was canceled (scroll ended when [CustomRefreshIndicatorState] was equal to `dragging` so `value` was less than `1` or the user started scrolling through the list)
86-
87-
(`CustomRefreshIndicatorData.value` decreases to `0` in duration specified by `CustomRefreshIndicator.dragingToIdleDuration`)
123+
124+
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.
125+
controller value decreases to `0.0` in duration specified by `dragingToIdleDuration` CustomRefreshIndicator widget argument.
126+
127+
```dart
128+
controller.value <= 1.0
129+
```
88130

89131
#### `loading`
90-
`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`
91-
92-
(`CustomRefreshIndicatorData.value == 1`)
132+
133+
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.
134+
135+
```dart
136+
controller.value == 1.0
137+
```

‎example/android/app/src/main/ic_launcher-playstore.png‎

21.2 KB
Loading

‎example/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
3+
<background android:drawable="@color/ic_launcher_background"/>
4+
<foreground android:drawable="@mipmap/ic_launcher_foreground"/>
5+
</adaptive-icon>

‎example/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
3+
<background android:drawable="@color/ic_launcher_background"/>
4+
<foreground android:drawable="@mipmap/ic_launcher_foreground"/>
5+
</adaptive-icon>

‎example/android/app/src/main/res/mipmap-hdpi/ic_launcher.png‎

1.22 KB
Loading

‎example/android/app/src/main/res/mipmap-hdpi/ic_launcher_foreground.png‎

2.82 KB
Loading

‎example/android/app/src/main/res/mipmap-hdpi/ic_launcher_round.png‎

3.58 KB
Loading

‎example/android/app/src/main/res/mipmap-mdpi/ic_launcher.png‎

723 Bytes
Loading

‎example/android/app/src/main/res/mipmap-mdpi/ic_launcher_foreground.png‎

1.73 KB
Loading

0 commit comments

Comments
 (0)