Commit Graph

3422 Commits

Author SHA1 Message Date
lsaudon
7cab354def
Deletes files that should be ignored (#127984)
Some files are supposed to ignore, but don't.

- **/windows/flutter/generated_plugins.cmake
- **/linux/flutter/generated_plugin_registrant.cc
- **/linux/flutter/generated_plugin_registrant.h
- **/linux/flutter/generated_plugins.cmake
- **/windows/flutter/generated_plugin_registrant.cc
- **/windows/flutter/generated_plugin_registrant.h
- **/ios/Runner/GeneratedPluginRegistrant.h
- **/ios/Runner/GeneratedPluginRegistrant.m

*List which issues are fixed by this PR. You must list at least one issue.*

*If you had to change anything in the [flutter/tests] repo, include a link to the migration guide as per the [breaking change policy].*
2023-06-29 19:45:22 +00:00
Jia Tan
87194a2301
Fix typos in ListTile examples. (#129606)
Fix typos.

*If you had to change anything in the [flutter/tests] repo, include a link to the migration guide as per the [breaking change policy].*
2023-06-29 06:29:03 +00:00
Hans Muller
0d4b5ae122
Dev, examples/api, etc updated for Material 3 by default (#129683)
Updated tests in dev, examples/api, and tests/widgets to ensure that
they continue to pass when the default for `ThemeData.useMaterial3` is
changed to true.

This is the final set of changes required for
https://github.com/flutter/flutter/issues/127064.
2023-06-28 09:41:58 -07:00
Hans Muller
548fe14730
Updated TextMagnifierExampleApp to M3 (#129381) 2023-06-26 10:44:11 -07:00
Renzo Olivares
b36ef583fb
Selection area right click behavior should match native (#128224)
This change updates `SelectableRegion`s right-click gesture to match native platform behavior.

Before: Right-click gesture selects word at position and opens context menu (All Platforms)
After: 
- Linux, toggles context menu on/off, and collapses selection when click was not on an active selection (uncollapsed).
- Windows, Android, Fuchsia, shows context menu at right-clicked position (unless the click is at an active selection).
- macOS, toggles the context menu if right click was at the same position as the previous / or selects word at position and opens context menu.
- iOS, selects word at position and opens context menu.

This change also prevents the `copy` menu button from being shown when there is a collapsed selection (nothing to copy).

Fixes #117561
2023-06-21 19:32:04 +00:00
Tae Hyung Kim
541fdd60d3
DecoratedSliver (#127823)
This is a second attempt to merge #107269. Currently I've fixed two of the issues:
1. Fixed horizontal scrollview by using a switch statement to consider vertical/horizontal case.
2. Fixed issue of `paintExtent` not being the right extent for painting. Rather using a `scrollExtent` for the main axis length of the decoration box and painting it offsetted by the `scrollOffset`.
3. If the sliver child has inifinite scrollExtent, then we only draw the decoration down to the bottom of the `cacheExtent`. The developer is expected to ensure that the border does not creep up above the cache area.

This PR includes a test that checks that the correct rectangle is drawn at a certain scrollOffset for both the horizontal and vertical case which should be sufficient for checking that `SliverDecoration` works properly now.

Fixes https://github.com/flutter/flutter/issues/107498.
2023-06-20 23:35:42 +00:00
Chris Yang
fadcaee842
iOS info.plist template: make UIViewControllerBasedStatusBar to be true (#128970)
Now that we support UIViewControllerBasedStatusBar by default (after engine roll: c7167765d7), we should make this value to be true.

Part of https://github.com/flutter/flutter/issues/128969
2023-06-20 18:11:18 +00:00
Qun Cheng
c3b2175a40
Update golden tests (#128914) 2023-06-15 13:09:43 -07:00
Mouad Debbar
a162d7546a
flutter update-packages --force-upgrade (#128908)
- Bumps `vm_service` from `11.6.0` to `11.7.1`
- Bumps `web` from `0.1.3-beta` to `0.1.4-beta` and adds it everywhere.
- Moves `js` from `dependencies` to `dev_dependencies`
2023-06-15 18:17:09 +00:00
Hans Muller
ce248e87f9
Update misc tests for Material3 (#128712) 2023-06-13 08:57:27 -07:00
Greg Spencer
a280346193
Add AppLifecycleListener, with support for application exit handling (#123274)
## Description

This adds `AppLifecycleListener`, a class for listening to changes in the application lifecycle, and responding to requests to exit the application.

It depends on changes in the Engine that add new lifecycle states: https://github.com/flutter/engine/pull/42418

Here's a diagram for the lifecycle states. I'll add a similar diagram to the documentation for these classes.

![Application Lifecycle Diagram](https://github.com/flutter/flutter/assets/8867023/f6937002-cb93-4ab9-a221-25de2c45cf0e)

## Related Issues
 - https://github.com/flutter/flutter/issues/30735

## Tests
- Added tests for new lifecycle value, as well as for the `AppLifecycleListener` itself.
2023-06-08 22:57:19 +00:00
Tae Hyung Kim
f2351f61d4
Sliver Main Axis Group (#126596)
This widget implements the ability to place slivers one after another in
a single ScrollView in a way that all child slivers are drawn within the
bounds of the group itself (i.e. SliverPersistentHeaders aren't drawn
outside of the scroll extent provided by all of the child slivers). The
design document for SliverMainAxisGroup can be found
[here](https://docs.google.com/document/d/1e2bdLSYV_Dq2h8aHpF8mda67aOmZocPiMyjCcTTZhTg/edit?resourcekey=0-Xj2X2XA3CAFae22Sv3hAiA).

Fixes https://github.com/flutter/flutter/issues/33137.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[test-exempt]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat

---------

Co-authored-by: Kate Lovett <katelovett@google.com>
2023-06-08 15:54:09 -07:00
Jackson Gardner
7c15a26eab
Reland "Migrate benchmarks to package:web" (#128266)
This attempts to reland https://github.com/flutter/flutter/pull/126848

This was reverted because it made some unexpected changes to our perf measurements. After landing https://github.com/flutter/flutter/pull/127900, we have much less noise in our benchmarks, so I'd like to reland this and see if there is still a significant measurement difference.
2023-06-08 22:25:40 +00:00
Greg Spencer
36f73cf645
Disable context menu (#128365)
## Description

Changes the context menu example for `MenuAnchor` so that it uses right-click, or (on macOS and iOS only) ctrl-left-click, for the context menu. Also disables the browser context menu on web platforms.

## Tests
 - Updated test to reflect new triggers.
2023-06-07 23:40:17 +00:00
Leigha Jarett
6848110ff3
Update menu API docs to help developers migrate to m3 (#128351)
Fixes: https://github.com/flutter/flutter/issues/127215
2023-06-07 13:21:12 +00:00
Michael Goderbauer
6221d5c709
Refactor tests (#128371)
To make them a little more resilient to changes in the tree shape as the tree will be changing a little bit for multi view.
2023-06-07 03:02:55 +00:00
Leigha Jarett
32a1c275df
Adding example for migrating to navigation drawer (#128295)
Fixes https://github.com/flutter/flutter/issues/127214
2023-06-06 19:23:19 +00:00
Leigha Jarett
6c8cf3a9d0
Migration guide for moving from BottomNavigationBar to NavigationBar (#128263)
Fixes https://github.com/flutter/flutter/issues/127213
2023-06-06 03:52:07 +00:00
Hans Muller
4464d09db0
Updated TabBar and ToggleButtons examples (#128088)
Updated the ToggleButtons example and test to M3.

Updated the nested tabs test to avoid warnings like:
```
Warning: A call to tap() with finder "exactly one widget with type "Tab" which is an ancestor of text "Explore": Tab(text: "Explore", icon: Icon)" derived an Offset (Offset(666.7, 92.0)) that would not hit test on the specified widget.
```
2023-06-02 01:05:31 +00:00
Hans Muller
14136ae319
Updated custom ListTile examples (#128071) 2023-06-01 16:21:42 -07:00
Hans Muller
f0e32fc6ca
Updated Menu examples (#128080) 2023-06-01 15:27:34 -07:00
Hans Muller
420f442e5c
Updated InputDecoratorExamples for M3 (#128065) 2023-06-01 15:22:03 -07:00
Hans Muller
1a098ae8eb
Revised Floating Action Button examples (#128058)
Of the original 4 examples, the first 3 mostly covered the same API features and occupied quite a bit of real-estate at the top of https://api.flutter.dev/flutter/material/FloatingActionButton-class.html.  Additionally the illustrations and the code samples didn't match in some cases.

Replaced examples 0,1,2 with one example that changes attributes of the FAB when it's pushed. 

Fixes https://github.com/flutter/flutter/issues/128048
2023-06-01 22:16:48 +00:00
Loïc Sharma
071ea49248
[Windows] Address feedback for show window comment (#127998)
Address Tong's feedback here: https://github.com/flutter/flutter/issues/127695#issuecomment-1564884872

Follow-up to: https://github.com/flutter/flutter/pull/127046
2023-05-31 23:42:54 +00:00
Christopher Fujino
0763d61f56
[flutter_tools] manually roll pub deps (#127447)
Fixes https://github.com/flutter/flutter/issues/127226
2023-05-30 23:34:52 +00:00
Taha Tesser
9bce790162
Updated the ToggleButtons API doc to link to SegmentedButton (#127021)
fixes https://github.com/flutter/flutter/issues/124884
2023-05-27 00:27:19 +00:00
Phil Quitslund
5bf6318688
Update collection-fors to prefer final (as per updated prefer_final_in_for_each) (#127511)
The newly updated lint will soon flag for-each in collections.

See discussion: https://github.com/dart-lang/linter/pull/4383

/cc @goderbauer
2023-05-26 23:34:36 +00:00
Chris Bracken
be9dbfa994
[Linux] Use up_client_get_devices2 when possible (#127699)
The Linux platform channels sample makes a call to the libupower function `up_client_get_devices`, which was deprecated in libupower 0.99.8 in favour of `up_client_get_devices2`.

In order to build both for users on older versions of libupower, such as 0.99.7, which ships with Ubuntu 18.04 (Bionic), as well as users on newer versions where `up_client_get_devices` is deprecated, this adds a preprocessor check and selects the function available on the host system on which the build takes place.

The Flutter devicelab prod bots have been migrated to Ubuntu 20.04 LTS (Focal) which includes 0.99.11, but the trybots are still in the process of being migrated. This allows the build to work on both, and makes life easier for users running on a variety of Linux distributions.

No tests are added or modified since `up_client_get_devices` and `up_client_get_devices2` have the same semantics.

See: https://upower.freedesktop.org/docs/UpClient.html#up-client-get-devices
See: https://gitlab.freedesktop.org/upower/upower/-/blob/master/libupower-glib/up-version.h.in

Note: the `UP_CHECK_VERSION` macro has been around since 2010 (13 years ago), when DKP was forked into libupower. 27fada20be

Issue: https://github.com/flutter/flutter/issues/127611
2023-05-26 19:19:04 +00:00
Taha Tesser
c05a05e6fc
Add ScrollNotificationObserver sample (#127023)
fixes https://github.com/flutter/flutter/issues/126702

### Preview

https://github.com/flutter/flutter/assets/48603081/4c529a0d-b8a5-4950-9095-429f1c5eccbb
2023-05-25 15:58:52 +00:00
LongCatIsLooong
1b800fd496
Remove Tooltip mouse tracker listener & update hovering/MouseRegion logic & animation (#119199)
Fixes https://github.com/flutter/flutter/issues/117627

### Behavior changes:
1. If fade in/fade out animation is already in progress, hiding/showing the tooltip will immediately take effect without waiting for `waitDuration`.
2. A PointerDownEvent that doesn't become a part of a "trigger" gesture dismisses the tooltip, even for hovered ones.
3. The OverlayEntry is now updated only when the previous tooltip was completely dismissed. This can be fixed by OverlayPortal but I'm not sure what the correct behavior is.
2023-05-25 07:24:45 +00:00
Sun Jiao
7b67aa587a
make suggestionsBuilder in SearchAnchor asyncable (#127019) 2023-05-24 13:12:47 -07:00
Chris Bracken
edf4a91f5f
[Linux] Ignore deprecation of libupower call in example (#127503)
The Linux platform channels sample makes a call to the libupower
function `up_client_get_devices`, which was deprecated in libupower
0.99.8 in favour of `up_client_get_devices2`.

The prod bots have been migrated to focal, which ships libupower 0.99.11
in which the old function is deprecated and the new one is available.

The try bots have not yet been migrated and remain on bionic, which
ships libupower 0.99.7 in which the old function is not deprecated and
the new one is not available.

This marks the line in question to ignore deprecation warnings. Once all
bots have migrated to focal, we'll migrate to the new function. See
tracking issue below.

See:
https://upower.freedesktop.org/docs/UpClient.html#up-client-get-devices

Issue: https://github.com/flutter/flutter/issues/127506

## Pre-launch Checklist

- [X] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [X] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [X] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [X] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [X] I updated/added relevant documentation (doc comments with `///`).
- [ ] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [X] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[test-exempt]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat
2023-05-24 11:44:05 -07:00
Justin McCandless
f6f5bb9023
Fix bug in Autocomplete example (#127219)
This example was incorrectly throwing away results from a query when multiple queries were pending at once.   Thanks to @sun-jiao in https://github.com/flutter/flutter/pull/127019#issuecomment-1552347037 for pointing this out.

I also added a quick  `Text` widget explaining what to do to use the examples.  Since there are only three small possible `options`, it's easy to type into the field and not get any results and wonder what's wrong.
2023-05-22 16:55:21 +00:00
Loïc Sharma
ce61eda70c
[Windows] Ensure window is shown (#127046)
## Background

The Windows runner has a race at startup:

1. **Platform thread**: creates a hidden window
2. **Platform thread**: launches the Flutter engine
3. **UI/Raster threads**: renders the first frame
4. **Platform thread**: Registers a callback to show the window once the next frame has been rendered.

Steps 3 and 4 happen in parallel and it is possible for step 3 to complete before step 4 starts. In this scenario, the next frame callback is never called and the window is never shown.

As a result the `windows_startup_test`'s test, which [verifies that the "show window" callback is called](1f09a8662d/dev/integration_tests/windows_startup_test/windows/runner/flutter_window.cpp (L60-L64)), can flake if the first frame is rendered before the show window callback has been registered.

## Solution

This change makes the runner schedule a frame after it registers the next frame callback. If step 3 hasn't completed yet, this no-ops as a frame is already scheduled. If step 3 has already completed, a new frame will be rendered, which will call the next frame callback and show the window.

Part of https://github.com/flutter/flutter/issues/119415

See this thread for alternatives that were considered: https://github.com/flutter/engine/pull/42061#issuecomment-1550080722
2023-05-19 22:25:55 +00:00
Loïc Sharma
718f444bc3
[Windows] Improve version migration message (#127048)
This also migrates the platform channel example to stamp version information on Windows.
2023-05-17 23:07:16 +00:00
Justin McCandless
9d882983ff
Autocomplete async examples (#126283)
Added examples clarifying how to fetch Autocomplete options asynchronously.
2023-05-17 09:46:26 -07:00
Ian Hickson
027bb84444
Make SlottedMultiChildRenderObjectWidgetMixin a concrete class (#126108)
This is a proof of concept for renaming SlottedMultiChildRenderObjectWidgetMixin to SlottedMultiChildRenderObjectWidget and making it a concrete class.

I also made SlottedContainerRenderObjectMixin generic instead of being specialized to RenderBox.

I don't think this is something we can easily automigrate, but we may not need to, I don't know how common this is...
2023-05-16 22:28:54 +00:00
Polina Cherkasova
ea5eddb5a9
Upgrade leak_tracker to 5.0.0 (#126367)
Fixes https://github.com/flutter/flutter/issues/126259

Updated pubspec:
345f0bffbf/packages/flutter/pubspec.yaml
2023-05-16 04:39:26 +00:00
Kate Lovett
27caa7fed9
Add ScrollController.onAttach & onDetach, samples/docs on listening/getting scrolling info (#124823)
This PR does a couple of things!

https://user-images.githubusercontent.com/16964204/231897483-416287f9-50ce-468d-a714-2a4bc0f2e011.mov

![Screenshot 2023-04-13 at 3 24 28 PM](https://user-images.githubusercontent.com/16964204/231897497-f5bee17d-43ed-46e5-acd7-e1bd64768274.png)

Fixes #20819 
Fixes #41910 
Fixes #121419

### Adds ScrollController.onAttach and ScrollController.onDetach

This resolves a long held pain point for developers. When using a scroll controller, there is not scroll position until the scrollable widget is built, and almost all methods of notification are only triggered when scrolling happens. Adding these two methods will help developers gain access to the scroll position when it is created. A common workaround for this was using a post frame callback to access controller.position after the first frame, but this is ripe for issues such as having multiple positions attached to the controller, or the scrollable no longer existing after that post frame callback. I think this can also be helpful for folks to debug cases when the scroll controller has multiple positions attached.

In particular, this also resolves this commented case: https://github.com/flutter/flutter/issues/20819#issuecomment-417784218
The isScrollingNotifier is hard for developers to access.

### Docs & samples

I was surprised we did not have samples on scroll notification or scroll controller, so I overhauled it and added a lot of docs on all the different ways to access scrolling information, when it is available and how they differ.
2023-05-15 21:01:06 +00:00
Taha Tesser
12659f2a7b
Fix MultiChildLayoutDelegate.hasChild doc (#126433)
fixes https://github.com/flutter/flutter/issues/115898

`hasChild` checks `_idToChild` map.  `_idToChild` is not assigned until `_callPerformLayout` is called.
So `hasChild` shouldn't be called in `getSize`.

df789c9e76/packages/flutter/lib/src/rendering/custom_layout.dart (L400-L404)

Updated docs and example class names.
2023-05-11 14:59:07 +00:00
Michael Goderbauer
58454e9e31
Remove dead code (#126266)
Dead code was flagged by `unreachable_from_main` lint, which is still experimental and not ready to be enabled yet.
2023-05-09 15:47:16 +00:00
Yu
e11a2213e2
[Refactor] Fix style in example (#126191)
Replaces #125616

I just fixed "IMAGES" to "images" in examples/image_list.
Currently, "PREFER uses the lower case of the constant name ".
2023-05-08 18:57:06 +00:00
Pierre-Louis
65dfb555c0
Update packages (#126140)
In particular, update pin for `material_color_utilities` to `0.5.0`.
2023-05-08 09:51:28 +02:00
Loïc Sharma
a47a754539
Add Windows and Linux support to the 'layers' example (#126105)
Enables running the `layers` example on Linux and Windows.

Part of https://github.com/flutter/flutter/issues/126033
2023-05-06 00:45:19 +00:00
Istiak Ahmed
042eaf6b90
Add sample code for SliverAppBar (#125785)
This PR adds an another example for SliverAppBar, showing the use of stretch and onStretchTrigger

https://user-images.githubusercontent.com/68919043/235420973-2bfb9871-9e05-4d87-9538-941d43178c76.mp4

Fixes #125651 

### Adds sample code for SliverAppBar [stretch, onStretchTrigger]

This PR adds an another simple and easily understandable example code for SliverAppBar.
2023-05-05 18:09:25 +00:00
Bruno Leroux
de2615462c
Add a ReorderableListView example with cards + cleanup existing tests (#126155)
## Description

This PR adds one `ReorderableListView` example to demonstrate how `proxyDecorator` can be used to animate cards elevation.

https://user-images.githubusercontent.com/840911/236468570-d2b33ab3-6b6d-4f8d-90de-778dcf1ad8ce.mp4

For motivation, see https://github.com/flutter/flutter/issues/124729#issuecomment-1521524190.

## Related Issue

Fixes https://github.com/flutter/flutter/issues/124729

## Tests

Adds 1 tests.

This PR also moves some misplaced example tests from `examples/api/test/reorderable_list` to `examples/api/test/material/reorderable_list` (and replaces two existing ones).
2023-05-05 16:39:11 +00:00
Yu
ce32282c0c
Fix typo in README.md (#126053) 2023-05-04 14:58:17 +02:00
Jenn Magder
1861ac470a
Migrate Xcode projects last version checks to Xcode 14.3 (#125827)
1. Add iOS and macOS migration to mark "last upgraded" Xcode version to 14.3 to prevent `Update to recommended settings` warning.
2. Update iOS and macOS templates to same.
3. Update iOS template to set `BuildIndependentTargetsInParallel` to YES as suggested.  I didn't add a migration for this since it seems like a minor optimization and I don't think it's worth a potentially botched/corrupted migration.
4. Run all example/integration test project to see migrator work.
5. Add some missing test projects to the build shard since I noticed they were missing and I had to build those manually outside `SHARD=build_tests`.

Fixes https://github.com/flutter/flutter/issues/125817
See https://github.com/flutter/flutter/pull/90304 for Xcode 13 example.
2023-05-02 00:06:33 +00:00
Tae Hyung Kim
1a0b03cb25
Sliver Cross Axis Group (#123862)
This widget implements the ability to place slivers side by side in a single ScrollView so that they scroll together. The design document for `SliverCrossAxisGroup` can be found [here](https://docs.google.com/document/d/1e2bdLSYV_Dq2h8aHpF8mda67aOmZocPiMyjCcTTZhTg/edit?resourcekey=0-Xj2X2XA3CAFae22Sv3hAiA).

Fixes #56756.
2023-04-28 23:41:58 +00:00
yaakovschectman
7d37f2a616
Opt into CMake policy CMP0135 (#125502)
~Update the windows app template and migration to use `CMP0135` when
cmake version is >= 3.24.~

Update app templates' and examples' CMakeLists.txt to use
`cmake_policy(VERSION`. https://github.com/flutter/packages/pull/3828
should obviate the need for a migration.

Addresses https://github.com/flutter/flutter/issues/116866

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [ ] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[test-exempt]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat
2023-04-28 17:49:54 -04:00