Commit 50193212 authored by Brian Egan's avatar Brian Egan Committed by Kate Lovett

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

parent f167067d
......@@ -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].
......
......@@ -532,8 +532,10 @@ class DropdownButtonHideUnderline extends InheritedWidget {
///
/// {@tool snippet --template=stateful_widget_scaffold}
///
/// This sample shows a `DropdownButton` whose value is one of
/// "One", "Two", "Free", or "Four".
/// This sample shows a `DropdownButton` with a customized icon, text style,
/// 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;
......
......@@ -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,
......
......@@ -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),
/// backgroundColor: Colors.pink,
/// child: Icon(Icons.navigation),
/// 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: () {
......
......@@ -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]
......
......@@ -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!',
/// style: TextStyle(fontSize: 10, height: 5.0),
/// 'Ladies and gentlemen, you coulda been anywhere in the world tonight, but you’re here with us in New York City.',
/// 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')
/// ```
......
......@@ -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,
/// ),
/// ),
......
......@@ -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
/// color pink, and 30 x 30 pixels in size.
/// 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 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
/// Icon(
/// Icons.add,
/// color: Colors.pink,
/// size: 30.0,
/// 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}
......
......@@ -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
/// [CustomScrollView]:
/// ![A screenshot of a GridView](https://flutter.github.io/assets-for-api-docs/assets/widgets/grid_view.png)
///
/// ```dart
/// GridView.count(
/// primary: false,
/// padding: const EdgeInsets.all(20.0),
/// crossAxisSpacing: 10.0,
/// padding: const EdgeInsets.all(20),
/// crossAxisSpacing: 10,
/// mainAxisSpacing: 10,
/// crossAxisCount: 2,
/// children: <Widget>[
/// const Text('He\'d have you all unravel at the'),
/// const Text('Heed not the rabble'),
/// const Text('Sound of screams but the'),
/// const Text('Who scream'),
/// const Text('Revolution is coming...'),
/// const Text('Revolution, they...'),
/// Container(
/// padding: const EdgeInsets.all(8),
/// child: const Text('He\'d have you all unravel at the'),
/// color: Colors.teal[100],
/// ),
/// 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'),
/// const Text('Heed not the rabble'),
/// const Text('Sound of screams but the'),
/// const Text('Who scream'),
/// const Text('Revolution is coming...'),
/// const Text('Revolution, they...'),
/// Container(
/// padding: const EdgeInsets.all(8),
/// child: const Text('He\'d have you all unravel at the'),
/// color: Colors.green[100],
/// ),
/// 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],
/// ),
/// ],
/// ),
/// ),
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment