diff --git a/packages/flutter/lib/src/material/mergeable_material.dart b/packages/flutter/lib/src/material/mergeable_material.dart index 9bab283a51d..3c4dba64af8 100644 --- a/packages/flutter/lib/src/material/mergeable_material.dart +++ b/packages/flutter/lib/src/material/mergeable_material.dart @@ -118,6 +118,9 @@ class MergeableMaterial extends StatefulWidget { /// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24 /// /// Defaults to 2, the appropriate elevation for cards. + /// + /// This uses [kElevationToShadow] to simulate shadows, it does not use + /// [Material]'s arbitrary elevation feature. final int elevation; /// Whether connected pieces of [MaterialSlice] have dividers between them. diff --git a/packages/flutter/lib/src/material/shadows.dart b/packages/flutter/lib/src/material/shadows.dart index e88fbd1f3f1..a2fbe96df0a 100644 --- a/packages/flutter/lib/src/material/shadows.dart +++ b/packages/flutter/lib/src/material/shadows.dart @@ -17,9 +17,13 @@ import 'package:flutter/painting.dart'; /// Each entry has three shadows which must be combined to obtain the defined /// effect for that elevation. /// +/// This is useful when simulating a shadow with a [BoxDecoration] or other +/// class that uses a list of [BoxShadow] objects. +/// /// See also: /// -/// * [Material] +/// * [Material], which takes an arbitrary double for its elevation and generates +/// a shadow dynamically. /// * const Map> kElevationToShadow = _elevationToShadow; // to hide the literal from the docs diff --git a/packages/flutter/lib/src/painting/box_decoration.dart b/packages/flutter/lib/src/painting/box_decoration.dart index 455ceb61dd5..9523f0e727c 100644 --- a/packages/flutter/lib/src/painting/box_decoration.dart +++ b/packages/flutter/lib/src/painting/box_decoration.dart @@ -169,6 +169,12 @@ class BoxDecoration extends Decoration { /// A list of shadows cast by this box behind the box. /// /// The shadow follows the [shape] of the box. + /// + /// See also: + /// + /// * [kElevationToShadow], for some predefined shadows used in Material + /// Design. + /// * [PhysicalModel], a widget for showing shadows. final List boxShadow; /// A gradient to use when filling the box. diff --git a/packages/flutter/lib/src/painting/box_shadow.dart b/packages/flutter/lib/src/painting/box_shadow.dart index 04a86e127f2..cadc77e7848 100644 --- a/packages/flutter/lib/src/painting/box_shadow.dart +++ b/packages/flutter/lib/src/painting/box_shadow.dart @@ -12,8 +12,6 @@ import 'debug.dart'; /// A shadow cast by a box. /// -/// Inherits from [Shadow] -/// /// [BoxShadow] can cast non-rectangular shadows if the box is non-rectangular /// (e.g., has a border radius or a circular shape). /// @@ -22,6 +20,9 @@ import 'debug.dart'; /// See also: /// /// * [Canvas.drawShadow], which is a more efficient way to draw shadows. +/// * [PhysicalModel], a widget for showing shadows. +/// * [kElevationToShadow], for some predefined shadows used in Material +/// Design. /// * [Shadow], which is the parent class that lacks [spreadRadius]. @immutable class BoxShadow extends ui.Shadow { diff --git a/packages/flutter/lib/src/painting/shape_decoration.dart b/packages/flutter/lib/src/painting/shape_decoration.dart index 7c6a3ef6122..7c3ef669564 100644 --- a/packages/flutter/lib/src/painting/shape_decoration.dart +++ b/packages/flutter/lib/src/painting/shape_decoration.dart @@ -141,7 +141,13 @@ class ShapeDecoration extends Decoration { /// The image is drawn over the [color] or [gradient]. final DecorationImage image; - /// A list of shadows cast by this shape behind the shape. + /// A list of shadows cast by the [shape]. + /// + /// See also: + /// + /// * [kElevationToShadow], for some predefined shadows used in Material + /// Design. + /// * [PhysicalModel], a widget for showing shadows. final List shadows; /// The shape to fill the [color], [gradient], and [image] into and to cast as diff --git a/packages/flutter/lib/src/widgets/animated_cross_fade.dart b/packages/flutter/lib/src/widgets/animated_cross_fade.dart index 26f95a3c45d..e5ac68afd9c 100644 --- a/packages/flutter/lib/src/widgets/animated_cross_fade.dart +++ b/packages/flutter/lib/src/widgets/animated_cross_fade.dart @@ -102,10 +102,11 @@ typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChild /// /// See also: /// +/// * [AnimatedOpacity], which fades between nothing and a single child. +/// * [AnimatedSwitcher], which switches out a child for a new one with a +/// customizable transition, supporting multiple cross-fades at once. /// * [AnimatedSize], the lower-level widget which [AnimatedCrossFade] uses to /// automatically change size. -/// * [AnimatedSwitcher], which switches out a child for a new one with a -/// customizable transition. class AnimatedCrossFade extends StatefulWidget { /// Creates a cross-fade animation widget. /// diff --git a/packages/flutter/lib/src/widgets/animated_size.dart b/packages/flutter/lib/src/widgets/animated_size.dart index 43e4ec33b08..2b888714951 100644 --- a/packages/flutter/lib/src/widgets/animated_size.dart +++ b/packages/flutter/lib/src/widgets/animated_size.dart @@ -10,6 +10,10 @@ import 'framework.dart'; /// Animated widget that automatically transitions its size over a given /// duration whenever the given child's size changes. +/// +/// See also: +/// +/// * [SizeTransition], which changes its size based on an [Animation]. class AnimatedSize extends SingleChildRenderObjectWidget { /// Creates a widget that animates its size to match that of its child. /// diff --git a/packages/flutter/lib/src/widgets/animated_switcher.dart b/packages/flutter/lib/src/widgets/animated_switcher.dart index 92042c4445e..5bbc49d6939 100644 --- a/packages/flutter/lib/src/widgets/animated_switcher.dart +++ b/packages/flutter/lib/src/widgets/animated_switcher.dart @@ -63,8 +63,8 @@ typedef AnimatedSwitcherTransitionBuilder = Widget Function(Widget child, Animat /// `currentChild`. typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, List previousChildren); -/// A widget that by default does a [FadeTransition] between a new widget and -/// the widget previously set on the [AnimatedSwitcher] as a child. +/// A widget that by default does a cross-fade between a new widget and the +/// widget previously set on the [AnimatedSwitcher] as a child. /// /// If they are swapped fast enough (i.e. before [duration] elapses), more than /// one previous child can exist and be transitioning out while the newest one @@ -140,7 +140,9 @@ typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, Lis /// /// * [AnimatedCrossFade], which only fades between two children, but also /// interpolates their sizes, and is reversible. -/// * [FadeTransition] which [AnimatedSwitcher] uses to perform the transition. +/// * [AnimatedOpacity], which can be used to switch between nothingness and +/// a given child by fading the child in and out. +/// * [FadeTransition], which [AnimatedSwitcher] uses to perform the transition. class AnimatedSwitcher extends StatefulWidget { /// Creates an [AnimatedSwitcher]. /// diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index b16504ba999..aa0daf1cc5b 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -3999,10 +3999,6 @@ class Flex extends MultiChildRenderObjectWidget { /// ) /// ``` /// -/// You will see this issue when you run the app: -/// -/// ![A screenshot of the error using the Row widget](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_error.png) -/// /// The row first asks its first child, the [FlutterLogo], to lay out, at /// whatever size the logo would like. The logo is friendly and happily decides /// to be 24 pixels to a side. This leaves lots of room for the next child. The @@ -4015,12 +4011,11 @@ class Flex extends MultiChildRenderObjectWidget { /// have no more room available for my other children!", and gets angry and /// sprouts a yellow and black strip. /// -/// {@tool sample} +/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_error.png) +/// /// The fix is to wrap the second child in an [Expanded] widget, which tells the /// row that the child should be given the remaining room: /// -/// ![A screenshot of the Row widget after applying the fix](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_fixed.png) -/// /// ```dart /// Row( /// children: [ @@ -4032,7 +4027,6 @@ class Flex extends MultiChildRenderObjectWidget { /// ], /// ) /// ``` -/// {@end-tool} /// /// Now, the row first asks the logo to lay out, and then asks the _icon_ to lay /// out. The [Icon], like the logo, is happy to take on a reasonable size (also @@ -4042,6 +4036,8 @@ class Flex extends MultiChildRenderObjectWidget { /// text, now happy to comply to a reasonable request, wraps the text within /// that width, and you end up with a paragraph split over several lines. /// +/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/row_fixed.png) +/// /// ## Layout algorithm /// /// _This section describes how a [Row] is rendered by the framework._ diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index ea223af260f..b0bccf3d3e0 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -5008,6 +5008,15 @@ abstract class RenderObjectElement extends Element { /// this element has a single child, the slot should always be null. If this /// element has a list of children, the previous sibling is a convenient value /// for the slot. + /// + /// This method is only ever called if [updateChild] can end up being called + /// with an existing [Element] child and a `slot` that differs from the slot + /// that element was previously given. [MultiChildRenderObjectElement] does this, + /// for example. [SingleChildRenderObjectElement] does not (since the `slot` is + /// always null). An [Element] that has a specific set of slots with each child + /// always having the same slot (and where children in different slots are never + /// compared against each other for the purposes of updating one slot with the + /// element from another slot) would never call this. @protected void moveChildRenderObject(covariant RenderObject child, covariant dynamic slot); diff --git a/packages/flutter/lib/src/widgets/implicit_animations.dart b/packages/flutter/lib/src/widgets/implicit_animations.dart index 4631ce47188..40b8364b0ac 100644 --- a/packages/flutter/lib/src/widgets/implicit_animations.dart +++ b/packages/flutter/lib/src/widgets/implicit_animations.dart @@ -1259,6 +1259,8 @@ class _AnimatedPositionedDirectionalState extends AnimatedWidgetBaseState { @mustCallSuper void didReplace(Route oldRoute) { } - /// Returns false if this route wants to veto a [Navigator.pop]. This method is + /// Returns whether this route wants to veto a [Navigator.pop]. This method is /// called by [Navigator.maybePop]. /// /// By default, routes veto a pop if they're the first route in the history @@ -1304,12 +1304,18 @@ class Navigator extends StatefulWidget { return navigator != null && navigator.canPop(); } - /// Returns the value of the current route's [Route.willPop] method for the - /// navigator that most tightly encloses the given context. + /// Tries to pop the current route of the navigator that most tightly encloses + /// the given context, while honoring the route's [Route.willPop] + /// state. /// /// {@template flutter.widgets.navigator.maybePop} - /// This method is typically called before a user-initiated [pop]. For example - /// on Android it's called by the binding for the system's back button. + /// Returns false if the route deferred to the next enclosing navigator + /// (possibly the system); otherwise, returns true (whether the route was + /// popped or not). + /// + /// This method is typically called to handle a user-initiated [pop]. For + /// example on Android it's called by the binding for the system's back + /// button. /// /// The `T` type argument is the type of the return value of the current /// route. @@ -2017,8 +2023,8 @@ class NavigatorState extends State with TickerProviderStateMixin { return _history.length > 1 || _history[0].willHandlePopInternally; } - /// Returns the value of the current route's [Route.willPop] method for the - /// navigator. + /// Tries to pop the current route, while honoring the route's [Route.willPop] + /// state. /// /// {@macro flutter.widgets.navigator.maybePop} /// diff --git a/packages/flutter/lib/src/widgets/scroll_view.dart b/packages/flutter/lib/src/widgets/scroll_view.dart index 9304c71e5a7..8c2d19dc853 100644 --- a/packages/flutter/lib/src/widgets/scroll_view.dart +++ b/packages/flutter/lib/src/widgets/scroll_view.dart @@ -768,8 +768,8 @@ abstract class BoxScrollView extends ScrollView { /// [new ListView] constructor's `children` argument corresponds to the /// [childrenDelegate] being a [SliverChildListDelegate] with that same /// argument. The [new ListView.builder] constructor's `itemBuilder` and -/// `childCount` arguments correspond to the [childrenDelegate] being a -/// [SliverChildBuilderDelegate] with the matching arguments. +/// `itemCount` arguments correspond to the [childrenDelegate] being a +/// [SliverChildBuilderDelegate] with the equivalent arguments. /// /// The [padding] property corresponds to having a [SliverPadding] in the /// [CustomScrollView.slivers] property instead of the list itself, and having diff --git a/packages/flutter/lib/src/widgets/sliver.dart b/packages/flutter/lib/src/widgets/sliver.dart index 1997ba77d3f..e59e3efb7de 100644 --- a/packages/flutter/lib/src/widgets/sliver.dart +++ b/packages/flutter/lib/src/widgets/sliver.dart @@ -127,7 +127,11 @@ abstract class SliverChildDelegate { /// return a precise non-null value. /// /// Subclasses typically override this function and wrap their children in - /// [AutomaticKeepAlive] and [RepaintBoundary] widgets. + /// [AutomaticKeepAlive], [IndexedSemantics], and [RepaintBoundary] widgets. + /// + /// The values returned by this method are cached. To indicate that the + /// widgets have changed, a new delegate must be provided, and the new + /// delegate's [shouldRebuild] method must return true. Widget build(BuildContext context, int index); /// Returns an estimate of the number of children this delegate will build. @@ -711,6 +715,10 @@ abstract class SliverWithKeepAliveWidget extends RenderObjectWidget { /// A base class for sliver that have multiple box children. /// /// Helps subclasses build their children lazily using a [SliverChildDelegate]. +/// +/// The widgets returned by the [delegate] are cached and the delegate is only +/// consulted again if it changes and the new delegate's [shouldRebuild] method +/// returns true. abstract class SliverMultiBoxAdaptorWidget extends SliverWithKeepAliveWidget { /// Initializes fields for subclasses. const SliverMultiBoxAdaptorWidget({ @@ -722,7 +730,7 @@ abstract class SliverMultiBoxAdaptorWidget extends SliverWithKeepAliveWidget { /// {@template flutter.widgets.sliverChildDelegate} /// The delegate that provides the children for this widget. /// - /// The children are constructed lazily using this widget to avoid creating + /// The children are constructed lazily using this delegate to avoid creating /// more children than are visible through the [Viewport]. /// /// See also: diff --git a/packages/flutter_test/lib/src/finders.dart b/packages/flutter_test/lib/src/finders.dart index 214995f530e..dddeff07344 100644 --- a/packages/flutter_test/lib/src/finders.dart +++ b/packages/flutter_test/lib/src/finders.dart @@ -244,7 +244,12 @@ class CommonFinders { /// /// If the [skipOffstage] argument is true (the default), then nodes that are /// [Offstage] or that are from inactive [Route]s are skipped. - Finder descendant({ Finder of, Finder matching, bool matchRoot = false, bool skipOffstage = true }) { + Finder descendant({ + @required Finder of, + @required Finder matching, + bool matchRoot = false, + bool skipOffstage = true, + }) { return _DescendantFinder(of, matching, matchRoot: matchRoot, skipOffstage: skipOffstage); } @@ -269,7 +274,11 @@ class CommonFinders { /// /// If the [matchRoot] argument is true then the widget(s) specified by [of] /// will be matched along with the ancestors. - Finder ancestor({ Finder of, Finder matching, bool matchRoot = false }) { + Finder ancestor({ + @required Finder of, + @required Finder matching, + bool matchRoot = false, + }) { return _AncestorFinder(of, matching, matchRoot: matchRoot); }