You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -65,14 +62,27 @@ Almost all of these examples are available in the example application.
65
62
66
63
# Documentation
67
64
68
-
## CustomRefreshIndicator widget
65
+
## CustomRefreshIndicator
69
66
70
67
The _CustomRefreshIndicator_ widget provides an absolute minimum functionality that allows you to create and set your own custom indicators.
71
68
69
+
### child (Widget)
70
+
The widget tree that contains scrollable widget (eg. *ListView*).
71
+
### builder (IndicatorBuilder)
72
+
Function that builds the custom refresh indicator.
73
+
74
+
### onRefresh (AsyncCallback)
75
+
A function that is called when the user drags the refresh indicator far enough to trigger a "pull to refresh" action.
76
+
77
+
### controller (IndicatorController?)
78
+
The indicator controller stores all the data related to the refresh indicator widget. It will be passed as the third argument to the *builder* function.
79
+
80
+
If not specified, it will be created by the *CustomRefreshIndicator* widget.
81
+
72
82
### onStateChanged
73
83
74
-
The _onStateChanged_callback is called everytime_IndicatorState_ has been changed.
75
-
This is a convenient place for tracking indicator state changes. For a reference take a look at the [example check mark indicator widget](example/lib/indicators/check_mark_indicator.dart).
84
+
The _onStateChanged_function is called whenever_IndicatorState_ has changed.
85
+
This is a convenient way to track changes in the state of the indicator. For reference, take a look at [example checkmark indicator widget](example/lib/indicators/check_mark_indicator.dart).
76
86
77
87
Example usage:
78
88
@@ -91,28 +101,122 @@ CustomRefreshIndicator(
91
101
// ...
92
102
)
93
103
```
104
+
### indicatorCancelDuration (Duration)
105
+
Duration of hiding the indicator when dragging was stopped before the indicator was armed (the *onRefresh* callback was not called).
106
+
107
+
The default is 300 milliseconds.
108
+
### indicatorSettleDuration (Duration)
109
+
The time of settling the pointer on the target location after releasing the pointer in the armed state. During this process, the value of the indicator decreases from its current value, which can be greater than or equal to *1.0* but less or equal to *1.5*, to a target value of *1.0*.
110
+
111
+
The default is 150 milliseconds.
94
112
95
-
## IndicatorController
113
+
### indicatorFinalizeDuration (Duration)
114
+
Duration of hiding the pointer after the *onRefresh* function completes.
115
+
116
+
During this time, the value of the controller decreases from *1.0* to *0.0* with a state set to *IndicatorState.finalizing*.
117
+
118
+
The default is 100 milliseconds.
96
119
97
-
### Controller state and value changes.
120
+
### completeStateDuration (Duration?)
121
+
The duration the indicator remains at value *1.0* and the *IndicatorState.complete* state after the [onRefresh] function completes.
122
+
123
+
This value is optional, specifying it will enable the optional *IndicatorState.complete* state.
98
124
99
-
The best way to understand how the _CustomRefreshIndicator_ widget changes its controller data is to see the example 😉. An example is available in the example application.
Determines whether the received [ScrollNotification] should be handled by this widget.
127
+
128
+
By default, it only accepts *0* depth level notifications. This can be helpful for more complex layouts with nested scrollviews.
100
129
101
-
[](https://custom-refresh-indicator.klyta.it/#/presentation)
130
+
### leadingScrollIndicatorVisible (bool)
131
+
Whether to display leading scroll indicator (glow or stretch effect).
132
+
### trailingScrollIndicatorVisible (bool)
133
+
Whether to display trailing scroll indicator (glow or stretch effect).
134
+
135
+
### offsetToArmed (double?)
136
+
The distance in number of pixels that the user should drag to arm the indicator. The armed indicator will trigger the *onRefresh* function when the gesture is completed.
137
+
138
+
If not specified, *containerExtentPercentageToArmed* argument will be used instead.
139
+
140
+
### containerExtentPercentageToArmed (double)
141
+
The distance the user must scroll for the indicator to be armed, as a percentage of the scrollable's container extent.
142
+
143
+
If the *offsetToArmed* argument is specified, it will be used instead, and this value will not take effect.
144
+
145
+
The default value equals `0.1(6)`.
146
+
147
+
### trigger (IndicatorTrigger)
148
+
Defines the trigger for the pull to refresh gesture.
|**startEdge**| Pull to refresh can be triggered only from the **start** edge of the list. Mostly top side, but can be bottom for reversed ListView (with *reverse* argument set to true). |
152
+
|**endEdge**| Pull to refresh can be triggered only from the **end** edge of the list. Mostly bottom, but can be top for reversed ListView (with *reverse* argument set to true). |
153
+
|**bothEdges**| Pull to refresh can be triggered from **both edges** of the list. |
154
+
155
+
### triggerMode (IndicatorTriggerMode)
156
+
Configures how *CustomRefreshIndicator* widget can be triggered. Works in the same way as the triggerMode of the built-in *RefreshIndicator* widget.
|**idle**|`==0.0`| Value eqals `0.0`. | No user action. |
108
-
|**dragging**|`=<0.0`| Value is eqal `0.0` or larger but lower than `1.0`. | User is dragging the indicator. |
109
-
|**armed**|`>=1.0`| Value is larger than `1.0`. | User dragged the indicator further than the distance declared by `extentPercentageToArmed` or `offsetToArmed`. User still keeps the finger on the screen. |
110
-
|**loading**|`>=1.0`| Value decreses from last `armed` state value in duration of `armedToLoadingDuration` argument to `1.0`. | User finished dragging (took his finger off the screen), when state was equal to `armed`. `onRefresh` function is called. |
111
-
|**hiding**|`<=1.0`| Value decreses in duration of `draggingToIdleDuration` or `loadingToIdleDuration` arguments to `0.0`. | Indicator is hiding after:<br />- User ended dragging when indicator was in `dragging` state.<br />- Future returned from `onRefresh` function is resolved.<br />- Complete state ended.<br />- User started scrolling through the list. |
112
-
|**complete**|`==1.0`| Value equals `1.0` for duration of `completeStateDuration` argument. |**This state is OPTIONAL, provide `completeStateDuration` argument with non null value to enable it.**<br /> Loading is completed. |
|**anywhere**| The indicator can be triggered regardless of the scroll position of the *Scrollable* when the drag starts. |
163
+
|**onEdge**| The indicator can only be triggered if the *Scrollable* is at the edge when the drag starts. |
164
+
165
+
### autoRebuild (bool)
166
+
When set to *true*, the *builder* function will be triggered whenever the controller changes. This can be useful for optimizing performance in complex widgets. When setting this to *false*, you can manage which part of the ui you want to rebuild, such as using the *AnimationBuilder* widget in conjunction with *IndicatorController*.
167
+
168
+
The default is *true*.
169
+
170
+
## IndicatorController
171
+
172
+
The best way to understand how the _CustomRefreshIndicator_ widget changes the data of its controller is to look at the example 😉.
173
+
Open the sample application and try it yourself ([online example](https://custom-refresh-indicator.klyta.it/#/presentation)).
174
+
175
+
[](https://custom-refresh-indicator.klyta.it/#/presentation)
176
+
177
+
### state
178
+
The following table describes each state of the indicator controller.
|**idle**| In this state, the indicator is not visible. No user action is performed. Value remains at *0.0*. |
183
+
|**dragging**| The user starts scrolling/dragging the pointer to refresh. Releasing the pointer in this state will not trigger the *onRefresh* function. The controller value changes from *0.0* to *1.0*. |
184
+
|**canceling**| The function *onRefresh***has not been executed**, and the indicator is hidding from its current value that is lower than *1.0* to *0.0*. |
185
+
|**armed**| The user has dragged the pointer further than the distance declared by *containerExtentPercentageToArmed* or *offsetToArmed* (over the value of *1.0*). Releasing the pointer in this state will trigger the *onRefresh* function. |
186
+
|**loading**| The user has released the indicator in the armed state. The indicator settles on its target value *1.0* and the *onRefresh* function is called. |
187
+
|**complete**|**OPTIONAL** - Provide `completeStateDuration` argument to enable it. The *onRefresh* callback has completed and the pointer remains at value *1.0* for the specified duration. |
188
+
|**finalizing**| The *onRefresh* function **has been executed**, and the indicator hides from the value *1.0* to *0.0*. |
113
189
114
190
---
115
191
192
+
### edge (IndicatorEdge?)
193
+
Whether the pull to refresh gesture is triggered from the start of the list or from the end.
194
+
195
+
This is especially useful with the *trigger* argument set to `IndicatorTrigger.bothEdges`, as the gesture can then be triggered from start and end edge.
196
+
197
+
It is null when the edge is still not determined by the *CustomRefreshIndicator* widget.
|**top**| The indicator should be displayed on the **top** of the scrollable. |
208
+
|**bottom**| The indicator should be displayed on the **bottom** of the scrollable. |
209
+
|**left**| The indicator should be displayed on the **left** of the scrollable. |
210
+
|**right**| The indicator should be displayed on the **right** of the scrollable. |
211
+
|**none**| The indicator should not be displayed. |
212
+
### direction (AxisDirection)
213
+
The direction in which the list scrolls.
214
+
215
+
### scrollingDirection (ScrollDirection)
216
+
The direction in which the user scrolls.
217
+
218
+
___
219
+
116
220
### Support
117
221
118
222
If you like this package, you have learned something from it, or you just don't know what to do with your money 😅 just buy me a cup of coffee ☕️ and this dose of caffeine will put a smile on my face which in turn will help me improve this package. Also as a thank you, you will be mentioned in this readme as a sponsor.
0 commit comments