diff --git a/packages/flutter/lib/src/material/app.dart b/packages/flutter/lib/src/material/app.dart index 22c1c6a0bd..4fecd2e208 100644 --- a/packages/flutter/lib/src/material/app.dart +++ b/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: { +/// '/': (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]. diff --git a/packages/flutter/lib/src/material/dropdown.dart b/packages/flutter/lib/src/material/dropdown.dart index f12b67ef7d..840d0513b5 100644 --- a/packages/flutter/lib/src/material/dropdown.dart +++ b/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 -/// "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( /// 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; diff --git a/packages/flutter/lib/src/material/flat_button.dart b/packages/flutter/lib/src/material/flat_button.dart index 8ed921524f..55721d228e 100644 --- a/packages/flutter/lib/src/material/flat_button.dart +++ b/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, diff --git a/packages/flutter/lib/src/material/floating_action_button.dart b/packages/flutter/lib/src/material/floating_action_button.dart index bf83e6da02..ab0ec00705 100644 --- a/packages/flutter/lib/src/material/floating_action_button.dart +++ b/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), -/// 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: () { diff --git a/packages/flutter/lib/src/material/icons.dart b/packages/flutter/lib/src/material/icons.dart index e5128360b5..5d3208e627 100644 --- a/packages/flutter/lib/src/material/icons.dart +++ b/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 [ +/// 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] diff --git a/packages/flutter/lib/src/painting/text_style.dart b/packages/flutter/lib/src/painting/text_style.dart index 1e11cadd00..4ab45452b6 100644 --- a/packages/flutter/lib/src/painting/text_style.dart +++ b/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!', -/// 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') /// ``` diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index c5feabc537..c06e93cb06 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -4376,6 +4376,8 @@ class Flexible extends ParentDataWidget { /// 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 { /// child: Column( /// children: [ /// 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 { /// 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 { /// Expanded( /// flex: 2, /// child: Container( -/// color: Colors.red, +/// color: Colors.amber, /// height: 100, /// ), /// ), @@ -4437,7 +4441,7 @@ class Flexible extends ParentDataWidget { /// Expanded( /// flex: 1, /// child: Container( -/// color: Colors.red, +/// color: Colors.amber, /// height: 100, /// ), /// ), diff --git a/packages/flutter/lib/src/widgets/icon.dart b/packages/flutter/lib/src/widgets/icon.dart index aa41fb510a..a000f3cdf1 100644 --- a/packages/flutter/lib/src/widgets/icon.dart +++ b/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 -/// 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 [ +/// 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} diff --git a/packages/flutter/lib/src/widgets/scroll_view.dart b/packages/flutter/lib/src/widgets/scroll_view.dart index c1b2897372..9304c71e5a 100644 --- a/packages/flutter/lib/src/widgets/scroll_view.dart +++ b/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: [ /// Container( /// height: 50, @@ -646,7 +648,7 @@ abstract class BoxScrollView extends ScrollView { /// final List colorCodes = [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 colorCodes = [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: [ -/// 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: [ /// 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: [ -/// 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], +/// ), /// ], /// ), /// ),