diff --git a/packages/flutter/lib/src/animation/animation_controller.dart b/packages/flutter/lib/src/animation/animation_controller.dart index 68e823ad03..8a30b6d8e5 100644 --- a/packages/flutter/lib/src/animation/animation_controller.dart +++ b/packages/flutter/lib/src/animation/animation_controller.dart @@ -179,6 +179,10 @@ class AnimationController extends Animation _checkStatusChanged(); } + /// The rate of change of [value] per second. + /// + /// If [isAnimating] is false, then [value] is not changing and the rate of + /// change is zero. double get velocity { if (!isAnimating) return 0.0; diff --git a/packages/flutter/lib/src/material/app_bar.dart b/packages/flutter/lib/src/material/app_bar.dart index 4eb35030fa..43e818a2ab 100644 --- a/packages/flutter/lib/src/material/app_bar.dart +++ b/packages/flutter/lib/src/material/app_bar.dart @@ -255,8 +255,22 @@ class AppBar extends StatefulWidget { /// Defaults to being adapted to the current [TargetPlatform]. final bool centerTitle; + /// How opaque the toolbar part of the app bar is. + /// + /// A value of 1.0 is fully opaque, and a value of 0.0 is fully transparent. + /// + /// Typically, this value is not changed from its default value (1.0). It is + /// used by [SliverAppBar] to animate the opacity of the toolbar when the app + /// bar is scrolled. final double toolbarOpacity; + /// How opaque the bottom part of the app bar is. + /// + /// A value of 1.0 is fully opaque, and a value of 0.0 is fully transparent. + /// + /// Typically, this value is not changed from its default value (1.0). It is + /// used by [SliverAppBar] to animate the opacity of the toolbar when the app + /// bar is scrolled. final double bottomOpacity; final double _bottomHeight; @@ -286,10 +300,10 @@ class AppBar extends StatefulWidget { } @override - AppBarState createState() => new AppBarState(); + _AppBarState createState() => new _AppBarState(); } -class AppBarState extends State { +class _AppBarState extends State { bool _hasDrawer = false; bool _canPop = false; @@ -562,6 +576,35 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate { } } +/// A material design app bar that integrates with a [CustomScrollView]. +/// +/// An app bar consists of a toolbar and potentially other widgets, such as a +/// [TabBar] and a [FlexibleSpaceBar]. App bars typically expose one or more +/// common actions with [IconButton]s which are optionally followed by a +/// [PopupMenuButton] for less common operations. +/// +/// Sliver app bars are typically used as the first child of a +/// [CustomScrollView], which lets the app bar integrate with the scroll view so +/// that it can vary in height according to the scroll offset or float above the +/// other content in the scroll view. For a fixed-height app bar at the top of +/// the screen see [AppBar], which is used in the [Scaffold.appBar] slot. +/// +/// The AppBar displays the toolbar widgets, [leading], [title], and +/// [actions], above the [bottom] (if any). If a [flexibleSpace] widget is +/// specified then it is stacked behind the toolbar and the bottom widget. +/// +/// See also: +/// +/// * [CustomScrollView], which integrates the [SliverAppBar] into its +/// scrolling. +/// * [AppBar], which is a fixed-height app bar for use in [Scaffold.appBar]. +/// * [TabBar], which is typically placed in the [bottom] slot of the [AppBar] +/// if the screen has multiple pages arranged in tabs. +/// * [IconButton], which is used with [actions] to show buttons on the app bar. +/// * [PopupMenuButton], to show a popup menu on the app bar, via [actions]. +/// * [FlexibleSpaceBar], which is used with [flexibleSpace] when the app bar +/// can expand and collapse. +/// * class SliverAppBar extends StatelessWidget { /// Creates a material design app bar that can be placed in a [CustomScrollView]. SliverAppBar({ @@ -585,6 +628,7 @@ class SliverAppBar extends StatelessWidget { assert(primary != null); assert(floating != null); assert(pinned != null); + assert(!floating || !pinned); } /// A widget to display before the [title]. @@ -702,8 +746,17 @@ class SliverAppBar extends StatelessWidget { /// See also [AppBar.getExpandedHeightFor]. final double expandedHeight; + /// Whether the app bar should become visible as soon as the user scrolls + /// towards the app bar. + /// + /// Otherwise, the user will need to scroll near the top of the scroll view to + /// reveal the app bar. final bool floating; + /// Whether the app bar should remain visible at the start of the scroll view. + /// + /// The app bar can still expand an contract as the user scrolls, but it will + /// remain visible rather than being scrolled out of view. final bool pinned; @override diff --git a/packages/flutter/lib/src/material/flexible_space_bar.dart b/packages/flutter/lib/src/material/flexible_space_bar.dart index f7e81dc88c..c9686c9dd8 100644 --- a/packages/flutter/lib/src/material/flexible_space_bar.dart +++ b/packages/flutter/lib/src/material/flexible_space_bar.dart @@ -52,6 +52,10 @@ class FlexibleSpaceBar extends StatefulWidget { /// Defaults to being adapted to the current [TargetPlatform]. final bool centerTitle; + /// Wraps a widget that contains an [AppBar] to convey sizing information down + /// to the [FlexibleSpaceBar]. + /// + /// Used by [Scaffold] and [SliverAppBar]. static Widget createSettings({ double toolbarOpacity, double minExtent, diff --git a/packages/flutter/lib/src/material/material.dart b/packages/flutter/lib/src/material/material.dart index c746458cda..13ea57867b 100644 --- a/packages/flutter/lib/src/material/material.dart +++ b/packages/flutter/lib/src/material/material.dart @@ -357,6 +357,10 @@ abstract class InkFeature { assert(referenceBox != null); } + /// The [MaterialInkController] associated with this [InkFeature]. + /// + /// Typically used by subclasses to call + /// [MaterialInkController.markNeedsPaint] when they need to repaint. MaterialInkController get controller => _controller; _RenderInkFeatures _controller; diff --git a/packages/flutter/lib/src/material/scaffold.dart b/packages/flutter/lib/src/material/scaffold.dart index b674866767..0f8428f0fe 100644 --- a/packages/flutter/lib/src/material/scaffold.dart +++ b/packages/flutter/lib/src/material/scaffold.dart @@ -492,6 +492,7 @@ class ScaffoldState extends State with TickerProviderStateMixin { final GlobalKey _drawerKey = new GlobalKey(); + /// Whether this scaffold has a non-null [Scaffold.drawer]. bool get hasDrawer => config.drawer != null; /// Opens the [Drawer] (if any). diff --git a/packages/flutter/lib/src/material/scrollbar.dart b/packages/flutter/lib/src/material/scrollbar.dart index 6a27b6303a..8b4b5e8590 100644 --- a/packages/flutter/lib/src/material/scrollbar.dart +++ b/packages/flutter/lib/src/material/scrollbar.dart @@ -10,15 +10,32 @@ import 'package:flutter/widgets.dart'; import 'theme.dart'; +/// A material design scrollbar. +/// +/// A scrollbar indicates which portion of a [Scrollable] widget is actually +/// visible. +/// +/// To add a scrollbar to a [ScrollView], simply wrap the scroll view widget in +/// a [Scrollbar] widget. +/// +/// See also: +/// +/// * [ListView], which display a linear, scrollable list of children. +/// * [GridView], which display a 2 dimensional, scrollable array of children. class Scrollbar extends StatefulWidget { + /// Creates a material design scrollbar that wraps the given [child]. + /// + /// The [child] should be a source of [ScrollNotification] notifications, + /// typically a [Scrollable] widget. Scrollbar({ Key key, - this.child, + @required this.child, }) : super(key: key); - /// The subtree to place inside the [Scrollbar]. This should include - /// a source of [ScrollNotification] notifications, typically a [Scrollable] - /// widget. + /// The subtree to place inside the [Scrollbar]. + /// + /// This should include a source of [ScrollNotification] notifications, + /// typically a [Scrollable] widget. final Widget child; @override diff --git a/packages/flutter/lib/src/material/tab_controller.dart b/packages/flutter/lib/src/material/tab_controller.dart index a78e0e332e..4a22f40c9d 100644 --- a/packages/flutter/lib/src/material/tab_controller.dart +++ b/packages/flutter/lib/src/material/tab_controller.dart @@ -82,8 +82,8 @@ class TabController extends ChangeNotifier { /// selected tab is changed, the animation's value equals [index]. The /// animation's value can be [offset] by +/- 1.0 to reflect [TabBarView] /// drag scrolling. - final AnimationController _animationController; Animation get animation => _animationController.view; + final AnimationController _animationController; /// The total number of tabs. Must be greater than one. final int length; @@ -217,6 +217,9 @@ class _TabControllerScope extends InheritedWidget { /// } /// ``` class DefaultTabController extends StatefulWidget { + /// Creates a default tab controller for the given [child] widget. + /// + /// The [length] argument must be great than one. DefaultTabController({ Key key, @required this.length, diff --git a/packages/flutter/lib/src/material/tabs.dart b/packages/flutter/lib/src/material/tabs.dart index acda1c3800..ceab87ea36 100644 --- a/packages/flutter/lib/src/material/tabs.dart +++ b/packages/flutter/lib/src/material/tabs.dart @@ -312,14 +312,27 @@ class _ChangeAnimation extends Animation with AnimationWithParentMixin _indexChangeProgress(controller); } -/// A material design widget that displays a horizontal row of tabs. Typically -/// created as part of an [AppBar] and in conjuction with a [TabBarView]. +/// A material design widget that displays a horizontal row of tabs. /// -/// If a [TabController] is not provided, then there must be a [DefaultTabController] -/// ancestor. +/// Typically created as part of an [AppBar] and in conjuction with a +/// [TabBarView]. /// -/// Requires one of its ancestors to be a [Material] widget +/// If a [TabController] is not provided, then there must be a +/// [DefaultTabController] ancestor. +/// +/// Requires one of its ancestors to be a [Material] widget. +/// +/// See also: +/// +/// * [TabBarView], which displays the contents that the tab bar is selecting +/// between. class TabBar extends StatefulWidget implements AppBarBottomWidget { + /// Creates a material design tab bar. + /// + /// The [tabs] argument must not be nuull and must have more than one widget. + /// + /// If a [TabController] is not provided, then there must be a + /// [DefaultTabController] ancestor. TabBar({ Key key, @required this.tabs, diff --git a/packages/flutter/lib/src/painting/text_painter.dart b/packages/flutter/lib/src/painting/text_painter.dart index 5b0a17e9d0..46e877c2b0 100644 --- a/packages/flutter/lib/src/painting/text_painter.dart +++ b/packages/flutter/lib/src/painting/text_painter.dart @@ -112,6 +112,7 @@ class TextPainter { } /// An optional maximum number of lines for the text to span, wrapping if necessary. + /// /// If the text exceeds the given number of lines, it will be truncated according /// to [overflow]. /// @@ -127,6 +128,12 @@ class TextPainter { } ui.Paragraph _layoutTemplate; + + /// The height of a zero-width space in [style] in logical pixels. + /// + /// Not every line of text in [style] will have this height, but this height + /// is "typical" for text in [style] and useful for sizing other objects + /// relative a typical line of text. double get preferredLineHeight { assert(text != null); if (_layoutTemplate == null) { @@ -206,6 +213,10 @@ class TextPainter { return null; } + /// Whether the previous call to [layout] attempted to produce more than + /// [maxLines] lines. + /// + /// If [didExceedMaxLines] is true, then any overflow effect is operative. bool get didExceedMaxLines { assert(!_needsLayout); return _paragraph.didExceedMaxLines; diff --git a/packages/flutter/lib/src/physics/simulation.dart b/packages/flutter/lib/src/physics/simulation.dart index 9dda3d933c..16ef70f726 100644 --- a/packages/flutter/lib/src/physics/simulation.dart +++ b/packages/flutter/lib/src/physics/simulation.dart @@ -30,6 +30,7 @@ import 'tolerance.dart'; /// should establish a convention and use that convention consistently with all /// related objects. abstract class Simulation { + /// Initializes the [tolerance] field for subclasses. Simulation({ this.tolerance: Tolerance.defaultTolerance }); /// The position of the object in the simulation at the given time. diff --git a/packages/flutter/lib/src/rendering/binding.dart b/packages/flutter/lib/src/rendering/binding.dart index 0a586a1fe2..ebdba8f86b 100644 --- a/packages/flutter/lib/src/rendering/binding.dart +++ b/packages/flutter/lib/src/rendering/binding.dart @@ -143,6 +143,8 @@ abstract class RendererBinding extends BindingBase implements SchedulerBinding, setSemanticsEnabled(ui.window.semanticsEnabled); } + /// Whether the render tree associated with this binding should produce a tree + /// of [SemanticsNode] objects. void setSemanticsEnabled(bool enabled) { if (enabled) { _semanticsHandle ??= _pipelineOwner.ensureSemantics(); diff --git a/packages/flutter/lib/src/rendering/error.dart b/packages/flutter/lib/src/rendering/error.dart index 14b18ccec2..051e4d342d 100644 --- a/packages/flutter/lib/src/rendering/error.dart +++ b/packages/flutter/lib/src/rendering/error.dart @@ -9,8 +9,9 @@ import 'object.dart'; const double _kMaxWidth = 100000.0; const double _kMaxHeight = 100000.0; + // Line length to fit small phones without dynamically checking size. -const String line = '\n────────────────────\n\n'; +const String _kLine = '\n\n────────────────────\n\n'; /// A render object used as a placeholder when an error occurs. /// @@ -45,8 +46,8 @@ class RenderErrorBox extends RenderBox { ui.ParagraphBuilder builder = new ui.ParagraphBuilder(paragraphStyle); builder.pushStyle(textStyle); builder.addText( - '$message$line$message$line$message$line$message$line$message$line$message$line' - '$message$line$message$line$message$line$message$line$message$line$message' + '$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message$_kLine' + '$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message$_kLine$message' ); _paragraph = builder.build(); }