From 21c6dda1a15d3e84709b36e69c6515806c3d34b9 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Tue, 18 Dec 2018 10:18:48 -0800 Subject: [PATCH] assert(elevation >= 0.0) and doc clarifications (#25345) --- .../flutter/lib/src/material/app_bar.dart | 12 ++++--- .../lib/src/material/bottom_app_bar.dart | 8 +++-- .../lib/src/material/bottom_sheet.dart | 9 +++--- packages/flutter/lib/src/material/button.dart | 18 ++++++----- packages/flutter/lib/src/material/card.dart | 12 ++++--- packages/flutter/lib/src/material/chip.dart | 16 +++++++--- packages/flutter/lib/src/material/drawer.dart | 13 +++++--- .../src/material/floating_action_button.dart | 32 +++++++++++-------- .../flutter/lib/src/material/material.dart | 18 +++++++---- .../lib/src/material/material_button.dart | 22 ++++++------- .../lib/src/material/raised_button.dart | 3 +- .../flutter/lib/src/rendering/proxy_box.dart | 18 +++++++---- packages/flutter/lib/src/widgets/basic.dart | 16 +++++++--- .../lib/src/widgets/implicit_animations.dart | 10 ++++-- 14 files changed, 130 insertions(+), 77 deletions(-) diff --git a/packages/flutter/lib/src/material/app_bar.dart b/packages/flutter/lib/src/material/app_bar.dart index 304cef1a59..36a596317d 100644 --- a/packages/flutter/lib/src/material/app_bar.dart +++ b/packages/flutter/lib/src/material/app_bar.dart @@ -131,7 +131,8 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget { /// Creates a material design app bar. /// /// The arguments [elevation], [primary], [toolbarOpacity], [bottomOpacity] - /// and [automaticallyImplyLeading] must not be null. + /// and [automaticallyImplyLeading] must not be null. Additionally, + /// [elevation] must be non-negative. /// /// Typically used in the [Scaffold.appBar] property. AppBar({ @@ -153,7 +154,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget { this.toolbarOpacity = 1.0, this.bottomOpacity = 1.0, }) : assert(automaticallyImplyLeading != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(primary != null), assert(titleSpacing != null), assert(toolbarOpacity != null), @@ -264,10 +265,13 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget { /// * [PreferredSize], which can be used to give an arbitrary widget a preferred size. final PreferredSizeWidget bottom; - /// The z-coordinate at which to place this app bar. This controls the size of - /// the shadow below the app bar. + /// The z-coordinate at which to place this app bar relative to its parent. + /// + /// This controls the size of the shadow below the app bar. /// /// Defaults to 4, the appropriate elevation for app bars. + /// + /// The value is non-negative. final double elevation; /// The color to use for the app bar's material. Typically this should be set diff --git a/packages/flutter/lib/src/material/bottom_app_bar.dart b/packages/flutter/lib/src/material/bottom_app_bar.dart index a513b69faf..92268b6404 100644 --- a/packages/flutter/lib/src/material/bottom_app_bar.dart +++ b/packages/flutter/lib/src/material/bottom_app_bar.dart @@ -42,6 +42,7 @@ class BottomAppBar extends StatefulWidget { /// Creates a bottom application bar. /// /// The [color], [elevation], and [clipBehavior] arguments must not be null. + /// Additionally, [elevation] must be non-negative. const BottomAppBar({ Key key, this.color, @@ -68,8 +69,11 @@ class BottomAppBar extends StatefulWidget { /// When null defaults to [ThemeData.bottomAppBarColor]. final Color color; - /// The z-coordinate at which to place this bottom app bar. This controls the - /// size of the shadow below the bottom app bar. + /// The z-coordinate at which to place this bottom app bar relative to its + /// parent. + /// + /// This controls the size of the shadow below the bottom app bar. The + /// value is non-negative. /// /// Defaults to 8, the appropriate elevation for bottom app bars. final double elevation; diff --git a/packages/flutter/lib/src/material/bottom_sheet.dart b/packages/flutter/lib/src/material/bottom_sheet.dart index 0bff512677..08d69f4be5 100644 --- a/packages/flutter/lib/src/material/bottom_sheet.dart +++ b/packages/flutter/lib/src/material/bottom_sheet.dart @@ -59,7 +59,7 @@ class BottomSheet extends StatefulWidget { }) : assert(enableDrag != null), assert(onClosing != null), assert(builder != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), super(key: key); /// The animation that controls the bottom sheet's position. @@ -87,10 +87,11 @@ class BottomSheet extends StatefulWidget { /// Default is true. final bool enableDrag; - /// The z-coordinate at which to place this material. This controls the size - /// of the shadow below the material. + /// The z-coordinate at which to place this material relative to its parent. /// - /// Defaults to 0. + /// This controls the size of the shadow below the material. + /// + /// Defaults to 0. The value is non-negative. final double elevation; @override diff --git a/packages/flutter/lib/src/material/button.dart b/packages/flutter/lib/src/material/button.dart index e0c770686d..9552d21b4c 100644 --- a/packages/flutter/lib/src/material/button.dart +++ b/packages/flutter/lib/src/material/button.dart @@ -28,8 +28,10 @@ import 'theme_data.dart'; class RawMaterialButton extends StatefulWidget { /// Create a button based on [Semantics], [Material], and [InkWell] widgets. /// - /// The [shape], [elevation], [padding], [constraints], and [clipBehavior] - /// arguments must not be null. + /// The [shape], [elevation], [highlightElevation], [disabledElevation], + /// [padding], [constraints], and [clipBehavior] arguments must not be null. + /// Additionally, [elevation], [highlightElevation], and [disabledElevation] + /// must be non-negative. const RawMaterialButton({ Key key, @required this.onPressed, @@ -50,9 +52,9 @@ class RawMaterialButton extends StatefulWidget { this.child, }) : materialTapTargetSize = materialTapTargetSize ?? MaterialTapTargetSize.padded, assert(shape != null), - assert(elevation != null), - assert(highlightElevation != null), - assert(disabledElevation != null), + assert(elevation != null && elevation >= 0.0), + assert(highlightElevation != null && highlightElevation >= 0.0), + assert(disabledElevation != null && disabledElevation >= 0.0), assert(padding != null), assert(constraints != null), assert(animationDuration != null), @@ -84,7 +86,7 @@ class RawMaterialButton extends StatefulWidget { /// The elevation for the button's [Material] when the button /// is [enabled] but not pressed. /// - /// Defaults to 2.0. + /// Defaults to 2.0. The value is always non-negative. /// /// See also: /// @@ -95,7 +97,7 @@ class RawMaterialButton extends StatefulWidget { /// The elevation for the button's [Material] when the button /// is [enabled] and pressed. /// - /// Defaults to 8.0. + /// Defaults to 8.0. The value is always non-negative. /// /// See also: /// @@ -106,7 +108,7 @@ class RawMaterialButton extends StatefulWidget { /// The elevation for the button's [Material] when the button /// is not [enabled]. /// - /// Defaults to 0.0. + /// Defaults to 0.0. The value is always non-negative. /// /// * [elevation], the default elevation. /// * [highlightElevation], the elevation when the button is pressed. diff --git a/packages/flutter/lib/src/material/card.dart b/packages/flutter/lib/src/material/card.dart index d63b3f6c32..30f79ea3b0 100644 --- a/packages/flutter/lib/src/material/card.dart +++ b/packages/flutter/lib/src/material/card.dart @@ -65,17 +65,19 @@ import 'theme.dart'; class Card extends StatelessWidget { /// Creates a material design card. /// - /// The [clipBehavior] argument must not be null. + /// The [clipBehavior] and [elevation] arguments must not be null. + /// Additionally, the [elevation] must be non-negative. const Card({ Key key, this.color, - this.elevation, + this.elevation = 1.0, this.shape, this.margin = const EdgeInsets.all(4.0), this.clipBehavior = Clip.none, this.child, this.semanticContainer = true, - }) : super(key: key); + }) : assert(elevation != null && elevation >= 0.0), + super(key: key); /// The card's background color. /// @@ -89,7 +91,7 @@ class Card extends StatelessWidget { /// /// Defines the card's [Material.elevation]. /// - /// The default elevation is 1.0. + /// The default elevation is 1.0. The value is always non-negative. final double elevation; /// The shape of the card's [Material]. @@ -139,7 +141,7 @@ class Card extends StatelessWidget { child: Material( type: MaterialType.card, color: color ?? Theme.of(context).cardColor, - elevation: elevation ?? 1.0, + elevation: elevation, shape: shape ?? const RoundedRectangleBorder( borderRadius: BorderRadius.all(Radius.circular(4.0)), ), diff --git a/packages/flutter/lib/src/material/chip.dart b/packages/flutter/lib/src/material/chip.dart index 951f9f1e29..37118b83c7 100644 --- a/packages/flutter/lib/src/material/chip.dart +++ b/packages/flutter/lib/src/material/chip.dart @@ -287,10 +287,12 @@ abstract class SelectableChipAttributes { /// {@end-tool} ValueChanged get onSelected; - /// Elevation to be applied on the chip during the press motion. + /// Elevation to be applied on the chip relative to its parent during the + /// press motion. + /// /// This controls the size of the shadow below the chip. /// - /// Defaults to 8. + /// Defaults to 8. The value is always non-negative. double get pressElevation; /// Color to be used for the chip's background, indicating that it is @@ -397,10 +399,12 @@ abstract class TappableChipAttributes { /// {@end-tool} VoidCallback get onPressed; - /// Elevation to be applied on the chip during the press motion. + /// Elevation to be applied on the chip relative to its parent during the + /// press motion. + /// /// This controls the size of the shadow below the chip. /// - /// Defaults to 8. + /// Defaults to 8. The value is always non-negative. double get pressElevation; /// Tooltip string to be used for the body area (where the label and avatar @@ -1159,7 +1163,8 @@ class RawChip extends StatefulWidget /// The [onPressed] and [onSelected] callbacks must not both be specified at /// the same time. /// - /// The [label], [isEnabled], and [clipBehavior] arguments must not be null. + /// The [label], [pressElevation], [isEnabled], and [clipBehavior] arguments + /// must not be null. Additionally, [pressElevation] must be non-negative. const RawChip({ Key key, this.avatar, @@ -1188,6 +1193,7 @@ class RawChip extends StatefulWidget }) : assert(label != null), assert(isEnabled != null), assert(clipBehavior != null), + assert(pressElevation != null && pressElevation >= 0.0), deleteIcon = deleteIcon ?? _kDefaultDeleteIcon, super(key: key); diff --git a/packages/flutter/lib/src/material/drawer.dart b/packages/flutter/lib/src/material/drawer.dart index 3bd122f97e..89c4e22187 100644 --- a/packages/flutter/lib/src/material/drawer.dart +++ b/packages/flutter/lib/src/material/drawer.dart @@ -85,17 +85,22 @@ class Drawer extends StatelessWidget { /// Creates a material design drawer. /// /// Typically used in the [Scaffold.drawer] property. + /// + /// The [elevation] must be non-negative. const Drawer({ Key key, this.elevation = 16.0, this.child, this.semanticLabel, - }) : super(key: key); + }) : assert(elevation != null && elevation >= 0.0), + super(key: key); - /// The z-coordinate at which to place this drawer. This controls the size of - /// the shadow below the drawer. + /// The z-coordinate at which to place this drawer relative to its parent. /// - /// Defaults to 16, the appropriate elevation for drawers. + /// This controls the size of the shadow below the drawer. + /// + /// Defaults to 16, the appropriate elevation for drawers. The value is + /// always non-negative. final double elevation; /// The widget below this widget in the tree. diff --git a/packages/flutter/lib/src/material/floating_action_button.dart b/packages/flutter/lib/src/material/floating_action_button.dart index e1b0243445..73689e7d23 100644 --- a/packages/flutter/lib/src/material/floating_action_button.dart +++ b/packages/flutter/lib/src/material/floating_action_button.dart @@ -58,7 +58,8 @@ class FloatingActionButton extends StatefulWidget { /// Creates a circular floating action button. /// /// The [elevation], [highlightElevation], [mini], [shape], and [clipBehavior] - /// arguments must not be null. + /// arguments must not be null. Additionally, [elevation] and + /// [highlightElevation] must be non-negative. const FloatingActionButton({ Key key, this.child, @@ -74,8 +75,8 @@ class FloatingActionButton extends StatefulWidget { this.clipBehavior = Clip.none, this.materialTapTargetSize, this.isExtended = false, - }) : assert(elevation != null), - assert(highlightElevation != null), + }) : assert(elevation != null && elevation >= 0.0), + assert(highlightElevation != null && highlightElevation >= 0.0), assert(mini != null), assert(shape != null), assert(isExtended != null), @@ -86,7 +87,8 @@ class FloatingActionButton extends StatefulWidget { /// an [icon] and a [label]. /// /// The [label], [icon], [elevation], [highlightElevation], [clipBehavior] - /// and [shape] arguments must not be null. + /// and [shape] arguments must not be null. Additionally, [elevation] and + // [highlightElevation] must be non-negative. FloatingActionButton.extended({ Key key, this.tooltip, @@ -102,8 +104,8 @@ class FloatingActionButton extends StatefulWidget { this.clipBehavior = Clip.none, @required Widget icon, @required Widget label, - }) : assert(elevation != null), - assert(highlightElevation != null), + }) : assert(elevation != null && elevation >= 0.0), + assert(highlightElevation != null && highlightElevation >= 0.0), assert(shape != null), assert(isExtended != null), assert(clipBehavior != null), @@ -163,18 +165,22 @@ class FloatingActionButton extends StatefulWidget { /// If this is set to null, the button will be disabled. final VoidCallback onPressed; - /// The z-coordinate at which to place this button. This controls the size of - /// the shadow below the floating action button. + /// The z-coordinate at which to place this button releative to its parent. /// - /// Defaults to 6, the appropriate elevation for floating action buttons. + /// + /// This controls the size of the shadow below the floating action button. + /// + /// Defaults to 6, the appropriate elevation for floating action buttons. The + /// value is always non-negative. final double elevation; - /// The z-coordinate at which to place this button when the user is touching - /// the button. This controls the size of the shadow below the floating action - /// button. + /// The z-coordinate at which to place this button relative to its parent when + /// the user is touching the button. + /// + /// This controls the size of the shadow below the floating action button. /// /// Defaults to 12, the appropriate elevation for floating action buttons - /// while they are being touched. + /// while they are being touched. The value is always non-negative. /// /// See also: /// diff --git a/packages/flutter/lib/src/material/material.dart b/packages/flutter/lib/src/material/material.dart index 489b95a04e..d7560db247 100644 --- a/packages/flutter/lib/src/material/material.dart +++ b/packages/flutter/lib/src/material/material.dart @@ -156,7 +156,7 @@ class Material extends StatefulWidget { /// Creates a piece of material. /// /// The [type], [elevation], [shadowColor], and [animationDuration] arguments - /// must not be null. + /// must not be null. Additionally, [elevation] must be non-negative. /// /// If a [shape] is specified, then the [borderRadius] property must be /// null and the [type] property must not be [MaterialType.circle]. If the @@ -176,7 +176,7 @@ class Material extends StatefulWidget { this.animationDuration = kThemeChangeDuration, this.child, }) : assert(type != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(shadowColor != null), assert(!(shape != null && borderRadius != null)), assert(animationDuration != null), @@ -195,14 +195,17 @@ class Material extends StatefulWidget { final MaterialType type; /// {@template flutter.material.material.elevation} - /// The z-coordinate at which to place this material. This controls the size - /// of the shadow below the material. + /// The z-coordinate at which to place this material relative to its parent. + /// + /// This controls the size of the shadow below the material. /// /// If this is non-zero, the contents of the material are clipped, because the /// widget conceptually defines an independent printed piece of material. /// /// Defaults to 0. Changing this value will cause the shadow to animate over /// [animationDuration]. + /// + /// The value is non-negative. /// {@endtemplate} final double elevation; @@ -609,7 +612,7 @@ class _MaterialInterior extends ImplicitlyAnimatedWidget { }) : assert(child != null), assert(shape != null), assert(clipBehavior != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(color != null), assert(shadowColor != null), super(key: key, curve: curve, duration: duration); @@ -628,7 +631,10 @@ class _MaterialInterior extends ImplicitlyAnimatedWidget { /// {@macro flutter.widgets.Clip} final Clip clipBehavior; - /// The target z-coordinate at which to place this physical object. + /// The target z-coordinate at which to place this physical object relative + /// to its parent. + /// + /// The value is non-negative. final double elevation; /// The target background color. diff --git a/packages/flutter/lib/src/material/material_button.dart b/packages/flutter/lib/src/material/material_button.dart index ad83b239c3..121c81aaa2 100644 --- a/packages/flutter/lib/src/material/material_button.dart +++ b/packages/flutter/lib/src/material/material_button.dart @@ -41,8 +41,6 @@ class MaterialButton extends StatelessWidget { /// Rather than creating a material button directly, consider using /// [FlatButton] or [RaisedButton]. To create a custom Material button /// consider using [RawMaterialButton]. - /// - /// The [clipBehavior] argument must not be null. const MaterialButton({ Key key, @required this.onPressed, @@ -150,10 +148,12 @@ class MaterialButton extends StatelessWidget { /// the current theme's highlight color, [ThemeData.highlightColor]. final Color highlightColor; - /// The z-coordinate at which to place this button. This controls the size of - /// the shadow below the raised button. + /// The z-coordinate at which to place this button relative to its parent. /// - /// Defaults to 2, the appropriate elevation for raised buttons. + /// This controls the size of the shadow below the raised button. + /// + /// Defaults to 2, the appropriate elevation for raised buttons. The value + /// is always non-negative. /// /// See also: /// @@ -162,14 +162,14 @@ class MaterialButton extends StatelessWidget { /// * [highlightElevation], the elevation when the button is pressed. final double elevation; - /// The elevation for the button's [Material] when the button - /// is [enabled] and pressed. + /// The elevation for the button's [Material] relative to its parent when the + /// button is [enabled] and pressed. /// /// This controls the size of the shadow below the button. When a tap /// down gesture occurs within the button, its [InkWell] displays a /// [highlightColor] "highlight". /// - /// Defaults to 8.0. + /// Defaults to 8.0. The value is always non-negative. /// /// See also: /// @@ -177,10 +177,10 @@ class MaterialButton extends StatelessWidget { /// * [disabledElevation], the elevation when the button is disabled. final double highlightElevation; - /// The elevation for the button's [Material] when the button - /// is not [enabled]. + /// The elevation for the button's [Material] relative to its parent when the + /// button is not [enabled]. /// - /// Defaults to 0.0. + /// Defaults to 0.0. The value is always non-negative. /// /// See also: /// diff --git a/packages/flutter/lib/src/material/raised_button.dart b/packages/flutter/lib/src/material/raised_button.dart index 97c34e0ec0..8da498e3a7 100644 --- a/packages/flutter/lib/src/material/raised_button.dart +++ b/packages/flutter/lib/src/material/raised_button.dart @@ -44,7 +44,8 @@ class RaisedButton extends MaterialButton { /// Create a filled button. /// /// The [elevation], [highlightElevation], [disabledElevation], and - /// [clipBehavior] arguments must not be null. + /// [clipBehavior] arguments must not be null. Additionally, [elevation], + /// [highlightElevation], and [disabledElevation] must be non-negative. const RaisedButton({ Key key, @required VoidCallback onPressed, diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart index 39f45ae468..8214c4a823 100644 --- a/packages/flutter/lib/src/rendering/proxy_box.dart +++ b/packages/flutter/lib/src/rendering/proxy_box.dart @@ -1504,6 +1504,7 @@ class RenderClipPath extends _RenderCustomClip { /// determine the actual shape of the physical model. abstract class _RenderPhysicalModelBase extends _RenderCustomClip { /// The [shape], [elevation], [color], and [shadowColor] must not be null. + /// Additionally, the [elevation] must be non-negative. _RenderPhysicalModelBase({ @required RenderBox child, @required double elevation, @@ -1511,7 +1512,7 @@ abstract class _RenderPhysicalModelBase extends _RenderCustomClip { @required Color shadowColor, Clip clipBehavior = Clip.none, CustomClipper clipper, - }) : assert(elevation != null), + }) : assert(elevation != null && elevation >= 0.0), assert(color != null), assert(shadowColor != null), assert(clipBehavior != null), @@ -1520,14 +1521,16 @@ abstract class _RenderPhysicalModelBase extends _RenderCustomClip { _shadowColor = shadowColor, super(child: child, clipBehavior: clipBehavior, clipper: clipper); - /// The z-coordinate at which to place this material. + /// The z-coordinate relative to the parent at which to place this material. + /// + /// The value is non-negative. /// /// If [debugDisableShadows] is set, this value is ignored and no shadow is /// drawn (an outline is rendered instead). double get elevation => _elevation; double _elevation; set elevation(double value) { - assert(value != null); + assert(value != null && value >= 0.0); if (elevation == value) return; final bool didNeedCompositing = alwaysNeedsCompositing; @@ -1585,6 +1588,7 @@ class RenderPhysicalModel extends _RenderPhysicalModelBase { /// The [color] is required. /// /// The [shape], [elevation], [color], and [shadowColor] must not be null. + /// Additionally, the [elevation] must be non-negative. RenderPhysicalModel({ RenderBox child, BoxShape shape = BoxShape.rectangle, @@ -1595,7 +1599,7 @@ class RenderPhysicalModel extends _RenderPhysicalModelBase { Color shadowColor = const Color(0xFF000000), }) : assert(shape != null), assert(clipBehavior != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(color != null), assert(shadowColor != null), _shape = shape, @@ -1742,8 +1746,8 @@ class RenderPhysicalShape extends _RenderPhysicalModelBase { /// /// The [color] and [shape] parameters are required. /// - /// The [clipper], [elevation], [color] and [shadowColor] must - /// not be null. + /// The [clipper], [elevation], [color] and [shadowColor] must not be null. + /// Additionally, the [elevation] must be non-negative. RenderPhysicalShape({ RenderBox child, @required CustomClipper clipper, @@ -1752,7 +1756,7 @@ class RenderPhysicalShape extends _RenderPhysicalModelBase { @required Color color, Color shadowColor = const Color(0xFF000000), }) : assert(clipper != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(color != null), assert(shadowColor != null), super( diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index 5b5a88f448..4aa5251d7a 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -748,6 +748,7 @@ class PhysicalModel extends SingleChildRenderObjectWidget { /// The [color] is required; physical things have a color. /// /// The [shape], [elevation], [color], and [shadowColor] must not be null. + /// Additionally, the [elevation] must be non-negative. const PhysicalModel({ Key key, this.shape = BoxShape.rectangle, @@ -758,7 +759,7 @@ class PhysicalModel extends SingleChildRenderObjectWidget { this.shadowColor = const Color(0xFF000000), Widget child, }) : assert(shape != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(color != null), assert(shadowColor != null), super(key: key, child: child); @@ -777,7 +778,10 @@ class PhysicalModel extends SingleChildRenderObjectWidget { /// This is ignored if the [shape] is not [BoxShape.rectangle]. final BorderRadius borderRadius; - /// The z-coordinate at which to place this physical object. + /// The z-coordinate relative to the parent at which to place this physical + /// object. + /// + /// The value is non-negative. final double elevation; /// The background color. @@ -836,6 +840,7 @@ class PhysicalShape extends SingleChildRenderObjectWidget { /// The [color] is required; physical things have a color. /// /// The [clipper], [elevation], [color], and [shadowColor] must not be null. + /// Additionally, the [elevation] must be non-negative. const PhysicalShape({ Key key, @required this.clipper, @@ -846,7 +851,7 @@ class PhysicalShape extends SingleChildRenderObjectWidget { Widget child, }) : assert(clipper != null), assert(clipBehavior != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(color != null), assert(shadowColor != null), super(key: key, child: child); @@ -861,7 +866,10 @@ class PhysicalShape extends SingleChildRenderObjectWidget { /// {@macro flutter.widgets.Clip} final Clip clipBehavior; - /// The z-coordinate at which to place this physical object. + /// The z-coordinate relative to the parent at which to place this physical + /// object. + /// + /// The value is non-negative. final double elevation; /// The background color. diff --git a/packages/flutter/lib/src/widgets/implicit_animations.dart b/packages/flutter/lib/src/widgets/implicit_animations.dart index e8ecd1ad90..64a6d28442 100644 --- a/packages/flutter/lib/src/widgets/implicit_animations.dart +++ b/packages/flutter/lib/src/widgets/implicit_animations.dart @@ -1240,7 +1240,8 @@ class AnimatedPhysicalModel extends ImplicitlyAnimatedWidget { /// Creates a widget that animates the properties of a [PhysicalModel]. /// /// The [child], [shape], [borderRadius], [elevation], [color], [shadowColor], [curve], and - /// [duration] arguments must not be null. + /// [duration] arguments must not be null. Additionally, [elevation] must be + /// non-negative. /// /// Animating [color] is optional and is controlled by the [animateColor] flag. /// @@ -1262,7 +1263,7 @@ class AnimatedPhysicalModel extends ImplicitlyAnimatedWidget { assert(shape != null), assert(clipBehavior != null), assert(borderRadius != null), - assert(elevation != null), + assert(elevation != null && elevation >= 0.0), assert(color != null), assert(shadowColor != null), assert(animateColor != null), @@ -1285,7 +1286,10 @@ class AnimatedPhysicalModel extends ImplicitlyAnimatedWidget { /// The target border radius of the rounded corners for a rectangle shape. final BorderRadius borderRadius; - /// The target z-coordinate at which to place this physical object. + /// The target z-coordinate relative to the parent at which to place this + /// physical object. + /// + /// The value will always be non-negative. final double elevation; /// The target background color.