From bf4cde74e18286c7254692fa33828b3bf3118752 Mon Sep 17 00:00:00 2001 From: Hans Muller Date: Fri, 31 Jan 2020 15:33:01 -0800 Subject: [PATCH] Clarified AppBar toolbar layout API docs (#49583) --- .../flutter/lib/src/material/app_bar.dart | 41 +++++++++++++++++-- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/packages/flutter/lib/src/material/app_bar.dart b/packages/flutter/lib/src/material/app_bar.dart index 1108d1293e..e2ff809c92 100644 --- a/packages/flutter/lib/src/material/app_bar.dart +++ b/packages/flutter/lib/src/material/app_bar.dart @@ -207,6 +207,12 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget { /// A widget to display before the [title]. /// + /// Typically the [leading] widget is an [Icon] or an [IconButton]. + /// + /// Becomes the leading component of the [NavigationToolBar] built + /// by this widget. The [leading] widget's width and height are constrained to + /// be no bigger than toolbar's height, which is [kToolbarHeight]. + /// /// If this is null and [automaticallyImplyLeading] is set to true, the /// [AppBar] will imply an appropriate widget. For example, if the [AppBar] is /// in a [Scaffold] that also has a [Drawer], the [Scaffold] will fill this @@ -255,15 +261,44 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget { /// The primary widget displayed in the app bar. /// - /// Typically a [Text] widget containing a description of the current contents - /// of the app. + /// Typically a [Text] widget that contains a description of the current + /// contents of the app. + /// + /// Becomes the middle component of the [NavigationToolBar] built by this widget. + /// The [title]'s width is constrained to fit within the remaining space + /// between the toolbar's [leading] and [actions] widgets. Its height is + /// _not_ constrained. The [title] is vertically centered and clipped to fit + /// within the toolbar, whose height is [kToolbarHeight]. Typically this + /// isn't noticeable because a simple [Text] [title] will fit within the + /// toolbar by default. On the other hand, it is noticeable when a + /// widget with an intrinsic height that is greater than [kToolbarHeight] + /// is used as the [title]. For example, when the height of an Image used + /// as the [title] exceeds [kToolbarHeight], it will be centered and + /// clipped (top and bottom), which may be undesirable. In cases like this + /// the height of the [title] widget can be constrained. For example: + /// + /// ```dart + /// MaterialApp( + /// home: Scaffold( + /// appBar: AppBar( + /// title: SizedBox( + /// height: kToolbarHeight, + /// child: child: Image.asset(logoAsset), + /// ), + /// ), + /// ) + /// ``` final Widget title; - /// Widgets to display after the [title] widget. + /// Widgets to display in a row after the [title] widget. /// /// Typically these widgets are [IconButton]s representing common operations. /// For less common operations, consider using a [PopupMenuButton] as the /// last action. + /// + /// The [actions] become the trailing component of the [NavigationToolBar] built + /// by this widget. The the height of each action is constrained to be no bigger + /// than the toolbar's height, which is [kToolbarHeight]. final List actions; /// This widget is stacked behind the toolbar and the tab bar. It's height will