diff --git a/dev/manual_tests/card_collection.dart b/dev/manual_tests/card_collection.dart index 121641dd02..7a274b8156 100644 --- a/dev/manual_tests/card_collection.dart +++ b/dev/manual_tests/card_collection.dart @@ -282,16 +282,14 @@ class CardCollectionState extends State { actions: [ new Text(_dismissDirectionText(_dismissDirection)) ], - flexibleSpace: (_) { - return new Container( - padding: const EdgeInsets.only(left: 72.0), - height: 128.0, - child: new Align( - alignment: const FractionalOffset(0.0, 0.75), - child: new Text('Swipe Away: ${_cardModels.length}', style: Theme.of(context).primaryTextTheme.title) - ) - ); - } + flexibleSpace: new Container( + padding: const EdgeInsets.only(left: 72.0), + height: 128.0, + child: new Align( + alignment: const FractionalOffset(0.0, 0.75), + child: new Text('Swipe Away: ${_cardModels.length}', style: Theme.of(context).primaryTextTheme.title) + ) + ) ); } diff --git a/examples/material_gallery/lib/demo/flexible_space_demo.dart b/examples/material_gallery/lib/demo/flexible_space_demo.dart index 06fd88ceaf..e1f5ca6fd9 100644 --- a/examples/material_gallery/lib/demo/flexible_space_demo.dart +++ b/examples/material_gallery/lib/demo/flexible_space_demo.dart @@ -122,16 +122,14 @@ class FlexibleSpaceDemoState extends State { ] ) ], - flexibleSpace: (BuildContext context) { - return new FlexibleSpaceBar( - title : new Text('Ali Connors'), - image: new AssetImage( - name: 'packages/flutter_gallery_assets/ali_connors.png', - fit: ImageFit.cover, - height: _appBarHeight - ) - ); - } + flexibleSpace: new FlexibleSpaceBar( + title : new Text('Ali Connors'), + image: new AssetImage( + name: 'packages/flutter_gallery_assets/ali_connors.png', + fit: ImageFit.cover, + height: _appBarHeight + ) + ) ), body: new Block( scrollableKey: _scrollableKey, diff --git a/examples/material_gallery/lib/gallery/home.dart b/examples/material_gallery/lib/gallery/home.dart index 514020fed0..1e2bc02efc 100644 --- a/examples/material_gallery/lib/gallery/home.dart +++ b/examples/material_gallery/lib/gallery/home.dart @@ -83,7 +83,7 @@ class GalleryHomeState extends State { ), appBar: new AppBar( expandedHeight: _kFlexibleSpaceMaxHeight, - flexibleSpace: (BuildContext context) => new FlexibleSpaceBar( + flexibleSpace: new FlexibleSpaceBar( image: new GalleryHeader(), title: new Text("Flutter gallery") ) diff --git a/packages/flutter/lib/src/material/app.dart b/packages/flutter/lib/src/material/app.dart index dcf74fa2f9..849d3968ba 100644 --- a/packages/flutter/lib/src/material/app.dart +++ b/packages/flutter/lib/src/material/app.dart @@ -22,7 +22,19 @@ const TextStyle _errorTextStyle = const TextStyle( decorationStyle: TextDecorationStyle.double ); - +/// An application that uses material design. +/// +/// A convenience widget that wraps a number of widgets that are commonly +/// required for material design applications. It builds upon +/// [WidgetsApp] by adding material-design specific functionality, such as +/// [AnimatedTheme] and [GridPaper]. This widget also configures the top-level +/// [Navigator] to perform [Hero] animations. +/// +/// See also: +/// +/// * [WidgetsApp] +/// * [Scaffold] +/// * [MaterialPageRoute] class MaterialApp extends WidgetsApp { MaterialApp({ Key key, @@ -65,6 +77,12 @@ class MaterialApp extends WidgetsApp { /// The colors to use for the application's widgets. final ThemeData theme; + /// The application's top-level routing table. + /// + /// When a named route is pushed with [Navigator.pushNamed], the route name is + /// looked up in this map. If the name is present, the associated + /// [WidgetBuilder] is used to construct a [MaterialPageRoute] that performs + /// an appropriate transition, including [Hero] animations, to the new route. final Map routes; /// Turns on a [GridPaper] overlay that paints a baseline grid diff --git a/packages/flutter/lib/src/material/app_bar.dart b/packages/flutter/lib/src/material/app_bar.dart index 982cabc5af..52bf955bb9 100644 --- a/packages/flutter/lib/src/material/app_bar.dart +++ b/packages/flutter/lib/src/material/app_bar.dart @@ -12,6 +12,24 @@ import 'tabs.dart'; import 'theme.dart'; import 'typography.dart'; +/// A material design app bar. +/// +/// An app bar consists of a tool bar and potentially other widgets, such as a +/// [TabBar] and a [FlexibleSpaceBar]. App bars typically expose one or more +/// common actions with [IconButtons]s which are optionally followed by a +/// [PopupMenuButton] for less common operations. +/// +/// App bars are most commonly used in a [Scaffold], which places the app bar at +/// the top of the app. +/// +/// See also: +/// +/// * [Scaffold] +/// * [TabBar] +/// * [IconButton] +/// * [PopupMenuButton] +/// * [FlexibleSpaceBar] +/// * class AppBar extends StatelessWidget { AppBar({ Key key, @@ -19,7 +37,6 @@ class AppBar extends StatelessWidget { this.title, this.actions, this.flexibleSpace, - this.foregroundOpacity: 1.0, this.tabBar, this.elevation: 4, this.backgroundColor, @@ -38,28 +55,65 @@ class AppBar extends StatelessWidget { assert((tabBar != null) ? flexibleSpace == null : true); } + /// A widget to display before the [title]. + /// + /// If this field is null and this app bar is used in a [Scaffold], the + /// [Scaffold] will fill this field with an appropriate widget. For example, + /// if the [Scaffold] also has a [Drawer], the [Scaffold] will fill this + /// widget with an [IconButton] that opens the drawer. If there's no [Drawer] + /// and the parent [Navigator] can go back, the [Scaffold] will fill this + /// field with an [IconButton] that calls [Navigator.pop]. final Widget leading; + + /// The primary widget displayed in the app bar. + /// + /// Typically a [Text] widget containing a description of the current contents + /// of the app. final Widget title; + + /// Widgets to display after the title. + /// + /// Typically these widgets are [IconButton]s representing common operations. + /// For less common operations, consider using a [PopupMenuButton] as the + /// last action. final List actions; - final WidgetBuilder flexibleSpace; - final double foregroundOpacity; + + /// A widget to aid in building scroll-based collapsing app bar effects. + /// + /// Typically a [FlexibleSpaceBar]. See [FlexibleSpaceBar] for details. + final Widget flexibleSpace; + + /// A horizontal strip of tabs to display at the bottom of the app bar. final TabBar tabBar; + + /// The z-coordinate at which to place this app bar. final int elevation; + + /// The color to use for the the app bar's material. + /// + /// Defaults to [ThemeData.primaryColor]. final Color backgroundColor; + + /// The typographic style to use for text in the app bar. + /// + /// Defaults to [ThemeData.primaryTextTheme]. final TextTheme textTheme; + + /// The amount of space to inset the contents of the app bar. final EdgeInsets padding; + final double _expandedHeight; final double _collapsedHeight; final double _minimumHeight; final double _actualHeight; + /// Creates a copy of this app bar but with the given fields replaced with the new values. AppBar copyWith({ Key key, Widget leading, Widget title, List actions, - WidgetBuilder flexibleSpace, - double foregroundOpacity, + Widget flexibleSpace, int elevation, Color backgroundColor, TextTheme textTheme, @@ -74,7 +128,6 @@ class AppBar extends StatelessWidget { title: title ?? this.title, actions: actions ?? this.actions, flexibleSpace: flexibleSpace ?? this.flexibleSpace, - foregroundOpacity: foregroundOpacity ?? this.foregroundOpacity, tabBar: tabBar ?? this.tabBar, elevation: elevation ?? this.elevation, backgroundColor: backgroundColor ?? this.backgroundColor, @@ -90,8 +143,10 @@ class AppBar extends StatelessWidget { double get _toolBarHeight => kToolBarHeight; + /// The height of this app bar when fully expanded. double get expandedHeight => _expandedHeight ?? (_toolBarHeight + (_tabBarHeight ?? 0.0)); + /// The height of this app bar when fully collapsed. double get collapsedHeight => _collapsedHeight ?? (_toolBarHeight + (_tabBarHeight ?? 0.0)); double get minimumHeight => _minimumHeight ?? _tabBarHeight ?? _toolBarHeight; @@ -202,7 +257,7 @@ class AppBar extends StatelessWidget { if (flexibleSpace != null) { appBar = new Stack( children: [ - flexibleSpace(context), + flexibleSpace, new Align(child: appBar, alignment: FractionalOffset.topLeft) ] ); diff --git a/packages/flutter/lib/src/material/bottom_sheet.dart b/packages/flutter/lib/src/material/bottom_sheet.dart index 0a30c1e2d2..96f0627f6e 100644 --- a/packages/flutter/lib/src/material/bottom_sheet.dart +++ b/packages/flutter/lib/src/material/bottom_sheet.dart @@ -15,7 +15,36 @@ const double _kCloseProgressThreshold = 0.5; const Color _kTransparent = const Color(0x00000000); const Color _kBarrierColor = Colors.black54; +/// A material design bottom sheet. +/// +/// There are two kinds of bottom sheets in material design: +/// +/// * _Persistent_. A persistent bottom sheet shows information that +/// supplements the primary content of the app. A persistent bottom sheet +/// remains visible even when the user interacts with other parts of the app. +/// Persistent bottom sheets can be created and displayed with the +/// [Scaffold.showBottomSheet] function. +/// +/// * _Modal_. A modal bottom sheet is an alternative to a menu or a dialog and +/// prevents the user from interacting with the rest of the app. Modal bottom +/// sheets can be created and displayed with the [showModalBottomSheet] +/// function. +/// +/// The [BottomSheet] widget itself is rarely used directly. Instead, prefer to +/// create a persistent bottom sheet with [Scaffold.showBottomSheet] and a modal +/// bottom sheet with [showModalBottomSheet]. +/// +/// See also: +/// +/// * [Scaffold.showBottomSheet] +/// * [showModalBottomSheet] +/// * class BottomSheet extends StatefulWidget { + /// Creates a bottom sheet. + /// + /// Typically, bottom sheets are created implicitly by + /// [Scaffold.showBottomSheet], for persistent bottom sheets, or by + /// [showModalBottomSheet], for modal bottom sheets. BottomSheet({ Key key, this.animationController, @@ -25,16 +54,29 @@ class BottomSheet extends StatefulWidget { assert(onClosing != null); } - /// The animation that controls the bottom sheet's position. The BottomSheet - /// widget will manipulate the position of this animation, it is not just a - /// passive observer. + /// The animation that controls the bottom sheet's position. + /// + /// The BottomSheet widget will manipulate the position of this animation, it + /// is not just a passive observer. final AnimationController animationController; + + /// Called when the bottom sheet begins to close. + /// + /// A bottom sheet might be be prevented from closing (e.g., by user + /// interaction) even after this callback is called. For this reason, this + /// callback might be call multiple times for a given bottom sheet. final VoidCallback onClosing; + + /// A builder for the contents of the sheet. + /// + /// The bottom sheet will wrap the widget produced by this builder in a + /// [Material] widget. final WidgetBuilder builder; @override _BottomSheetState createState() => new _BottomSheetState(); + /// Creates an animation controller suitable for controlling a [BottomSheet]. static AnimationController createAnimationController() { return new AnimationController( duration: _kBottomSheetDuration, @@ -183,6 +225,25 @@ class _ModalBottomSheetRoute extends PopupRoute { } } +/// Shows a modal material design bottom sheet. +/// +/// A modal bottom sheet is an alternative to a menu or a dialog and prevents +/// the user from interacting with the rest of the app. +/// +/// A closely related widget is a persistent bottom sheet, which shows +/// information that supplements the primary content of the app without +/// preventing the use from interacting with the app. Persistent bottom sheets +/// can be created and displayed with the [Scaffold.showBottomSheet] function. +/// +/// Returns a `Future` that resolves to the value (if any) that was passed to +/// [Navigator.pop] when the modal bottom sheet is removed from the navigation +/// history. +/// +/// See also: +/// +/// * [BottomSheet] +/// * [Scaffold.showBottomSheet] +/// * Future showModalBottomSheet/**/({ BuildContext context, WidgetBuilder builder }) { assert(context != null); assert(builder != null); diff --git a/packages/flutter/lib/src/material/button.dart b/packages/flutter/lib/src/material/button.dart index 7dee88808f..6c187c27e0 100644 --- a/packages/flutter/lib/src/material/button.dart +++ b/packages/flutter/lib/src/material/button.dart @@ -10,8 +10,28 @@ import 'ink_well.dart'; import 'material.dart'; import 'theme.dart'; -enum ButtonColor { normal, accent } +/// Whether a button should use the accent color for its text. +/// +/// See also: +/// +/// * [ButtonTheme] +/// * [RaisedButton] +/// * [FlatButton] +enum ButtonColor { + /// The button should use the normal color (e.g., black or white depending on the [ThemeData.brightness]) for its text. + normal, + /// The button should use the accent color (e.g., [ThemeData.accentColor]) for its text. + accent, +} + +/// Defines the button color used by a widget subtree. +/// +/// See also: +/// +/// * [ButtonColor] +/// * [RaisedButton] +/// * [FlatButton] class ButtonTheme extends InheritedWidget { ButtonTheme({ Key key, @@ -21,6 +41,7 @@ class ButtonTheme extends InheritedWidget { assert(child != null); } + /// The button color that this subtree should use. final ButtonColor color; /// The color from the closest instance of this class that encloses the given context. @@ -45,6 +66,7 @@ abstract class MaterialButton extends StatefulWidget { MaterialButton({ Key key, this.child, + this.colorBrightness, this.textTheme, this.textColor, this.disabledTextColor, @@ -54,10 +76,24 @@ abstract class MaterialButton extends StatefulWidget { /// The widget below this widget in the tree. final Widget child; + /// The theme brightness to use for this button. + /// + /// Defaults to the brightness from [ThemeData.brightness]. + final ThemeBrightness colorBrightness; + + /// The color scheme to use for this button's text. + /// + /// Defaults to the button color from [ButtonTheme]. final ButtonColor textTheme; + /// The color to use for this button's text. + /// + /// Defaults to the color determined by the [textTheme]. final Color textColor; + /// The color to use for this button's text when the button cannot be pressed. + /// + /// Defaults to a color derived from the [Theme]. final Color disabledTextColor; /// The callback that is invoked when the button is tapped or otherwise activated. @@ -77,14 +113,25 @@ abstract class MaterialButton extends StatefulWidget { } } +/// A state object for [MaterialButton]. +/// +/// Subclasses of [MaterialButton] should use a subclass of +/// [MaterialButtonState] for their state objects. abstract class MaterialButtonState extends State { + /// Whether this button is in the process of potentially being pressed. bool highlight = false; + /// The z-coordinate at which to place this button. int get elevation; - Color getColor(BuildContext context); - ThemeBrightness getColorBrightness(BuildContext context); - Color getTextColor(BuildContext context) { + /// The color to use for the button's material. + Color getColor(BuildContext context); + + ThemeBrightness _getColorBrightness(BuildContext context) { + return config.colorBrightness ?? Theme.of(context).brightness; + } + + Color _getTextColor(BuildContext context) { if (config.enabled) { if (config.textColor != null) return config.textColor; @@ -92,7 +139,7 @@ abstract class MaterialButtonState extends State { case ButtonColor.accent: return Theme.of(context).accentColor; case ButtonColor.normal: - switch (getColorBrightness(context)) { + switch (_getColorBrightness(context)) { case ThemeBrightness.light: return Colors.black87; case ThemeBrightness.dark: @@ -102,7 +149,7 @@ abstract class MaterialButtonState extends State { } if (config.disabledTextColor != null) return config.disabledTextColor; - switch (getColorBrightness(context)) { + switch (_getColorBrightness(context)) { case ThemeBrightness.light: return Colors.black26; case ThemeBrightness.dark: @@ -131,7 +178,7 @@ abstract class MaterialButtonState extends State { ) ) ); - TextStyle style = Theme.of(context).textTheme.button.copyWith(color: getTextColor(context)); + TextStyle style = Theme.of(context).textTheme.button.copyWith(color: _getTextColor(context)); int elevation = this.elevation; Color color = getColor(context); if (elevation > 0 || color != null) { diff --git a/packages/flutter/lib/src/material/card.dart b/packages/flutter/lib/src/material/card.dart index 7c0d792dd2..57d142ec9a 100644 --- a/packages/flutter/lib/src/material/card.dart +++ b/packages/flutter/lib/src/material/card.dart @@ -10,7 +10,11 @@ const EdgeInsets _kCardMargins = const EdgeInsets.all(4.0); /// A material design card /// -/// +/// See also: +/// +/// * [Dialog] +/// * [showDialog] +/// * class Card extends StatelessWidget { const Card({ Key key, this.child, this.color }) : super(key: key); diff --git a/packages/flutter/lib/src/material/chip.dart b/packages/flutter/lib/src/material/chip.dart index 54e297d780..5293e27c8e 100644 --- a/packages/flutter/lib/src/material/chip.dart +++ b/packages/flutter/lib/src/material/chip.dart @@ -33,7 +33,7 @@ const TextStyle _kLabelStyle = const TextStyle( /// See also: /// /// * [CircleAvatar] -/// * https://www.google.com/design/spec/components/chips.html +/// * class Chip extends StatelessWidget { const Chip({ Key key, diff --git a/packages/flutter/lib/src/material/drawer.dart b/packages/flutter/lib/src/material/drawer.dart index 4a411ab074..e6f0f038d3 100644 --- a/packages/flutter/lib/src/material/drawer.dart +++ b/packages/flutter/lib/src/material/drawer.dart @@ -48,7 +48,7 @@ class Drawer extends StatelessWidget { this.child }) : super(key: key); - /// The height at which to place this drawer. + /// The z-coordinate at which to place this drawer. final int elevation; /// The widget below this widget in the tree. diff --git a/packages/flutter/lib/src/material/drop_down.dart b/packages/flutter/lib/src/material/drop_down.dart index 19c399d4e4..c4ec203de6 100644 --- a/packages/flutter/lib/src/material/drop_down.dart +++ b/packages/flutter/lib/src/material/drop_down.dart @@ -280,7 +280,7 @@ class DropDownButton extends StatefulWidget { /// Called when the user selects an item. final ValueChanged onChanged; - /// The height at which to place the menu when open. + /// The z-coordinate at which to place the menu when open. final int elevation; @override diff --git a/packages/flutter/lib/src/material/flat_button.dart b/packages/flutter/lib/src/material/flat_button.dart index a9ba067578..ab57cb8598 100644 --- a/packages/flutter/lib/src/material/flat_button.dart +++ b/packages/flutter/lib/src/material/flat_button.dart @@ -32,20 +32,21 @@ import 'theme.dart'; /// /// * [RaisedButton] /// * [DropDownButton] -/// * https://www.google.com/design/spec/components/buttons.html +/// * class FlatButton extends MaterialButton { FlatButton({ Key key, Widget child, + ThemeBrightness colorBrightness, ButtonColor textTheme, Color textColor, Color disabledTextColor, this.color, - this.colorBrightness, this.disabledColor, VoidCallback onPressed }) : super(key: key, child: child, + colorBrightness: colorBrightness, textTheme: textTheme, textColor: textColor, disabledTextColor: disabledTextColor, @@ -60,9 +61,6 @@ class FlatButton extends MaterialButton { /// value. final Color disabledColor; - /// Controls the default text color if the text color isn't explicit set. - final ThemeBrightness colorBrightness; - @override _FlatButtonState createState() => new _FlatButtonState(); } @@ -77,9 +75,4 @@ class _FlatButtonState extends MaterialButtonState { return config.disabledColor; return config.color; } - - @override - ThemeBrightness getColorBrightness(BuildContext context) { - return config.colorBrightness ?? Theme.of(context).brightness; - } } diff --git a/packages/flutter/lib/src/material/floating_action_button.dart b/packages/flutter/lib/src/material/floating_action_button.dart index 960842d4e3..67893aaa67 100644 --- a/packages/flutter/lib/src/material/floating_action_button.dart +++ b/packages/flutter/lib/src/material/floating_action_button.dart @@ -63,7 +63,7 @@ class FloatingActionButton extends StatefulWidget { /// If this is set to null, the button will be disabled. final VoidCallback onPressed; - /// The height at which to place this button. + /// The z-coordinate at which to place this button. final int elevation; final int highlightElevation; diff --git a/packages/flutter/lib/src/material/material.dart b/packages/flutter/lib/src/material/material.dart index 7def8a3b97..0ab0316cda 100644 --- a/packages/flutter/lib/src/material/material.dart +++ b/packages/flutter/lib/src/material/material.dart @@ -91,7 +91,7 @@ class Material extends StatefulWidget { final MaterialType type; - /// The height at which to place this material. + /// The z-coordinate at which to place this material. final int elevation; final Color color; diff --git a/packages/flutter/lib/src/material/popup_menu.dart b/packages/flutter/lib/src/material/popup_menu.dart index c21d4bbee4..da946118bb 100644 --- a/packages/flutter/lib/src/material/popup_menu.dart +++ b/packages/flutter/lib/src/material/popup_menu.dart @@ -409,7 +409,7 @@ class PopupMenuButton extends StatefulWidget { final String tooltip; - /// The height at which to place the menu when open. + /// The z-coordinate at which to place the menu when open. final int elevation; /// The widget below this widget in the tree. diff --git a/packages/flutter/lib/src/material/raised_button.dart b/packages/flutter/lib/src/material/raised_button.dart index 817e275044..4e514e8c07 100644 --- a/packages/flutter/lib/src/material/raised_button.dart +++ b/packages/flutter/lib/src/material/raised_button.dart @@ -35,8 +35,8 @@ class RaisedButton extends MaterialButton { RaisedButton({ Key key, Widget child, + ThemeBrightness colorBrightness, this.color, - this.colorBrightness, this.disabledColor, this.elevation: 2, this.highlightElevation: 8, @@ -44,6 +44,7 @@ class RaisedButton extends MaterialButton { VoidCallback onPressed }) : super(key: key, child: child, + colorBrightness: colorBrightness, onPressed: onPressed); /// The color of the button, as printed on the [Material]. Defaults to null, @@ -55,16 +56,13 @@ class RaisedButton extends MaterialButton { /// value. final Color disabledColor; - /// Controls the default text color if the text color isn't explicit set. - final ThemeBrightness colorBrightness; - - /// The height at which to place this button. + /// The z-coordinate at which to place this button. final int elevation; - /// The height at which to place this button when highlighted. + /// The z-coordinate at which to place this button when highlighted. final int highlightElevation; - /// The height at which to place this button when disabled. + /// The z-coordinate at which to place this button when disabled. final int disabledElevation; @override @@ -98,9 +96,4 @@ class _RaisedButtonState extends MaterialButtonState { } } } - - @override - ThemeBrightness getColorBrightness(BuildContext context) { - return config.colorBrightness ?? Theme.of(context).brightness; - } } diff --git a/packages/flutter/lib/src/material/scaffold.dart b/packages/flutter/lib/src/material/scaffold.dart index 733e7f367e..33272b1d53 100644 --- a/packages/flutter/lib/src/material/scaffold.dart +++ b/packages/flutter/lib/src/material/scaffold.dart @@ -238,16 +238,27 @@ class ScaffoldState extends State { AnimationController _appBarController; + /// The animation controlling the size of the app bar. + /// + /// Useful for linking animation effects to the expansion and collapse of the + /// app bar. Animation get appBarAnimation => _appBarController.view; + /// The height of the app bar when fully expanded. + /// + /// See [AppBar.expandedHeight]. double get appBarHeight => config.appBar?.expandedHeight ?? 0.0; // DRAWER API final GlobalKey _drawerKey = new GlobalKey(); + /// Opens the [Drawer] (if any). + /// + /// If the scaffold has a non-null [Scaffold.drawer], this function will cause + /// the drawer to begin its entrance animation. void openDrawer() { - _drawerKey.currentState.open(); + _drawerKey.currentState?.open(); } // SNACKBAR API @@ -256,6 +267,12 @@ class ScaffoldState extends State { AnimationController _snackBarController; Timer _snackBarTimer; + /// Shows a [SnackBar] at the bottom fo the scaffold. + /// + /// A scaffold can show at most one snack bar at a time. If this function is + /// called while another snack bar is already visible, the given snack bar + /// will be added to a queue and displayed after the earlier snack bars have + /// closed. ScaffoldFeatureController showSnackBar(SnackBar snackbar) { _snackBarController ??= SnackBar.createAnimationController() ..addStatusListener(_handleSnackBarStatusChange); @@ -304,6 +321,10 @@ class ScaffoldState extends State { } } + /// Removes the current [SnackBar] (if any) immediately. + /// + /// The removed snack bar does not run its normal exit animation. If there are + /// any queued snack bars, they begin their entrance animation immediately. void removeCurrentSnackBar() { if (_snackBars.isEmpty) return; @@ -330,6 +351,25 @@ class ScaffoldState extends State { List _dismissedBottomSheets; PersistentBottomSheetController _currentBottomSheet; + /// Shows a persistent material design bottom sheet. + /// + /// A persistent bottom sheet shows information that supplements the primary + /// content of the app. A persistent bottom sheet remains visible even when + /// the user interacts with other parts of the app. + /// + /// A closely related widget is a modal bottom sheet, which is an alternative + /// to a menu or a dialog and prevents the user from interacting with the rest + /// of the app. Modal bottom sheets can be created and displayed with the + /// [showModalBottomSheet] function. + /// + /// Returns a contoller that can be used to close and otherwise manipulate the + /// button sheet. + /// + /// See also: + /// + /// * [BottomSheet] + /// * [showModalBottomSheet] + /// * PersistentBottomSheetController showBottomSheet/**/(WidgetBuilder builder) { if (_currentBottomSheet != null) { _currentBottomSheet.close(); diff --git a/packages/flutter/lib/src/painting/text_style.dart b/packages/flutter/lib/src/painting/text_style.dart index 7e55ba5000..f4b366b9ab 100644 --- a/packages/flutter/lib/src/painting/text_style.dart +++ b/packages/flutter/lib/src/painting/text_style.dart @@ -72,8 +72,7 @@ class TextStyle { /// The style in which to paint the text decorations (e.g., dashed). final TextDecorationStyle decorationStyle; - /// Returns a new text style that matches this text style but with the given - /// values replaced. + /// Creates a copy of this text style but with the given fields replaced with the new values. TextStyle copyWith({ Color color, String fontFamily, diff --git a/packages/flutter/lib/src/rendering/box.dart b/packages/flutter/lib/src/rendering/box.dart index bc6c347c51..39ce2d6074 100644 --- a/packages/flutter/lib/src/rendering/box.dart +++ b/packages/flutter/lib/src/rendering/box.dart @@ -91,7 +91,7 @@ class BoxConstraints extends Constraints { minHeight = height != null ? height : double.INFINITY, maxHeight = height != null ? height : double.INFINITY; - /// Returns new box constraints that remove the minimum width and height requirements. + /// Creates a copy of this box constraints but with the given fields replaced with the new values. BoxConstraints copyWith({ double minWidth, double maxWidth, diff --git a/packages/flutter/lib/src/widgets/editable.dart b/packages/flutter/lib/src/widgets/editable.dart index 801d9a636c..9bbaf70c67 100644 --- a/packages/flutter/lib/src/widgets/editable.dart +++ b/packages/flutter/lib/src/widgets/editable.dart @@ -125,6 +125,7 @@ class InputValue { composing.hashCode ); + /// Creates a copy of this input value but with the given fields replaced with the new values. InputValue copyWith({ String text, TextSelection selection,