Update style for CupertinoRefreshControl. (#19025)

All slivers must start with Sliver (or CupertinoSliver).
All widgets must have a key argument.

Also, some minor tweaks here and there to style and docs.

examples/flutter_gallery/lib/demo/cupertino/cupertino_refresh_demo.dart

@@ -51,7 +51,7 @@ class _CupertinoRefreshControlDemoState extends State<CupertinoRefreshControlDem
               const CupertinoSliverNavigationBar(
                 largeTitle: const Text('Cupertino Refresh'),
               ),
-              new CupertinoRefreshControl(
+              new CupertinoSliverRefreshControl(
                 onRefresh: () {
                   return new Future<void>.delayed(const Duration(seconds: 2))
                       ..then((_) => setState(() => repopulateList()));

packages/flutter/lib/src/cupertino/refresh.dart

@@ -13,34 +13,35 @@ import 'activity_indicator.dart';
 import 'colors.dart';
 import 'icons.dart';
 
-class _CupertinoRefreshSliver extends SingleChildRenderObjectWidget {
-  const _CupertinoRefreshSliver({
+class _CupertinoSliverRefresh extends SingleChildRenderObjectWidget {
+  const _CupertinoSliverRefresh({
+    Key key,
     this.refreshIndicatorLayoutExtent = 0.0,
     this.hasLayoutExtent = false,
     Widget child,
   }) : assert(refreshIndicatorLayoutExtent != null),
        assert(refreshIndicatorLayoutExtent >= 0.0),
        assert(hasLayoutExtent != null),
-       super(child: child);
+       super(key: key, child: child);
 
   // The amount of space the indicator should occupy in the sliver in a
   // resting state when in the refreshing mode.
   final double refreshIndicatorLayoutExtent;
-  // _RenderCupertinoRefreshSliver will paint the child in the available
-  // space either way but this instructs the _RenderCupertinoRefreshSliver
+  // _RenderCupertinoSliverRefresh will paint the child in the available
+  // space either way but this instructs the _RenderCupertinoSliverRefresh
   // on whether to also occupy any layoutExtent space or not.
   final bool hasLayoutExtent;
 
   @override
-  _RenderCupertinoRefreshSliver createRenderObject(BuildContext context) {
-    return new _RenderCupertinoRefreshSliver(
+  _RenderCupertinoSliverRefresh createRenderObject(BuildContext context) {
+    return new _RenderCupertinoSliverRefresh(
       refreshIndicatorExtent: refreshIndicatorLayoutExtent,
       hasLayoutExtent: hasLayoutExtent,
     );
   }
 
   @override
-  void updateRenderObject(BuildContext context, covariant _RenderCupertinoRefreshSliver renderObject) {
+  void updateRenderObject(BuildContext context, covariant _RenderCupertinoSliverRefresh renderObject) {
     renderObject
       ..refreshIndicatorLayoutExtent = refreshIndicatorLayoutExtent
       ..hasLayoutExtent = hasLayoutExtent;
@@ -53,10 +54,9 @@ class _CupertinoRefreshSliver extends SingleChildRenderObjectWidget {
 //
 // The [layoutExtentOffsetCompensation] field keeps internal accounting to
 // prevent scroll position jumps as the [layoutExtent] is set and unset.
-class _RenderCupertinoRefreshSliver
-    extends RenderSliver
+class _RenderCupertinoSliverRefresh extends RenderSliver
     with RenderObjectWithChildMixin<RenderBox> {
-  _RenderCupertinoRefreshSliver({
+  _RenderCupertinoSliverRefresh({
     @required double refreshIndicatorExtent,
     @required bool hasLayoutExtent,
     RenderBox child,
@@ -185,13 +185,17 @@ enum RefreshIndicatorMode {
   /// Initial state, when not being overscrolled into, or after the overscroll
   /// is canceled or after done and the sliver retracted away.
   inactive,
+
   /// While being overscrolled but not far enough yet to trigger the refresh.
   drag,
+
   /// Dragged far enough that the onRefresh callback will run and the dragged
   /// displacement is not yet at the final refresh resting state.
   armed,
+
   /// While the onRefresh task is running.
   refresh,
+
   /// While the indicator is animating away after refreshing.
   done,
 }
@@ -201,7 +205,7 @@ enum RefreshIndicatorMode {
 /// control and the space available.
 ///
 /// The `refreshTriggerPullDistance` and `refreshIndicatorExtent` parameters are
-/// the same values passed into the [CupertinoRefreshControl].
+/// the same values passed into the [CupertinoSliverRefreshControl].
 ///
 /// The `pulledExtent` parameter is the currently available space either from
 /// overscrolling or as held by the sliver during refresh.
@@ -213,9 +217,9 @@ typedef Widget RefreshControlIndicatorBuilder(
   double refreshIndicatorExtent,
 );
 
-/// A callback function that's invoked when the [CupertinoRefreshControl] is
+/// A callback function that's invoked when the [CupertinoSliverRefreshControl] is
 /// pulled a `refreshTriggerPullDistance`. Must return a [Future]. Upon
-/// completion of the [Future], the [CupertinoRefreshControl] enters the
+/// completion of the [Future], the [CupertinoSliverRefreshControl] enters the
 /// [RefreshIndicatorMode.done] state and will start to go away.
 typedef Future<void> RefreshCallback();
 
@@ -254,19 +258,22 @@ typedef Future<void> RefreshCallback();
 ///  * [RefreshIndicator], a Material Design version of the pull-to-refresh
 ///    paradigm. This widget works differently than [RefreshIndicator] because
 ///    instead of being an overlay on top of the scrollable, the
-///    [CupertinoRefreshControl] is part of the scrollable and actively occupies
+///    [CupertinoSliverRefreshControl] is part of the scrollable and actively occupies
 ///    scrollable space.
-class CupertinoRefreshControl extends StatefulWidget {
-  /// Create a new [CupertinoRefreshControl] for inserting into a list of slivers.
+class CupertinoSliverRefreshControl extends StatefulWidget {
+  /// Create a new refresh control for inserting into a list of slivers.
   ///
-  /// [refreshTriggerPullDistance], [refreshIndicatorExtent] both have reasonable
-  /// defaults and cannot be null.
+  /// The [refreshTriggerPullDistance] and [refreshIndicatorExtent] arguments
+  /// must not be null.
   ///
-  /// [builder] has a default indicator builder but can be null, in which case
-  /// no indicator UI will be shown but the [onRefresh] will still be invoked.
+  /// The [builder] argument may be null, in which case no indicator UI will be
+  /// shown but the [onRefresh] will still be invoked. By default, [builder]
+  /// shows a [CupertinoActivityIndicator].
   ///
-  /// [onRefresh] will be called when pulled far enough to trigger a refresh.
-  const CupertinoRefreshControl({
+  /// The [onRefresh] argument will be called when pulled far enough to trigger
+  /// a refresh.
+  const CupertinoSliverRefreshControl({
+    Key key,
     this.refreshTriggerPullDistance = _defaultRefreshTriggerPullDistance,
     this.refreshIndicatorExtent = _defaultRefreshIndicatorExtent,
     this.builder = buildSimpleRefreshIndicator,
@@ -279,7 +286,8 @@ class CupertinoRefreshControl extends StatefulWidget {
          refreshTriggerPullDistance >= refreshIndicatorExtent,
          'The refresh indicator cannot take more space in its final state '
          'than the amount initially created by overscrolling.'
-       );
+       ),
+       super(key: key);
 
   /// The amount of overscroll the scrollable must be dragged to trigger a reload.
   ///
@@ -327,12 +335,12 @@ class CupertinoRefreshControl extends StatefulWidget {
   static const double _defaultRefreshTriggerPullDistance = 100.0;
   static const double _defaultRefreshIndicatorExtent = 60.0;
 
-  /// Retrieve the current state of the CupertinoRefreshControl. The same as the
+  /// Retrieve the current state of the CupertinoSliverRefreshControl. The same as the
   /// state that gets passed into the [builder] function. Used for testing.
   @visibleForTesting
   static RefreshIndicatorMode state(BuildContext context) {
-    final _CupertinoRefreshControlState state
-        = context.ancestorStateOfType(const TypeMatcher<_CupertinoRefreshControlState>());
+    final _CupertinoSliverRefreshControlState state
+        = context.ancestorStateOfType(const TypeMatcher<_CupertinoSliverRefreshControlState>());
     return state.refreshState;
   }
 
@@ -373,10 +381,10 @@ class CupertinoRefreshControl extends StatefulWidget {
   }
 
   @override
-  _CupertinoRefreshControlState createState() => new _CupertinoRefreshControlState();
+  _CupertinoSliverRefreshControlState createState() => new _CupertinoSliverRefreshControlState();
 }
 
-class _CupertinoRefreshControlState extends State<CupertinoRefreshControl> {
+class _CupertinoSliverRefreshControlState extends State<CupertinoSliverRefreshControl> {
   /// Reset the state from done to inactive when only this fraction of the
   /// original `refreshTriggerPullDistance` is left.
   static const double _inactiveResetOverscrollFraction = 0.1;
@@ -498,7 +506,7 @@ class _CupertinoRefreshControlState extends State<CupertinoRefreshControl> {
 
   @override
   Widget build(BuildContext context) {
-    return new _CupertinoRefreshSliver(
+    return new _CupertinoSliverRefresh(
       refreshIndicatorLayoutExtent: widget.refreshIndicatorExtent,
       hasLayoutExtent: hasSliverLayoutExtent,
       // A LayoutBuilder lets the sliver's layout changes be fed back out to
@@ -515,9 +523,8 @@ class _CupertinoRefreshControlState extends State<CupertinoRefreshControl> {
               widget.refreshTriggerPullDistance,
               widget.refreshIndicatorExtent,
             );
-          } else {
-            return new Container();
           }
+          return new Container();
         },
       )
     );

packages/flutter/lib/src/material/refresh_indicator.dart

@@ -75,7 +75,7 @@ enum _RefreshIndicatorMode {
 ///  * [RefreshIndicatorState], can be used to programmatically show the refresh indicator.
 ///  * [RefreshProgressIndicator], widget used by [RefreshIndicator] to show
 ///    the inner circular progress spinner during refreshes.
-///  * [CupertinoRefreshControl], an iOS equivalent of the pull-to-refresh pattern.
+///  * [CupertinoSliverRefreshControl], an iOS equivalent of the pull-to-refresh pattern.
 ///    Must be used as a sliver inside a [CustomScrollView] instead of wrapping
 ///    around a [ScrollView] because it's a part of the scrollable instead of
 ///    being overlaid on top of it.