firka/flutter
firka/flutter
5
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

API documentation cleanup (#108500)

Browse Source
This commit is contained in:
Ian Hickson 2022-08-10 15:03:20 -07:00 committed by GitHub
parent c89f1cbb4c
commit 7ded3d91da
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
138 changed files with 2418 additions and 1425 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
dev/bots/analyze.dart
View File

@ -177,7 +177,7 @@ Future<void> run(List<String> arguments) async {
// Analyze the code in `{@tool snippet}` sections in the repo.
print('$clock Snippet code...');
await runCommand(dart,
<String>[path.join(flutterRoot, 'dev', 'bots', 'analyze_snippet_code.dart'), '--verbose'],
<String>['--enable-asserts', path.join(flutterRoot, 'dev', 'bots', 'analyze_snippet_code.dart'), '--verbose'],
workingDirectory: flutterRoot,
);

1276
dev/bots/analyze_snippet_code.dart
View File

File diff suppressed because it is too large Load Diff

23
dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart
View File

@ -8,28 +8,15 @@
library dart.ui;
/// Annotation used by Flutter's Dart compiler to indicate that an
/// [Object.toString] override should not be replaced with a supercall.
///
/// {@tool snippet}
/// A sample if using keepToString to prevent replacement by a supercall.
/// Bla bla bla bla bla bla bla bla bla.
///
/// ```dart
/// class MyStringBuffer {
/// error;
/// error; // error (missing_const_final_var_or_type, always_specify_types)
///
/// StringBuffer _buffer = StringBuffer();
///
/// @keepToString
/// @override
/// String toString() {
/// return _buffer.toString();
/// }
/// StringBuffer _buffer = StringBuffer(); // error (prefer_final_fields, unused_field)
/// }
/// ```
/// {@end-tool}
const Object keepToString = _KeepToString();
class _KeepToString {
const _KeepToString();
class Foo {
const Foo();
}

62
dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart
View File

@ -8,8 +8,8 @@
// Examples can assume:
// bool _visible = true;
// class _Text extends Text {
// const _Text(String text) : super(text);
// const _Text.__(String text) : super(text);
// const _Text(super.text);
// const _Text.__(super.text);
// }
/// A blabla that blabla its blabla blabla blabla.
@ -27,7 +27,7 @@
/// blabla it when it is blabla:
///
/// ```dart
/// new Opacity(
/// new Opacity( // error (unnecessary_new)
/// opacity: _visible ? 1.0 : 0.0,
/// child: const Text('Poor wandering ones!'),
/// )
@ -38,12 +38,12 @@
/// Bla blabla blabla some [Text] when the `_blabla` blabla blabla is true, and
/// blabla it when it is blabla:
///
/// ```dart preamble
/// bool _visible = true;
/// ```dart
/// final GlobalKey globalKey = GlobalKey();
/// ```
///
/// ```dart
/// // continuing from previous example...
/// Widget build(BuildContext context) {
/// return Opacity(
/// key: globalKey,
@ -59,7 +59,7 @@
/// blabla finale blabla:
///
/// ```dart
/// new Opacity(
/// Opacity(
/// opacity: _visible ? 1.0 : 0.0,
/// child: const Text('Poor wandering ones!'),
/// )
@ -92,7 +92,7 @@
/// const variable
///
/// ```dart
/// const text0 = Text('Poor wandering ones!');
/// const Widget text0 = Text('Poor wandering ones!');
/// ```
/// {@end-tool}
///
@ -100,7 +100,7 @@
/// more const variables
///
/// ```dart
/// const text1 = _Text('Poor wandering ones!');
/// const text1 = _Text('Poor wandering ones!'); // error (always_specify_types)
/// ```
/// {@end-tool}
///
@ -108,35 +108,61 @@
/// Snippet with null-safe syntax
///
/// ```dart
/// final String? bar = 'Hello';
/// final int foo = null;
/// final String? bar = 'Hello'; // error (unnecessary_nullable_for_final_variable_declarations, prefer_const_declarations)
/// final int foo = null; // error (invalid_assignment, prefer_const_declarations)
/// ```
/// {@end-tool}
///
/// {@tool snippet}
/// snippet with trailing comma
///
/// ```dart
/// const SizedBox(),
/// ```
/// {@end-tool}
///
/// {@tool snippet}
/// {@tool dartpad}
/// Dartpad with null-safe syntax
///
/// ```dart preamble
/// bool? _visible = true;
/// ```dart
/// final GlobalKey globalKey = GlobalKey();
/// ```
///
/// ```dart
/// // not continuing from previous example...
/// Widget build(BuildContext context) {
/// final String title;
/// return Opacity(
/// key: globalKey,
/// opacity: _visible! ? 1.0 : 0.0,
/// child: Text(title),
/// key: globalKey, // error (undefined_identifier, argument_type_not_assignable)
/// opacity: _visible ? 1.0 : 0.0,
/// child: Text(title), // error (read_potentially_unassigned_final)
/// );
/// }
/// ```
/// {@end-tool}
///
/// ```csv
/// this,is,fine
/// ```
///
/// ```dart
/// import 'dart:io'; // error (unused_import)
/// final Widget p = Placeholder(); // error (undefined_class, undefined_function, avoid_dynamic_calls)
/// ```
///
/// ```dart
/// // (e.g. in a stateful widget)
/// void initState() { // error (must_call_super, annotate_overrides)
/// widget.toString(); // error (undefined_identifier, return_of_invalid_type)
/// }
/// ```
///
/// ```dart
/// // not in a stateful widget
/// void initState() {
/// widget.toString(); // error (undefined_identifier)
/// }
/// ```
///
/// ```
/// error (something about backticks)
/// this must be the last error, since it aborts parsing of this file
/// ```

17
dev/bots/test/analyze-snippet-code-test-input/short_but_still_broken.dart Normal file
View File

@ -0,0 +1,17 @@
// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// This file is used by ../analyze_snippet_code_test.dart, which depends on the
// precise contents (including especially the comments) of this file.
// Examples can assume:
// int x = ''; // error (invalid_assignment)
/// ```dart
/// print(x);
/// ```
/// error: empty dart block
/// ```dart
/// ```

97
dev/bots/test/analyze_snippet_code_test.dart
View File

@ -2,10 +2,43 @@
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// we ignore these so that the format of the strings below matches what package:test prints, to make maintenance easier
// ignore_for_file: avoid_escaping_inner_quotes
// ignore_for_file: use_raw_strings
import 'dart:io';
import 'common.dart';
const List<String> expectedMainErrors = <String>[
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:30:5: Unnecessary new keyword (expression) (unnecessary_new)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:103:5: Specify type annotations (statement) (always_specify_types)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:111:5: Prefer const over final for declarations (top-level declaration) (prefer_const_declarations)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:111:19: Use a non-nullable type for a final variable initialized with a non-nullable value (top-level declaration) (unnecessary_nullable_for_final_variable_declarations)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:5: Prefer const over final for declarations (top-level declaration) (prefer_const_declarations)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:21: A value of type \'Null\' can\'t be assigned to a variable of type \'int\' (top-level declaration) (invalid_assignment)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:134:14: The argument type \'dynamic\' can\'t be assigned to the parameter type \'Key?\' (top-level declaration) (argument_type_not_assignable)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:134:14: Undefined name \'globalKey\' (top-level declaration) (undefined_identifier)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:136:21: The final variable \'title\' can\'t be read because it\'s potentially unassigned at this point (top-level declaration) (read_potentially_unassigned_final)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:147:12: Unused import: \'dart:io\' (self-contained program) (unused_import)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:148:11: Undefined class \'Widget\' (self-contained program) (undefined_class)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:148:22: Avoid method calls or property accesses on a "dynamic" target (self-contained program) (avoid_dynamic_calls)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:148:22: The function \'Placeholder\' isn\'t defined (self-contained program) (undefined_function)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:153:10: Annotate overridden members (stateful widget) (annotate_overrides)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:153:10: This method overrides a method annotated as \'@mustCallSuper\' in \'State\', but doesn\'t invoke the overridden method (stateful widget) (must_call_super)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:161:7: Undefined name \'widget\' (top-level declaration) (undefined_identifier)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:165: Found "```" in code but it did not match RegExp: pattern=^ */// *```dart\$ flags= so something is wrong. Line was: "/// ```"',
'dev/bots/test/analyze-snippet-code-test-input/short_but_still_broken.dart:9:12: A value of type \'String\' can\'t be assigned to a variable of type \'int\' (statement) (invalid_assignment)',
'dev/bots/test/analyze-snippet-code-test-input/short_but_still_broken.dart:17:4: Empty ```dart block in snippet code.',
];
const List<String> expectedUiErrors = <String>[
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:15:7: Prefer typing uninitialized variables and fields (top-level declaration) (prefer_typing_uninitialized_variables)',
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:15:7: Variables must be declared using the keywords \'const\', \'final\', \'var\' or a type name (top-level declaration) (missing_const_final_var_or_type)',
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:17:20: Private field could be final (top-level declaration) (prefer_final_fields)',
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:17:20: The value of the field \'_buffer\' isn\'t used (top-level declaration) (unused_field)',
];
void main() {
// These tests don't run on Windows because the sample analyzer doesn't
// support Windows as a platform, since it is only run on Linux in the
@ -17,55 +50,45 @@ void main() {
test('analyze_snippet_code smoke test', () {
final ProcessResult process = Process.runSync(
'../../bin/cache/dart-sdk/bin/dart',
<String>['analyze_snippet_code.dart', '--no-include-dart-ui', 'test/analyze-snippet-code-test-input'],
<String>[
'--enable-asserts',
'analyze_snippet_code.dart',
'--no-include-dart-ui',
'test/analyze-snippet-code-test-input',
],
);
final List<String> stdoutLines = process.stdout.toString().split('\n');
expect(process.stdout, isEmpty);
final List<String> stderrLines = process.stderr.toString().split('\n');
expect(process.exitCode, isNot(equals(0)));
expect(stderrLines, containsAll(<Object>[
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:138:25: child: Text(title),',
matches(RegExp(r">>> error: The final variable 'title' can't be read because (it is|it's) potentially unassigned at this point \(read_potentially_unassigned_final\)")),
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:30:9: new Opacity(',
'>>> info: Unnecessary new keyword (unnecessary_new)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:62:9: new Opacity(',
'>>> info: Unnecessary new keyword (unnecessary_new)',
"dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:111:9: final String? bar = 'Hello';",
'>>> info: Prefer const over final for declarations (prefer_const_declarations)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:9: final int foo = null;',
'>>> info: Prefer const over final for declarations (prefer_const_declarations)',
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:112:25: final int foo = null;',
">>> error: A value of type 'Null' can't be assigned to a variable of type 'int' (invalid_assignment)",
'dev/bots/test/analyze-snippet-code-test-input/known_broken_documentation.dart:120:24: const SizedBox(),',
'>>> error: Unexpected comma at end of snippet code. (missing_identifier)',
'Found 1 snippet code errors.',
]));
expect(stdoutLines, containsAll(<String>[
'Found 13 snippet code blocks',
'Starting analysis of code snippets.',
]));
expect(stderrLines.length, stderrLines.toSet().length, reason: 'found duplicates in $stderrLines');
expect(stderrLines, <String>[
...expectedMainErrors,
'Found 19 snippet code errors.',
'See the documentation at the top of dev/bots/analyze_snippet_code.dart for details.',
'', // because we end with a newline, split gives us an extra blank line
]);
expect(process.exitCode, 1);
});
test('Analyzes dart:ui code', () {
final ProcessResult process = Process.runSync(
'../../bin/cache/dart-sdk/bin/dart',
<String>[
'--enable-asserts',
'analyze_snippet_code.dart',
'--dart-ui-location=test/analyze-snippet-code-test-dart-ui',
'test/analyze-snippet-code-test-input',
],
);
final List<String> stdoutLines = process.stdout.toString().split('\n');
expect(process.stdout, isEmpty);
final List<String> stderrLines = process.stderr.toString().split('\n');
expect(process.exitCode, isNot(equals(0)));
expect(stderrLines, containsAll(<String>[
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:19:11: error;',
">>> error: Variables must be declared using the keywords 'const', 'final', 'var' or a type name (missing_const_final_var_or_type)",
'dev/bots/test/analyze-snippet-code-test-dart-ui/ui.dart:23:11: @keepToString',
">>> error: Undefined name 'keepToString' used as an annotation (undefined_annotation)",
]));
expect(stdoutLines, containsAll(<String>[
// There is one snippet code section in the test's dummy dart:ui code.
'Found 14 snippet code blocks',
'Starting analysis of code snippets.',
]));
expect(stderrLines.length, stderrLines.toSet().length, reason: 'found duplicates in $stderrLines');
expect(stderrLines, <String>[
...expectedUiErrors,
...expectedMainErrors,
'Found 23 snippet code errors.',
'See the documentation at the top of dev/bots/analyze_snippet_code.dart for details.',
'', // because we end with a newline, split gives us an extra blank line
]);
expect(process.exitCode, 1);
});
}

75
examples/api/lib/widgets/sliver/sliver_opacity.1.dart Normal file
View File

@ -0,0 +1,75 @@
// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Flutter code sample for SliverOpacity
import 'package:flutter/material.dart';
void main() => runApp(const MyApp());
class MyApp extends StatelessWidget {
const MyApp({super.key});
static const String _title = 'Flutter Code Sample';
@override
Widget build(BuildContext context) {
return const MaterialApp(
title: _title,
home: MyStatefulWidget(),
);
}
}
class MyStatefulWidget extends StatefulWidget {
const MyStatefulWidget({super.key});
@override
State<MyStatefulWidget> createState() => _MyStatefulWidgetState();
}
class _MyStatefulWidgetState extends State<MyStatefulWidget> {
static const List<Widget> _listItems = <Widget>[
ListTile(title: Text('Now you see me,')),
ListTile(title: Text("Now you don't!")),
];
bool _visible = true;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('SliverOpacity demo'),
),
body: CustomScrollView(
slivers: <Widget>[
const SliverToBoxAdapter(
child: ListTile(title: Text('Press on the button to toggle the list visibilty.')),
),
const SliverToBoxAdapter(
child: ListTile(title: Text('Before the list...')),
),
SliverOpacity(
opacity: _visible ? 1.0 : 0.0,
sliver: SliverList(
delegate: SliverChildListDelegate(_listItems),
),
),
const SliverToBoxAdapter(
child: ListTile(title: Text('Before the list...')),
),
],
),
floatingActionButton: FloatingActionButton(
child: const Icon(Icons.disabled_visible),
onPressed: () {
setState(() {
_visible = !_visible;
});
},
),
);
}
}

23
examples/api/test/widgets/sliver/sliver_opacity.1_test.dart Normal file
View File

@ -0,0 +1,23 @@
// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'package:flutter/material.dart';
import 'package:flutter_api_samples/widgets/sliver/sliver_opacity.1.dart'
as example;
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('SliverOpacity example', (WidgetTester tester) async {
await tester.pumpWidget(
const example.MyApp(),
);
final Finder button = find.byType(FloatingActionButton);
final Finder opacity = find.byType(SliverOpacity);
expect((tester.widget(opacity) as SliverOpacity).opacity, 1.0);
await tester.tap(button);
await tester.pump();
expect((tester.widget(opacity) as SliverOpacity).opacity, 0.0);
});
}

1
packages/flutter/lib/cupertino.dart
View File

@ -31,6 +31,7 @@ export 'src/cupertino/constants.dart';
export 'src/cupertino/context_menu.dart';
export 'src/cupertino/context_menu_action.dart';
export 'src/cupertino/date_picker.dart';
export 'src/cupertino/debug.dart';
export 'src/cupertino/desktop_text_selection.dart';
export 'src/cupertino/dialog.dart';
export 'src/cupertino/form_row.dart';

6
packages/flutter/lib/src/animation/animation.dart
View File

@ -173,7 +173,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// controller goes from 0.0 to 1.0:
///
/// ```dart
/// Animation<Alignment> _alignment1 = _controller.drive(
/// Animation<Alignment> alignment1 = _controller.drive(
/// AlignmentTween(
/// begin: Alignment.topLeft,
/// end: Alignment.topRight,
@ -208,7 +208,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// values that depend on other variables:
///
/// ```dart
/// Animation<Alignment> _alignment3 = _controller
/// Animation<Alignment> alignment3 = _controller
/// .drive(CurveTween(curve: Curves.easeIn))
/// .drive(AlignmentTween(
/// begin: Alignment.topLeft,
@ -226,7 +226,7 @@ abstract class Animation<T> extends Listenable implements ValueListenable<T> {
/// of red.
///
/// ```dart
/// Animation<Color> _offset1 = Animation<double>.fromValueListenable(_scrollPosition)
/// Animation<Color> color = Animation<double>.fromValueListenable(_scrollPosition)
/// .drive(Animatable<Color>.fromCallback((double value) {
/// return Color.fromRGBO(value.round() % 255, 0, 0, 1);
/// }));

3
packages/flutter/lib/src/cupertino/debug.dart
View File

@ -6,6 +6,9 @@ import 'package:flutter/widgets.dart';
import 'localizations.dart';
// Examples can assume:
// late BuildContext context;
/// Asserts that the given context has a [Localizations] ancestor that contains
/// a [CupertinoLocalizations] delegate.
///

3
packages/flutter/lib/src/cupertino/localizations.dart
View File

@ -7,6 +7,9 @@ import 'package:flutter/widgets.dart';
import 'debug.dart';
// Examples can assume:
// late BuildContext context;
/// Determines the order of the columns inside [CupertinoDatePicker] in
/// time and date time mode.
enum DatePickerDateTimeOrder {

3
packages/flutter/lib/src/cupertino/switch.dart
View File

@ -2,6 +2,9 @@
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Examples can assume:
// bool _giveVerse = false;
import 'dart:ui' show lerpDouble;
import 'package:flutter/foundation.dart';

23
packages/flutter/lib/src/foundation/assertions.dart
View File

@ -20,6 +20,8 @@ export 'stack_frame.dart' show StackFrame;
// late bool draconisAmulet;
// late Diagnosticable draconis;
// void methodThatMayThrow() { }
// class Trace implements StackTrace { late StackTrace vmTrace; }
// class Chain implements StackTrace { Trace toTrace() => Trace(); }
/// Signature for [FlutterError.onError] handler.
typedef FlutterExceptionHandler = void Function(FlutterErrorDetails details);
@ -933,24 +935,27 @@ class FlutterError extends Error with DiagnosticableTreeMixin implements Asserti
/// Called by the Flutter framework before attempting to parse a [StackTrace].
///
/// Some [StackTrace] implementations have a different toString format from
/// what the framework expects, like ones from package:stack_trace. To make
/// Some [StackTrace] implementations have a different [toString] format from
/// what the framework expects, like ones from `package:stack_trace`. To make
/// sure we can still parse and filter mangled [StackTrace]s, the framework
/// first calls this function to demangle them.
///
/// This should be set in any environment that could propagate a non-standard
/// This should be set in any environment that could propagate an unusual
/// stack trace to the framework. Otherwise, the default behavior is to assume
/// all stack traces are in a standard format.
/// all stack traces are in a format usually generated by Dart.
///
/// The following example demangles package:stack_trace traces by converting
/// them into vm traces, which the framework is able to parse:
/// The following example demangles `package:stack_trace` traces by converting
/// them into VM traces, which the framework is able to parse:
///
/// ```dart
/// FlutterError.demangleStackTrace = (StackTrace stackTrace) {
/// if (stack is stack_trace.Trace)
/// FlutterError.demangleStackTrace = (StackTrace stack) {
/// // Trace and Chain are classes in package:stack_trace
/// if (stack is Trace) {
/// return stack.vmTrace;
/// if (stack is stack_trace.Chain)
/// }
/// if (stack is Chain) {
/// return stack.toTrace().vmTrace;
/// }
/// return stack;
/// };
/// ```

3
packages/flutter/lib/src/foundation/basic_types.dart
View File

@ -115,9 +115,10 @@ class CachingIterable<E> extends IterableBase<E> {
///
/// ```dart
/// Iterable<int> range(int start, int end) sync* {
/// for (int index = start; index <= end; index += 1)
/// for (int index = start; index <= end; index += 1) {
/// yield index;
/// }
/// }
///
/// Iterable<int> i = CachingIterable<int>(range(1, 5).iterator);
/// print(i.length); // walks the list

1
packages/flutter/lib/src/foundation/binding.dart
View File

@ -119,6 +119,7 @@ typedef ServiceExtensionCallback = Future<Map<String, dynamic>> Function(Map<Str
/// class.
///
/// ```dart
/// // continuing from previous example...
/// class FooLibraryBinding extends BindingBase with BarBinding, FooBinding {
/// static FooBinding ensureInitialized() {
/// if (FooBinding._instance == null) {

54
packages/flutter/lib/src/foundation/diagnostics.dart
View File

@ -16,6 +16,32 @@ import 'object.dart';
// late int rows, columns;
// late String _name;
// late bool inherit;
// abstract class ExampleSuperclass with Diagnosticable { }
// late String message;
// late double stepWidth;
// late double scale;
// late double hitTestExtent;
// late double paintExtent;
// late double maxWidth;
// late double progress;
// late int maxLines;
// late Duration duration;
// late int depth;
// late bool primary;
// late bool isCurrent;
// late bool keepAlive;
// late bool obscureText;
// late TextAlign textAlign;
// late ImageRepeat repeat;
// late Widget widget;
// late List<BoxShadow> boxShadow;
// late Size size;
// late bool hasSize;
// late Matrix4 transform;
// late Color color;
// late Map<Listenable, VoidCallback>? handles;
// late DiagnosticsTreeStyle style;
// late IconData icon;
/// The various priority levels used to filter which diagnostics are shown and
/// omitted.
@ -383,7 +409,7 @@ class TextTreeConfiguration {
/// Default text tree configuration.
///
/// Example:
/// ```
///
/// <root_name>: <root_description>
/// │ <property1>
/// │ <property2>
@ -406,7 +432,6 @@ class TextTreeConfiguration {
/// <property2>
/// ...
/// <propertyN>
/// ```
///
/// See also:
///
@ -425,7 +450,7 @@ final TextTreeConfiguration sparseTextConfiguration = TextTreeConfiguration(
/// parent to children are dashed.
///
/// Example:
/// ```
///
/// <root_name>: <root_description>
/// │ <property1>
/// │ <property2>
@ -460,7 +485,6 @@ final TextTreeConfiguration sparseTextConfiguration = TextTreeConfiguration(
/// <property2>
/// ...
/// <propertyN>
/// ```
///
/// See also:
///
@ -480,11 +504,10 @@ final TextTreeConfiguration dashedTextConfiguration = TextTreeConfiguration(
/// Dense text tree configuration that minimizes horizontal whitespace.
///
/// Example:
/// ```
///
/// <root_name>: <root_description>(<property1>; <property2> <propertyN>)
/// ├<child_name>: <child_description>(<property1>, <property2>, <propertyN>)
/// └<child_name>: <child_description>(<property1>, <property2>, <propertyN>)
/// ```
///
/// See also:
///
@ -511,7 +534,7 @@ final TextTreeConfiguration denseTextConfiguration = TextTreeConfiguration(
/// contents of a node.
///
/// Example:
/// ```
///
/// <parent_node>
/// ╞═╦══ <name> ═══
/// │ ║ <description>:
@ -523,7 +546,6 @@ final TextTreeConfiguration denseTextConfiguration = TextTreeConfiguration(
/// ║ <body>
/// ║ ...
/// ╚═══════════
/// ```
///
/// See also:
///
@ -563,7 +585,7 @@ final TextTreeConfiguration transitionTextConfiguration = TextTreeConfiguration(
/// Used to draw a decorative box around detailed descriptions of an exception.
///
/// Example:
/// ```
///
/// ══╡ <name>: <description> ╞═════════════════════════════════════
/// <body>
/// ...
@ -593,7 +615,6 @@ final TextTreeConfiguration transitionTextConfiguration = TextTreeConfiguration(
/// ╎
/// └╌<dashed_child_name>: <child_description>'
/// ════════════════════════════════════════════════════════════════
/// ```
///
/// See also:
///
@ -626,7 +647,7 @@ final TextTreeConfiguration errorTextConfiguration = TextTreeConfiguration(
/// draws line art would be visually distracting for those cases.
///
/// Example:
/// ```
///
/// <parent_node>
/// <name>: <description>:
/// <properties>
@ -634,7 +655,6 @@ final TextTreeConfiguration errorTextConfiguration = TextTreeConfiguration(
/// <name>: <description>:
/// <properties>
/// <children>
/// ```
///
/// See also:
///
@ -660,7 +680,7 @@ final TextTreeConfiguration whitespaceTextConfiguration = TextTreeConfiguration(
/// children as in the case of a [DiagnosticsStackTrace].
///
/// Example:
/// ```
///
/// <parent_node>
/// <name>: <description>:
/// <properties>
@ -668,7 +688,6 @@ final TextTreeConfiguration whitespaceTextConfiguration = TextTreeConfiguration(
/// <name>: <description>:
/// <properties>
/// <children>
/// ```
///
/// See also:
///
@ -716,10 +735,9 @@ final TextTreeConfiguration singleLineTextConfiguration = TextTreeConfiguration(
/// line omitting the children.
///
/// Example:
/// ```
///
/// <name>:
/// <description>(<property1>, <property2>, ..., <propertyN>)
/// ```
///
/// See also:
///
@ -3162,7 +3180,7 @@ mixin Diagnosticable {
/// Shows using `showSeparator` to get output `child(3, 4) is null` which
/// is more polished than `child(3, 4): is null`.
/// ```dart
/// DiagnosticsProperty<IconData>('icon', icon, ifNull: '<empty>', showName: false)).toString()
/// DiagnosticsProperty<IconData>('icon', icon, ifNull: '<empty>', showName: false).toString()
/// ```
/// Shows using `showName` to omit the property name as in this context the
/// property name does not add useful information.
@ -3238,7 +3256,7 @@ mixin Diagnosticable {
/// properties.add(DoubleProperty('hitTestExtent', hitTestExtent, defaultValue: paintExtent));
///
/// // maxWidth of double.infinity indicates the width is unconstrained and
/// // so maxWidth has no impact.,
/// // so maxWidth has no impact.
/// properties.add(DoubleProperty('maxWidth', maxWidth, defaultValue: double.infinity));
///
/// // Progress is a value between 0 and 1 or null. Showing it as a

7
packages/flutter/lib/src/gestures/events.dart
View File

@ -184,9 +184,10 @@ int nthStylusButton(int number) => (kPrimaryStylusButton << (number - 1)) & kMax
/// Example:
///
/// ```dart
/// assert(rightmostButton(0x1) == 0x1);
/// assert(rightmostButton(0x11) == 0x1);
/// assert(rightmostButton(0) == 0);
/// assert(smallestButton(0x01) == 0x01);
/// assert(smallestButton(0x11) == 0x01);
/// assert(smallestButton(0x10) == 0x10);
/// assert(smallestButton(0) == 0);
/// ```
///
/// See also:

2
packages/flutter/lib/src/gestures/force_press.dart
View File

@ -204,7 +204,7 @@ class ForcePressGestureRecognizer extends OneSequenceGestureRecognizer {
/// value:
///
/// ```dart
/// static double interpolateWithEasing(double min, double max, double t) {
/// double interpolateWithEasing(double min, double max, double t) {
/// final double lerp = (t - min) / (max - min);
/// return Curves.easeIn.transform(lerp);
/// }

19
packages/flutter/lib/src/material/about.dart
View File

@ -30,6 +30,9 @@ import 'text_button.dart';
import 'text_theme.dart';
import 'theme.dart';
// Examples can assume:
// BuildContext context;
/// A [ListTile] that shows an about box.
///
/// This widget is often added to an app's [Drawer]. When tapped it shows
@ -1062,14 +1065,14 @@ class _MasterDetailFlow extends StatefulWidget {
@override
_MasterDetailFlowState createState() => _MasterDetailFlowState();
/// The master detail flow proxy from the closest instance of this class that encloses the given
/// context.
///
/// Typical usage is as follows:
///
/// ```dart
/// _MasterDetailFlow.of(context).openDetailPage(arguments);
/// ```
// The master detail flow proxy from the closest instance of this class that encloses the given
// context.
//
// Typical usage is as follows:
//
// ```dart
// _MasterDetailFlow.of(context).openDetailPage(arguments);
// ```
static _MasterDetailFlowProxy? of(BuildContext context) {
_PageOpener? pageOpener = context.findAncestorStateOfType<_MasterDetailScaffoldState>();
pageOpener ??= context.findAncestorStateOfType<_MasterDetailFlowState>();

66
packages/flutter/lib/src/material/app.dart
View File

@ -19,6 +19,10 @@ import 'scrollbar.dart';
import 'theme.dart';
import 'tooltip.dart';
// Examples can assume:
// typedef GlobalWidgetsLocalizations = DefaultWidgetsLocalizations;
// typedef GlobalMaterialLocalizations = DefaultMaterialLocalizations;
/// [MaterialApp] uses this [TextStyle] as its [DefaultTextStyle] to encourage
/// developers to be intentional about their [DefaultTextStyle].
///
@ -171,7 +175,7 @@ enum ThemeMode {
/// a [Material] widget that defines its default text style.
///
/// ```dart
/// MaterialApp(
/// const MaterialApp(
/// title: 'Material App',
/// home: Scaffold(
/// body: Center(
@ -513,16 +517,19 @@ class MaterialApp extends StatefulWidget {
/// and list the [supportedLocales] that the application can handle.
///
/// ```dart
/// import 'package:flutter_localizations/flutter_localizations.dart';
/// MaterialApp(
/// localizationsDelegates: [
/// // ... app-specific localization delegate[s] here
/// // The GlobalMaterialLocalizations and GlobalWidgetsLocalizations
/// // classes require the following import:
/// // import 'package:flutter_localizations/flutter_localizations.dart';
///
/// const MaterialApp(
/// localizationsDelegates: <LocalizationsDelegate<Object>>[
/// // ... app-specific localization delegate(s) here
/// GlobalMaterialLocalizations.delegate,
/// GlobalWidgetsLocalizations.delegate,
/// ],
/// supportedLocales: [
/// const Locale('en', 'US'), // English
/// const Locale('he', 'IL'), // Hebrew
/// supportedLocales: <Locale>[
/// Locale('en', 'US'), // English
/// Locale('he', 'IL'), // Hebrew
/// // ... other locales the app supports
/// ],
/// // ...
@ -542,33 +549,39 @@ class MaterialApp extends StatefulWidget {
/// [LocalizationsDelegate<MaterialLocalizations>] whose load methods return
/// custom versions of [WidgetsLocalizations] or [MaterialLocalizations].
///
/// For example: to add support to [MaterialLocalizations] for a
/// locale it doesn't already support, say `const Locale('foo', 'BR')`,
/// one could just extend [DefaultMaterialLocalizations]:
/// For example: to add support to [MaterialLocalizations] for a locale it
/// doesn't already support, say `const Locale('foo', 'BR')`, one first
/// creates a subclass of [MaterialLocalizations] that provides the
/// translations:
///
/// ```dart
/// class FooLocalizations extends DefaultMaterialLocalizations {
/// FooLocalizations(Locale locale) : super(locale);
/// class FooLocalizations extends MaterialLocalizations {
/// FooLocalizations();
/// @override
/// String get okButtonLabel {
/// if (locale == const Locale('foo', 'BR'))
/// return 'foo';
/// return super.okButtonLabel;
/// String get okButtonLabel => 'foo';
/// // ...
/// // lots of other getters and methods to override!
/// }
/// }
///
/// ```
///
/// A `FooLocalizationsDelegate` is essentially just a method that constructs
/// a `FooLocalizations` object. We return a [SynchronousFuture] here because
/// no asynchronous work takes place upon "loading" the localizations object.
/// One must then create a [LocalizationsDelegate] subclass that can provide
/// an instance of the [MaterialLocalizations] subclass. In this case, this is
/// essentially just a method that constructs a `FooLocalizations` object. A
/// [SynchronousFuture] is used here because no asynchronous work takes place
/// upon "loading" the localizations object.
///
/// ```dart
/// // continuing from previous example...
/// class FooLocalizationsDelegate extends LocalizationsDelegate<MaterialLocalizations> {
/// const FooLocalizationsDelegate();
/// @override
/// bool isSupported(Locale locale) {
/// return locale == const Locale('foo', 'BR');
/// }
/// @override
/// Future<FooLocalizations> load(Locale locale) {
/// return SynchronousFuture(FooLocalizations(locale));
/// assert(locale == const Locale('foo', 'BR'));
/// return SynchronousFuture<FooLocalizations>(FooLocalizations());
/// }
/// @override
/// bool shouldReload(FooLocalizationsDelegate old) => false;
@ -582,9 +595,10 @@ class MaterialApp extends StatefulWidget {
/// [localizationsDelegates] list.
///
/// ```dart
/// MaterialApp(
/// localizationsDelegates: [
/// const FooLocalizationsDelegate(),
/// // continuing from previous example...
/// const MaterialApp(
/// localizationsDelegates: <LocalizationsDelegate<Object>>[
/// FooLocalizationsDelegate(),
/// ],
/// // ...
/// )

10
packages/flutter/lib/src/material/app_bar.dart
View File

@ -25,6 +25,10 @@ import 'tabs.dart';
import 'text_theme.dart';
import 'theme.dart';
// Examples can assume:
// late String _logoAsset;
// double _myToolbarHeight = 250.0;
const double _kLeadingWidth = kToolbarHeight; // So the leading button is square.
const double _kMaxTitleTextScaleFactor = 1.34; // TODO(perc): Add link to Material spec when available, https://github.com/flutter/flutter/issues/58769.
@ -319,10 +323,10 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
/// home: Scaffold(
/// appBar: AppBar(
/// title: SizedBox(
/// height: toolbarHeight,
/// child: Image.asset(logoAsset),
/// height: _myToolbarHeight,
/// child: Image.asset(_logoAsset),
/// ),
/// toolbarHeight: toolbarHeight,
/// toolbarHeight: _myToolbarHeight,
/// ),
/// ),
/// )

12
packages/flutter/lib/src/material/banner.dart
View File

@ -10,6 +10,9 @@ import 'material.dart';
import 'scaffold.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
const Duration _materialBannerTransitionDuration = Duration(milliseconds: 250);
const Curve _materialBannerHeightCurve = Curves.fastOutSlowIn;
@ -24,9 +27,14 @@ const Curve _materialBannerHeightCurve = Curves.fastOutSlowIn;
///
/// ```dart
/// ScaffoldMessenger.of(context).showMaterialBanner(
/// MaterialBanner( ... )
/// const MaterialBanner(
/// content: Text('Message...'),
/// actions: <Widget>[
/// // ...
/// ],
/// )
/// ).closed.then((MaterialBannerClosedReason reason) {
/// ...
/// // ...
/// });
/// ```
enum MaterialBannerClosedReason {

3
packages/flutter/lib/src/material/banner_theme.dart
View File

@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the visual properties of [MaterialBanner] widgets.
///
/// Descendant widgets obtain the current [MaterialBannerThemeData] object using

3
packages/flutter/lib/src/material/bottom_navigation_bar_theme.dart
View File

@ -11,6 +11,9 @@ import 'bottom_navigation_bar.dart';
import 'material_state.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [BottomNavigationBar]
/// widgets.
///

3
packages/flutter/lib/src/material/button_bar_theme.dart
View File

@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
import 'button_theme.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the visual properties of [ButtonBar] widgets.
///
/// Used by [ButtonBarTheme] to control the visual properties of [ButtonBar]

34
packages/flutter/lib/src/material/button_style.dart
View File

@ -12,6 +12,10 @@ import 'ink_well.dart';
import 'material_state.dart';
import 'theme_data.dart';
// Examples can assume:
// late BuildContext context;
// typedef MyAppHome = Placeholder;
/// The visual properties that most buttons have in common.
///
/// Buttons and their themes have a ButtonStyle property which defines the visual
@ -37,13 +41,18 @@ import 'theme_data.dart';
/// style: ButtonStyle(
/// backgroundColor: MaterialStateProperty.resolveWith<Color?>(
/// (Set<MaterialState> states) {
/// if (states.contains(MaterialState.pressed))
/// if (states.contains(MaterialState.pressed)) {
/// return Theme.of(context).colorScheme.primary.withOpacity(0.5);
/// }
/// return null; // Use the component's default.
/// },
/// ),
/// ),
/// )
/// child: const Text('Fly me to the moon'),
/// onPressed: () {
/// // ...
/// },
/// ),
/// ```
///
/// In this case the background color for all other button states would fallback
@ -52,10 +61,14 @@ import 'theme_data.dart';
///
/// ```dart
/// ElevatedButton(
/// style: ButtonStyle(
/// style: const ButtonStyle(
/// backgroundColor: MaterialStatePropertyAll<Color>(Colors.green),
/// ),
/// )
/// child: const Text('Let me play among the stars'),
/// onPressed: () {
/// // ...
/// },
/// ),
/// ```
///
/// Configuring a ButtonStyle directly makes it possible to very
@ -76,11 +89,16 @@ import 'theme_data.dart';
/// ```dart
/// TextButton(
/// style: TextButton.styleFrom(foregroundColor: Colors.green),
/// )
/// child: const Text('Let me see what spring is like'),
/// onPressed: () {
/// // ...
/// },
/// ),
/// ```
///
/// To configure all of the application's text buttons in the same
/// way, specify the overall theme's `textButtonTheme`:
///
/// ```dart
/// MaterialApp(
/// theme: ThemeData(
@ -88,8 +106,8 @@ import 'theme_data.dart';
/// style: TextButton.styleFrom(foregroundColor: Colors.green),
/// ),
/// ),
/// home: MyAppHome(),
/// )
/// home: const MyAppHome(),
/// ),
/// ```
///
/// ## Material 3 button types
@ -285,7 +303,7 @@ class ButtonStyle with Diagnosticable {
/// splashFactory: NoSplash.splashFactory,
/// ),
/// onPressed: () { },
/// child: Text('No Splash'),
/// child: const Text('No Splash'),
/// )
/// ```
final InteractiveInkFeatureFactory? splashFactory;

12
packages/flutter/lib/src/material/button_theme.dart
View File

@ -13,6 +13,9 @@ import 'material_state.dart';
import 'theme.dart';
import 'theme_data.dart' show MaterialTapTargetSize;
// Examples can assume:
// late BuildContext context;
/// Used with [ButtonTheme] and [ButtonThemeData] to define a button's base
/// colors, and the defaults for the button's minimum size, internal padding,
/// and shape.
@ -232,14 +235,7 @@ class ButtonThemeData with Diagnosticable {
final ButtonBarLayoutBehavior layoutBehavior;
/// Simply a convenience that returns [minWidth] and [height] as a
/// [BoxConstraints] object:
///
/// ```dart
/// return BoxConstraints(
/// minWidth: minWidth,
/// minHeight: height,
/// );
/// ```
/// [BoxConstraints] object.
BoxConstraints get constraints {
return BoxConstraints(
minWidth: minWidth,

7
packages/flutter/lib/src/material/calendar_date_picker.dart
View File

@ -906,19 +906,18 @@ class _DayPickerState extends State<_DayPicker> {
///
/// Examples:
///
/// ```
/// ┌ Sunday is the first day of week in the US (en_US)
/// |
/// S M T W T F S <-- the returned list contains these widgets
/// S M T W T F S ← the returned list contains these widgets
/// _ _ _ _ _ 1 2
/// 3 4 5 6 7 8 9
///
/// ┌ But it's Monday in the UK (en_GB)
/// |
/// M T W T F S S <-- the returned list contains these widgets
/// M T W T F S S ← the returned list contains these widgets
/// _ _ _ _ 1 2 3
/// 4 5 6 7 8 9 10
/// ```
///
List<Widget> _dayHeaders(TextStyle? headerStyle, MaterialLocalizations localizations) {
final List<Widget> result = <Widget>[];
for (int i = localizations.firstDayOfWeekIndex; true; i = (i + 1) % 7) {

4
packages/flutter/lib/src/material/checkbox.dart
View File

@ -12,6 +12,10 @@ import 'theme.dart';
import 'theme_data.dart';
import 'toggleable.dart';
// Examples can assume:
// bool _throwShotAway = false;
// late StateSetter setState;
/// A Material Design checkbox.
///
/// The checkbox itself does not maintain any state. Instead, when the state of

2
packages/flutter/lib/src/material/checkbox_list_tile.dart
View File

@ -13,7 +13,7 @@ import 'theme.dart';
import 'theme_data.dart';
// Examples can assume:
// bool? _throwShotAway = false;
// late bool? _throwShotAway;
// void setState(VoidCallback fn) { }
/// A [ListTile] with a [Checkbox]. In other words, a checkbox with a label.

3
packages/flutter/lib/src/material/checkbox_theme.dart
View File

@ -12,6 +12,9 @@ import 'material_state.dart';
import 'theme.dart';
import 'theme_data.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [Checkbox] widgets.
///
/// Descendant widgets obtain the current [CheckboxThemeData] object using

21
packages/flutter/lib/src/material/data_table.dart
View File

@ -21,6 +21,11 @@ import 'material_state.dart';
import 'theme.dart';
import 'tooltip.dart';
// Examples can assume:
// late BuildContext context;
// late List<DataColumn> _columns;
// late List<DataRow> _rows;
/// Signature for [DataColumn.onSort] callback.
typedef DataColumnSortCallback = void Function(int columnIndex, bool ascending);
@ -183,10 +188,14 @@ class DataRow {
/// ```dart
/// DataRow(
/// color: MaterialStateProperty.resolveWith<Color?>((Set<MaterialState> states) {
/// if (states.contains(MaterialState.selected))
/// if (states.contains(MaterialState.selected)) {
/// return Theme.of(context).colorScheme.primary.withOpacity(0.08);
/// }
/// return null; // Use the default value.
/// }),
/// cells: const <DataCell>[
/// // ...
/// ],
/// )
/// ```
///
@ -474,10 +483,13 @@ class DataTable extends StatelessWidget {
/// ```dart
/// DataTable(
/// dataRowColor: MaterialStateProperty.resolveWith<Color?>((Set<MaterialState> states) {
/// if (states.contains(MaterialState.selected))
/// if (states.contains(MaterialState.selected)) {
/// return Theme.of(context).colorScheme.primary.withOpacity(0.08);
/// }
/// return null; // Use the default value.
/// }),
/// columns: _columns,
/// rows: _rows,
/// )
/// ```
///
@ -521,9 +533,12 @@ class DataTable extends StatelessWidget {
/// {@template flutter.material.DataTable.headingRowColor}
/// ```dart
/// DataTable(
/// columns: _columns,
/// rows: _rows,
/// headingRowColor: MaterialStateProperty.resolveWith<Color?>((Set<MaterialState> states) {
/// if (states.contains(MaterialState.hovered))
/// if (states.contains(MaterialState.hovered)) {
/// return Theme.of(context).colorScheme.primary.withOpacity(0.08);
/// }
/// return null; // Use the default value.
/// }),
/// )

3
packages/flutter/lib/src/material/data_table_theme.dart
View File

@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
import 'material_state.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [DataTable]
/// widgets.
///

18
packages/flutter/lib/src/material/date.dart
View File

@ -47,10 +47,11 @@ class DateUtils {
/// Determines the number of months between two [DateTime] objects.
///
/// For example:
/// ```
/// DateTime date1 = DateTime(year: 2019, month: 6, day: 15);
/// DateTime date2 = DateTime(year: 2020, month: 1, day: 15);
/// int delta = monthDelta(date1, date2);
///
/// ```dart
/// DateTime date1 = DateTime(2019, 6, 15);
/// DateTime date2 = DateTime(2020, 1, 15);
/// int delta = DateUtils.monthDelta(date1, date2);
/// ```
///
/// The value for `delta` would be `7`.
@ -62,8 +63,9 @@ class DateUtils {
/// of months and the day set to 1 and time set to midnight.
///
/// For example:
/// ```
/// DateTime date = DateTime(year: 2019, month: 1, day: 15);
///
/// ```dart
/// DateTime date = DateTime(2019, 1, 15);
/// DateTime futureDate = DateUtils.addMonthsToMonthDate(date, 3);
/// ```
///
@ -85,10 +87,8 @@ class DateUtils {
/// For example, September 1, 2017 falls on a Friday, which in the calendar
/// localized for United States English appears as:
///
/// ```
/// S M T W T F S
/// _ _ _ _ _ 1 2
/// ```
///
/// The offset for the first day of the months is the number of leading blanks
/// in the calendar, i.e. 5.
@ -96,10 +96,8 @@ class DateUtils {
/// The same date localized for the Russian calendar has a different offset,
/// because the first day of week is Monday rather than Sunday:
///
/// ```
/// M T W T F S S
/// _ _ _ _ 1 2 3
/// ```
///
/// So the offset is 4, rather than 5.
///

7
packages/flutter/lib/src/material/date_picker.dart
View File

@ -1954,19 +1954,18 @@ class _DayHeaders extends StatelessWidget {
///
/// Examples:
///
/// ```
/// ┌ Sunday is the first day of week in the US (en_US)
/// |
/// S M T W T F S <-- the returned list contains these widgets
/// S M T W T F S ← the returned list contains these widgets
/// _ _ _ _ _ 1 2
/// 3 4 5 6 7 8 9
///
/// ┌ But it's Monday in the UK (en_GB)
/// |
/// M T W T F S S <-- the returned list contains these widgets
/// M T W T F S S ← the returned list contains these widgets
/// _ _ _ _ 1 2 3
/// 4 5 6 7 8 9 10
/// ```
///
List<Widget> _getDayHeaders(TextStyle headerStyle, MaterialLocalizations localizations) {
final List<Widget> result = <Widget>[];
for (int i = localizations.firstDayOfWeekIndex; true; i = (i + 1) % 7) {

3
packages/flutter/lib/src/material/debug.dart
View File

@ -8,6 +8,9 @@ import 'material.dart';
import 'material_localizations.dart';
import 'scaffold.dart' show Scaffold, ScaffoldMessenger;
// Examples can assume:
// late BuildContext context;
/// Asserts that the given context has a [Material] ancestor.
///
/// Used by many Material Design widgets to make sure that they are

3
packages/flutter/lib/src/material/divider_theme.dart
View File

@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the visual properties of [Divider], [VerticalDivider], dividers
/// between [ListTile]s, and dividers between rows in [DataTable]s.
///

7
packages/flutter/lib/src/material/drawer.dart
View File

@ -14,6 +14,9 @@ import 'material.dart';
import 'material_localizations.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// The possible alignments of a [Drawer].
enum DrawerAlignment {
/// Denotes that the [Drawer] is at the start side of the [Scaffold].
@ -117,8 +120,8 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246);
///
/// ```dart
/// ListTile(
/// leading: Icon(Icons.change_history),
/// title: Text('Change history'),
/// leading: const Icon(Icons.change_history),
/// title: const Text('Change history'),
/// onTap: () {
/// // change app state...
/// Navigator.pop(context); // close the drawer

3
packages/flutter/lib/src/material/drawer_theme.dart
View File

@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [Drawer] widgets.
///
/// Descendant widgets obtain the current [DrawerThemeData] object

12
packages/flutter/lib/src/material/elevated_button.dart
View File

@ -130,7 +130,11 @@ class ElevatedButton extends ButtonStyleButton {
/// ```dart
/// ElevatedButton(
/// style: ElevatedButton.styleFrom(foregroundColor: Colors.green),
/// )
/// onPressed: () {
/// // ...
/// },
/// child: const Text('Jump'),
/// ),
/// ```
///
/// And to change the fill color:
@ -138,7 +142,11 @@ class ElevatedButton extends ButtonStyleButton {
/// ```dart
/// ElevatedButton(
/// style: ElevatedButton.styleFrom(backgroundColor: Colors.green),
/// )
/// onPressed: () {
/// // ...
/// },
/// child: const Text('Meow'),
/// ),
/// ```
///
static ButtonStyle styleFrom({

3
packages/flutter/lib/src/material/elevated_button_theme.dart
View File

@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
import 'button_style.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// A [ButtonStyle] that overrides the default appearance of
/// [ElevatedButton]s when it's used with [ElevatedButtonTheme] or with the
/// overall [Theme]'s [ThemeData.elevatedButtonTheme].

4
packages/flutter/lib/src/material/expansion_tile_theme.dart
View File

@ -2,12 +2,14 @@
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Used with [ExpansionTileTheme] to define default property values for
/// descendant [ExpansionTile] widgets.
///

42
packages/flutter/lib/src/material/icon_button.dart
View File

@ -23,6 +23,9 @@ import 'theme.dart';
import 'theme_data.dart';
import 'tooltip.dart';
// Examples can assume:
// late BuildContext context;
// Minimum logical pixel size of the IconButton.
// See: <https://material.io/design/usability/accessibility.html#layout-typography>.
const double _kMinButtonSize = kMinInteractiveDimension;
@ -64,13 +67,24 @@ const double _kMinButtonSize = kMinInteractiveDimension;
/// [iconSize] parameter instead. For example do this:
///
/// ```dart
/// IconButton(iconSize: 72, icon: Icon(Icons.favorite), ...)
/// IconButton(
/// iconSize: 72,
/// icon: const Icon(Icons.favorite),
/// onPressed: () {
/// // ...
/// },
/// ),
/// ```
///
/// Avoid doing this:
///
/// ```dart
/// IconButton(icon: Icon(Icons.favorite, size: 72), ...)
/// IconButton(
/// icon: const Icon(Icons.favorite, size: 72),
/// onPressed: () {
/// // ...
/// },
/// ),
/// ```
///
/// If you do, the button's size will be based on the default icon
@ -257,6 +271,10 @@ class IconButton extends StatelessWidget {
/// ```dart
/// IconButton(
/// focusColor: Colors.orange.withOpacity(0.3),
/// icon: const Icon(Icons.sunny),
/// onPressed: () {
/// // ...
/// },
/// )
/// ```
///
@ -273,6 +291,10 @@ class IconButton extends StatelessWidget {
/// ```dart
/// IconButton(
/// hoverColor: Colors.orange.withOpacity(0.3),
/// icon: const Icon(Icons.ac_unit),
/// onPressed: () {
/// // ...
/// },
/// )
/// ```
///
@ -287,8 +309,10 @@ class IconButton extends StatelessWidget {
/// ```dart
/// IconButton(
/// color: Colors.blue,
/// onPressed: _handleTap,
/// icon: Icon(Icons.widgets),
/// icon: const Icon(Icons.sunny_snowing),
/// onPressed: () {
/// // ...
/// },
/// )
/// ```
final Color? color;
@ -320,6 +344,10 @@ class IconButton extends StatelessWidget {
/// ```dart
/// IconButton(
/// highlightColor: Colors.orange.withOpacity(0.3),
/// icon: const Icon(Icons.question_mark),
/// onPressed: () {
/// // ...
/// },
/// )
/// ```
///
@ -459,8 +487,12 @@ class IconButton extends StatelessWidget {
///
/// ```dart
/// IconButton(
/// icon: const Icon(Icons.pets),
/// style: IconButton.styleFrom(foregroundColor: Colors.green),
/// )
/// onPressed: () {
/// // ...
/// },
/// ),
/// ```
static ButtonStyle styleFrom({
Color? foregroundColor,

3
packages/flutter/lib/src/material/icon_button_theme.dart
View File

@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
import 'button_style.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// A [ButtonStyle] that overrides the default appearance of
/// [IconButton]s when it's used with the [IconButton], the [IconButtonTheme] or the
/// overall [Theme]'s [ThemeData.iconButtonTheme].

3
packages/flutter/lib/src/material/ink_well.dart
View File

@ -16,6 +16,9 @@ import 'material.dart';
import 'material_state.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// An ink feature that displays a [color] "splash" in response to a user
/// gesture that can be confirmed or canceled.
///

7
packages/flutter/lib/src/material/input_decorator.dart
View File

@ -19,6 +19,9 @@ import 'text_theme.dart';
import 'theme.dart';
import 'theme_data.dart';
// Examples can assume:
// late Widget _myIcon;
const Duration _kTransitionDuration = Duration(milliseconds: 200);
const Curve _kTransitionCurve = Curves.fastOutSlowIn;
const double _kFinalLabelScale = 0.75;
@ -2877,7 +2880,7 @@ class InputDecoration {
/// ```dart
/// prefixIcon: Padding(
/// padding: const EdgeInsetsDirectional.only(start: 12.0),
/// child: myIcon, // myIcon is a 48px-wide widget.
/// child: _myIcon, // _myIcon is a 48px-wide widget.
/// )
/// ```
///
@ -2999,7 +3002,7 @@ class InputDecoration {
/// ```dart
/// suffixIcon: Padding(
/// padding: const EdgeInsetsDirectional.only(end: 12.0),
/// child: myIcon, // myIcon is a 48px-wide widget.
/// child: _myIcon, // myIcon is a 48px-wide widget.
/// )
/// ```
///

5
packages/flutter/lib/src/material/list_tile.dart
View File

@ -18,6 +18,9 @@ import 'material_state.dart';
import 'theme.dart';
import 'theme_data.dart';
// Examples can assume:
// int _act = 1;
/// Defines the title font used for [ListTile] descendants of a [ListTileTheme].
///
/// List tiles that appear in a [Drawer] use the theme's [TextTheme.bodyText1]
@ -166,8 +169,6 @@ enum ListTileControlAffinity {
/// tapped, the whole row has an ink splash effect (see [InkWell]).
///
/// ```dart
/// int _act = 1;
/// // ...
/// ListTile(
/// leading: const Icon(Icons.flight_land),
/// title: const Text("Trix's airplane"),

3
packages/flutter/lib/src/material/list_tile_theme.dart
View File

@ -13,6 +13,9 @@ import 'material_state.dart';
import 'theme.dart';
import 'theme_data.dart';
// Examples can assume:
// late BuildContext context;
/// Used with [ListTileTheme] to define default property values for
/// descendant [ListTile] widgets, as well as classes that build
/// [ListTile]s, like [CheckboxListTile], [RadioListTile], and

5
packages/flutter/lib/src/material/material.dart
View File

@ -10,6 +10,9 @@ import 'constants.dart';
import 'elevation_overlay.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Signature for the callback used by ink effects to obtain the rectangle for the effect.
///
/// Used by [InkHighlight] and [InkSplash], for example.
@ -345,7 +348,7 @@ class Material extends StatefulWidget {
/// Typical usage is as follows:
///
/// ```dart
/// MaterialInkController inkController = Material.of(context);
/// MaterialInkController? inkController = Material.of(context);
/// ```
///
/// This method can be expensive (it walks the element tree).

17
packages/flutter/lib/src/material/material_localizations.dart
View File

@ -9,6 +9,9 @@ import 'debug.dart';
import 'time.dart';
import 'typography.dart';
// Examples can assume:
// late BuildContext context;
// ADDING A NEW STRING
//
// If you (someone contributing to the Flutter framework) want to add a new
@ -28,16 +31,15 @@ import 'typography.dart';
//
// Then you need to add new entries for the string to all of the other
// language locale files by running:
// ```
//
// dart dev/tools/localization/bin/gen_missing_localizations.dart
// ```
//
// Which will copy the english strings into the other locales as placeholders
// until they can be translated.
//
// Finally you need to re-generate lib/src/l10n/localizations.dart by running:
// ```
//
// dart dev/tools/localization/bin/gen_localizations.dart --overwrite
// ```
//
// There is a README file with further information in the lib/src/l10n/
// directory.
@ -57,9 +59,8 @@ import 'typography.dart';
// strings in lib/src/l10n/material_en.arb.
//
// You also need to re-generate lib/src/l10n/localizations.dart by running:
// ```
//
// dart dev/tools/localization/bin/gen_localizations.dart --overwrite
// ```
//
// This script may result in your updated getters being created in newer
// locales and set to the old value of the strings. This is to be expected.
@ -348,9 +349,9 @@ abstract class MaterialLocalizations {
/// This getter is compatible with [narrowWeekdays]. For example:
///
/// ```dart
/// var localizations = MaterialLocalizations.of(context);
/// MaterialLocalizations localizations = MaterialLocalizations.of(context);
/// // The name of the first day of week for the current locale.
/// var firstDayOfWeek = localizations.narrowWeekdays[localizations.firstDayOfWeekIndex];
/// String firstDayOfWeek = localizations.narrowWeekdays[localizations.firstDayOfWeekIndex];
/// ```
int get firstDayOfWeekIndex;

22
packages/flutter/lib/src/material/material_state.dart
View File

@ -8,6 +8,9 @@ import 'package:flutter/services.dart';
import 'input_border.dart';
// Examples can assume:
// late BuildContext context;
/// Interactive states that some of the Material widgets can take on when
/// receiving input from the user.
///
@ -321,30 +324,35 @@ abstract class MaterialStateBorderSide extends BorderSide implements MaterialSta
/// (the empty set of states) will be used.
///
/// Usage:
///
/// ```dart
/// ChipTheme(
/// data: Theme.of(context).chipTheme.copyWith(
/// side: MaterialStateBorderSide.resolveWith((Set<MaterialState> states) {
/// if (states.contains(MaterialState.selected)) {
/// return const BorderSide(width: 1, color: Colors.red);
/// return const BorderSide(color: Colors.red);
/// }
/// return null; // Defer to default value on the theme or widget.
/// }),
/// ),
/// child: Chip(),
/// )
/// child: const Chip(
/// label: Text('Transceiver'),
/// ),
/// ),
/// ```
///
/// // OR
/// Alternatively:
///
/// ```dart
/// Chip(
/// ...
/// label: const Text('Transceiver'),
/// side: MaterialStateBorderSide.resolveWith((Set<MaterialState> states) {
/// if (states.contains(MaterialState.selected)) {
/// return const BorderSide(width: 1, color: Colors.red);
/// return const BorderSide(color: Colors.red);
/// }
/// return null; // Defer to default value on the theme or widget.
/// }),
/// )
/// ),
/// ```
static MaterialStateBorderSide resolveWith(MaterialPropertyResolver<BorderSide?> callback) =>
_MaterialStateBorderSide(callback);

108
packages/flutter/lib/src/material/navigation_bar.dart
View File

@ -17,6 +17,10 @@ import 'text_theme.dart';
import 'theme.dart';
import 'tooltip.dart';
// Examples can assume:
// late BuildContext context;
// late bool _isDrawerOpen;
/// Material 3 Navigation Bar component.
///
/// Navigation bars offer a persistent and convenient way to switch between
@ -444,12 +448,25 @@ class _NavigationDestinationInfo extends InheritedWidget {
/// Which destination index is this in the navigation bar.
///
/// For example:
///
/// ```dart
/// NavigationBar(
/// destinations: [
/// NavigationDestination(), // This is destination index 0.
/// NavigationDestination(), // This is destination index 1.
/// NavigationDestination(), // This is destination index 2.
/// destinations: const <Widget>[
/// NavigationDestination(
/// // This is destination index 0.
/// icon: Icon(Icons.surfing),
/// label: 'Surfing',
/// ),
/// NavigationDestination(
/// // This is destination index 1.
/// icon: Icon(Icons.support),
/// label: 'Support',
/// ),
/// NavigationDestination(
/// // This is destination index 2.
/// icon: Icon(Icons.local_hospital),
/// label: 'Hospital',
/// ),
/// ]
/// )
/// ```
@ -888,17 +905,18 @@ class _NavigationDestinationLayoutDelegate extends MultiChildLayoutDelegate {
/// Utility Widgets
/// Clamps [MediaQueryData.textScaleFactor] so that if it is greater than
/// [upperLimit] or less than [lowerLimit], [upperLimit] or [lowerLimit] will be
/// used instead for the [child] widget.
///
/// Example:
/// ```
/// _ClampTextScaleFactor(
/// upperLimit: 2.0,
/// child: Text('Foo'), // If textScaleFactor is 3.0, this will only scale 2x.
/// )
/// ```
// Clamps [MediaQueryData.textScaleFactor] so that if it is greater than
// [upperLimit] or less than [lowerLimit], [upperLimit] or [lowerLimit] will be
// used instead for the [child] widget.
//
// Example:
//
// ```dart
// _ClampTextScaleFactor(
// upperLimit: 2.0,
// child: const Text('Foo'), // If textScaleFactor is 3.0, this will only scale 2x.
// )
// ```
class _ClampTextScaleFactor extends StatelessWidget {
/// Clamps the text scale factor of descendants by modifying the [MediaQuery]
/// surrounding [child].
@ -965,36 +983,36 @@ class _StatusTransitionWidgetBuilder extends StatusTransitionWidget {
Widget build(BuildContext context) => builder(context, child);
}
/// Builder widget for widgets that need to be animated from 0 (unselected) to
/// 1.0 (selected).
///
/// This widget creates and manages an [AnimationController] that it passes down
/// to the child through the [builder] function.
///
/// When [isSelected] is `true`, the animation controller will animate from
/// 0 to 1 (for [duration] time).
///
/// When [isSelected] is `false`, the animation controller will animate from
/// 1 to 0 (for [duration] time).
///
/// If [isSelected] is updated while the widget is animating, the animation will
/// be reversed until it is either 0 or 1 again. If [alwaysDoFullAnimation] is
/// true, the animation will reset to 0 or 1 before beginning the animation, so
/// that the full animation is done.
///
/// Usage:
/// ```dart
/// _SelectableAnimatedBuilder(
/// isSelected: _isDrawerOpen,
/// builder: (context, animation) {
/// return AnimatedIcon(
/// icon: AnimatedIcons.menu_arrow,
/// progress: animation,
/// semanticLabel: 'Show menu',
/// );
/// }
/// )
/// ```
// Builder widget for widgets that need to be animated from 0 (unselected) to
// 1.0 (selected).
//
// This widget creates and manages an [AnimationController] that it passes down
// to the child through the [builder] function.
//
// When [isSelected] is `true`, the animation controller will animate from
// 0 to 1 (for [duration] time).
//
// When [isSelected] is `false`, the animation controller will animate from
// 1 to 0 (for [duration] time).
//
// If [isSelected] is updated while the widget is animating, the animation will
// be reversed until it is either 0 or 1 again. If [alwaysDoFullAnimation] is
// true, the animation will reset to 0 or 1 before beginning the animation, so
// that the full animation is done.
//
// Usage:
// ```dart
// _SelectableAnimatedBuilder(
// isSelected: _isDrawerOpen,
// builder: (context, animation) {
// return AnimatedIcon(
// icon: AnimatedIcons.menu_arrow,
// progress: animation,
// semanticLabel: 'Show menu',
// );
// }
// )
// ```
class _SelectableAnimatedBuilder extends StatefulWidget {
/// Builds and maintains an [AnimationController] that will animate from 0 to
/// 1 and back depending on when [isSelected] is true.

3
packages/flutter/lib/src/material/navigation_bar_theme.dart
View File

@ -12,6 +12,9 @@ import 'material_state.dart';
import 'navigation_bar.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [NavigationBar]
/// widgets.
///

3
packages/flutter/lib/src/material/navigation_rail_theme.dart
View File

@ -11,6 +11,9 @@ import 'package:flutter/widgets.dart';
import 'navigation_rail.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [NavigationRail]
/// widgets.
///

3
packages/flutter/lib/src/material/no_splash.dart
View File

@ -38,13 +38,14 @@ class _NoSplashFactory extends InteractiveInkFeatureFactory {
/// Use [NoSplash.splashFactory] to defeat the default ink splash drawn by
/// an [InkWell] or [ButtonStyle]. For example, to create an [ElevatedButton]
/// that does not draw the default "ripple" ink splash when it's tapped:
///
/// ```dart
/// ElevatedButton(
/// style: ElevatedButton.styleFrom(
/// splashFactory: NoSplash.splashFactory,
/// ),
/// onPressed: () { },
/// child: Text('No Splash'),
/// child: const Text('No Splash'),
/// )
/// ```
class NoSplash extends InteractiveInkFeature {

10
packages/flutter/lib/src/material/outlined_button.dart
View File

@ -127,10 +127,14 @@ class OutlinedButton extends ButtonStyleButton {
/// ```dart
/// OutlinedButton(
/// style: OutlinedButton.styleFrom(
/// shape: StadiumBorder(),
/// side: BorderSide(width: 2, color: Colors.green),
/// shape: const StadiumBorder(),
/// side: const BorderSide(width: 2, color: Colors.green),
/// ),
/// child: const Text('Seasons of Love'),
/// onPressed: () {
/// // ...
/// },
/// ),
/// )
/// ```
static ButtonStyle styleFrom({
Color? foregroundColor,

3
packages/flutter/lib/src/material/outlined_button_theme.dart
View File

@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
import 'button_style.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// A [ButtonStyle] that overrides the default appearance of
/// [OutlinedButton]s when it's used with [OutlinedButtonTheme] or with the
/// overall [Theme]'s [ThemeData.outlinedButtonTheme].

3
packages/flutter/lib/src/material/popup_menu_theme.dart
View File

@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
import 'material_state.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the visual properties of the routes used to display popup menus
/// as well as [PopupMenuItem] and [PopupMenuDivider] widgets.
///

3
packages/flutter/lib/src/material/progress_indicator_theme.dart
View File

@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
@immutable
/// Defines the visual properties of [ProgressIndicator] widgets.
///

8
packages/flutter/lib/src/material/radio.dart
View File

@ -12,6 +12,12 @@ import 'theme.dart';
import 'theme_data.dart';
import 'toggleable.dart';
// Examples can assume:
// late BuildContext context;
// enum SingingCharacter { lafayette }
// late SingingCharacter? _character;
// late StateSetter setState;
const double _kOuterRadius = 8.0;
const double _kInnerRadius = 4.5;
@ -116,7 +122,7 @@ class Radio<T> extends StatefulWidget {
/// Radio<SingingCharacter>(
/// value: SingingCharacter.lafayette,
/// groupValue: _character,
/// onChanged: (SingingCharacter newValue) {
/// onChanged: (SingingCharacter? newValue) {
/// setState(() {
/// _character = newValue;
/// });

4
packages/flutter/lib/src/material/radio_list_tile.dart
View File

@ -15,6 +15,8 @@ import 'theme_data.dart';
// Examples can assume:
// void setState(VoidCallback fn) { }
// enum Meridiem { am, pm }
// enum SingingCharacter { lafayette }
// late SingingCharacter? _character;
/// A [ListTile] with a [Radio]. In other words, a radio button with a label.
///
@ -206,7 +208,7 @@ class RadioListTile<T> extends StatelessWidget {
/// title: const Text('Lafayette'),
/// value: SingingCharacter.lafayette,
/// groupValue: _character,
/// onChanged: (SingingCharacter newValue) {
/// onChanged: (SingingCharacter? newValue) {
/// setState(() {
/// _character = newValue;
/// });

3
packages/flutter/lib/src/material/radio_theme.dart
View File

@ -12,6 +12,9 @@ import 'material_state.dart';
import 'theme.dart';
import 'theme_data.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [Radio] widgets.
///
/// Descendant widgets obtain the current [RadioThemeData] object using

2
packages/flutter/lib/src/material/refresh_indicator.dart
View File

@ -98,7 +98,7 @@ enum RefreshIndicatorTriggerMode {
/// ```dart
/// ListView(
/// physics: const AlwaysScrollableScrollPhysics(),
/// children: ...
/// // ...
/// )
/// ```
///

3
packages/flutter/lib/src/material/scrollbar_theme.dart
View File

@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
import 'material_state.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [Scrollbar] widgets.
///
/// Descendant widgets obtain the current [ScrollbarThemeData] object with

6
packages/flutter/lib/src/material/selectable_text.dart
View File

@ -15,6 +15,10 @@ import 'magnifier.dart';
import 'text_selection.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
// late FocusNode myFocusNode;
/// An eyeballed value that moves the cursor slightly left of where it is
/// rendered for text on Android so its positioning more accurately matches the
/// native iOS text cursor positioning.
@ -313,7 +317,7 @@ class SelectableText extends StatefulWidget {
/// to the [focusNode]:
///
/// ```dart
/// focusNode.addListener(() { print(myFocusNode.hasFocus); });
/// myFocusNode.addListener(() { print(myFocusNode.hasFocus); });
/// ```
///
/// If null, this widget will create its own [FocusNode] with

31
packages/flutter/lib/src/material/snack_bar.dart
View File

@ -15,6 +15,9 @@ import 'text_button.dart';
import 'text_button_theme.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
const double _singleLineVerticalPadding = 14.0;
// TODO(ianh): We should check if the given text and actions are going to fit on
@ -40,9 +43,11 @@ const Curve _snackBarFadeOutCurve = Interval(0.72, 1.0, curve: Curves.fastOutSlo
///
/// ```dart
/// ScaffoldMessenger.of(context).showSnackBar(
/// SnackBar( ... )
/// const SnackBar(
/// content: Text('He likes me. I think he likes me.'),
/// )
/// ).closed.then((SnackBarClosedReason reason) {
/// ...
/// // ...
/// });
/// ```
enum SnackBarClosedReason {
@ -256,29 +261,29 @@ class SnackBar extends StatefulWidget {
/// The amount of padding to apply to the snack bar's content and optional
/// action.
///
/// If this property is null, the default padding values for:
/// If this property is null, the default padding values are as follows:
///
/// * [content]
/// * Top and bottom paddings are 14.
/// * Left padding is 24 if [behavior] is [SnackBarBehavior.fixed],
/// 16 if [behavior] is [SnackBarBehavior.floating]
/// * Right padding is same as start padding if there is no [action], otherwise 0.
/// 16 if [behavior] is [SnackBarBehavior.floating].
/// * Right padding is same as start padding if there is no [action],
/// otherwise 0.
/// * [action]
/// * Top and bottom paddings are 14
/// * Top and bottom paddings are 14.
/// * Left and right paddings are half of [content]'s left padding.
///
/// If this property is not null, the padding assignment for:
/// If this property is not null, the padding is as follows:
///
/// * [content]
/// * Left, top and bottom paddings are assigned normally.
/// * Right padding is assigned normally if there is no [action], otherwise 0.
/// * Right padding is assigned normally if there is no [action],
/// otherwise 0.
/// * [action]
/// * Left padding is replaced with half value of right padding.
/// * Left padding is replaced with half the right padding.
/// * Top and bottom paddings are assigned normally.
/// * Right padding has an additional half value of right padding.
/// ```dart
/// right + (right / 2)
/// ```
/// * Right padding is replaced with one and a half times the
/// right padding.
final EdgeInsetsGeometry? padding;
/// The width of the snack bar.

4
packages/flutter/lib/src/material/switch.dart
View File

@ -17,6 +17,10 @@ import 'theme.dart';
import 'theme_data.dart';
import 'toggleable.dart';
// Examples can assume:
// bool _giveVerse = true;
// late StateSetter setState;
const double _kTrackHeight = 14.0;
const double _kTrackWidth = 33.0;
const double _kTrackRadius = _kTrackHeight / 2.0;

3
packages/flutter/lib/src/material/switch_theme.dart
View File

@ -12,6 +12,9 @@ import 'material_state.dart';
import 'theme.dart';
import 'theme_data.dart';
// Examples can assume:
// late BuildContext context;
/// Defines default property values for descendant [Switch] widgets.
///
/// Descendant widgets obtain the current [SwitchThemeData] object using

8
packages/flutter/lib/src/material/tab_controller.dart
View File

@ -302,7 +302,9 @@ class _TabControllerScope extends InheritedWidget {
///
/// ```dart
/// class MyDemo extends StatelessWidget {
/// final List<Tab> myTabs = <Tab>[
/// const MyDemo({super.key});
///
/// static const List<Tab> myTabs = <Tab>[
/// Tab(text: 'LEFT'),
/// Tab(text: 'RIGHT'),
/// ];
@ -313,13 +315,13 @@ class _TabControllerScope extends InheritedWidget {
/// length: myTabs.length,
/// child: Scaffold(
/// appBar: AppBar(
/// bottom: TabBar(
/// bottom: const TabBar(
/// tabs: myTabs,
/// ),
/// ),
/// body: TabBarView(
/// children: myTabs.map((Tab tab) {
/// final String label = tab.text.toLowerCase();
/// final String label = tab.text!.toLowerCase();
/// return Center(
/// child: Text(
/// 'This is the $label tab',

10
packages/flutter/lib/src/material/tabs.dart
View File

@ -843,6 +843,7 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
/// Use [NoSplash.splashFactory] to defeat ink splash rendering. For example
/// to defeat both the splash and the hover/pressed overlay, but not the
/// keyboard focused overlay:
///
/// ```dart
/// TabBar(
/// splashFactory: NoSplash.splashFactory,
@ -851,7 +852,9 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
/// return states.contains(MaterialState.focused) ? null : Colors.transparent;
/// },
/// ),
/// ...
/// tabs: const <Widget>[
/// // ...
/// ],
/// )
/// ```
final InteractiveInkFeatureFactory? splashFactory;
@ -859,13 +862,16 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget {
/// Defines the clipping radius of splashes that extend outside the bounds of the tab.
///
/// This can be useful to match the [BoxDecoration.borderRadius] provided as [indicator].
///
/// ```dart
/// TabBar(
/// indicator: BoxDecoration(
/// borderRadius: BorderRadius.circular(40),
/// ),
/// splashBorderRadius: BorderRadius.circular(40),
/// ...
/// tabs: const <Widget>[
/// // ...
/// ],
/// )
/// ```
///

6
packages/flutter/lib/src/material/text_button.dart
View File

@ -137,7 +137,11 @@ class TextButton extends ButtonStyleButton {
/// ```dart
/// TextButton(
/// style: TextButton.styleFrom(foregroundColor: Colors.green),
/// )
/// child: const Text('Give Kate a mix tape'),
/// onPressed: () {
/// // ...
/// },
/// ),
/// ```
static ButtonStyle styleFrom({
Color? foregroundColor,

3
packages/flutter/lib/src/material/text_button_theme.dart
View File

@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
import 'button_style.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// A [ButtonStyle] that overrides the default appearance of
/// [TextButton]s when it's used with [TextButtonTheme] or with the
/// overall [Theme]'s [ThemeData.textButtonTheme].

6
packages/flutter/lib/src/material/text_field.dart
View File

@ -23,6 +23,10 @@ import 'theme.dart';
export 'package:flutter/services.dart' show SmartDashesType, SmartQuotesType, TextCapitalization, TextInputAction, TextInputType;
// Examples can assume:
// late BuildContext context;
// late FocusNode myFocusNode;
/// Signature for the [TextField.buildCounter] callback.
typedef InputCounterWidgetBuilder = Widget? Function(
/// The build context for the TextField.
@ -427,7 +431,7 @@ class TextField extends StatefulWidget {
/// to the [focusNode]:
///
/// ```dart
/// focusNode.addListener(() { print(myFocusNode.hasFocus); });
/// myFocusNode.addListener(() { print(myFocusNode.hasFocus); });
/// ```
///
/// If null, this widget will create its own [FocusNode].

3
packages/flutter/lib/src/material/text_selection_theme.dart
View File

@ -7,6 +7,9 @@ import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the visual properties needed for text selection in [TextField] and
/// [SelectableText] widgets.
///

32
packages/flutter/lib/src/material/text_theme.dart
View File

@ -32,22 +32,22 @@ import 'typography.dart';
/// bodyText1 and bodyText2.
///
/// The 2018 spec has thirteen text styles:
/// ```
/// NAME SIZE WEIGHT SPACING
/// headline1 96.0 light -1.5
/// headline2 60.0 light -0.5
/// headline3 48.0 regular 0.0
/// headline4 34.0 regular 0.25
/// headline5 24.0 regular 0.0
/// headline6 20.0 medium 0.15
/// subtitle1 16.0 regular 0.15
/// subtitle2 14.0 medium 0.1
/// body1 16.0 regular 0.5 (bodyText1)
/// body2 14.0 regular 0.25 (bodyText2)
/// button 14.0 medium 1.25
/// caption 12.0 regular 0.4
/// overline 10.0 regular 1.5
/// ```
///
/// | NAME | SIZE | WEIGHT | SPACING | |
/// |------------|------|---------|----------|-------------|
/// | headline1 | 96.0 | light | -1.5 | |
/// | headline2 | 60.0 | light | -0.5 | |
/// | headline3 | 48.0 | regular | 0.0 | |
/// | headline4 | 34.0 | regular | 0.25 | |
/// | headline5 | 24.0 | regular | 0.0 | |
/// | headline6 | 20.0 | medium | 0.15 | |
/// | subtitle1 | 16.0 | regular | 0.15 | |
/// | subtitle2 | 14.0 | medium | 0.1 | |
/// | body1 | 16.0 | regular | 0.5 | (bodyText1) |
/// | body2 | 14.0 | regular | 0.25 | (bodyText2) |
/// | button | 14.0 | medium | 1.25 | |
/// | caption | 12.0 | regular | 0.4 | |
/// | overline | 10.0 | regular | 1.5 | |
///
/// ...where "light" is `FontWeight.w300`, "regular" is `FontWeight.w400` and
/// "medium" is `FontWeight.w500`.

2
packages/flutter/lib/src/material/theme.dart
View File

@ -89,7 +89,7 @@ class Theme extends StatelessWidget {
/// Widget build(BuildContext context) {
/// return MaterialApp(
/// theme: ThemeData.light(),
/// body: Builder(
/// home: Builder(
/// // Create an inner BuildContext so that we can refer to
/// // the Theme with Theme.of().
/// builder: (BuildContext context) {

8
packages/flutter/lib/src/material/theme_data.dart
View File

@ -57,6 +57,9 @@ import 'typography.dart';
export 'package:flutter/services.dart' show Brightness;
// Examples can assume:
// late BuildContext context;
/// An interface that defines custom additions to a [ThemeData] object.
///
/// Typically used for custom colors. To use, subclass [ThemeExtension],
@ -1576,9 +1579,10 @@ class ThemeData with Diagnosticable {
///
/// ```dart
/// final ThemeData theme = Theme.of(context);
/// theme.textTheme.headline1.copyWith(
/// final TextStyle style = theme.textTheme.headline1!.copyWith(
/// color: theme.colorScheme.onSecondary,
/// )
/// );
/// // ...use style...
/// ```
@Deprecated(
'No longer used by the framework, please remove any reference to it. '

21
packages/flutter/lib/src/material/time_picker_theme.dart
View File

@ -8,6 +8,9 @@ import 'package:flutter/widgets.dart';
import 'input_decorator.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the visual properties of the widget displayed with [showTimePicker].
///
/// Descendant widgets obtain the current [TimePickerThemeData] object using
@ -133,7 +136,8 @@ class TimePickerThemeData with Diagnosticable {
/// The color of the entry mode [IconButton].
///
/// If this is null, the time picker defaults to:
/// ```
///
/// ```dart
/// Theme.of(context).colorScheme.onSurface.withOpacity(
/// Theme.of(context).colorScheme.brightness == Brightness.dark ? 1.0 : 0.6,
/// )
@ -173,8 +177,9 @@ class TimePickerThemeData with Diagnosticable {
/// The shape of the day period that the time picker uses.
///
/// If this is null, the time picker defaults to:
/// ```
/// RoundedRectangleBorder(
///
/// ```dart
/// const RoundedRectangleBorder(
/// borderRadius: BorderRadius.all(Radius.circular(4.0)),
/// side: BorderSide(),
/// )
@ -184,10 +189,14 @@ class TimePickerThemeData with Diagnosticable {
/// The color and weight of the day period's outline.
///
/// If this is null, the time picker defaults to:
/// ```
///
/// ```dart
/// BorderSide(
/// color: Color.alphaBlend(colorScheme.onBackground.withOpacity(0.38), colorScheme.surface),
/// )
/// color: Color.alphaBlend(
/// Theme.of(context).colorScheme.onBackground.withOpacity(0.38),
/// Theme.of(context).colorScheme.surface,
/// ),
/// ),
/// ```
final BorderSide? dayPeriodBorderSide;

80
packages/flutter/lib/src/material/toggle_buttons.dart
View File

@ -18,6 +18,10 @@ import 'theme.dart';
import 'theme_data.dart';
import 'toggle_buttons_theme.dart';
// Examples can assume:
// List<bool> isSelected = <bool>[];
// void setState(dynamic arg) { }
/// A set of toggle buttons.
///
/// The list of [children] are laid out along [direction]. The state of each button
@ -43,34 +47,32 @@ import 'toggle_buttons_theme.dart';
/// Here is an implementation that allows for multiple buttons to be
/// simultaneously selected, while requiring none of the buttons to be
/// selected.
///
/// ```dart
/// ToggleButtons(
/// children: <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// isSelected: isSelected,
/// onPressed: (int index) {
/// setState(() {
/// isSelected[index] = !isSelected[index];
/// });
/// },
/// isSelected: isSelected,
/// children: const <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// ),
/// ```
///
/// {@animation 700 150 https://flutter.github.io/assets-for-api-docs/assets/material/toggle_buttons_required_mutually_exclusive.mp4}
///
/// Here is an implementation that requires mutually exclusive selection
/// while requiring at least one selection. Note that this assumes that
/// [isSelected] was properly initialized with one selection.
/// Here is an implementation that requires mutually exclusive selection while
/// requiring at least one selection. This assumes that [isSelected] was
/// properly initialized with one selection.
///
/// ```dart
/// ToggleButtons(
/// children: <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// isSelected: isSelected,
/// onPressed: (int index) {
/// setState(() {
/// for (int buttonIndex = 0; buttonIndex < isSelected.length; buttonIndex++) {
@ -82,7 +84,11 @@ import 'toggle_buttons_theme.dart';
/// }
/// });
/// },
/// isSelected: isSelected,
/// children: const <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// ),
/// ```
///
@ -90,13 +96,10 @@ import 'toggle_buttons_theme.dart';
///
/// Here is an implementation that requires mutually exclusive selection,
/// but allows for none of the buttons to be selected.
///
/// ```dart
/// ToggleButtons(
/// children: <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// isSelected: isSelected,
/// onPressed: (int index) {
/// setState(() {
/// for (int buttonIndex = 0; buttonIndex < isSelected.length; buttonIndex++) {
@ -108,37 +111,42 @@ import 'toggle_buttons_theme.dart';
/// }
/// });
/// },
/// isSelected: isSelected,
/// children: const <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// ),
/// ```
///
/// {@animation 700 150 https://flutter.github.io/assets-for-api-docs/assets/material/toggle_buttons_required.mp4}
///
/// Here is an implementation that allows for multiple buttons to be
/// simultaneously selected, while requiring at least one selection. Note
/// that this assumes that [isSelected] was properly initialized with one
/// selection.
/// simultaneously selected, while requiring at least one selection. This
/// assumes that [isSelected] was properly initialized with one selection.
///
/// ```dart
/// ToggleButtons(
/// children: <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// isSelected: isSelected,
/// onPressed: (int index) {
/// int count = 0;
/// isSelected.forEach((bool val) {
/// if (val) count++;
/// });
///
/// if (isSelected[index] && count < 2)
/// for (final bool value in isSelected) {
/// if (value) {
/// count += 1;
/// }
/// }
/// if (isSelected[index] && count < 2) {
/// return;
///
/// }
/// setState(() {
/// isSelected[index] = !isSelected[index];
/// });
/// },
/// isSelected: isSelected,
/// children: const <Widget>[
/// Icon(Icons.ac_unit),
/// Icon(Icons.call),
/// Icon(Icons.cake),
/// ],
/// ),
/// ```
///

5
packages/flutter/lib/src/material/toggle_buttons_theme.dart
View File

@ -10,6 +10,9 @@ import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the color and border properties of [ToggleButtons] widgets.
///
/// Used by [ToggleButtonsTheme] to control the color and border properties
@ -263,7 +266,7 @@ class ToggleButtonsTheme extends InheritedTheme {
/// Typical usage is as follows:
///
/// ```dart
/// ToggleButtonsTheme theme = ToggleButtonsTheme.of(context);
/// ToggleButtonsThemeData theme = ToggleButtonsTheme.of(context);
/// ```
static ToggleButtonsThemeData of(BuildContext context) {
final ToggleButtonsTheme? toggleButtonsTheme = context.dependOnInheritedWidgetOfExactType<ToggleButtonsTheme>();

3
packages/flutter/lib/src/material/tooltip_theme.dart
View File

@ -9,6 +9,9 @@ import 'package:flutter/widgets.dart';
import 'theme.dart';
// Examples can assume:
// late BuildContext context;
/// Defines the visual properties of [Tooltip] widgets.
///
/// Used by [TooltipTheme] to control the visual properties of tooltips in a

3
packages/flutter/lib/src/material/typography.dart
View File

@ -8,6 +8,9 @@ import 'package:flutter/painting.dart';
import 'colors.dart';
import 'text_theme.dart';
// Examples can assume:
// late TargetPlatform platform;
/// A characterization of the of a [TextTheme]'s glyphs that is used to define
/// its localized [TextStyle] geometry for [ThemeData.textTheme].
///

3
packages/flutter/lib/src/painting/decoration.dart
View File

@ -8,6 +8,9 @@ import 'basic_types.dart';
import 'edge_insets.dart';
import 'image_provider.dart';
// Examples can assume:
// late Decoration myDecoration;
// This group of classes is intended for painting in cartesian coordinates.
/// A description of a box decoration (a decoration applied to a [Rect]).

2
packages/flutter/lib/src/painting/image_provider.dart
View File

@ -1162,11 +1162,9 @@ class MemoryImage extends ImageProvider<MemoryImage> {
/// bundled, the app has to specify which ones to include. For instance a
/// package named `fancy_backgrounds` could have:
///
/// ```
/// lib/backgrounds/background1.png
/// lib/backgrounds/background2.png
/// lib/backgrounds/background3.png
/// ```
///
/// To include, say the first image, the `pubspec.yaml` of the app should specify
/// it in the `assets` section:

11
packages/flutter/lib/src/painting/image_resolution.dart
View File

@ -40,11 +40,9 @@ const double _kLowDprLimit = 2.0;
/// as 2.0 and 4.0 pixel ratios (variants). The asset bundle should then
/// contain the following assets:
///
/// ```
/// heart.png
/// 2.0x/heart.png
/// 4.0x/heart.png
/// ```
///
/// On a device with a 1.0 device pixel ratio, the image chosen would be
/// heart.png; on a device with a 2.0 device pixel ratio, the image chosen
@ -88,16 +86,13 @@ const double _kLowDprLimit = 2.0;
/// at the equivalent level; that is, the following is also a valid bundle
/// structure:
///
/// ```
/// icons/heart.png
/// icons/1.5x/heart.png
/// icons/2.0x/heart.png
/// ```
///
/// assets/icons/3.0x/heart.png would be a valid variant of
/// assets/icons/heart.png.
///
///
/// ## Fetching assets
///
/// When fetching an image provided by the app itself, use the [assetName]
@ -113,7 +108,7 @@ const double _kLowDprLimit = 2.0;
///
/// Then, to fetch the image, use:
/// ```dart
/// AssetImage('icons/heart.png')
/// const AssetImage('icons/heart.png')
/// ```
///
/// {@tool snippet}
@ -204,7 +199,7 @@ const double _kLowDprLimit = 2.0;
/// `my_icons`. Then to fetch the image, use:
///
/// ```dart
/// AssetImage('icons/heart.png', package: 'my_icons')
/// const AssetImage('icons/heart.png', package: 'my_icons')
/// ```
///
/// Assets used by the package itself should also be fetched using the [package]
@ -219,11 +214,9 @@ const double _kLowDprLimit = 2.0;
/// bundled, the app has to specify which ones to include. For instance a
/// package named `fancy_backgrounds` could have:
///
/// ```
/// lib/backgrounds/background1.png
/// lib/backgrounds/background2.png
/// lib/backgrounds/background3.png
/// ```
///
/// To include, say the first image, the `pubspec.yaml` of the app should specify
/// it in the `assets` section:

9
packages/flutter/lib/src/painting/image_stream.dart
View File

@ -62,9 +62,11 @@ class ImageInfo {
/// {@tool snippet}
///
/// The following sample shows how to appropriately check whether the
/// [ImageInfo] reference refers to new image data or not.
/// [ImageInfo] reference refers to new image data or not (in this case in a
/// setter).
///
/// ```dart
/// ImageInfo? get imageInfo => _imageInfo;
/// ImageInfo? _imageInfo;
/// set imageInfo (ImageInfo? value) {
/// // If the image reference is exactly the same, do nothing.
@ -78,9 +80,12 @@ class ImageInfo {
/// value.dispose();
/// return;
/// }
/// // It is a new image. Dispose of the old one and take a reference
/// // to the new one.
/// _imageInfo?.dispose();
/// _imageInfo = value;
/// // Perform work to determine size, or paint the image.
/// // Perform work to determine size, paint the image, etc.
/// // ...
/// }
/// ```
/// {@end-tool}

3
packages/flutter/lib/src/painting/inline_span.dart
View File

@ -12,6 +12,9 @@ import 'text_painter.dart';
import 'text_span.dart';
import 'text_style.dart';
// Examples can assume:
// late InlineSpan myInlineSpan;
/// Mutable wrapper of an integer that can be passed by reference to track a
/// value across a recursive stack.
class Accumulator {

18
packages/flutter/lib/src/painting/matrix_utils.dart
View File

@ -235,12 +235,12 @@ class MatrixUtils {
// First, consider that a full point transform using the vector math
// package involves expanding it out into a vector3 with a Z coordinate
// of 0.0 and then performing 3 multiplies and 3 adds per coordinate:
// ```
//
// xt = x*m00 + y*m10 + z*m20 + m30;
// yt = x*m01 + y*m11 + z*m21 + m31;
// zt = x*m02 + y*m12 + z*m22 + m32;
// wt = x*m03 + y*m13 + z*m23 + m33;
// ```
//
// Immediately we see that we can get rid of the 3rd column of multiplies
// since we know that Z=0.0. We can also get rid of the 3rd row because
// we ignore the resulting Z coordinate. Finally we can get rid of the
@ -307,7 +307,7 @@ class MatrixUtils {
// you combine both of them, the resulting "opposite corner" will
// actually be between the limits they established by pushing the walls
// away from each other, as below:
// ```
//
// +---------(originx,originy)--------------+
// | -----^---- |
// | ----- ---- |
@ -320,13 +320,13 @@ class MatrixUtils {
// | ---- ----- |
// | v |
// +---------------(+wx+hx,+wy+hy)----------+
// ```
//
// In this diagram, consider that:
// ```
// wx would be a positive number
// hx would be a negative number
// wy and hy would both be positive numbers
// ```
//
// * wx would be a positive number
// * hx would be a negative number
// * wy and hy would both be positive numbers
//
// As a result, wx pushes out the right wall, hx pushes out the left wall,
// and both wy and hy push down the bottom wall of the bounding box. The
// wx,hx pair (of opposite signs) worked on opposite walls and the final

5
packages/flutter/lib/src/painting/text_span.dart
View File

@ -12,6 +12,9 @@ import 'basic_types.dart';
import 'inline_span.dart';
import 'text_painter.dart';
// Examples can assume:
// late TextSpan myTextSpan;
/// An immutable span of text.
///
/// A [TextSpan] object can be styled using its [style] property. The style will
@ -214,7 +217,7 @@ class TextSpan extends InlineSpan implements HitTestTarget, MouseTrackerAnnotati
/// text value:
///
/// ```dart
/// TextSpan(text: r'$$', semanticsLabel: 'Double dollars')
/// const TextSpan(text: r'$$', semanticsLabel: 'Double dollars')
/// ```
final String? semanticsLabel;

6
packages/flutter/lib/src/painting/text_style.dart
View File

@ -357,9 +357,7 @@ const double _kDefaultFontSize = 14.0;
/// the app can use these selectively when declaring a font. Suppose a package
/// named `my_package` has:
///
/// ```
/// lib/fonts/Raleway-Medium.ttf
/// ```
///
/// Then the app can declare a font like in the example below:
///
@ -790,9 +788,9 @@ class TextStyle with Diagnosticable {
/// For example, to control the weight axis of the Roboto Slab variable font
/// (https://fonts.google.com/specimen/Roboto+Slab):
/// ```dart
/// TextStyle(
/// const TextStyle(
/// fontFamily: 'RobotoSlab',
/// fontVariations: <FontVariation>[FontVariation('wght', 900.0)]
/// fontVariations: <ui.FontVariation>[ui.FontVariation('wght', 900.0)]
/// )
/// ```
final List<ui.FontVariation>? fontVariations;

30
packages/flutter/lib/src/rendering/box.dart
View File

@ -14,6 +14,11 @@ import 'package:vector_math/vector_math_64.dart';
import 'debug.dart';
import 'object.dart';
// Examples can assume:
// abstract class RenderBar extends RenderBox { }
// late RenderBox firstChild;
// void markNeedsLayout() { }
// This class should only be used in debug builds.
class _DebugSize extends Size {
_DebugSize(super.source, this._owner, this._canBeUsedByParent) : super.copy();
@ -994,11 +999,12 @@ class _IntrinsicDimensionsCacheEntry {
///
/// ```dart
/// AxisDirection get axis => _axis;
/// AxisDirection _axis;
/// AxisDirection _axis = AxisDirection.down; // or initialized in constructor
/// set axis(AxisDirection value) {
/// assert(value != null); // same check as in the constructor
/// if (value == _axis)
/// assert(value != null); // same checks as in the constructor
/// if (value == _axis) {
/// return;
/// }
/// _axis = value;
/// markNeedsLayout();
/// }
@ -1135,6 +1141,7 @@ class _IntrinsicDimensionsCacheEntry {
/// The declaration of the `RenderFoo` class itself would thus look like this:
///
/// ```dart
/// // continuing from previous example...
/// class RenderFoo extends RenderBox with
/// ContainerRenderObjectMixin<RenderBox, FooParentData>,
/// RenderBoxContainerDefaultsMixin<RenderBox, FooParentData> {
@ -1148,9 +1155,10 @@ class _IntrinsicDimensionsCacheEntry {
/// children's [parentData] fields):
///
/// ```dart
/// RenderBox child = firstChild;
/// // continuing from previous example...
/// RenderBox? child = firstChild;
/// while (child != null) {
/// final FooParentData childParentData = child.parentData;
/// final FooParentData childParentData = child.parentData! as FooParentData;
/// // ...operate on child and childParentData...
/// assert(child.parentData == childParentData);
/// child = childParentData.nextSibling;
@ -2675,11 +2683,17 @@ abstract class RenderBox extends RenderObject {
/// so that they support [debugPaintPointersEnabled]:
///
/// ```dart
/// class RenderFoo extends RenderBox {
/// // ...
///
/// @override
/// void handleEvent(PointerEvent event, HitTestEntry entry) {
/// assert(debugHandleEvent(event, entry));
/// // ... handle the event ...
/// }
///
/// // ...
/// }
/// ```
@override
void handleEvent(PointerEvent event, BoxHitTestEntry entry) {
@ -2694,11 +2708,17 @@ abstract class RenderBox extends RenderObject {
/// [debugHandleEvent] from their [handleEvent] method, as follows:
///
/// ```dart
/// class RenderFoo extends RenderBox {
/// // ...
///
/// @override
/// void handleEvent(PointerEvent event, HitTestEntry entry) {
/// assert(debugHandleEvent(event, entry));
/// // ... handle the event ...
/// }
///
/// // ...
/// }
/// ```
///
/// If you call this for a [PointerDownEvent], make sure you also call it for

22
packages/flutter/lib/src/services/deferred_component.dart
View File

@ -6,6 +6,10 @@ import 'dart:async';
import 'system_channels.dart';
// Examples can assume:
// // so that we can import the fake "split_component.dart" in an example below:
// // ignore_for_file: uri_does_not_exist
/// Manages the installation and loading of deferred components.
///
/// Deferred components allow Flutter applications to download precompiled AOT
@ -41,13 +45,17 @@ class DeferredComponent {
/// the assets from a component with both dart code and assets. Deferred components
/// containing dart code should call `loadLibrary()` on a deferred imported
/// library's prefix to ensure that the dart code is properly loaded as
/// `loadLibrary()` will provide the loading unit id needed for the dart
/// `loadLibrary()` will provide the loading unit ID needed for the Dart
/// library loading process. For example:
///
/// ```dart
/// import 'split_component.dart' deferred as SplitComponent;
/// ...
/// SplitComponent.loadLibrary();
/// import 'split_component.dart' deferred as split_component;
/// // ...
/// void _showSplit() {
/// // ...
/// split_component.loadLibrary();
/// // ...
/// }
/// ```
///
/// This method will not load associated dart libraries contained in the component,
@ -60,9 +68,9 @@ class DeferredComponent {
/// See also:
///
/// * [uninstallDeferredComponent], a method to request the uninstall of a component.
/// * [loadLibrary](https://api.dart.dev/dart-mirrors/LibraryDependencyMirror/loadLibrary.html),
/// the dart method to trigger the installation of the corresponding deferred component that
/// contains the dart library.
/// * [loadLibrary](https://dart.dev/guides/language/language-tour#lazily-loading-a-library),
/// the Dart method to trigger the installation of the corresponding deferred component that
/// contains the Dart library.
static Future<void> installDeferredComponent({required String componentName}) async {
await SystemChannels.deferredComponent.invokeMethod<void>(
'installDeferredComponent',

2
packages/flutter/lib/src/services/message_codec.dart
View File

@ -137,7 +137,7 @@ class PlatformException implements Exception {
///
/// ```dart
/// try {
/// ...
/// // ...
/// } catch (e, stacktrace) {
/// print(stacktrace);
/// }

2
packages/flutter/lib/src/services/system_channels.dart
View File

@ -409,7 +409,7 @@ class SystemChannels {
/// a list of [MenuItem]s, and ends up looking like this example:
///
/// ```dart
/// List<Map<String, Object?>> menu = <String, Object?>{
/// Map<String, Object?> menu = <String, Object?>{
/// '0': <Map<String, Object?>>[
/// <String, Object?>{
/// 'id': 1,

17
packages/flutter/lib/src/services/text_formatter.dart
View File

@ -14,6 +14,14 @@ export 'package:flutter/foundation.dart' show TargetPlatform;
export 'text_input.dart' show TextEditingValue;
// Examples can assume:
// late RegExp _pattern;
/// Mechanisms for enforcing maximum length limits.
///
/// This is used by [TextField] to specify how the [TextField.maxLength] should
/// be applied.
///
/// {@template flutter.services.textFormatter.maxLengthEnforcement}
/// ### [MaxLengthEnforcement.enforced] versus
/// [MaxLengthEnforcement.truncateAfterCompositionEnds]
@ -227,9 +235,16 @@ class _TextEditingValueAccumulator {
/// [TextEditingValue] and falls back to the current [TextEditingValue] when the
/// given [filterPattern] fails to match. Consider using a different
/// [TextInputFormatter] such as:
///
/// ```dart
/// TextInputFormatter.withFunction((oldValue, newValue) => regExp.hasMatch(newValue.text) ? newValue : oldValue)
/// // _pattern is a RegExp or other Pattern object
/// TextInputFormatter.withFunction(
/// (TextEditingValue oldValue, TextEditingValue newValue) {
/// return _pattern.hasMatch(newValue.text) ? newValue : oldValue;
/// },
/// ),
/// ```
///
/// for accepting/rejecting new input based on a predicate on the full string.
/// As an example, [FilteringTextInputFormatter] typically shouldn't be used
/// with [RegExp]s that contain positional matchers (`^` or `$`) since these

5
packages/flutter/lib/src/services/text_input.dart
View File

@ -1248,7 +1248,9 @@ mixin DeltaTextInputClient implements TextInputClient {
/// This example shows what an implementation of this method could look like.
///
/// ```dart
/// class MyClient with DeltaTextInputClient {
/// TextEditingValue? _localValue;
///
/// @override
/// void updateEditingValueWithDeltas(List<TextEditingDelta> textEditingDeltas) {
/// if (_localValue == null) {
@ -1260,6 +1262,9 @@ mixin DeltaTextInputClient implements TextInputClient {
/// }
/// _localValue = newValue;
/// }
///
/// // ...
/// }
/// ```
/// {@end-tool}
void updateEditingValueWithDeltas(List<TextEditingDelta> textEditingDeltas);

14
packages/flutter/lib/src/widgets/actions.dart
View File

@ -260,12 +260,12 @@ abstract class Action<T extends Intent> with Diagnosticable {
/// changing the return type of the override to match the type of the returned
/// value provides more type safety.
///
/// For instance, if your override of `invoke` returns an `int`, then define
/// it like so:
/// For instance, if an override of `invoke` returned an `int`, then it might
/// be defined like so:
///
/// ```dart
/// class IncrementIntent extends Intent {
/// const IncrementIntent({this.index});
/// const IncrementIntent({required this.index});
///
/// final int index;
/// }
@ -479,19 +479,19 @@ abstract class ContextAction<T extends Intent> extends Action<T> {
/// changing the return type of the override to match the type of the returned
/// value provides more type safety.
///
/// For instance, if your override of `invoke` returns an `int`, then define
/// it like so:
/// For instance, if an override of `invoke` returned an `int`, then it might
/// be defined like so:
///
/// ```dart
/// class IncrementIntent extends Intent {
/// const IncrementIntent({this.index});
/// const IncrementIntent({required this.index});
///
/// final int index;
/// }
///
/// class MyIncrementAction extends ContextAction<IncrementIntent> {
/// @override
/// int invoke(IncrementIntent intent, [BuildContext context]) {
/// int invoke(IncrementIntent intent, [BuildContext? context]) {
/// return intent.index + 1;
/// }
/// }

50
packages/flutter/lib/src/widgets/animated_list.dart
View File

@ -252,11 +252,27 @@ class AnimatedList extends StatefulWidget {
/// can refer to the [AnimatedList]'s state with a global key:
///
/// ```dart
/// // (e.g. in a stateful widget)
/// GlobalKey<AnimatedListState> listKey = GlobalKey<AnimatedListState>();
/// ...
/// AnimatedList(key: listKey, ...);
/// ...
/// listKey.currentState.insert(123);
///
/// // ...
///
/// @override
/// Widget build(BuildContext context) {
/// return AnimatedList(
/// key: listKey,
/// itemBuilder: (BuildContext context, int index, Animation<double> animation) {
/// return const Placeholder();
/// },
/// );
/// }
///
/// // ...
///
/// void _updateList() {
/// // adds "123" to the AnimatedList
/// listKey.currentState!.insertItem(123);
/// }
/// ```
///
/// [AnimatedList] item input handlers can also refer to their [AnimatedListState]
@ -440,11 +456,27 @@ class SliverAnimatedList extends StatefulWidget {
/// can refer to the [SliverAnimatedList]'s state with a global key:
///
/// ```dart
/// GlobalKey<SliverAnimatedListState> listKey = GlobalKey<SliverAnimatedListState>();
/// ...
/// SliverAnimatedList(key: listKey, ...);
/// ...
/// listKey.currentState.insert(123);
/// // (e.g. in a stateful widget)
/// GlobalKey<AnimatedListState> listKey = GlobalKey<AnimatedListState>();
///
/// // ...
///
/// @override
/// Widget build(BuildContext context) {
/// return AnimatedList(
/// key: listKey,
/// itemBuilder: (BuildContext context, int index, Animation<double> animation) {
/// return const Placeholder();
/// },
/// );
/// }
///
/// // ...
///
/// void _updateList() {
/// // adds "123" to the AnimatedList
/// listKey.currentState!.insertItem(123);
/// }
/// ```
///
/// [SliverAnimatedList] item input handlers can also refer to their

5
packages/flutter/lib/src/widgets/app.dart
View File

@ -33,6 +33,9 @@ import 'widget_inspector.dart';
export 'dart:ui' show Locale;
// Examples can assume:
// late Widget myWidget;
/// The signature of [WidgetsApp.localeListResolutionCallback].
///
/// A [LocaleListResolutionCallback] is responsible for computing the locale of the app's
@ -947,7 +950,7 @@ class WidgetsApp extends StatefulWidget {
///
/// ```dart
/// // Full Chinese support for CN, TW, and HK
/// supportedLocales: [
/// supportedLocales: <Locale>[
/// const Locale.fromSubtags(languageCode: 'zh'), // generic Chinese 'zh'
/// const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans'), // generic simplified Chinese 'zh_Hans'
/// const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant'), // generic traditional Chinese 'zh_Hant'

Some files were not shown because too many files have changed in this diff Show More