Diagrams for API docs rank 10-20 in most views (#37624)

packages/flutter/lib/src/material/app.dart

@@ -77,6 +77,71 @@ enum ThemeMode {
 /// If [home], [routes], [onGenerateRoute], and [onUnknownRoute] are all null,
 /// and [builder] is not null, then no [Navigator] is created.
 ///
+/// {@tool sample}
+/// This example shows how to create a [MaterialApp] that disables the "debug"
+/// banner with a [home] route that will be displayed when the app is launched.
+///
+/// ![A screenshot of the MaterialApp class with a home Scaffold](https://flutter.github.io/assets-for-api-docs/assets/material/basic_material_app.png)
+///
+/// ```dart
+/// MaterialApp(
+///   home: Scaffold(
+///     appBar: AppBar(
+///       title: const Text('Home'),
+///     ),
+///   ),
+///   debugShowCheckedModeBanner: false,
+/// )
+/// ```
+/// {@end-tool}
+///
+/// {@tool sample}
+/// This example shows how to create a [MaterialApp] that uses the [routes]
+/// `Map` to define the "home" route and an "about" route.
+///
+/// ```dart
+/// MaterialApp(
+///   routes: <String, WidgetBuilder>{
+///     '/': (BuildContext context) {
+///       return Scaffold(
+///         appBar: AppBar(
+///           title: const Text('Home Route'),
+///         ),
+///       );
+///     },
+///     '/about': (BuildContext context) {
+///       return Scaffold(
+///         appBar: AppBar(
+///           title: const Text('About Route'),
+///         ),
+///       );
+///      }
+///    },
+/// )
+/// ```
+/// {@end-tool}
+///
+/// {@tool sample}
+/// This example shows how to create a [MaterialApp] that defines a [theme] that
+/// will be used for material widgets in the app.
+///
+/// ![A screenshot of the MaterialApp class with a custom theme](https://flutter.github.io/assets-for-api-docs/assets/material/theme_material_app.png)
+///
+/// ```dart
+/// MaterialApp(
+///   theme: ThemeData(
+///     brightness: Brightness.dark,
+///     primaryColor: Colors.blueGrey
+///   ),
+///   home: Scaffold(
+///     appBar: AppBar(
+///       title: const Text('MaterialApp Theme'),
+///     ),
+///   ),
+/// )
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [Scaffold], which provides standard app elements like an [AppBar] and a [Drawer].

packages/flutter/lib/src/material/dropdown.dart

@@ -532,8 +532,10 @@ class DropdownButtonHideUnderline extends InheritedWidget {
 ///
 /// {@tool snippet --template=stateful_widget_scaffold}
 ///
-/// This sample shows a `DropdownButton` whose value is one of
+/// This sample shows a `DropdownButton` with a customized icon, text style,
-/// "One", "Two", "Free", or "Four".
+/// and underline and whose value is one of "One", "Two", "Free", or "Four".
+///
+/// ![A screenshot of the dropdown button](https://flutter.github.io/assets-for-api-docs/assets/material/dropdown_button.png)
 ///
 /// ```dart
 /// String dropdownValue = 'One';
@@ -544,6 +546,16 @@ class DropdownButtonHideUnderline extends InheritedWidget {
 ///     body: Center(
 ///       child: DropdownButton<String>(
 ///         value: dropdownValue,
+///         icon: Icon(Icons.arrow_downward),
+///         iconSize: 24,
+///         elevation: 16,
+///         style: TextStyle(
+///           color: Colors.deepPurple
+///         ),
+///         underline: Container(
+///           height: 2,
+///           color: Colors.deepPurpleAccent,
+///         ),
 ///         onChanged: (String newValue) {
 ///           setState(() {
 ///             dropdownValue = newValue;

packages/flutter/lib/src/material/flat_button.dart

@@ -44,6 +44,8 @@ import 'theme_data.dart';
 ///
 /// This example shows a simple [FlatButton].
 ///
+/// ![A simple FlatButton](https://flutter.github.io/assets-for-api-docs/assets/material/flat_button.png)
+///
 /// ```dart
 /// FlatButton(
 ///   onPressed: () {
@@ -63,6 +65,8 @@ import 'theme_data.dart';
 /// It turns black-on-grey when disabled.
 /// The button has 8px of padding on each side, and the text is 20px high.
 ///
+/// ![A FlatButton with white text on a blue background](https://flutter.github.io/assets-for-api-docs/assets/material/flat_button_properties.png)
+///
 /// ```dart
 /// FlatButton(
 ///   color: Colors.blue,

packages/flutter/lib/src/material/floating_action_button.dart

@@ -61,21 +61,23 @@ class _DefaultHeroTag {
 /// This example shows how to make a simple [FloatingActionButton] in a
 /// [Scaffold], with a pink [backgroundColor] and a thumbs up [Icon].
 ///
+/// ![A screenshot of a green floating action button with a navigation icon](https://flutter.github.io/assets-for-api-docs/assets/material/floating_action_button.png)
+///
 /// ```dart
 /// Widget build(BuildContext context) {
 ///   return Scaffold(
 ///     appBar: AppBar(
-///       title: Text('Floating Action Button Sample'),
+///       title: const Text('Floating Action Button'),
 ///     ),
 ///     body: Center(
-///       child: Text('Press the button below!')
+///       child: const Text('Press the button below!')
 ///     ),
 ///     floatingActionButton: FloatingActionButton(
 ///       onPressed: () {
 ///         // Add your onPressed code here!
 ///       },
-///       child: Icon(Icons.thumb_up),
+///       child: Icon(Icons.navigation),
-///       backgroundColor: Colors.pink,
+///       backgroundColor: Colors.green,
 ///     ),
 ///   );
 /// }
@@ -84,17 +86,19 @@ class _DefaultHeroTag {
 ///
 /// {@tool snippet --template=stateless_widget_material}
 /// This example shows how to make an extended [FloatingActionButton] in a
-/// [Scaffold], with a  pink [backgroundColor] and a thumbs up [Icon] and a
+/// [Scaffold], with a  pink [backgroundColor], a thumbs up [Icon] and a
 /// [Text] label.
 ///
+/// ![A screenshot of a pink floating action button with a thumbs up icon and a label that reads "Approve"](https://flutter.github.io/assets-for-api-docs/assets/material/floating_action_button_label.png)
+///
 /// ```dart
 /// Widget build(BuildContext context) {
 ///   return Scaffold(
 ///     appBar: AppBar(
-///       title: Text('Floating Action Button Sample'),
+///       title: const Text('Floating Action Button Label'),
 ///     ),
 ///     body: Center(
-///       child: Text('Press the extended button below!'),
+///       child: const Text('Press the button with a label below!'),
 ///     ),
 ///     floatingActionButton: FloatingActionButton.extended(
 ///       onPressed: () {

packages/flutter/lib/src/material/icons.dart

@@ -21,6 +21,38 @@ import 'package:flutter/widgets.dart';
 ///   uses-material-design: true
 /// ```
 ///
+/// {@tool sample}
+/// This example shows how to create a [Row] of [Icon]s in different colors and
+/// sizes. The first [Icon] uses a [semanticLabel] to announce in accessibility
+/// modes like TalkBack and VoiceOver.
+///
+/// ![A row of icons representing a pink heart, a green musical note, and a blue umbrella](https://flutter.github.io/assets-for-api-docs/assets/widgets/icon.png)
+///
+/// ```dart
+/// Row(
+///   mainAxisAlignment: MainAxisAlignment.spaceAround,
+///   children: const <Widget>[
+///     Icon(
+///       Icons.favorite,
+///       color: Colors.pink,
+///       size: 24.0,
+///       semanticLabel: 'Text to announce in accessibility modes',
+///     ),
+///     Icon(
+///       Icons.audiotrack,
+///       color: Colors.green,
+///       size: 30.0,
+///     ),
+///     Icon(
+///       Icons.beach_access,
+///       color: Colors.blue,
+///       size: 36.0,
+///     ),
+///   ],
+/// )
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [Icon]

packages/flutter/lib/src/painting/text_style.dart

@@ -30,6 +30,8 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// override. The style is mixed with the ambient [DefaultTextStyle] by the
 /// [Text] widget.
 ///
+/// ![An example using TextStyle to create bold text](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_bold.png)
+///
 /// ```dart
 /// Text(
 ///   'No, we need bold strokes. We need this plan.',
@@ -44,6 +46,8 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// As in the previous example, the [Text] widget is given a specific style
 /// override which is implicitly mixed with the ambient [DefaultTextStyle].
 ///
+/// ![An example using TextStyle to create italic text](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_italics.png)
+///
 /// ```dart
 /// Text(
 ///   'Welcome to the present, we\'re running a real nation.',
@@ -68,6 +72,8 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// The [backgroundColor] is treated as a shorthand for
 /// `background: Paint()..color = backgroundColor`.
 ///
+/// ![An example using TextStyle to change the text opacity and color](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_opacity_and_color.png)
+///
 /// ```dart
 /// RichText(
 ///   text: TextSpan(
@@ -96,6 +102,8 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// In this example, the ambient [DefaultTextStyle] is explicitly manipulated to
 /// obtain a [TextStyle] that doubles the default font size.
 ///
+/// ![An example using TextStyle to change the text size](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_size.png)
+///
 /// ```dart
 /// Text(
 ///   'These are wise words, enterprising men quote \'em.',
@@ -124,8 +132,8 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 ///
 /// ```dart
 /// Text(
-///   'Don\'t act surprised, you guys, cuz I wrote \'em!',
+///   'Ladies and gentlemen, you coulda been anywhere in the world tonight, but you’re here with us in New York City.',
-///   style: TextStyle(fontSize: 10, height: 5.0),
+///   style: TextStyle(height: 5, fontSize: 10),
 /// )
 /// ```
 /// {@end-tool}
@@ -145,6 +153,8 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// ambient [DefaultTextStyle], since no explicit style is given and [RichText]
 /// does not automatically use the ambient [DefaultTextStyle].)
 ///
+/// ![An example using TextStyle to highlight a word with a red wavy underline](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_wavy_red_underline.png)
+///
 /// ```dart
 /// RichText(
 ///   text: TextSpan(
@@ -266,6 +276,8 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
 /// argument as shown in the example below:
 ///
 /// {@tool sample}
+/// ![An example using TextStyle to change the font family](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_custom_fonts.png)
+///
 /// ```dart
 /// const TextStyle(fontFamily: 'Raleway')
 /// ```

packages/flutter/lib/src/widgets/basic.dart

@@ -4376,6 +4376,8 @@ class Flexible extends ParentDataWidget<Flex> {
 /// This example shows how to use an [Expanded] widget in a [Column] so that
 /// it's middle child, a [Container] here, expands to fill the space.
 ///
+/// ![An example using Expanded widget in a Column](https://flutter.github.io/assets-for-api-docs/assets/widgets/expanded_column.png)
+///
 /// ```dart
 /// Widget build(BuildContext context) {
 ///   return Scaffold(
@@ -4386,18 +4388,18 @@ class Flexible extends ParentDataWidget<Flex> {
 ///        child: Column(
 ///         children: <Widget>[
 ///           Container(
-///             color: Colors.red,
+///             color: Colors.blue,
 ///             height: 100,
 ///             width: 100,
 ///           ),
 ///           Expanded(
 ///             child: Container(
-///               color: Colors.blue,
+///               color: Colors.amber,
 ///               width: 100,
 ///             ),
 ///           ),
 ///           Container(
-///             color: Colors.red,
+///             color: Colors.blue,
 ///             height: 100,
 ///             width: 100,
 ///           ),
@@ -4413,6 +4415,8 @@ class Flexible extends ParentDataWidget<Flex> {
 /// This example shows how to use an [Expanded] widget in a [Row] with multiple
 /// children expanded, utilizing the [flex] factor to prioritize available space.
 ///
+/// ![An example using Expanded widget in a Row](https://flutter.github.io/assets-for-api-docs/assets/widgets/expanded_row.png)
+///
 /// ```dart
 /// Widget build(BuildContext context) {
 ///   return Scaffold(
@@ -4425,7 +4429,7 @@ class Flexible extends ParentDataWidget<Flex> {
 ///           Expanded(
 ///             flex: 2,
 ///             child: Container(
-///               color: Colors.red,
+///               color: Colors.amber,
 ///               height: 100,
 ///             ),
 ///           ),
@@ -4437,7 +4441,7 @@ class Flexible extends ParentDataWidget<Flex> {
 ///           Expanded(
 ///             flex: 1,
 ///             child: Container(
-///               color: Colors.red,
+///               color: Colors.amber,
 ///               height: 100,
 ///             ),
 ///           ),

packages/flutter/lib/src/widgets/icon.dart

@@ -26,16 +26,33 @@ import 'icon_theme_data.dart';
 ///
 /// {@tool sample}
 ///
-/// This example shows how to use [Icon] to create an addition icon, in the
+/// This example shows how to create a [Row] of [Icon]s in different colors and
-/// color pink, and 30 x 30 pixels in size.
+/// sizes. The first [Icon] uses a [semanticLabel] to announce in accessibility
+/// modes like TalkBack and VoiceOver.
 ///
-/// ![A pink plus sign](https://flutter.github.io/assets-for-api-docs/assets/widgets/icon.png)
+/// ![A row of icons representing a pink heart, a green musical note, and a blue umbrella](https://flutter.github.io/assets-for-api-docs/assets/widgets/icon.png)
 ///
 /// ```dart
+/// Row(
+///   mainAxisAlignment: MainAxisAlignment.spaceAround,
+///   children: const <Widget>[
 ///     Icon(
-///   Icons.add,
+///       Icons.favorite,
 ///       color: Colors.pink,
+///       size: 24.0,
+///       semanticLabel: 'Text to announce in accessibility modes',
+///     ),
+///     Icon(
+///       Icons.audiotrack,
+///       color: Colors.green,
 ///       size: 30.0,
+///     ),
+///     Icon(
+///       Icons.beach_access,
+///       color: Colors.blue,
+///       size: 36.0,
+///     ),
+///   ],
 /// )
 /// ```
 /// {@end-tool}

packages/flutter/lib/src/widgets/scroll_view.dart

@@ -339,6 +339,8 @@ abstract class ScrollView extends StatelessWidget {
 /// To control the initial scroll offset of the scroll view, provide a
 /// [controller] with its [ScrollController.initialScrollOffset] property set.
 ///
+/// {@animation 400 376 https://flutter.github.io/assets-for-api-docs/assets/widgets/custom_scroll_view.mp4}
+///
 /// {@tool sample}
 ///
 /// This sample code shows a scroll view that contains a flexible pinned app
@@ -366,7 +368,7 @@ abstract class ScrollView extends StatelessWidget {
 ///           return Container(
 ///             alignment: Alignment.center,
 ///             color: Colors.teal[100 * (index % 9)],
-///             child: Text('grid item $index'),
+///             child: Text('Grid Item $index'),
 ///           );
 ///         },
 ///         childCount: 20,
@@ -379,7 +381,7 @@ abstract class ScrollView extends StatelessWidget {
 ///           return Container(
 ///             alignment: Alignment.center,
 ///             color: Colors.lightBlue[100 * (index % 9)],
-///             child: Text('list item $index'),
+///             child: Text('List Item $index'),
 ///           );
 ///         },
 ///       ),
@@ -612,7 +614,7 @@ abstract class BoxScrollView extends ScrollView {
 ///
 /// ```dart
 /// ListView(
-///   padding: const EdgeInsets.all(8.0),
+///   padding: const EdgeInsets.all(8),
 ///   children: <Widget>[
 ///     Container(
 ///       height: 50,
@@ -646,7 +648,7 @@ abstract class BoxScrollView extends ScrollView {
 /// final List<int> colorCodes = <int>[600, 500, 100];
 ///
 /// ListView.builder(
-///   padding: const EdgeInsets.all(8.0),
+///   padding: const EdgeInsets.all(8),
 ///   itemCount: entries.length,
 ///   itemBuilder: (BuildContext context, int index) {
 ///     return Container(
@@ -672,7 +674,7 @@ abstract class BoxScrollView extends ScrollView {
 /// final List<int> colorCodes = <int>[600, 500, 100];
 ///
 /// ListView.separated(
-///   padding: const EdgeInsets.all(8.0),
+///   padding: const EdgeInsets.all(8),
 ///   itemCount: entries.length,
 ///   itemBuilder: (BuildContext context, int index) {
 ///     return Container(
@@ -1284,45 +1286,102 @@ class ListView extends BoxScrollView {
 /// list.
 ///
 /// {@tool sample}
+/// This example demonstrates how to create a [GridView] with two columns. The
+/// children are spaced apart using the [crossAxisSpacing] and [mainAxisSpacing]
+/// properties.
 ///
-/// Here are two brief snippets showing a [GridView] and its equivalent using
+/// ![A screenshot of a GridView](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view.png)
-/// [CustomScrollView]:
 ///
 /// ```dart
 /// GridView.count(
 ///   primary: false,
-///   padding: const EdgeInsets.all(20.0),
+///   padding: const EdgeInsets.all(20),
-///   crossAxisSpacing: 10.0,
+///   crossAxisSpacing: 10,
+///   mainAxisSpacing: 10,
 ///   crossAxisCount: 2,
 ///   children: <Widget>[
-///     const Text('He\'d have you all unravel at the'),
+///     Container(
-///     const Text('Heed not the rabble'),
+///       padding: const EdgeInsets.all(8),
-///     const Text('Sound of screams but the'),
+///       child: const Text('He\'d have you all unravel at the'),
-///     const Text('Who scream'),
+///       color: Colors.teal[100],
-///     const Text('Revolution is coming...'),
+///     ),
-///     const Text('Revolution, they...'),
+///     Container(
+///       padding: const EdgeInsets.all(8),
+///       child: const Text('Heed not the rabble'),
+///       color: Colors.teal[200],
+///     ),
+///     Container(
+///       padding: const EdgeInsets.all(8),
+///       child: const Text('Sound of screams but the'),
+///       color: Colors.teal[300],
+///     ),
+///     Container(
+///       padding: const EdgeInsets.all(8),
+///       child: const Text('Who scream'),
+///       color: Colors.teal[400],
+///     ),
+///     Container(
+///       padding: const EdgeInsets.all(8),
+///       child: const Text('Revolution is coming...'),
+///       color: Colors.teal[500],
+///     ),
+///     Container(
+///       padding: const EdgeInsets.all(8),
+///       child: const Text('Revolution, they...'),
+///       color: Colors.teal[600],
+///     ),
 ///   ],
 /// )
 /// ```
 /// {@end-tool}
+///
 /// {@tool sample}
+/// This example shows how to create the same grid as the previous example
+/// using a [CustomScrollView] and a [SliverGrid].
+///
+/// ![A screenshot of a CustomScrollView with a SliverGrid](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view_custom_scroll.png)
 ///
 /// ```dart
 /// CustomScrollView(
 ///   primary: false,
 ///   slivers: <Widget>[
 ///     SliverPadding(
-///       padding: const EdgeInsets.all(20.0),
+///       padding: const EdgeInsets.all(20),
 ///       sliver: SliverGrid.count(
-///         crossAxisSpacing: 10.0,
+///         crossAxisSpacing: 10,
+///         mainAxisSpacing: 10,
 ///         crossAxisCount: 2,
 ///         children: <Widget>[
-///           const Text('He\'d have you all unravel at the'),
+///           Container(
-///           const Text('Heed not the rabble'),
+///             padding: const EdgeInsets.all(8),
-///           const Text('Sound of screams but the'),
+///             child: const Text('He\'d have you all unravel at the'),
-///           const Text('Who scream'),
+///             color: Colors.green[100],
-///           const Text('Revolution is coming...'),
+///           ),
-///           const Text('Revolution, they...'),
+///           Container(
+///             padding: const EdgeInsets.all(8),
+///             child: const Text('Heed not the rabble'),
+///             color: Colors.green[200],
+///           ),
+///           Container(
+///             padding: const EdgeInsets.all(8),
+///             child: const Text('Sound of screams but the'),
+///             color: Colors.green[300],
+///           ),
+///           Container(
+///             padding: const EdgeInsets.all(8),
+///             child: const Text('Who scream'),
+///             color: Colors.green[400],
+///           ),
+///           Container(
+///             padding: const EdgeInsets.all(8),
+///             child: const Text('Revolution is coming...'),
+///             color: Colors.green[500],
+///           ),
+///           Container(
+///             padding: const EdgeInsets.all(8),
+///             child: const Text('Revolution, they...'),
+///             color: Colors.green[600],
+///           ),
 ///         ],
 ///       ),
 ///     ),