Skip to content

F
Front-End
Unverified Commit a6e90113 authored by Greg Spencer's avatar Greg Spencer Committed by GitHub
Browse files
Options

Convert existing '## Sample code' samples to '{@tool sample}...{@end-tool}' form. (#24077) 

This converts existing ## Sample code samples to {@tool sample}...{@end-tool} form.

Also:
1. Fixed a minor bug in analyze-sample-code.dart
2. Made the snippet tool only insert descriptions if the description is non-empty.
3. Moved the Card diagram to before the code sample.
parent 9d53d7f8
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 527 additions and 261 deletions
dev/bots/analyze-sample-code.dart
View file @ a6e90113
......@@ -715,7 +715,7 @@ class Line {
final String code;
String toStringWithColumn(int column) {
if (column != null) {
if (column != null && indent != null) {
return '$filename:$line:${column + indent}: $code';
}
return toString();
......
dev/snippets/config/skeletons/application.html
View file @ a6e90113
......@@ -5,11 +5,7 @@
</div>
<div class="snippet-container">
<div class="snippet" id="shortSnippet">
<div class="snippet-description">
{@end-inject-html}
{{description}}
{@inject-html}
</div>
{{description}}
<div class="copyable-container">
<button class="copy-button-overlay copy-button" title="Copy to clipboard"
onclick="copyTextToClipboard();">
......
dev/snippets/config/skeletons/sample.html
View file @ a6e90113
......@@ -3,10 +3,7 @@
<button id="shortSnippetButton" selected>Sample</button>
</div>
<div class="snippet-container">
<div class="snippet">
<div class="snippet-description">{@end-inject-html}
{{description}}{@inject-html}
</div>
<div class="snippet">{{description}}
<div class="copyable-container">
<button class="copy-button-overlay copy-button" title="Copy to clipboard"
onclick="copyTextToClipboard(findSiblingWithId(this, 'sample-code'));">
......
dev/snippets/config/templates/stateless_widget.tmpl
View file @ a6e90113
......@@ -25,6 +25,6 @@ class MyStatelessWidget extends StatelessWidget {
@override
Widget build(BuildContext context) {
return {{code}}
return {{code}};
}
}
dev/snippets/lib/snippets.dart
View file @ a6e90113
......@@ -113,10 +113,15 @@ class SnippetGenerator {
if (result.length > 3) {
result.removeRange(result.length - 3, result.length);
}
// Only insert a div for the description if there actually is some text there.
// This means that the {{description}} marker in the skeleton needs to
// be inside of an {@inject-html} block.
String description = injections.firstWhere((_ComponentTuple tuple) => tuple.name == 'description').mergedContent;
description = description.trim().isNotEmpty
? '<div class="snippet-description">{@end-inject-html}$description{@inject-html}</div>'
: '';
final Map<String, String> substitutions = <String, String>{
'description': injections
.firstWhere((_ComponentTuple tuple) => tuple.name == 'description')
.mergedContent,
'description': description,
'code': htmlEscape.convert(result.join('\n')),
'language': language ?? 'dart',
}..addAll(type == SnippetType.application
......
dev/snippets/test/snippets_test.dart
View file @ a6e90113
......@@ -106,7 +106,9 @@ void main() {
expect(html, contains('<div>HTML Bits</div>'));
expect(html, contains('<div>More HTML Bits</div>'));
expect(html, contains(' print(&#39;The actual \$name.&#39;);'));
expect(html, contains('A description of the snippet.\n\nOn several lines.\n'));
expect(html, contains('<div class="snippet-description">'
'{@end-inject-html}A description of the snippet.\n\n'
'On several lines.{@inject-html}</div>\n'));
expect(html, contains('main() {'));
});
});
......
packages/flutter/lib/src/animation/animation.dart
View file @ a6e90113
......@@ -101,7 +101,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// argument to the method (`child`), whose value is derived by applying the
/// given [Tween] to the value of this [Animation].
///
/// ## Sample code
/// {@tool sample}
///
/// Given an [AnimationController] `_controller`, the following code creates
/// an `Animation<Alignment>` that swings from top left to top right as the
......@@ -115,6 +115,8 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// ),
/// );
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// The `_alignment.value` could then be used in a widget's build method, for
/// instance, to position a child using an [Align] widget such that the
......@@ -133,6 +135,8 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// // ...
/// Animation<Alignment> _alignment2 = _controller.drive(_tween);
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// The following code is exactly equivalent, and is typically clearer when
/// the tweens are created inline, as might be preferred when the tweens have
......@@ -146,6 +150,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// end: Alignment.topRight,
/// ));
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/animation/animation_controller.dart
View file @ a6e90113
......@@ -123,7 +123,7 @@ enum AnimationBehavior {
/// This can be used to write code such as the `fadeOutAndUpdateState` method
/// below.
///
/// ## Sample code
/// {@tool sample}
///
/// Here is a stateful [Foo] widget. Its [State] uses the
/// [SingleTickerProviderStateMixin] to implement the necessary
......@@ -172,6 +172,8 @@ enum AnimationBehavior {
/// }
/// }
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// The following method (for a [State] subclass) drives two animation
/// controllers using Dart's asynchronous syntax for awaiting [Future] objects:
......@@ -189,6 +191,7 @@ enum AnimationBehavior {
/// }
/// }
/// ```
/// {@end-tool}
///
/// The assumption in the code above is that the animation controllers are being
/// disposed in the [State] subclass' override of the [State.dispose] method.
......
packages/flutter/lib/src/animation/animations.dart
View file @ a6e90113
......@@ -328,7 +328,7 @@ class ReverseAnimation extends Animation<double>
///
/// If you want to apply a [Curve] to a [Tween], consider using [CurveTween].
///
/// ## Sample code
/// {@tool sample}
///
/// The following code snippet shows how you can apply a curve to a linear
/// animation produced by an [AnimationController] `controller`.
......@@ -339,6 +339,8 @@ class ReverseAnimation extends Animation<double>
/// curve: Curves.ease,
/// );
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// This second code snippet shows how to apply a different curve in the forward
/// direction than in the reverse direction. This can't be done using a
......@@ -352,6 +354,7 @@ class ReverseAnimation extends Animation<double>
/// reverseCurve: Curves.easeOut,
/// );
/// ```
/// {@end-tool}
///
/// By default, the [reverseCurve] matches the forward [curve].
///
......
packages/flutter/lib/src/animation/tween.dart
View file @ a6e90113
......@@ -128,7 +128,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
/// which results in two separate [Animation] objects, each configured with a
/// single [Tween].
///
/// ## Sample code
/// {@tool sample}
///
/// Suppose `_controller` is an [AnimationController], and we want to create an
/// [Animation<Offset>] that is controlled by that controller, and save it in
......@@ -142,6 +142,8 @@ class _ChainedEvaluation<T> extends Animatable<T> {
/// ),
/// );
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// ```dart
/// _animation = Tween<Offset>(
......@@ -149,6 +151,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
/// end: const Offset(200.0, 300.0),
/// ).animate(_controller);
/// ```
/// {@end-tool}
///
/// In both cases, the `_animation` variable holds an object that, over the
/// lifetime of the `_controller`'s animation, returns a value
......@@ -408,7 +411,7 @@ class ConstantTween<T> extends Tween<T> {
/// curves when the animation is going forward vs when it is going backward,
/// which can be useful in some scenarios.)
///
/// ## Sample code
/// {@tool sample}
///
/// The following code snippet shows how you can apply a curve to a linear
/// animation produced by an [AnimationController] `controller`:
......@@ -418,6 +421,7 @@ class ConstantTween<T> extends Tween<T> {
/// CurveTween(curve: Curves.ease),
/// );
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/animation/tween_sequence.dart
View file @ a6e90113
......@@ -98,7 +98,7 @@ class TweenSequenceItem<T> {
/// animation's duration indicated by [weight] and this item's position
/// in the list of items.
///
/// ## Sample code
/// {@tool sample}
///
/// The value of this item can be "curved" by chaining it to a [CurveTween].
/// For example to create a tween that eases from 0.0 to 10.0:
......@@ -107,6 +107,7 @@ class TweenSequenceItem<T> {
/// Tween<double>(begin: 0.0, end: 10.0)
/// .chain(CurveTween(curve: Curves.ease))
/// ```
/// {@end-tool}
final Animatable<T> tween;
/// An abitrary value that indicates the relative percentage of a
......
packages/flutter/lib/src/cupertino/segmented_control.dart
View file @ a6e90113
......@@ -125,7 +125,7 @@ class CupertinoSegmentedControl<T> extends StatefulWidget {
/// the parent [StatefulWidget] using the [State.setState] method, so that
/// the parent gets rebuilt; for example:
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class SegmentedControlExample extends StatefulWidget {
......@@ -157,6 +157,7 @@ class CupertinoSegmentedControl<T> extends StatefulWidget {
/// }
/// }
/// ```
/// {@end-tool}
final ValueChanged<T> onValueChanged;
/// The color used to fill the backgrounds of unselected widgets and as the
......
packages/flutter/lib/src/cupertino/slider.dart
View file @ a6e90113
......@@ -114,7 +114,7 @@ class CupertinoSlider extends StatefulWidget {
/// The value passed will be the last [value] that the slider had before the
/// change began.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// CupertinoSlider(
......@@ -132,6 +132,7 @@ class CupertinoSlider extends StatefulWidget {
/// },
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -145,7 +146,7 @@ class CupertinoSlider extends StatefulWidget {
/// [onChanged] for that), but rather to know when the user has completed
/// selecting a new [value] by ending a drag.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// CupertinoSlider(
......@@ -163,6 +164,7 @@ class CupertinoSlider extends StatefulWidget {
/// },
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/cupertino/switch.dart
View file @ a6e90113
......@@ -26,7 +26,7 @@ import 'thumb_painter.dart';
/// that use a switch will listen for the [onChanged] callback and rebuild the
/// switch with a new [value] to update the visual appearance of the switch.
///
/// ## Sample code
/// {@tool sample}
///
/// This sample shows how to use a [CupertinoSwitch] in a [ListTile]. The
/// [MergeSemantics] is used to turn the entire [ListTile] into a single item
......@@ -44,6 +44,7 @@ import 'thumb_painter.dart';
/// ),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/cupertino/tab_scaffold.dart
View file @ a6e90113
......@@ -22,7 +22,7 @@ import 'bottom_tab_bar.dart';
/// Use [CupertinoTabView] as the content of each tab to support tabs with parallel
/// navigation state and history.
///
/// ## Sample code
/// {@tool sample}
///
/// A sample code implementing a typical iOS information architecture with tabs.
///
......@@ -70,6 +70,7 @@ import 'bottom_tab_bar.dart';
/// },
/// )
/// ```
/// {@end-tool}
///
/// To push a route above all tabs instead of inside the currently selected one
/// (such as when showing a dialog on top of this scaffold), use
......
packages/flutter/lib/src/cupertino/text_field.dart
View file @ a6e90113
......@@ -85,7 +85,7 @@ enum OverlayVisibilityMode {
/// [controller]. For example, to set the initial value of the text field, use
/// a [controller] that already contains some text such as:
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class MyPrefilledText extends StatefulWidget {
......@@ -108,6 +108,7 @@ enum OverlayVisibilityMode {
/// }
/// }
/// ```
/// {@end-tool}
///
/// The [controller] can also control the selection and composing region (and to
/// observe changes to the text, selection, and composing region).
......
packages/flutter/lib/src/foundation/annotations.dart
View file @ a6e90113
......@@ -16,7 +16,7 @@
///
/// A class can have multiple categories.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// /// A copper coffee pot, as desired by Ben Turpin.
......@@ -29,6 +29,7 @@
/// // ...code...
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -53,7 +54,7 @@ class Category {
///
/// Each class should only have one [DocumentationIcon].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// /// Utility class for beginning a dream-sharing sequence.
......@@ -64,6 +65,7 @@ class Category {
/// // ...code...
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -85,7 +87,7 @@ class DocumentationIcon {
/// for this purpose, but on occasion the first paragraph is either too short
/// or too long for use in isolation, without the remainder of the documentation.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// /// A famous cat.
......@@ -100,6 +102,7 @@ class DocumentationIcon {
/// // ...code...
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/foundation/diagnostics.dart
View file @ a6e90113
......@@ -1012,7 +1012,7 @@ abstract class DiagnosticsNode {
/// Debugging message displayed like a property.
///
/// ## Sample code
/// {@tool sample}
///
/// The following two properties are better expressed using this
/// [MessageProperty] class, rather than [StringProperty], as the intent is to
......@@ -1020,18 +1020,19 @@ abstract class DiagnosticsNode {
/// of an actual property of the object:
///
/// ```dart
/// MessageProperty('table size', '$columns\u00D7$rows')
/// ```
/// ```dart
/// MessageProperty('usefulness ratio', 'no metrics collected yet (never painted)')
/// var table = MessageProperty('table size', '$columns\u00D7$rows');
/// var usefulness = MessageProperty('usefulness ratio', 'no metrics collected yet (never painted)');
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// On the other hand, [StringProperty] is better suited when the property has a
/// concrete value that is a string:
///
/// ```dart
/// StringProperty('name', _name)
/// var name = StringProperty('name', _name);
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -1324,7 +1325,7 @@ class PercentProperty extends DoubleProperty {
/// when `visible` is false and nothing when visible is true, in contrast to
/// `visible: true` or `visible: false`.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// FlagProperty(
......@@ -1333,6 +1334,8 @@ class PercentProperty extends DoubleProperty {
/// ifFalse: 'hidden',
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// [FlagProperty] should also be used instead of [DiagnosticsProperty<bool>]
/// if showing the bool value would not clearly indicate the meaning of the
......@@ -1346,6 +1349,7 @@ class PercentProperty extends DoubleProperty {
/// ifFalse: '<no style specified>',
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -2044,7 +2048,7 @@ String describeIdentity(Object object) => '${object.runtimeType}#${shortHash(obj
///
/// Strips off the enum class name from the `enumEntry.toString()`.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// enum Day {
......@@ -2056,6 +2060,7 @@ String describeIdentity(Object object) => '${object.runtimeType}#${shortHash(obj
/// assert(describeEnum(Day.monday) == 'monday');
/// }
/// ```
/// {@end-tool}
String describeEnum(Object enumEntry) {
final String description = enumEntry.toString();
final int indexOfDot = description.indexOf('.');
......@@ -2214,7 +2219,7 @@ abstract class Diagnosticable {
/// `toString` method implementation works fine using [DiagnosticsProperty]
/// directly.
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows best practices for implementing [debugFillProperties]
/// illustrating use of all common [DiagnosticsProperty] subclasses and all
......@@ -2343,6 +2348,7 @@ abstract class Diagnosticable {
/// }
/// }
/// ```
/// {@end-tool}
///
/// Used by [toDiagnosticsNode] and [toString].
@protected
......
packages/flutter/lib/src/foundation/licenses.dart
View file @ a6e90113
......@@ -63,7 +63,7 @@ enum _LicenseEntryWithLineBreaksParserState {
/// unless they start with the same number of spaces as the previous line, in
/// which case it's assumed they are a continuation of an indented paragraph.
///
/// ## Sample code
/// {@tool sample}
///
/// For example, the BSD license in this format could be encoded as follows:
///
......@@ -101,6 +101,7 @@ enum _LicenseEntryWithLineBreaksParserState {
/// });
/// }
/// ```
/// {@end-tool}
///
/// This would result in a license with six [paragraphs], the third, fourth, and
/// fifth being indented one level.
......
packages/flutter/lib/src/material/animated_icons/animated_icons.dart
View file @ a6e90113
......@@ -16,7 +16,7 @@ part of material_animated_icons;
///
/// The available icons are specified in [AnimatedIcons].
///
/// ### Sample code
/// {@tool sample}
///
/// ```dart
/// AnimatedIcon(
......@@ -25,6 +25,7 @@ part of material_animated_icons;
/// semanticLabel: 'Show menu',
/// )
/// ```
/// {@end-tool}
///
class AnimatedIcon extends StatelessWidget {
......
packages/flutter/lib/src/material/app_bar.dart
View file @ a6e90113
......@@ -89,7 +89,7 @@ class _ToolbarContainerLayout extends SingleChildLayoutDelegate {
/// to false. In that case a null leading widget will result in the middle/title widget
/// stretching to start.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// AppBar(
......@@ -113,6 +113,7 @@ class _ToolbarContainerLayout extends SingleChildLayoutDelegate {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -169,7 +170,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
/// there's no [Drawer] and the parent [Navigator] can go back, the [AppBar]
/// will use a [BackButton] that calls [Navigator.maybePop].
///
/// ## Sample code
/// {@tool sample}
///
/// The following code shows how the drawer button could be manually specified
/// instead of relying on [automaticallyImplyLeading]:
......@@ -187,6 +188,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
/// ),
/// )
/// ```
/// {@end-tool}
///
/// The [Builder] is used in this example to ensure that the `context` refers
/// to that part of the subtree. That way this code snippet can be used even
......@@ -237,7 +239,7 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
/// ),
/// ],
/// ),
/// );
/// )
/// ```
/// {@end-tool}
final List<Widget> actions;
......@@ -722,7 +724,7 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate {
/// [actions], above the [bottom] (if any). If a [flexibleSpace] widget is
/// specified then it is stacked behind the toolbar and the bottom widget.
///
/// ## Sample code
/// {@tool sample}
///
/// This is an example that could be included in a [CustomScrollView]'s
/// [CustomScrollView.slivers] list:
......@@ -742,6 +744,7 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate {
/// ]
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -820,7 +823,7 @@ class SliverAppBar extends StatefulWidget {
/// For less common operations, consider using a [PopupMenuButton] as the
/// last action.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Scaffold(
......@@ -844,6 +847,7 @@ class SliverAppBar extends StatefulWidget {
/// ),
/// )
/// ```
/// {@end-tool}
final List<Widget> actions;
/// This widget is stacked behind the toolbar and the tabbar. It's height will
......
packages/flutter/lib/src/material/bottom_app_bar.dart
View file @ a6e90113
......@@ -19,8 +19,7 @@ import 'theme.dart';
///
/// Typically used with a [Scaffold] and a [FloatingActionButton].
///
/// ## Sample code
///
/// {@tool sample}
/// ```dart
/// Scaffold(
/// bottomNavigationBar: BottomAppBar(
......@@ -30,6 +29,7 @@ import 'theme.dart';
/// floatingActionButton: FloatingActionButton(onPressed: null),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/card.dart
View file @ a6e90113
......@@ -12,47 +12,49 @@ import 'theme.dart';
/// A card is a sheet of [Material] used to represent some related information,
/// for example an album, a geographical location, a meal, contact details, etc.
///
/// This is what it looks like when run:
///
/// ![A card with a slight shadow, consisting of two rows, one with an icon and
/// some text describing a musical, and the other with buttons for buying
/// tickets or listening to the show.](https://flutter.github.io/assets-for-api-docs/assets/material/card.png)
///
/// {@tool snippet --template=stateless_widget}
///
/// This sample shows creation of a [Card] widget that shows album information
/// and two actions.
///
/// ```dart
/// Card(
/// child: Column(
/// mainAxisSize: MainAxisSize.min,
/// children: <Widget>[
/// const ListTile(
/// leading: Icon(Icons.album),
/// title: Text('The Enchanted Nightingale'),
/// subtitle: Text('Music by Julie Gable. Lyrics by Sidney Stein.'),
/// ),
/// ButtonTheme.bar( // make buttons use the appropriate styles for cards
/// child: ButtonBar(
/// children: <Widget>[
/// FlatButton(
/// child: const Text('BUY TICKETS'),
/// onPressed: () { /* ... */ },
/// ),
/// FlatButton(
/// child: const Text('LISTEN'),
/// onPressed: () { /* ... */ },
/// ),
/// ],
/// Center(
/// child: Card(
/// child: Column(
/// mainAxisSize: MainAxisSize.min,
/// children: <Widget>[
/// const ListTile(
/// leading: Icon(Icons.album),
/// title: Text('The Enchanted Nightingale'),
/// subtitle: Text('Music by Julie Gable. Lyrics by Sidney Stein.'),
/// ),
/// ButtonTheme.bar( // make buttons use the appropriate styles for cards
/// child: ButtonBar(
/// children: <Widget>[
/// FlatButton(
/// child: const Text('BUY TICKETS'),
/// onPressed: () { /* ... */ },
/// ),
/// FlatButton(
/// child: const Text('LISTEN'),
/// onPressed: () { /* ... */ },
/// ),
/// ],
/// ),
/// ),
/// ),
/// ],
/// ],
/// ),
/// ),
/// );
/// )
/// ```
/// {@end-tool}
///
/// This is what it looks like when run:
///
/// ![A card with a slight shadow, consisting of two rows, one with an icon and
/// some text describing a musical, and the other with buttons for buying
/// tickets or listening to the show.](https://flutter.github.io/assets-for-api-docs/assets/material/card.png)
///
/// See also:
///
/// * [ListTile], to display icons and text in a card.
......
packages/flutter/lib/src/material/checkbox_list_tile.dart
View file @ a6e90113
......@@ -37,11 +37,14 @@ import 'theme_data.dart';
/// To show the [CheckboxListTile] as disabled, pass null as the [onChanged]
/// callback.
///
/// ## Sample code
/// {@tool sample}
///
/// This widget shows a checkbox that, when checked, slows down all animations
/// (including the animation of the checkbox itself getting checked!).
///
/// This sample requires that you also import 'package:flutter/scheduler.dart',
/// so that you can reference [timeDilation].
///
/// ```dart
/// CheckboxListTile(
/// title: const Text('Animate Slowly'),
......@@ -52,9 +55,7 @@ import 'theme_data.dart';
/// secondary: const Icon(Icons.hourglass_empty),
/// )
/// ```
///
/// This sample requires that you also import 'package:flutter/scheduler.dart',
/// so that you can reference [timeDilation].
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/chip.dart
View file @ a6e90113
......@@ -377,7 +377,7 @@ abstract class TappableChipAttributes {
/// taps on the label or avatar parts of the chip. If [onPressed] is null,
/// then the chip will be disabled.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class Blacksmith extends StatelessWidget {
......@@ -394,6 +394,7 @@ abstract class TappableChipAttributes {
/// }
/// }
/// ```
/// {@end-tool}
VoidCallback get onPressed;
/// Elevation to be applied on the chip during the press motion.
......@@ -418,7 +419,7 @@ abstract class TappableChipAttributes {
/// Requires one of its ancestors to be a [Material] widget. The [label]
/// and [clipBehavior] arguments must not be null.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Chip(
......@@ -429,6 +430,7 @@ abstract class TappableChipAttributes {
/// label: Text('Aaron Burr'),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -534,7 +536,7 @@ class Chip extends StatelessWidget implements ChipAttributes, DeletableChipAttri
/// * In a horizontally scrollable list, like a [ListView] whose
/// scrollDirection is [Axis.horizontal].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// InputChip(
......@@ -548,6 +550,7 @@ class Chip extends StatelessWidget implements ChipAttributes, DeletableChipAttri
/// }
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -684,7 +687,7 @@ class InputChip extends StatelessWidget
/// Requires one of its ancestors to be a [Material] widget. The [selected] and
/// [label] arguments must not be null.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class MyThreeOptions extends StatefulWidget {
......@@ -716,6 +719,7 @@ class InputChip extends StatelessWidget
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -830,7 +834,7 @@ class ChoiceChip extends StatelessWidget
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class ActorFilterEntry {
......@@ -891,6 +895,7 @@ class ChoiceChip extends StatelessWidget
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -1012,7 +1017,7 @@ class FilterChip extends StatelessWidget
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// ActionChip(
......@@ -1026,6 +1031,7 @@ class FilterChip extends StatelessWidget
/// }
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/chip_theme.dart
View file @ a6e90113
......@@ -60,7 +60,7 @@ class ChipTheme extends InheritedWidget {
/// Defaults to the ambient [ThemeData.chipTheme] if there is no
/// [ChipTheme] in the given build context.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class Spaceship extends StatelessWidget {
......@@ -76,6 +76,7 @@ class ChipTheme extends InheritedWidget {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -111,7 +112,7 @@ class ChipTheme extends InheritedWidget {
/// you get from [ChipTheme.of], or create an entirely new one with
/// [ChipThemeData..fromDefaults].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class CarColor extends StatefulWidget {
......@@ -139,6 +140,7 @@ class ChipTheme extends InheritedWidget {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/circle_avatar.dart
View file @ a6e90113
......@@ -17,7 +17,7 @@ import 'theme_data.dart';
/// such an image, the user's initials. A given user's initials should
/// always be paired with the same background color, for consistency.
///
/// ## Sample code
/// {@tool sample}
///
/// If the avatar is to have an image, the image should be specified in the
/// [backgroundImage] property:
......@@ -27,9 +27,12 @@ import 'theme_data.dart';
/// backgroundImage: NetworkImage(userAvatarUrl),
/// )
/// ```
/// {@end-tool}
///
/// The image will be cropped to have a circle shape.
///
/// {@tool sample}
///
/// If the avatar is to just have the user's initials, they are typically
/// provided using a [Text] widget as the [child] and a [backgroundColor]:
///
......@@ -39,6 +42,7 @@ import 'theme_data.dart';
/// child: Text('AH'),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/dialog.dart
View file @ a6e90113
......@@ -133,7 +133,7 @@ class Dialog extends StatelessWidget {
/// Typically passed as the child widget to [showDialog], which displays the
/// dialog.
///
/// ## Sample code
/// {@tool sample}
///
/// This snippet shows a method in a [State] which, when called, displays a dialog box
/// and returns a [Future] that completes when the dialog is dismissed.
......@@ -167,6 +167,7 @@ class Dialog extends StatelessWidget {
/// );
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -334,7 +335,7 @@ class AlertDialog extends StatelessWidget {
/// title and the first option, and 24 pixels of spacing between the last option
/// and the bottom of the dialog.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// SimpleDialogOption(
......@@ -342,6 +343,7 @@ class AlertDialog extends StatelessWidget {
/// child: const Text('Treasury department'),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -398,7 +400,7 @@ class SimpleDialogOption extends StatelessWidget {
/// Typically passed as the child widget to [showDialog], which displays the
/// dialog.
///
/// ## Sample code
/// {@tool sample}
///
/// In this example, the user is asked to select between two options. These
/// options are represented as an enum. The [showDialog] method here returns
......@@ -441,6 +443,7 @@ class SimpleDialogOption extends StatelessWidget {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/divider.dart
View file @ a6e90113
......@@ -58,13 +58,14 @@ class Divider extends StatelessWidget {
/// Defaults to the current theme's divider color, given by
/// [ThemeData.dividerColor].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Divider(
/// color: Colors.deepOrange,
/// )
/// ```
/// {@end-tool}
final Color color;
/// Computes the [BorderSide] that represents a divider of the specified
......@@ -74,7 +75,7 @@ class Divider extends StatelessWidget {
/// The `width` argument can be used to override the default width of the
/// divider border, which is usually 0.0 (a hairline border).
///
/// ## Sample code
/// {@tool sample}
///
/// This example uses this method to create a box that has a divider above and
/// below it. This is sometimes useful with lists, for instance, to separate a
......@@ -91,6 +92,7 @@ class Divider extends StatelessWidget {
/// // child: ...
/// )
/// ```
/// {@end-tool}
static BorderSide createBorderSide(BuildContext context, { Color color, double width = 0.0 }) {
assert(width != null);
return BorderSide(
......@@ -164,13 +166,14 @@ class VerticalDivider extends StatelessWidget {
/// Defaults to the current theme's divider color, given by
/// [ThemeData.dividerColor].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Divider(
/// color: Colors.deepOrange,
/// )
/// ```
/// {@end-tool}
final Color color;
@override
......
packages/flutter/lib/src/material/feedback.dart
View file @ a6e90113
......@@ -28,7 +28,7 @@ import 'theme.dart';
/// [StatelessWidget.build] method or from a [State]'s methods as you have to
/// provide a [BuildContext].
///
/// ## Sample code
/// {@tool sample}
///
/// To trigger platform-specific feedback before executing the actual callback:
///
......@@ -52,6 +52,8 @@ import 'theme.dart';
/// }
/// }
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// Alternatively, you can also call [forTap] or [forLongPress] directly within
/// your tap or long press handler:
......@@ -76,6 +78,7 @@ import 'theme.dart';
/// }
/// }
/// ```
/// {@end-tool}
class Feedback {
Feedback._();
......
packages/flutter/lib/src/material/ink_decoration.dart
View file @ a6e90113
......@@ -44,7 +44,7 @@ import 'material.dart';
/// generally speaking will match the order they are given in the widget tree,
/// but this order may appear to be somewhat random in more dynamic situations.
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows how a [Material] widget can have a yellow rectangle drawn
/// on it using [Ink], while still having ink effects over the yellow rectangle:
......@@ -67,6 +67,8 @@ import 'material.dart';
/// ),
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// The following example shows how an image can be printed on a [Material]
/// widget with an [InkWell] above it:
......@@ -94,6 +96,7 @@ import 'material.dart';
/// ),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/list_tile.dart
View file @ a6e90113
......@@ -170,7 +170,7 @@ enum ListTileControlAffinity {
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// ## Sample code
/// {@tool sample}
///
/// Here is a simple tile with an icon and some text.
///
......@@ -180,6 +180,8 @@ enum ListTileControlAffinity {
/// title: const Text('The seat for the narrator'),
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// Tiles can be much more elaborate. Here is a tile which can be tapped, but
/// which is disabled when the `_act` variable is not 2. When the tile is
......@@ -196,6 +198,7 @@ enum ListTileControlAffinity {
/// onTap: () { /* react to the tile being tapped */ }
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/popup_menu.dart
View file @ a6e90113
......@@ -135,7 +135,7 @@ class _PopupMenuDividerState extends State<PopupMenuDivider> {
/// [PopupMenuItem] is 48 pixels high. If you use a widget with a different
/// height, it must be specified in the [height] property.
///
/// ## Sample code
/// {@tool sample}
///
/// Here, a [Text] widget is used with a popup menu item. The `WhyFarther` type
/// is an enum, not shown here.
......@@ -146,6 +146,7 @@ class _PopupMenuDividerState extends State<PopupMenuDivider> {
/// child: Text('Working a lot harder'),
/// )
/// ```
/// {@end-tool}
///
/// See the example at [PopupMenuButton] for how this example could be used in a
/// complete menu, and see the example at [CheckedPopupMenuItem] for one way to
......@@ -286,7 +287,7 @@ class PopupMenuItemState<T, W extends PopupMenuItem<T>> extends State<W> {
/// of a [PopupMenuItem]. The horizontal layout uses a [ListTile]; the checkmark
/// is an [Icons.done] icon, shown in the [ListTile.leading] position.
///
/// ## Sample code
/// {@tool sample}
///
/// Suppose a `Commands` enum exists that lists the possible commands from a
/// particular popup menu, including `Commands.heroAndScholar` and
......@@ -324,6 +325,7 @@ class PopupMenuItemState<T, W extends PopupMenuItem<T>> extends State<W> {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// In particular, observe how the second menu item uses a [ListTile] with a
/// blank [Icon] in the [ListTile.leading] position to get the same alignment as
......@@ -770,7 +772,7 @@ typedef PopupMenuItemBuilder<T> = List<PopupMenuEntry<T>> Function(BuildContext
/// If both are null, then a standard overflow icon is created (depending on the
/// platform).
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows a menu with four items, selecting between an enum's
/// values and setting a `_selection` field based on the selection.
......@@ -803,6 +805,7 @@ typedef PopupMenuItemBuilder<T> = List<PopupMenuEntry<T>> Function(BuildContext
/// ],
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/radio_list_tile.dart
View file @ a6e90113
......@@ -40,7 +40,7 @@ import 'theme_data.dart';
/// To show the [RadioListTile] as disabled, pass null as the [onChanged]
/// callback.
///
/// ## Sample code
/// {@tool sample}
///
/// This widget shows a pair of radio buttons that control the `_character`
/// field. The field is of the type `SingingCharacter`, an enum.
......@@ -70,6 +70,7 @@ import 'theme_data.dart';
/// ],
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/reorderable_list.dart
View file @ a6e90113
......@@ -25,9 +25,7 @@ import 'material_localizations.dart';
/// [ReorderableListView] will need to account for this when inserting before
/// [newIndex].
///
/// ## Sample code
///
/// Example implementation:
/// {@tool sample}
///
/// ```dart
/// final List<MyDataObject> backingList = <MyDataObject>[/* ... */];
......@@ -41,6 +39,7 @@ import 'material_localizations.dart';
/// backingList.insert(newIndex, element);
/// }
/// ```
/// {@end-tool}
typedef ReorderCallback = void Function(int oldIndex, int newIndex);
/// A list whose items the user can interactively reorder by dragging.
......
packages/flutter/lib/src/material/scaffold.dart
View file @ a6e90113
......@@ -657,7 +657,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
/// [ScaffoldState] for the current [BuildContext] via [Scaffold.of] and use the
/// [ScaffoldState.showSnackBar] and [ScaffoldState.showBottomSheet] functions.
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows a [Scaffold] with an [AppBar], a [BottomAppBar]
/// and a [FloatingActionButton]. The [body] is a [Text] placed in a [Center]
......@@ -684,6 +684,7 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr
/// floatingActionButtonLocation: FloatingActionButtonLocation.centerDocked,
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/slider.dart
View file @ a6e90113
......@@ -146,7 +146,7 @@ class Slider extends StatefulWidget {
/// [StatefulWidget] using the [State.setState] method, so that the parent
/// gets rebuilt; for example:
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Slider(
......@@ -162,6 +162,7 @@ class Slider extends StatefulWidget {
/// },
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -180,7 +181,7 @@ class Slider extends StatefulWidget {
/// The value passed will be the last [value] that the slider had before the
/// change began.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Slider(
......@@ -199,6 +200,7 @@ class Slider extends StatefulWidget {
/// },
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -212,7 +214,7 @@ class Slider extends StatefulWidget {
/// [onChanged] for that), but rather to know when the user has completed
/// selecting a new [value] by ending a drag or a click.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Slider(
......@@ -231,6 +233,7 @@ class Slider extends StatefulWidget {
/// },
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -305,7 +308,7 @@ class Slider extends StatefulWidget {
/// This is used by accessibility frameworks like TalkBack on Android to
/// inform users what the currently selected value is with more context.
///
/// ## Sample code:
/// {@tool sample}
///
/// In the example below, a slider for currency values is configured to
/// announce a value with a currency label.
......@@ -326,6 +329,7 @@ class Slider extends StatefulWidget {
/// }
/// )
/// ```
/// {@end-tool}
final SemanticFormatterCallback semanticFormatterCallback;
@override
......
packages/flutter/lib/src/material/slider_theme.dart
View file @ a6e90113
......@@ -48,7 +48,7 @@ class SliderTheme extends InheritedWidget {
/// Defaults to the ambient [ThemeData.sliderTheme] if there is no
/// [SliderTheme] in the given build context.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class Launch extends StatefulWidget {
......@@ -71,6 +71,7 @@ class SliderTheme extends InheritedWidget {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -155,7 +156,7 @@ class SliderThemeData extends Diagnosticable {
/// [copyWith] on the one you get from [SliderTheme.of], or create an
/// entirely new one with [SliderThemeData.fromPrimaryColors].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class Blissful extends StatefulWidget {
......@@ -178,6 +179,7 @@ class SliderThemeData extends Diagnosticable {
/// }
/// }
/// ```
/// {@end-tool}
const SliderThemeData({
@required this.activeTrackColor,
@required this.inactiveTrackColor,
......
packages/flutter/lib/src/material/switch_list_tile.dart
View file @ a6e90113
......@@ -39,7 +39,7 @@ import 'theme_data.dart';
/// To show the [SwitchListTile] as disabled, pass null as the [onChanged]
/// callback.
///
/// ## Sample code
/// {@tool sample}
///
/// This widget shows a switch that, when toggled, changes the state of a [bool]
/// member field called `_lights`.
......@@ -52,6 +52,7 @@ import 'theme_data.dart';
/// secondary: const Icon(Icons.lightbulb_outline),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/tab_controller.dart
View file @ a6e90113
......@@ -19,7 +19,7 @@ import 'constants.dart';
/// ancestor, a [TabController] can be shared by providing a
/// [DefaultTabController] inherited widget.
///
/// ## Sample code
/// {@tool sample}
///
/// This widget introduces a [Scaffold] with an [AppBar] and a [TabBar].
///
......@@ -69,6 +69,7 @@ import 'constants.dart';
/// }
/// }
/// ```
/// {@end-tool}
class TabController extends ChangeNotifier {
/// Creates an object that manages the state required by [TabBar] and a [TabBarView].
///
......
packages/flutter/lib/src/material/text_form_field.dart
View file @ a6e90113
......@@ -39,7 +39,7 @@ import 'theme.dart';
/// * [InputDecorator], which shows the labels and other visual elements that
/// surround the actual text editing widget.
///
/// ## Sample code
/// {@tool sample}
///
/// Creates a [TextFormField] with an [InputDecoration] and validator function.
///
......@@ -59,6 +59,7 @@ import 'theme.dart';
/// },
/// )
/// ```
/// {@end-tool}
class TextFormField extends FormField<String> {
/// Creates a [FormField] that contains a [TextField].
///
......
packages/flutter/lib/src/material/text_theme.dart
View file @ a6e90113
......@@ -176,7 +176,7 @@ class TextTheme extends Diagnosticable {
/// the typography styles in the material design specification, as a starting
/// point.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// /// A Widget that sets the ambient theme's title text color for its
......@@ -203,6 +203,7 @@ class TextTheme extends Diagnosticable {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -259,7 +260,7 @@ class TextTheme extends Diagnosticable {
/// [TextTheme] has only some fields defined, and you want to define the rest
/// by merging it with a default theme.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// /// A Widget that sets the ambient theme's title text color for its
......@@ -284,6 +285,7 @@ class TextTheme extends Diagnosticable {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/material/time.dart
View file @ a6e90113
......@@ -29,13 +29,14 @@ enum DayPeriod {
/// minute or using [DateTime] object.
/// Hours are specified between 0 and 23, as in a 24-hour clock.
///
/// ### Sample code
/// {@tool sample}
///
/// ```dart
/// TimeOfDay now = TimeOfDay.now();
/// TimeOfDay releaseTime = TimeOfDay(hour: 15, minute: 0); // 3:00pm
/// TimeOfDay roomBooked = TimeOfDay.fromDateTime(DateTime.parse('2018-10-20 16:30:04Z')); // 4:30pm
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/painting/borders.dart
View file @ a6e90113
......@@ -26,7 +26,7 @@ enum BorderStyle {
/// A [Border] consists of four [BorderSide] objects: [Border.top],
/// [Border.left], [Border.right], and [Border.bottom].
///
/// ## Sample code
/// {@tool sample}
///
/// This sample shows how [BorderSide] objects can be used in a [Container], via
/// a [BoxDecoration] and a [Border], to decorate some [Text]. In this example,
......@@ -45,6 +45,7 @@ enum BorderStyle {
/// child: Text('Flutter in the sky', textAlign: TextAlign.center),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/painting/box_border.dart
View file @ a6e90113
......@@ -239,19 +239,23 @@ abstract class BoxBorder extends ShapeBorder {
///
/// The sides are represented by [BorderSide] objects.
///
/// ## Sample code
/// {@tool sample}
///
/// All four borders the same, two-pixel wide solid white:
///
/// ```dart
/// Border.all(width: 2.0, color: const Color(0xFFFFFFFF))
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// The border for a material design divider:
///
/// ```dart
/// Border(bottom: BorderSide(color: Theme.of(context).dividerColor))
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// A 1990s-era "OK" button:
///
......@@ -284,6 +288,7 @@ abstract class BoxBorder extends ShapeBorder {
/// ),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/painting/box_decoration.dart
View file @ a6e90113
......@@ -32,7 +32,7 @@ import 'image_provider.dart';
///
/// The [border] paints over the body; the [boxShadow], naturally, paints below it.
///
/// ## Sample code
/// {@tool sample}
///
/// The following example uses the [Container] widget from the widgets layer to
/// draw an image with a border:
......@@ -52,6 +52,7 @@ import 'image_provider.dart';
/// ),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/painting/box_fit.dart
View file @ a6e90113
......@@ -102,7 +102,7 @@ class FittedSizes {
/// convenience function, [Alignment.inscribe], for resolving the sizes to
/// rects, as shown in the example below.
///
/// ## Sample code
/// {@tool sample}
///
/// This function paints a [dart:ui.Image] `image` onto the [Rect] `outputRect` on a
/// [Canvas] `canvas`, using a [Paint] `paint`, applying the [BoxFit] algorithm
......@@ -117,6 +117,7 @@ class FittedSizes {
/// canvas.drawImageRect(image, inputSubrect, outputSubrect, paint);
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/painting/edge_insets.dart
View file @ a6e90113
......@@ -282,7 +282,7 @@ abstract class EdgeInsetsGeometry {
/// _start_, top, _end_, and bottom, where start and end are resolved in terms
/// of a [TextDirection] (typically obtained from the ambient [Directionality]).
///
/// ## Sample code
/// {@tool sample}
///
/// Here are some examples of how to create [EdgeInsets] instances:
///
......@@ -291,18 +291,23 @@ abstract class EdgeInsetsGeometry {
/// ```dart
/// const EdgeInsets.all(8.0)
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// Eight pixel margin above and below, no horizontal margins:
///
/// ```dart
/// const EdgeInsets.symmetric(vertical: 8.0)
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// Left margin indent of 40 pixels:
///
/// ```dart
/// const EdgeInsets.only(left: 40.0)
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -316,25 +321,27 @@ class EdgeInsets extends EdgeInsetsGeometry {
/// Creates insets where all the offsets are `value`.
///
/// ## Sample code
/// {@tool sample}
///
/// Typical eight-pixel margin on all sides:
///
/// ```dart
/// const EdgeInsets.all(8.0)
/// ```
/// {@end-tool}
const EdgeInsets.all(double value)
: left = value, top = value, right = value, bottom = value;
/// Creates insets with only the given values non-zero.
///
/// ## Sample code
/// {@tool sample}
///
/// Left margin indent of 40 pixels:
///
/// ```dart
/// const EdgeInsets.only(left: 40.0)
/// ```
/// {@end-tool}
const EdgeInsets.only({
this.left = 0.0,
this.top = 0.0,
......@@ -344,13 +351,14 @@ class EdgeInsets extends EdgeInsetsGeometry {
/// Creates insets with symmetrical vertical and horizontal offsets.
///
/// ## Sample code
/// {@tool sample}
///
/// Eight pixel margin above and below, no horizontal margins:
///
/// ```dart
/// const EdgeInsets.symmetric(vertical: 8.0)
/// ```
/// {@end-tool}
const EdgeInsets.symmetric({ double vertical = 0.0,
double horizontal = 0.0 })
: left = horizontal, top = vertical, right = horizontal, bottom = vertical;
......@@ -600,13 +608,14 @@ class EdgeInsetsDirectional extends EdgeInsetsGeometry {
/// Creates insets with only the given values non-zero.
///
/// ## Sample code
/// {@tool sample}
///
/// A margin indent of 40 pixels on the leading side:
///
/// ```dart
/// const EdgeInsetsDirectional.only(start: 40.0)
/// ```
/// {@end-tool}
const EdgeInsetsDirectional.only({
this.start = 0.0,
this.top = 0.0,
......
packages/flutter/lib/src/painting/gradient.dart
View file @ a6e90113
......@@ -226,7 +226,7 @@ abstract class Gradient {
/// Typically this class is used with [BoxDecoration], which does the painting.
/// To use a [LinearGradient] to paint on a canvas directly, see [createShader].
///
/// ## Sample code
/// {@tool sample}
///
/// This sample draws a picture that looks like vertical window shades by having
/// a [Container] display a [BoxDecoration] with a [LinearGradient].
......@@ -243,6 +243,7 @@ abstract class Gradient {
/// ),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -460,7 +461,7 @@ class LinearGradient extends Gradient {
/// Typically this class is used with [BoxDecoration], which does the painting.
/// To use a [RadialGradient] to paint on a canvas directly, see [createShader].
///
/// ## Sample code
/// {@tool sample}
///
/// This function draws a gradient that looks like a sun in a blue sky.
///
......@@ -481,6 +482,7 @@ class LinearGradient extends Gradient {
/// canvas.drawRect(rect, paint);
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -718,7 +720,7 @@ class RadialGradient extends Gradient {
/// Typically this class is used with [BoxDecoration], which does the painting.
/// To use a [SweepGradient] to paint on a canvas directly, see [createShader].
///
/// ## Sample code
/// {@tool sample}
///
/// This sample draws a different color in each quadrant.
///
......@@ -741,6 +743,7 @@ class RadialGradient extends Gradient {
/// ),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/painting/image_provider.dart
View file @ a6e90113
......@@ -170,7 +170,7 @@ class ImageConfiguration {
///
/// The following image formats are supported: {@macro flutter.dart:ui.imageFormats}
///
/// ## Sample code
/// {@tool sample}
///
/// The following shows the code required to write a widget that fully conforms
/// to the [ImageProvider] and [Widget] protocols. (It is essentially a
......@@ -244,6 +244,7 @@ class ImageConfiguration {
/// }
/// }
/// ```
/// {@end-tool}
@optionalTypeArgs
abstract class ImageProvider<T> {
/// Abstract const constructor. This constructor enables subclasses to provide
......@@ -299,7 +300,7 @@ abstract class ImageProvider<T> {
/// The [configuration] is optional and defaults to
/// [ImageConfiguration.empty].
///
/// ## Sample code
/// {@tool sample}
///
/// The following sample code shows how an image loaded using the [Image]
/// widget can be evicted using a [NetworkImage] with a matching url.
......@@ -322,6 +323,7 @@ abstract class ImageProvider<T> {
/// }
/// }
/// ```
/// {@end-tool}
Future<bool> evict({ImageCache cache, ImageConfiguration configuration = ImageConfiguration.empty}) async {
cache ??= imageCache;
final T key = await obtainKey(configuration);
......
packages/flutter/lib/src/painting/shape_decoration.dart
View file @ a6e90113
......@@ -23,7 +23,7 @@ import 'rounded_rectangle_border.dart';
/// optionally filling it with a color or a gradient, optionally painting an
/// image into it, and optionally casting a shadow.
///
/// ## Sample code
/// {@tool sample}
///
/// The following example uses the [Container] widget from the widgets layer to
/// draw a white rectangle with a 24-pixel multicolor outline, with the text
......@@ -47,6 +47,7 @@ import 'rounded_rectangle_border.dart';
/// child: const Text('RGB', textAlign: TextAlign.center),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/painting/text_span.dart
View file @ a6e90113
......@@ -27,7 +27,7 @@ import 'text_style.dart';
/// span in a widget, use a [RichText]. For text with a single style, consider
/// using the [Text] widget.
///
/// ## Sample code
/// {@tool sample}
///
/// The text "Hello world!", in black:
///
......@@ -37,6 +37,7 @@ import 'text_style.dart';
/// style: TextStyle(color: Colors.black),
/// )
/// ```
/// {@end-tool}
///
/// _There is some more detailed sample code in the documentation for the
/// [recognizer] property._
......@@ -93,7 +94,7 @@ class TextSpan extends DiagnosticableTree {
/// The code that owns the [GestureRecognizer] object must call
/// [GestureRecognizer.dispose] when the [TextSpan] object is no longer used.
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows how to manage the lifetime of a gesture recognizer
/// provided to a [TextSpan] object. It defines a `BuzzingText` widget which
......@@ -152,6 +153,7 @@ class TextSpan extends DiagnosticableTree {
/// }
/// }
/// ```
/// {@end-tool}
final GestureRecognizer recognizer;
/// Apply the [style], [text], and [children] of this object to the
......
packages/flutter/lib/src/painting/text_style.dart
View file @ a6e90113
......@@ -18,7 +18,7 @@ const String _kColorForegroundWarning = 'Cannot provide both a color and a foreg
/// An immutable style in which paint text.
///
/// ## Sample code
/// {@tool sample}
///
/// ### Bold
///
......@@ -32,6 +32,8 @@ const String _kColorForegroundWarning = 'Cannot provide both a color and a foreg
/// style: TextStyle(fontWeight: FontWeight.bold),
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// ### Italics
///
......@@ -44,6 +46,7 @@ const String _kColorForegroundWarning = 'Cannot provide both a color and a foreg
/// style: TextStyle(fontStyle: FontStyle.italic),
/// )
/// ```
/// {@end-tool}
///
/// ### Opacity and Color
///
......
packages/flutter/lib/src/physics/gravity_simulation.dart
View file @ a6e90113
......@@ -12,7 +12,7 @@ import 'simulation.dart';
/// Models a particle that follows Newton's second law of motion. The simulation
/// ends when the position reaches a defined point.
///
/// ## Sample code
/// {@tool sample}
///
/// This method triggers an [AnimationController] (a previously constructed
/// `_controller` field) to simulate a fall of 300 pixels.
......@@ -27,6 +27,7 @@ import 'simulation.dart';
/// ));
/// }
/// ```
/// {@end-tool}
///
/// This [AnimationController] could be used with an [AnimatedBuilder] to
/// animate the position of a child as if it was falling.
......
packages/flutter/lib/src/rendering/custom_layout.dart
View file @ a6e90113
......@@ -45,7 +45,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentData<RenderBox> {
/// identifies it to the delegate. The [LayoutId.id] needs to be unique among
/// the children that the [CustomMultiChildLayout] manages.
///
/// ## Sample code
/// {@tool sample}
///
/// Below is an example implementation of [performLayout] that causes one widget
/// (the follower) to be the same size as another (the leader):
......@@ -80,6 +80,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentData<RenderBox> {
/// bool shouldRelayout(MultiChildLayoutDelegate oldDelegate) => false;
/// }
/// ```
/// {@end-tool}
///
/// The delegate gives the leader widget loose constraints, which means the
/// child determines what size to be (subject to fitting within the given size).
......
packages/flutter/lib/src/rendering/custom_paint.dart
View file @ a6e90113
......@@ -62,7 +62,7 @@ typedef SemanticsBuilderCallback = List<CustomPainterSemantics> Function(Size si
/// class is provided, to check if the new instance contains different
/// information that affects the semantics tree.
///
/// ## Sample code
/// {@tool sample}
///
/// This sample extends the same code shown for [RadialGradient] to create a
/// custom painter that paints a sky.
......@@ -117,6 +117,7 @@ typedef SemanticsBuilderCallback = List<CustomPainterSemantics> Function(Size si
/// bool shouldRebuildSemantics(Sky oldDelegate) => false;
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/rendering/debug_overflow_indicator.dart
View file @ a6e90113
......@@ -48,7 +48,7 @@ class _OverflowRegionData {
/// overflows. It will print on the first occurrence, and once after each time that
/// [reassemble] is called.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class MyRenderObject extends RenderAligningShiftedBox with DebugOverflowIndicatorMixin {
......@@ -81,6 +81,7 @@ class _OverflowRegionData {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/rendering/object.dart
View file @ a6e90113
......@@ -2232,7 +2232,7 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
/// asynchronous computation) will at best have no useful effect and at worse
/// will cause crashes as the data will be in an inconsistent state.
///
/// ## Sample code
/// {@tool sample}
///
/// The following snippet will describe the node as a button that responds to
/// tap actions.
......@@ -2253,6 +2253,7 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im
/// }
/// }
/// ```
/// {@end-tool}
@protected
void describeSemanticsConfiguration(SemanticsConfiguration config) {
// Nothing to do by default.
......
packages/flutter/lib/src/rendering/proxy_box.dart
View file @ a6e90113
......@@ -2572,7 +2572,7 @@ class RenderRepaintBoundary extends RenderProxyBox {
/// will give you a 1:1 mapping between logical pixels and the output pixels
/// in the image.
///
/// ## Sample code
/// {@tool sample}
///
/// The following is an example of how to go from a `GlobalKey` on a
/// `RepaintBoundary` to a PNG:
......@@ -2610,6 +2610,7 @@ class RenderRepaintBoundary extends RenderProxyBox {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/services/platform_channel.dart
View file @ a6e90113
......@@ -135,12 +135,14 @@ class MethodChannel {
/// * a [MissingPluginException], if the method has not been implemented by a
/// platform plugin.
///
/// ## Sample code
///
/// The following code snippets demonstrate how to invoke platform methods
/// in Dart using a MethodChannel and how to implement those methods in Java
/// (for Android) and Objective-C (for iOS). The code might be packaged up as
/// a musical plugin, see <https://flutter.io/developing-packages/>:
/// (for Android) and Objective-C (for iOS).
///
/// {@tool sample}
///
/// The code might be packaged up as a musical plugin, see
/// <https://flutter.io/developing-packages/>:
///
/// ```dart
/// class Music {
......@@ -188,6 +190,11 @@ class MethodChannel {
/// }
/// }
/// ```
/// {@end-tool}
///
/// {@tool sample}
///
/// Java (for Android):
///
/// ```java
/// // Assumes existence of an Android MusicApi.
......@@ -223,8 +230,13 @@ class MethodChannel {
/// // Other methods elided.
/// }
/// ```
/// {@end-tool}
///
/// {@tool sample}
///
/// Objective-C (for iOS):
///
/// ```objective-c
/// ```objectivec
/// @interface MusicPlugin : NSObject<FlutterPlugin>
/// @end
///
......@@ -259,6 +271,7 @@ class MethodChannel {
/// // Other methods elided.
/// @end
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/animated_cross_fade.dart
View file @ a6e90113
......@@ -38,7 +38,7 @@ enum CrossFadeState {
/// top child and the bottom child should be keyed using the provided
/// `topChildKey` and `bottomChildKey` keys respectively.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Widget defaultLayoutBuilder(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey) {
......@@ -60,6 +60,7 @@ enum CrossFadeState {
/// );
/// }
/// ```
/// {@end-tool}
typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey);
/// A widget that cross-fades between two given children and animates itself
......@@ -81,7 +82,7 @@ typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChild
/// [AnimatedCrossFade] is rebuilt with a different value for the
/// [crossFadeState] property.
///
/// ## Sample code
/// {@tool sample}
///
/// This code fades between two representations of the Flutter logo. It depends
/// on a boolean field `_first`; when `_first` is true, the first logo is shown,
......@@ -97,6 +98,7 @@ typedef AnimatedCrossFadeBuilder = Widget Function(Widget topChild, Key topChild
/// crossFadeState: _first ? CrossFadeState.showFirst : CrossFadeState.showSecond,
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/animated_switcher.dart
View file @ a6e90113
......@@ -87,7 +87,7 @@ typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, Lis
/// progress indicator and the image will be fading out while a new progress
/// indicator is fading in.)
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class ClickCounter extends StatefulWidget {
......@@ -136,6 +136,7 @@ typedef AnimatedSwitcherLayoutBuilder = Widget Function(Widget currentChild, Lis
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/async.dart
View file @ a6e90113
......@@ -342,7 +342,7 @@ typedef AsyncWidgetBuilder<T> = Widget Function(BuildContext context, AsyncSnaps
/// * [StreamBuilderBase], which supports widget building based on a computation
/// that spans all interactions made with the stream.
///
/// ## Sample code
/// {@tool sample}
///
/// This sample shows a [StreamBuilder] configuring a text label to show the
/// latest bid received for a lot in an auction. Assume the `_lot` field is
......@@ -364,6 +364,7 @@ typedef AsyncWidgetBuilder<T> = Widget Function(BuildContext context, AsyncSnaps
/// },
/// )
/// ```
/// {@end-tool}
// TODO(ianh): remove unreachable code above once https://github.com/dart-lang/linter/issues/1141 is fixed
class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// Creates a new [StreamBuilder] that builds itself based on the latest
......@@ -473,7 +474,7 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// `future?.asStream()`, except that snapshots with `ConnectionState.active`
/// may appear for the latter, depending on how the stream is implemented.
///
/// ## Sample code
/// {@tool sample}
///
/// This sample shows a [FutureBuilder] configuring a text label to show the
/// state of an asynchronous calculation returning a string. Assume the
......@@ -498,6 +499,7 @@ class StreamBuilder<T> extends StreamBuilderBase<T, AsyncSnapshot<T>> {
/// },
/// )
/// ```
/// {@end-tool}
// TODO(ianh): remove unreachable code above once https://github.com/dart-lang/linter/issues/1141 is fixed
class FutureBuilder<T> extends StatefulWidget {
/// Creates a widget that builds itself based on the latest snapshot of
......
packages/flutter/lib/src/widgets/basic.dart
View file @ a6e90113
This diff is collapsed.
packages/flutter/lib/src/widgets/binding.dart
View file @ a6e90113
......@@ -32,7 +32,7 @@ export 'dart:ui' show AppLifecycleState, Locale;
/// handlers must be implemented (and the analyzer will list those that have
/// been omitted).
///
/// ## Sample code
/// {@tool sample}
///
/// This [StatefulWidget] implements the parts of the [State] and
/// [WidgetsBindingObserver] protocols necessary to react to application
......@@ -72,6 +72,7 @@ export 'dart:ui' show AppLifecycleState, Locale;
/// }
/// }
/// ```
/// {@end-tool}
///
/// To respond to other notifications, replace the [didChangeAppLifecycleState]
/// method above with other methods from this class.
......@@ -109,7 +110,7 @@ abstract class WidgetsBindingObserver {
///
/// This method exposes notifications from [Window.onMetricsChanged].
///
/// ## Sample code
/// {@tool sample}
///
/// This [StatefulWidget] implements the parts of the [State] and
/// [WidgetsBindingObserver] protocols necessary to react when the device is
......@@ -149,6 +150,7 @@ abstract class WidgetsBindingObserver {
/// }
/// }
/// ```
/// {@end-tool}
///
/// In general, this is unnecessary as the layout system takes care of
/// automatically recomputing the application geometry when the application
......@@ -168,7 +170,7 @@ abstract class WidgetsBindingObserver {
///
/// This method exposes notifications from [Window.onTextScaleFactorChanged].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class TextScaleFactorReactor extends StatefulWidget {
......@@ -204,6 +206,7 @@ abstract class WidgetsBindingObserver {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/container.dart
View file @ a6e90113
......@@ -20,7 +20,7 @@ import 'image.dart';
///
/// Commonly used with [BoxDecoration].
///
/// ## Sample code
/// {@tool sample}
///
/// This sample shows a radial gradient that draws a moon on a night sky:
///
......@@ -39,6 +39,7 @@ import 'image.dart';
/// ),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -178,7 +179,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
/// [padding] (e.g. borders in a [BoxDecoration] contribute to the [padding]);
/// see [Decoration.padding].
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows a 48x48 green square (placed inside a [Center] widget in
/// case the parent widget has its own opinions regarding the size that the
......@@ -195,6 +196,8 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
/// ),
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// This example shows how to use many of the features of [Container] at once.
/// The [constraints] are set to fit the font size plus ample headroom
......@@ -223,6 +226,7 @@ class DecoratedBox extends SingleChildRenderObjectWidget {
/// transform: Matrix4.rotationZ(0.1),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/fade_in_image.dart
View file @ a6e90113
......@@ -49,7 +49,7 @@ import 'ticker_provider.dart';
/// different image. This is known as "gapless playback" (see also
/// [Image.gaplessPlayback]).
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// FadeInImage(
......@@ -58,6 +58,7 @@ import 'ticker_provider.dart';
/// image: NetworkImage('https://backend.example.com/image.png'),
/// )
/// ```
/// {@end-tool}
class FadeInImage extends StatefulWidget {
/// Creates a widget that displays a [placeholder] while an [image] is loading
/// then cross-fades to display the [image].
......
packages/flutter/lib/src/widgets/framework.dart
View file @ a6e90113
......@@ -498,7 +498,7 @@ abstract class Widget extends DiagnosticableTree {
/// widget, so that only the inner-most widget needs to be rebuilt when the
/// theme changes.
///
/// ## Sample code
/// {@tool sample}
///
/// The following is a skeleton of a stateless widget subclass called `GreenFrog`:
///
......@@ -512,6 +512,8 @@ abstract class Widget extends DiagnosticableTree {
/// }
/// }
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// Normally widgets have more constructor arguments, each of which corresponds
/// to a `final` property. The next example shows the more generic widget `Frog`
......@@ -535,6 +537,7 @@ abstract class Widget extends DiagnosticableTree {
/// }
/// }
/// ```
/// {@end-tool}
///
/// By convention, widget constructors only use named arguments. Named arguments
/// can be marked as required using [@required]. Also by convention, the first
......@@ -705,7 +708,7 @@ abstract class StatelessWidget extends Widget {
/// [KeyedSubtree] widget may be useful for this purpose if no other widget
/// can conveniently be assigned the key.)
///
/// ## Sample code
/// {@tool sample}
///
/// The following is a skeleton of a stateful widget subclass called `YellowBird`:
///
......@@ -724,6 +727,8 @@ abstract class StatelessWidget extends Widget {
/// }
/// }
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// In this example. the [State] has no actual state. State is normally
/// represented as private member fields. Also, normally widgets have more
......@@ -765,6 +770,7 @@ abstract class StatelessWidget extends Widget {
/// }
/// }
/// ```
/// {@end-tool}
///
/// By convention, widget constructors only use named arguments. Named arguments
/// can be marked as required using [@required]. Also by convention, the first
......@@ -1366,7 +1372,7 @@ abstract class ProxyWidget extends Widget {
/// thus also to a particular [RenderObjectWidget] class. That class is `T`, the
/// [ParentDataWidget] type argument.
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows how you would build a [ParentDataWidget] to configure a
/// `FrogJar` widget's children by specifying a [Size] for each one.
......@@ -1394,6 +1400,7 @@ abstract class ProxyWidget extends Widget {
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -1496,7 +1503,7 @@ abstract class ParentDataWidget<T extends RenderObjectWidget> extends ProxyWidge
/// Inherited widgets, when referenced in this way, will cause the consumer to
/// rebuild when the inherited widget itself changes state.
///
/// ## Sample code
/// {@tool sample}
///
/// The following is a skeleton of an inherited widget called `FrogColor`:
///
......@@ -1520,6 +1527,7 @@ abstract class ParentDataWidget<T extends RenderObjectWidget> extends ProxyWidge
/// bool updateShouldNotify(FrogColor old) => color != old.color;
/// }
/// ```
/// {@end-tool}
///
/// The convention is to provide a static method `of` on the [InheritedWidget]
/// which does the call to [BuildContext.inheritFromWidgetOfExactType]. This
......@@ -1988,13 +1996,14 @@ abstract class BuildContext {
/// an ancestor from one of those methods, save a reference to the ancestor
/// by calling [ancestorStateOfType] in [State.didChangeDependencies].
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// ScrollableState scrollable = context.ancestorStateOfType(
/// const TypeMatcher<ScrollableState>(),
/// );
/// ```
/// {@end-tool}
State ancestorStateOfType(TypeMatcher matcher);
/// Returns the [State] object of the furthest ancestor [StatefulWidget] widget
......
packages/flutter/lib/src/widgets/gesture_detector.dart
View file @ a6e90113
......@@ -113,7 +113,7 @@ class GestureRecognizerFactoryWithHandlers<T extends GestureRecognizer> extends
/// effects. The [InkWell] class implements this effect and can be used in place
/// of a [GestureDetector] for handling taps.
///
/// ## Sample code
/// {@tool sample}
///
/// This example makes a rectangle react to being tapped by setting the
/// `_lights` field:
......@@ -129,6 +129,7 @@ class GestureRecognizerFactoryWithHandlers<T extends GestureRecognizer> extends
/// ),
/// )
/// ```
/// {@end-tool}
///
/// ## Debugging
///
......@@ -453,7 +454,7 @@ class GestureDetector extends StatelessWidget {
/// Configuring the gesture recognizers requires a carefully constructed map, as
/// described in [gestures] and as shown in the example below.
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows how to hook up a [TapGestureRecognizer]. It assumes that
/// the code is being used inside a [State] object with a `_last` field that is
......@@ -476,6 +477,7 @@ class GestureDetector extends StatelessWidget {
/// child: Container(width: 300.0, height: 300.0, color: Colors.yellow, child: Text(_last)),
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/image.dart
View file @ a6e90113
......@@ -298,7 +298,7 @@ class Image extends StatefulWidget {
/// which corresponds to bilinear interpolation, rather than the default
/// [FilterQuality.none] which corresponds to nearest-neighbor.
///
/// ## Sample code
/// {@tool sample}
///
/// Suppose that the project's `pubspec.yaml` file contains the following:
///
......@@ -309,6 +309,7 @@ class Image extends StatefulWidget {
/// - images/2x/cat.png
/// - images/3.5x/cat.png
/// ```
/// {@end-tool}
///
/// On a screen with a device pixel ratio of 2.0, the following widget would
/// render the `images/2x/cat.png` file:
......@@ -336,11 +337,13 @@ class Image extends StatefulWidget {
/// must be provided. For instance, suppose a package called `my_icons` has
/// `icons/heart.png` .
///
/// {@tool sample}
/// Then to display the image, use:
///
/// ```dart
/// Image.asset('icons/heart.png', package: 'my_icons')
/// ```
/// {@end-tool}
///
/// Assets used by the package itself should also be displayed using the
/// [package] argument as above.
......
packages/flutter/lib/src/widgets/implicit_animations.dart
View file @ a6e90113
......@@ -1018,7 +1018,7 @@ class _AnimatedPositionedDirectionalState extends AnimatedWidgetBaseState<Animat
/// of [Curves.fastOutSlowIn].
/// {@animation 250 266 https://flutter.github.io/assets-for-api-docs/assets/widgets/animated_opacity.mp4}
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// class LogoFade extends StatefulWidget {
......@@ -1052,6 +1052,7 @@ class _AnimatedPositionedDirectionalState extends AnimatedWidgetBaseState<Animat
/// }
/// }
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/localizations.dart
View file @ a6e90113
......@@ -297,7 +297,7 @@ class _LocalizationsScope extends InheritedWidget {
/// `Localizations.of(context)` will be rebuilt after the resources
/// for the new locale have been loaded.
///
/// ## Sample code
/// {@tool sample}
///
/// This following class is defined in terms of the
/// [Dart `intl` package](https://github.com/dart-lang/intl). Using the `intl`
......@@ -324,6 +324,7 @@ class _LocalizationsScope extends InheritedWidget {
/// // ... more Intl.message() methods like title()
/// }
/// ```
/// {@end-tool}
/// A class based on the `intl` package imports a generated message catalog that provides
/// the `initializeMessages()` function and the per-locale backing store for `Intl.message()`.
/// The message catalog is produced by an `intl` tool that analyzes the source code for
......
packages/flutter/lib/src/widgets/nested_scroll_view.dart
View file @ a6e90113
......@@ -60,7 +60,7 @@ typedef NestedScrollViewHeaderSliversBuilder = List<Widget> Function(BuildContex
/// (those inside the [TabBarView], hooking them together so that they appear,
/// to the user, as one coherent scroll view.
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows a [NestedScrollView] whose header is the combination of a
/// [TabBar] in a [SliverAppBar] and whose body is a [TabBarView]. It uses a
......@@ -174,6 +174,7 @@ typedef NestedScrollViewHeaderSliversBuilder = List<Widget> Function(BuildContex
/// ),
/// )
/// ```
/// {@end-tool}
class NestedScrollView extends StatefulWidget {
/// Creates a nested scroll view.
///
......
packages/flutter/lib/src/widgets/routes.dart
View file @ a6e90113
......@@ -325,7 +325,7 @@ mixin LocalHistoryRoute<T> on Route<T> {
/// The given local history entry must not already be part of another local
/// history route.
///
/// ## Sample code
/// {@tool sample}
///
/// The following example is an app with 2 pages: `HomePage` and `SecondPage`.
/// The `HomePage` can navigate to the `SecondPage`.
......@@ -442,6 +442,7 @@ mixin LocalHistoryRoute<T> on Route<T> {
/// }
/// }
/// ```
/// {@end-tool}
void addLocalHistoryEntry(LocalHistoryEntry entry) {
assert(entry._owner == null);
entry._owner = this;
......@@ -1267,7 +1268,7 @@ abstract class PopupRoute<T> extends ModalRoute<T> {
/// than only specific subtypes. For example, to watch for all [PageRoute]
/// variants, the `RouteObserver<PageRoute<dynamic>>` type may be used.
///
/// ## Sample code
/// {@tool sample}
///
/// To make a [StatefulWidget] aware of its current [Route] state, implement
/// [RouteAware] in its [State] and subscribe it to a [RouteObserver]:
......@@ -1316,6 +1317,7 @@ abstract class PopupRoute<T> extends ModalRoute<T> {
///
/// }
/// ```
/// {@end-tool}
class RouteObserver<R extends Route<dynamic>> extends NavigatorObserver {
final Map<R, Set<RouteAware>> _listeners = <R, Set<RouteAware>>{};
......
packages/flutter/lib/src/widgets/scroll_controller.dart
View file @ a6e90113
......@@ -283,7 +283,7 @@ class ScrollController extends ChangeNotifier {
/// It tracks the most recently updated scroll position and reports it as its
/// `initialScrollOffset`.
///
/// ## Sample code
/// {@tool sample}
///
/// In this example each [PageView] page contains a [ListView] and all three
/// [ListView]'s share a [TrackingScrollController]. The scroll offsets of all
......@@ -308,6 +308,7 @@ class ScrollController extends ChangeNotifier {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// In this example the `_trackingController` would have been created by the
/// stateful widget that built the widget tree.
......
packages/flutter/lib/src/widgets/scroll_view.dart
View file @ a6e90113
......@@ -284,7 +284,7 @@ abstract class ScrollView extends StatelessWidget {
/// To control the initial scroll offset of the scroll view, provide a
/// [controller] with its [ScrollController.initialScrollOffset] property set.
///
/// ## Sample code
/// {@tool sample}
///
/// This sample code shows a scroll view that contains a flexible pinned app
/// bar, a grid, and an infinite list.
......@@ -332,6 +332,7 @@ abstract class ScrollView extends StatelessWidget {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// ## Accessibility
///
......@@ -539,7 +540,7 @@ abstract class BoxScrollView extends ScrollView {
/// extremities to avoid partial obstructions indicated by [MediaQuery]'s
/// padding. To avoid this behavior, override with a zero [padding] property.
///
/// ## Sample code
/// {@tool sample}
///
/// An infinite list of children:
///
......@@ -552,6 +553,7 @@ abstract class BoxScrollView extends ScrollView {
/// },
/// )
/// ```
/// {@end-tool}
///
/// ## Child elements' lifecycle
///
......@@ -648,7 +650,7 @@ abstract class BoxScrollView extends ScrollView {
/// [SliverGrid] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
/// list.
///
/// ### Sample code
/// {@tool sample}
///
/// Here are two brief snippets showing a [ListView] and its equivalent using
/// [CustomScrollView]:
......@@ -665,6 +667,8 @@ abstract class BoxScrollView extends ScrollView {
/// ],
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// ```dart
/// CustomScrollView(
......@@ -686,6 +690,7 @@ abstract class BoxScrollView extends ScrollView {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -836,7 +841,7 @@ class ListView extends BoxScrollView {
/// advance, or all at once when the [ListView] itself is created, it is more
/// efficient to use [new ListView].
///
/// ## Sample code
/// {@tool sample}
///
/// This example shows how to create [ListView] whose [ListTile] list items
/// are separated by [Divider]s.
......@@ -852,6 +857,7 @@ class ListView extends BoxScrollView {
/// },
/// )
/// ```
/// {@end-tool}
///
/// The `addAutomaticKeepAlives` argument corresponds to the
/// [SliverChildBuilderDelegate.addAutomaticKeepAlives] property. The
......@@ -1047,7 +1053,7 @@ class ListView extends BoxScrollView {
/// [SliverList] or [SliverAppBar], can be put in the [CustomScrollView.slivers]
/// list.
///
/// ### Sample code
/// {@tool sample}
///
/// Here are two brief snippets showing a [GridView] and its equivalent using
/// [CustomScrollView]:
......@@ -1068,6 +1074,8 @@ class ListView extends BoxScrollView {
/// ],
/// )
/// ```
/// {@end-tool}
/// {@tool sample}
///
/// ```dart
/// CustomScrollView(
......@@ -1091,6 +1099,7 @@ class ListView extends BoxScrollView {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/sliver.dart
View file @ a6e90113
......@@ -220,7 +220,7 @@ abstract class SliverChildDelegate {
/// delegates where the first has 10 children contributing semantics, then the
/// second delegate should offset its children by 10.
///
/// ## Sample code
/// {@tool sample}
///
/// This sample code shows how to use `semanticIndexOffset` to handle multiple
/// delegates in a single scroll view.
......@@ -251,6 +251,7 @@ abstract class SliverChildDelegate {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// In certain cases, only a subset of child widgets should be annotated
/// with a semantic index. For example, in [new ListView.separated()] the
......@@ -258,7 +259,7 @@ abstract class SliverChildDelegate {
/// providing a `semanticIndexCallback` which returns null for separators
/// indexes and rounds the non-separator indexes down by half.
///
/// ## Sample code
/// {@tool sample}
///
/// This sample code shows how to use `semanticIndexCallback` to handle
/// annotating a subset of child nodes with a semantic index. There is
......@@ -290,6 +291,7 @@ abstract class SliverChildDelegate {
/// ],
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......@@ -677,7 +679,7 @@ class SliverList extends SliverMultiBoxAdaptorWidget {
/// [SliverFixedExtentList] does not need to perform layout on its children to
/// obtain their extent in the main axis.
///
/// ## Sample code
/// {@tool sample}
///
/// This example, which would be inserted into a [CustomScrollView.slivers]
/// list, shows an infinite number of items in varying shades of blue:
......@@ -696,6 +698,7 @@ class SliverList extends SliverMultiBoxAdaptorWidget {
/// ),
/// )
/// ```
/// {@end-tool}
///
/// {@macro flutter.widgets.sliverChildDelegate.lifecycle}
///
......@@ -741,7 +744,7 @@ class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
/// The main axis direction of a grid is the direction in which it scrolls; the
/// cross axis direction is the orthogonal direction.
///
/// ## Sample code
/// {@tool sample}
///
/// This example, which would be inserted into a [CustomScrollView.slivers]
/// list, shows twenty boxes in a pretty teal grid:
......@@ -766,6 +769,7 @@ class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
/// ),
/// )
/// ```
/// {@end-tool}
///
/// {@macro flutter.widgets.sliverChildDelegate.lifecycle}
///
......
packages/flutter/lib/src/widgets/spacer.dart
View file @ a6e90113
......@@ -17,7 +17,7 @@ import 'framework.dart';
/// [Spacer] has taken up all of the additional space, therefore there is none
/// left to redistribute.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Row(
......@@ -31,6 +31,7 @@ import 'framework.dart';
/// ],
/// )
/// ```
/// {@end-tool}
///
/// See also:
///
......
packages/flutter/lib/src/widgets/text.dart
View file @ a6e90113
......@@ -167,7 +167,7 @@ class DefaultTextStyle extends InheritedWidget {
/// behavior is useful, for example, to make the text bold while using the
/// default font family and size.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// Text(
......@@ -177,13 +177,14 @@ class DefaultTextStyle extends InheritedWidget {
/// style: TextStyle(fontWeight: FontWeight.bold),
/// )
/// ```
/// {@end-tool}
///
/// Using the [Text.rich] constructor, the [Text] widget can
/// display a paragraph with differently styled [TextSpan]s. The sample
/// that follows displays "Hello beautiful world" with different styles
/// for each word.
///
/// ## Sample code
/// {@tool sample}
///
/// ```dart
/// const Text.rich(
......@@ -196,6 +197,7 @@ class DefaultTextStyle extends InheritedWidget {
/// ),
/// )
/// ```
/// {@end-tool}
///
/// ## Interactivity
///
......
packages/flutter/lib/src/widgets/transitions.dart
View file @ a6e90113
......@@ -760,7 +760,7 @@ class DefaultTextStyleTransition extends AnimatedWidget {
/// Using this pre-built child is entirely optional, but can improve
/// performance significantly in some cases and is therefore a good practice.
///
/// ## Sample code
/// {@tool sample}
///
/// This code defines a widget called `Spinner` that spins a green square
/// continually. It is built with an [AnimatedBuilder] and makes use of the
......@@ -805,6 +805,7 @@ class DefaultTextStyleTransition extends AnimatedWidget {
/// }
/// }
/// ```
/// {@end-tool}
class AnimatedBuilder extends AnimatedWidget {
/// Creates an animated builder.
///
......
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

HIAST - GitLab