diff --git a/.github/ISSUE_TEMPLATE/ACTIVATION.md b/.github/ISSUE_TEMPLATE/ACTIVATION.md index d9eb503e9a26d..b1ba3d3a8f005 100644 --- a/.github/ISSUE_TEMPLATE/ACTIVATION.md +++ b/.github/ISSUE_TEMPLATE/ACTIVATION.md @@ -18,7 +18,7 @@ assignees: '' * https://stackoverflow.com/questions/tagged/flutter?sort=frequent If you have found a bug or if our documentation doesn't have an answer - to what you're looking for, then fill our the template below. Please read + to what you're looking for, then fill out the template below. Please read our guide to filing a bug first: https://flutter.dev/docs/resources/bug-reports --> diff --git a/.github/ISSUE_TEMPLATE/BUG.md b/.github/ISSUE_TEMPLATE/BUG.md index d35aae0a12521..275decdfdf390 100644 --- a/.github/ISSUE_TEMPLATE/BUG.md +++ b/.github/ISSUE_TEMPLATE/BUG.md @@ -17,7 +17,7 @@ assignees: '' * https://stackoverflow.com/questions/tagged/flutter?sort=frequent If you have found a bug or if our documentation doesn't have an answer - to what you're looking for, then fill our the template below. Please read + to what you're looking for, then fill out the template below. Please read our guide to filing a bug first: https://flutter.dev/docs/resources/bug-reports --> diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index e2ba98238e4b3..0e851e47c1bf3 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -16,7 +16,7 @@ assignees: '' * https://stackoverflow.com/questions/tagged/flutter?sort=frequent If you have found a bug or if our documentation doesn't have an answer - to what you're looking for, then fill our the template below. Please read + to what you're looking for, then fill out the template below. Please read our guide to filing a bug first: https://flutter.dev/docs/resources/bug-reports --> @@ -29,7 +29,7 @@ assignees: '' Is your feature request related to a problem? Please give a clear and concise description of what the problem is. - Describe alternative solutions you've considered. Is there a package + Describe the alternative solutions you've considered. Is there a package on pub.dev/flutter that already solves this? --> diff --git a/.github/ISSUE_TEMPLATE/performance_others.md b/.github/ISSUE_TEMPLATE/performance_others.md index 56afd3287d48c..1ab260b051f25 100644 --- a/.github/ISSUE_TEMPLATE/performance_others.md +++ b/.github/ISSUE_TEMPLATE/performance_others.md @@ -15,7 +15,7 @@ assignees: '' * https://api.flutter.dev/ * https://stackoverflow.com/questions/tagged/flutter?sort=frequent - If you have found a performance problem, then fill our the template below. + If you have found a performance problem, then fill out the template below. Please read our guide to filing a bug first: https://flutter.dev/docs/resources/bug-reports --> @@ -39,7 +39,7 @@ assignees: '' **Target Platform:** diff --git a/.github/ISSUE_TEMPLATE/performance_speed.md b/.github/ISSUE_TEMPLATE/performance_speed.md index b4fb81ba2cae0..bd734aeceb56b 100644 --- a/.github/ISSUE_TEMPLATE/performance_speed.md +++ b/.github/ISSUE_TEMPLATE/performance_speed.md @@ -16,7 +16,7 @@ assignees: '' * https://api.flutter.dev/ * https://stackoverflow.com/questions/tagged/flutter?sort=frequent - If you have found a performance problem, then fill our the template below. + If you have found a performance problem, then fill out the template below. Please read our guide to filing a bug first: https://flutter.dev/docs/resources/bug-reports --> diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ed84a1b446586..dcfc2f9c8c2f9 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -10,12 +10,12 @@ I added the following tests: -*Replace this with a list of the tests that you added as part of this PR. A change in behaviour with no test covering it +*Replace this with a list of the tests that you added as part of this PR. A change in behavior with no test covering it will likely get reverted accidentally sooner or later. PRs must include tests for all changed/updated/fixed behaviors. See [Test Coverage].* ## Checklist -Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes (`[x]`). This will ensure a smooth and quick review process. +Before you create this PR, confirm that it meets all requirements listed below by checking the relevant checkboxes (`[x]`). This will ensure a smooth and quick review process. - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] I signed the [CLA]. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index d33c506e2eaef..33ac1da6a3cf7 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -44,6 +44,6 @@ an expert in all the systems. Once you find the answer, document it in the first place you looked. That way, the next person will be brought up to speed even quicker. -!["I try not to make fun of people for admitting they don't know things, because for each thing 'everyone knows' by the time they're adults, every day there are, on average, 10,000 people in the US hearing about it for the first time. If I make fun of people, I train them not to tell me when they have those moments. And I miss out on the fun." "Diet coke and mentos thing? What's that?" "Oh man! We're going to the grocery store." "Why?" "You're one of today's lucky 10,000."](https://imgs.xkcd.com/comics/ten_thousand.png) +!["I try not to make fun of people for admitting they don't know things, because for each thing 'everyone knows' by the time they're adults, every day there are, on average, 10,000 people in the US hearing about it for the first time. If I make fun of people, I train them not to tell me when they have those moments. And I miss out on the fun." "Diet coke and mentos thing? What's that?" "Oh, man! We're going to the grocery store." "Why?" "You're one of today's lucky 10,000."](https://imgs.xkcd.com/comics/ten_thousand.png) Source: _[xkcd, May 2012](https://xkcd.com/1053/)_ diff --git a/README.md b/README.md index 23f7be70124e6..663834a05688f 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Twitter handle][]][Twitter badge] Flutter is Google's SDK for crafting beautiful, fast user experiences for -mobile, web and desktop from a single codebase. Flutter works with existing +mobile, web, and desktop from a single codebase. Flutter works with existing code, is used by developers and organizations around the world, and is free and open source. @@ -30,8 +30,8 @@ extensible and open development model. We want to enable designers to deliver their full creative vision without being forced to water it down due to limitations of the underlying framework. Flutter's [layered architecture] gives you control over every pixel on the -screen, and its powerful compositing capabilities let you overlay and animate -graphics, video, text and controls without limitation. Flutter includes a full +screen and its powerful compositing capabilities let you overlay and animate +graphics, video, text, and controls without limitation. Flutter includes a full [set of widgets][widget catalog] that deliver pixel-perfect experiences on both iOS and Android. @@ -39,8 +39,8 @@ iOS and Android. ### Fast results -Flutter is fast. It's powered by the same hardware-accelerated [Skia] 2D -graphics library that underpins Chrome and Android. We architected Flutter to +Flutter is fast. It's powered by the same hardware-accelerated 2D graphics +library that underpins Chome and Android: [Skia]. We architected Flutter to support glitch-free, jank-free graphics at the native speed of your device. Flutter code is powered by the world-class [Dart platform], which enables compilation to 32-bit and 64-bit ARM machine code for iOS and Android, as well @@ -57,13 +57,13 @@ and see the results instantly without restarting your app or losing its state. ### Extensible and open model -Flutter works with any development tool (or none at all), but includes editor +Flutter works with any development tool (or none at all) but includes editor plug-ins for both [Visual Studio Code] and [IntelliJ / Android Studio]. Flutter provides [thousands of packages][Flutter packages] to speed your development, regardless of your target platform. And accessing other native code is easy, with support for both [FFI] and [platform-specific APIs][platform channels]. -Flutter is a fully open source project, and we welcome contributions. +Flutter is a fully open-source project, and we welcome contributions. Information on how to get started can be found at our [contributor guide](CONTRIBUTING.md). diff --git a/dev/README.md b/dev/README.md index 3c287dd6924da..e48142ead6081 100644 --- a/dev/README.md +++ b/dev/README.md @@ -1,7 +1,7 @@ This directory contains tools and resources that the Flutter team uses -during development of the framework. The tools in this directory +during the development of the framework. The tools in this directory should not be necessary for developing Flutter applications, though of -course they may be interesting if you are curious. +course, they may be interesting if you are curious. The tests in this directory are run in the `framework_tests_misc-*` shards. diff --git a/dev/automated_tests/flutter_test/README.md b/dev/automated_tests/flutter_test/README.md index 6c1ace42024d2..c3ffa859e7ae8 100644 --- a/dev/automated_tests/flutter_test/README.md +++ b/dev/automated_tests/flutter_test/README.md @@ -1,5 +1,5 @@ -The files in this directory are used as part of tests in the +The files in this directory are used as part of the tests in the `flutter_tools` package. Some are here because here these tests need a `pubspec.yaml` that references the flutter framework (which is intentionally not true of the `flutter_tools` package). Others are -here mostly out of peer pressure. +here mostly out of peer pressure. \ No newline at end of file diff --git a/dev/benchmarks/complex_layout/README.md b/dev/benchmarks/complex_layout/README.md index e8fbc65292bbb..f50b854e4cb69 100644 --- a/dev/benchmarks/complex_layout/README.md +++ b/dev/benchmarks/complex_layout/README.md @@ -21,6 +21,6 @@ To measure startup time on a device: flutter run --profile --trace-startup ``` -Results should be in the logs. +The results should be in the logs. Additional results should be in the file `build/start_up_info.json`. diff --git a/dev/benchmarks/macrobenchmarks/README.md b/dev/benchmarks/macrobenchmarks/README.md index 401c2bffe2eff..5fc7f0d25b7dd 100644 --- a/dev/benchmarks/macrobenchmarks/README.md +++ b/dev/benchmarks/macrobenchmarks/README.md @@ -4,6 +4,33 @@ Performance benchmarks use either flutter drive or the web benchmark harness. ## Mobile benchmarks +### Cull opacity benchmark + +To run the cull opacity benchmark on a device: + +``` +flutter drive --profile test_driver/cull_opacity_perf.dart +``` + +Results should be in the file `build/cull_opacity_perf.timeline_summary.json`. + +More detailed logs should be in `build/cull_opacity_perf.timeline.json`. + +### Cubic bezier benchmark + +To run the cubic-bezier benchmark on a device: + +``` +flutter drive --profile test_driver/cubic_bezier_perf.dart +``` + +Results should be in the file `build/cubic_bezier_perf.timeline_summary.json`. + +More detailed logs should be in `build/cubic_bezier_perf.timeline.json`. + +### Backdrop filter benchmark + +To run the backdrop filter benchmark on a device: To run a mobile benchmark on a device: ``` @@ -30,7 +57,7 @@ The key `[test_name]` can be: ## Web benchmarks -Web benchmarks are compiled from the same entrypoint in `lib/web_benchmarks.dart`. +Web benchmarks are compiled from the same entry point in `lib/web_benchmarks.dart`. ### How to write a web benchmark @@ -39,13 +66,13 @@ as an example. Choose one of the two benchmark types: -* A "raw benchmark" records performance metrics from direct interactions with +- A "raw benchmark" records performance metrics from direct interactions with `dart:ui` with no framework. This kind of benchmark is good for benchmarking low-level engine primitives, such as layer, picture, and semantics performance. -* A "widget benchmark" records performance metrics using a widget. This kind of +- A "widget benchmark" records performance metrics using a widget. This kind of benchmark is good for measuring the performance of widgets, often together with engine work that widget-under-test incurs. -* A "widget build benchmark" records the cost of building a widget from nothing. +- A "widget build benchmark" records the cost of building a widget from nothing. This is different from the "widget benchmark" because typically the latter only performs incremental UI updates, such as an animation. In contrast, this benchmark pumps an empty frame to clear all previously built widgets and @@ -83,7 +110,7 @@ flutter run --profile -d web-server lib/web_benchmarks.dart flutter run --dart-define=FLUTTER_WEB_USE_SKIA=true --profile -d web-server lib/web_benchmarks.dart ``` -You can also run all benchmarks exactly like the devicelab runs them: +You can also run all benchmarks exactly as the devicelab runs them: ``` cd dev/devicelab diff --git a/dev/benchmarks/platform_views_layout/README.md b/dev/benchmarks/platform_views_layout/README.md index 629ba8019d85b..a2f3a19178b28 100644 --- a/dev/benchmarks/platform_views_layout/README.md +++ b/dev/benchmarks/platform_views_layout/README.md @@ -21,6 +21,6 @@ To measure startup time on a device: flutter run --profile --trace-startup ``` -Results should be in the logs. +The results should be in the logs. Additional results should be in the file `build/start_up_info.json`. diff --git a/dev/benchmarks/test_apps/stocks/README.md b/dev/benchmarks/test_apps/stocks/README.md index 88b3ddee78081..f162b46469e44 100644 --- a/dev/benchmarks/test_apps/stocks/README.md +++ b/dev/benchmarks/test_apps/stocks/README.md @@ -30,9 +30,9 @@ the tool is used to generate localizations for this app. ## Icon -Icon was created using Android Asset Studio: +The icon was created using Android Asset Studio: https://romannurik.github.io/AndroidAssetStudio/icons-launcher.html#foreground.type=image&foreground.space.trim=0&foreground.space.pad=0&foreColor=607d8b%2C0&crop=0&backgroundShape=square&backColor=fff%2C100&effects=none From this clipart: https://openclipart.org/detail/30403/tango-go-up -Which is public domain. +Which is in the public domain. diff --git a/dev/bots/README.md b/dev/bots/README.md index b5eba0477ac0a..dca908bf744ac 100644 --- a/dev/bots/README.md +++ b/dev/bots/README.md @@ -4,9 +4,9 @@ This directory exists to support building Flutter on our build infrastructure. The results of such builds are viewable at: * https://cirrus-ci.com/github/flutter/flutter/master - - Testing done on PRs and submitted changes on GitHub. + - Testing is done on PRs and submitted changes on GitHub. * https://ci.chromium.org/p/flutter/ - - Additional testing and processing done after changes are submitted. + - Additional testing and processing are done after changes are submitted. The LUCI infra requires permissions to retrigger or schedule builds. Contact @kf6gpe or another Google member of the Flutter team if you need to do that. @@ -29,7 +29,7 @@ machines and what kind are managed internally by Google. Contact @kf6gpe or another Google member of the Flutter team if you suspect changes are needed there. Both of these technologies are highly specific to the [LUCI](https://github.com/luci) project, which is the successor to Chromium's infra. We're just borrowing some -of their infrastructure. +of their infrastructures. ### Prerequisites @@ -39,17 +39,17 @@ To work on this infrastructure you will need: - Python package installer: `sudo apt-get install python-pip` - Python coverage package (only needed for `training_simulation`): `sudo pip install coverage` -To run prepare_package.dart locally: +To run `prepare_package.dart` locally: -- Make sure the depot_tools is in your PATH. If you're on Windows, you also need - an environment variable called DEPOT_TOOLS with the path to depot_tools as value. +- Make sure the `depot_tools` is in your `PATH`. If you're on Windows, you also need + an environment variable called `DEPOT_TOOLS` with the path to `depot_tools` as value. - Run `gsutil.py config` (or `python %DEPOT_TOOLS%\gsutil.py` on Windows) to authenticate with your auth token. - Create a local temp directory. `cd` into it. - Run `dart [path to your normal Flutter repo]/dev/bots/prepare_package.dart --temp_dir=. --revision=[revision to package] --branch=[branch to deploy to] --publish`. -- If you're running into gsutil permission issues, check with @Hixie to make sure +- If you're running into `gsutil` permission issues, check with @Hixie to make sure you have the right push permissions. ### Getting the code @@ -81,22 +81,22 @@ and Recipes are just Python with some limitations on what can be imported. They are [documented](https://github.com/luci/recipes-py/blob/master/doc/user_guide.md) -by the [luci/recipes-py github project](https://github.com/luci/recipes-py). +by the [luci/recipes-py GitHub project](https://github.com/luci/recipes-py). The typical cycle for editing a recipe is: -1. Checkout the recipes project using `git clone https://flutter.googlesource.com/recipes`. +1. Check out the recipes project using `git clone https://flutter.googlesource.com/recipes`. 2. Make your edits (probably to files in `//recipes/recipes`). 3. Update the tests. Run `recipes.py test train` to update - existing expected output to match the new output. Verify completely new test + the existing expected output to match the new output. Verify completely new test cases by altering the `GenTests` method of the recipe. The recipe is required to have 100% test coverage. 4. Run `led get-builder 'luci.flutter.prod:BUILDER_NAME' | led edit -p 'revision="GIT_HASH"' | led edit-recipe-bundle | led launch`, where `BUILDER_NAME` is the builder name (e.g. `Linux Engine`), and `GIT_HASH` is the hash to build (which is important for the engine but not for the framework). 5. To submit a CL, you need a local branch first (`git checkout -b [some branch name]`). -6. Upload the patch (`git commit`, `git cl upload`) and send it to someone in +6. Upload the patch (`git commit`, `git cl upload`), and send it to someone in the `OWNERS` file for review. ### The infra config repository @@ -112,7 +112,7 @@ schema that describes available properties. ### Future Directions -We would like to host our own recipes instead of storing them in +We would like to host our recipes instead of storing them in [build](https://chromium.googlesource.com/chromium/tools/build.git/+/master/scripts/slave/recipes/flutter). Support for [cross-repository recipes](https://github.com/luci/recipes-py/blob/master/doc/cross_repo.md) is @@ -123,7 +123,7 @@ tried, but it's not quite ready. ### Android Tools The Android SDK and NDK used by Flutter's Chrome infra bots are stored in Google -Cloud. During the build a bot runs the `download_android_tools.py` script that +Cloud. During the build, a bot runs the `download_android_tools.py` script that downloads the required version of the Android SDK into `dev/bots/android_tools`. To check which components are currently installed, download the current SDK @@ -216,8 +216,8 @@ want to do, run: $ dart ./unpublish_package.dart --confirm --temp_dir=/tmp/foo --revision d444a455de87a2e40b7f576dc12ffd9ab82fd491 ``` -and it will actually perform the actions. You will of course need to have access -to the cloud storage server and have gsutil installed in order to perform this +and it will perform the actions. You will of course need to have access +to the cloud storage server and have `gsutil` installed to perform this operation. Only runs on Linux or macOS systems. See `dart ./unpublish_package.dart --help` for more details. diff --git a/dev/ci/README.md b/dev/ci/README.md index b603eaa41dc7e..546bc4fecbcd0 100644 --- a/dev/ci/README.md +++ b/dev/ci/README.md @@ -11,6 +11,6 @@ to manually build and push the Docker image locally. NOTE: there are some factors external to the actual `Dockerfile` that would necessitate rebuilding the Docker image, such as upstream code changes, (Linux -distribution) repository updates, or a file that gets `COPY`ied into the image +distribution) repository updates or a file that gets `COPY`ied into the image changing. In this case, a trivial `Dockerfile` change (such as a comment) would invalidate the cache and trigger a rebuild. diff --git a/dev/ci/docker_linux/README.md b/dev/ci/docker_linux/README.md index 8775b83067b58..ebaed3fdca965 100644 --- a/dev/ci/docker_linux/README.md +++ b/dev/ci/docker_linux/README.md @@ -1,8 +1,8 @@ This directory includes scripts to build the docker container image used for building flutter/flutter in our CI system (currently [Cirrus](cirrus-ci.org)). -In order to run the scripts, you have to setup `docker` and `gcloud`. Please -refer to the [internal flutter team doc](go/flutter-team) for how to setup in a +To run the scripts, you have to set up `docker` and `gcloud`. Please +refer to the [internal flutter team doc](go/flutter-team) for how to set up in a Google internal environment. To debug the image locally: diff --git a/dev/devicelab/README.md b/dev/devicelab/README.md index 609e8448b02ac..363c913e07ac3 100644 --- a/dev/devicelab/README.md +++ b/dev/devicelab/README.md @@ -3,7 +3,7 @@ "Devicelab" (a.k.a. [Cocoon](https://github.com/flutter/cocoon)) is a physical lab that tests Flutter on real Android and iOS devices. -This package contains the code for test framework and the tests. More generally +This package contains the code for the test framework and the tests. More generally the tests are referred to as "tasks" in the API, but since we primarily use it for testing, this document refers to them as "tests". @@ -26,7 +26,7 @@ start the build. **Task is running** (blue with clock): an agent is currently building the task. -**Task succeeded** (green): an agent reported a successful completion of the +**Task succeeded** (green): an agent reported the successful completion of the task. **Task is flaky** (yellow): the task was attempted multiple time, but only the @@ -37,10 +37,10 @@ latest attempt succeeded (we currently only try twice). **Task is rerunning** (orange): the task is being rerun. **Task was skipped** (transparent): the task is not scheduled for a build. This -usually happens when a task is removed from `manifest.yaml` file. +usually happens when a task is removed from the `manifest.yaml` file. In addition to color-coding, a task may display a question mark. This means -that the task was marked as flaky manually. The status of such task is ignored +that the task was marked as flaky manually. The status of such a task is ignored when considering whether the build is broken or not. For example, if a flaky task fails, GitHub will not prevent PR submissions. However, if the latest status of a non-flaky task is red, all pending PRs will contain a warning about @@ -83,7 +83,7 @@ If the task fails, the agent reports the failure to the server, the server increments the counter counting the number of attempts it took to run the task and puts the task back in the pool of available tasks. If a task does not succeed after a certain number of attempts (as of this writing the limit is 2), -the task is marked as failed and is displayed using red color on the dashboard. +the task is marked as failed and is displayed using a red color on the dashboard. # Running tests locally @@ -94,7 +94,7 @@ reproduce a CI test failure locally. ## Prerequisites -You must set `ANDROID_SDK_ROOT` environment variable to run +You must set the `ANDROID_SDK_ROOT` environment variable to run tests on Android. If you have a local build of the Flutter engine, then you have a copy of the Android SDK at `.../engine/src/third_party/android_tools/sdk`. @@ -102,9 +102,9 @@ You can find where your Android SDK is using `flutter doctor`. ## Warnings -Running devicelab will do things to your environment. +Running the devicelab will do things to your environment. -Notably, it will start and stop gradle, for instance. +Notably, it will start and stop Gradle, for instance. ## Running all tests @@ -141,10 +141,9 @@ To run multiple tests, repeat option `-t` (`--task`) multiple times: ``` To run tests from a specific stage, use option `-s` (`--stage`). -Currently there are only three stages defined, `devicelab`, +Currently, there are only three stages defined, `devicelab`, `devicelab_ios` and `devicelab_win`. - ```sh ../../bin/cache/dart-sdk/bin/dart bin/run.dart -s {NAME_OF_STAGE} ``` @@ -169,7 +168,7 @@ against a local engine build. The test runs the same benchmark a specified number of times against both engines, then outputs a tab-separated spreadsheet with the results and stores them in a JSON file for future reference. The results can be copied to a Google Spreadsheet for further inspection and the -JSON file can be reprocessed with the summarize.dart command for more detailed +JSON file can be reprocessed with the `summarize.dart` command for more detailed output. Example: @@ -188,7 +187,7 @@ engine build. `--local-engine` is required for A/B test. `--ab-result-file=filename` can be used to provide an alternate location to output the JSON results file (defaults to `ABresults#.json`). A single `#` character can be used to indicate where to insert a serial number if a file with that name already -exists, otherwise the file will be overwritten. +exists, otherwise, the file will be overwritten. A/B can run exactly one task. Multiple tasks are not supported. @@ -286,17 +285,17 @@ your test edit `manifest.yaml` and add the following in the "tasks" dictionary: Where: - - `{NAME_OF_TEST}` is the name of your test that also matches the name of the - file in `bin/tasks` without the `.dart` extension. - - `{DESCRIPTION}` is the plain English description of your test that helps - others understand what this test is testing. - - `{STAGE}` is `devicelab` if you want to run on Android, or `devicelab_ios` if - you want to run on iOS. - - `{CAPABILITIES}` is an array that lists the capabilities required of - the test agent (the computer that runs the test) to run your test. As of writing, - the available capabilities are: `linux`, `linux/android`, `linux-vm`, -`mac`, `mac/ios`, `mac/iphonexs`, `mac/ios32`, `mac-catalina/ios`, -`mac-catalina/android`, `ios/gl-render-image`, `windows`, `windows/android`. +- `{NAME_OF_TEST}` is the name of your test that also matches the name of the + file in `bin/tasks` without the `.dart` extension. +- `{DESCRIPTION}` is the plain English description of your test that helps + others understand what this test is testing. +- `{STAGE}` is `devicelab` if you want to run on Android, or `devicelab_ios` if + you want to run on iOS. +- `{CAPABILITIES}` is an array that lists the capabilities required of + the test agent (the computer that runs the test) to run your test. As of writing, + the available capabilities are: `linux`, `linux/android`, `linux-vm`, + `mac`, `mac/ios`, `mac/iphonexs`, `mac/ios32`, `mac-catalina/ios`, + `mac-catalina/android`, `ios/gl-render-image`, `windows`, `windows/android`. If your test needs to run on multiple operating systems, create a separate test for each operating system. diff --git a/dev/docs/README.md b/dev/docs/README.md index fd5971f8b858b..7cb28a93dd986 100644 --- a/dev/docs/README.md +++ b/dev/docs/README.md @@ -1,7 +1,7 @@ **Welcome to the Flutter API reference documentation!** Flutter is Google's SDK for crafting beautiful, fast user experiences for -mobile, web and desktop from a single codebase. Flutter works with existing +mobile, web, and desktop from a single codebase. Flutter works with existing code, is used by developers and organizations around the world, and is free and open source. @@ -58,7 +58,7 @@ import 'package:file/local.dart'; Flutter has a rich ecosystem of packages that have been contributed by the Flutter team and the broader open source community to a central repository. -Among the thousands of packages you'll find support for Firebase, Google +Among the thousands of packages, you'll find support for Firebase, Google Fonts, hardware services like Bluetooth and camera, new widgets and animations, and integration with other popular web services. You can browse those packages at [pub.dev](https://pub.dev). diff --git a/dev/integration_tests/android_splash_screens/splash_screen_load_rotate/README.md b/dev/integration_tests/android_splash_screens/splash_screen_load_rotate/README.md index 9169c186675ca..75374b421c2bf 100644 --- a/dev/integration_tests/android_splash_screens/splash_screen_load_rotate/README.md +++ b/dev/integration_tests/android_splash_screens/splash_screen_load_rotate/README.md @@ -2,6 +2,6 @@ This project is an example of a splash screen that displays an animation indefinitely. -A never ending animation is provided as a demo so that developers can manually verify that +A never-ending animation is provided as a demo so that developers can manually verify that orientation changes and other UI destruction processes do not cause issues with Flutter's splash system for Android. diff --git a/dev/integration_tests/android_views/README.md b/dev/integration_tests/android_views/README.md index f6df75f85d7e9..0d4490f9fdc5d 100644 --- a/dev/integration_tests/android_views/README.md +++ b/dev/integration_tests/android_views/README.md @@ -11,7 +11,7 @@ This is what the app looks like: ![android_views test app](https://flutter.github.io/assets-for-api-docs/assets/readme-assets/android_views_test.png) -The blue part is the embedded Android view, because it is positioned at the top +The blue part is the embedded Android view because it is positioned at the top left corner, the coordinate systems for FlutterView and for the embedded view's virtual display has the same origin (this makes the MotionEvent comparison easier as we don't need to translate the coordinates). diff --git a/dev/integration_tests/flutter_driver_screenshot_test/README.md b/dev/integration_tests/flutter_driver_screenshot_test/README.md index e9fba7b671317..558be1da3d53b 100644 --- a/dev/integration_tests/flutter_driver_screenshot_test/README.md +++ b/dev/integration_tests/flutter_driver_screenshot_test/README.md @@ -1,8 +1,8 @@ # Summary -This tests contains an app with a main page and sub pages. -The main page contains a list of buttons; each button leads to a designated sub page when tapped on. -Each sub page should displays some simple UIs to screenshot tested. +This test contains an app with a main page and subpages. +The main page contains a list of buttons; each button leads to a designated subpage when tapped on. +Each subpage should display some simple UIs to the screenshot tested. The flutter driver test runs the app and opens each page to take a screenshot. @@ -12,7 +12,7 @@ Note that new binaries can't be checked in the Flutter repo, so use [Flutter Gol # Add a new page to test -1. Create a new class which extends `Page` and implement the UI to be tested in the `build` method. +1. Create a new class that extends `Page` and implement the UI to be tested in the `build` method. 2. The new class should set a static `title` and `key` 3. Add an instance of the new class to the `_allPages` list in the `main.dart` 4. Create a new test case similar to `"'A page with an image screenshot"` in `test_driver/main_test.dart` to run the screenshot test. diff --git a/dev/integration_tests/flutter_gallery/README.md b/dev/integration_tests/flutter_gallery/README.md index 552bbc9595768..e62265dacdb9b 100644 --- a/dev/integration_tests/flutter_gallery/README.md +++ b/dev/integration_tests/flutter_gallery/README.md @@ -2,7 +2,7 @@ An older copy of the Flutter gallery demo application used for integration testing. -For the current Flutter gallery app sample, see this repo: +For the current Flutter Gallery app sample, see this repo: https://github.com/flutter/gallery ## Icon diff --git a/dev/integration_tests/gradle_deprecated_settings/README.md b/dev/integration_tests/gradle_deprecated_settings/README.md index a4c608111a111..bd04f25921e71 100644 --- a/dev/integration_tests/gradle_deprecated_settings/README.md +++ b/dev/integration_tests/gradle_deprecated_settings/README.md @@ -4,4 +4,4 @@ This project is meant to test that apps using the current `android/settings.grad can still be built. This project can be removed once apps have been migrated to this new file. -Issue: https://github.com/flutter/flutter/issues/54566 \ No newline at end of file +Issue: https://github.com/flutter/flutter/issues/54566 diff --git a/dev/integration_tests/ios_add2app_life_cycle/README.md b/dev/integration_tests/ios_add2app_life_cycle/README.md index 9797ffed0e0e3..4dd6fa98e8548 100644 --- a/dev/integration_tests/ios_add2app_life_cycle/README.md +++ b/dev/integration_tests/ios_add2app_life_cycle/README.md @@ -8,7 +8,7 @@ The following functionality is currently implemented: 1. A regular iOS view controller (UIViewController), similar to the default `flutter create` template (NativeViewController.m). -1. A FlutterViewController subclass that takes over full screen. Demos showing +1. A FlutterViewController subclass that takes over the full screen. Demos showing this both from a cold/fresh engine state and a warm engine state (FullScreenViewController.m). 1. A demo of pushing a FlutterViewController on as a child view. @@ -19,7 +19,7 @@ The following functionality is currently implemented: A few key things are tested here (IntegrationTests.m): -1. The ability to pre-warm the engine and attach/detatch a ViewController from +1. The ability to pre-warm the engine and attach/detach a ViewController from it. 1. The ability to use platform channels to communicate between views. 1. The ability to simultaneously run two instances of the engine. diff --git a/dev/integration_tests/ios_host_app/README.md b/dev/integration_tests/ios_host_app/README.md index feec9a5aaee34..75843e8e20bdb 100644 --- a/dev/integration_tests/ios_host_app/README.md +++ b/dev/integration_tests/ios_host_app/README.md @@ -17,7 +17,7 @@ interaction. 1. A regular iOS view controller (UIViewController), similar to the default `flutter create` template (NativeViewController.m). -1. A FlutterViewController subclass that takes over full screen. Demos showing +1. A FlutterViewController subclass that takes over the full screen. Demos showing this both from a cold/fresh engine state and a warm engine state (FullScreenViewController.m). 1. A demo of pushing a FlutterViewController on as a child view. @@ -28,7 +28,7 @@ interaction. A few key things are tested here (FlutterUITests.m): -1. The ability to pre-warm the engine and attach/detatch a ViewController from +1. The ability to pre-warm the engine and attach/detach a ViewController from it. 1. The ability to use platform channels to communicate between views. 1. The ability to simultaneously run two instances of the engine. diff --git a/dev/integration_tests/ios_platform_view_tests/README.md b/dev/integration_tests/ios_platform_view_tests/README.md index b5572b562f4d7..4ff53701f2c49 100644 --- a/dev/integration_tests/ios_platform_view_tests/README.md +++ b/dev/integration_tests/ios_platform_view_tests/README.md @@ -2,8 +2,8 @@ A simple app contains: -* A home with with a button that pushes a new page into the scene. -* A page contains a platform view, a button and a text. +* A home with a button that pushes a new page into the scene. +* A page contains a platform view, a button, and a text. * Press the button will update the text. -We use this app to test platform views in general such as platform view creation, destruction and thread merging(iOS only). +We use this app to test platform views in general such as platform view creation, destruction, and thread merging(iOS only). diff --git a/dev/snippets/README.md b/dev/snippets/README.md index 3690b0e1f256f..71a0a99f4b6b1 100644 --- a/dev/snippets/README.md +++ b/dev/snippets/README.md @@ -22,15 +22,15 @@ There are three kinds of code blocks. magically determine how to analyze, and * A `dartpad` sample, which gets placed into a full-fledged application, and can - be actually executed inline in the documentation on the web page using + be executed inline in the documentation on the web page using DartPad. * A `sample`, which gets placed into a full-fledged application, but isn't placed into DartPad in the documentation because it doesn't make sense to do so. -Ideally every sample is a DartPad sample, but some samples don't have any visual -representation, and some just don't make sense that way (for example, sample +Ideally, every sample is a DartPad sample, but some samples don't have any visual +representation and some just don't make sense that way (for example, sample code for setting the system UI's notification area color on Android won't do anything on the web). @@ -70,7 +70,7 @@ There are several kinds of sample code you can specify: * Constructor calls, typically showing what might exist in a build method. These will be inserted into an assignment expression assigning to a variable of type - "dynamic" and followed by a semicolon, for the purposes of analysis. + "dynamic" and followed by a semicolon, for analysis. * Class definitions. These start with "class", and are analyzed verbatim. @@ -79,7 +79,7 @@ There are several kinds of sample code you can specify: individually. The above means that it's tricky to include verbatim imperative code (e.g. a -call to a method), since it won't be valid to have such code at the top level. +call to a method) since it won't be valid to have such code at the top level. Instead, wrap it in a function or even a whole class, or make it a valid variable declaration. @@ -151,7 +151,7 @@ This command is displayed as part of the sample in the API docs. #### Templates -In order to support showing an entire app when you click on the right tab of the +To support showing an entire app when you click on the right tab of the code sample UI, we have to be able to insert the `sample` or `dartpad` block into the template and instantiate the right parts. @@ -171,7 +171,7 @@ specified template. ## Skeletons -A skeleton (in relation to this tool) is an HTML template into which the Dart +A skeleton (concerning this tool) is an HTML template into which the Dart code blocks and descriptions are interpolated. There is currently one skeleton for @@ -180,11 +180,11 @@ There is currently one skeleton for [snippet](config/skeletons/snippet.html) code samples, but there could be more. Skeletons use mustache notation (e.g. `{{code}}`) to mark where components will -be interpolated into the template. It doesn't actually use the mustache -package, since these are simple string substitutions, but it uses the same +be interpolated into the template. It doesn't use the mustache +package since these are simple string substitutions, but it uses the same syntax. -The code block generation tools process the source input and emit HTML for +The code block generation tools that process the source input and emit HTML for output, which dartdoc places back into the documentation. Any options given to the `{@tool ...}` directive are passed on verbatim to the tool. diff --git a/dev/snippets/config/templates/README.md b/dev/snippets/config/templates/README.md index e52a341223bfa..6671b517226dc 100644 --- a/dev/snippets/config/templates/README.md +++ b/dev/snippets/config/templates/README.md @@ -58,13 +58,13 @@ additional burden, since all code will also be compiled to be sure it compiles). ## Available Templates -The templates available for using as an argument to the snippets tool are as +The templates available for use as an argument to the snippets tool are as follows: - [`freeform`](freeform.tmpl) : This is a simple template for which you provide everything. It has no code of its own, just the sections for `imports`, `main`, and `preamble`. You must - provide the `main` section in order to have a `main()`. + provide the `main` section to have a `main()`. ### WidgetsApp Templates @@ -74,14 +74,14 @@ the widgets library. - [`stateful_widget`](stateful_widget.tmpl) : The default code block will be placed as the body of the `State` object of a `StatefulWidget` subclass. Because the default code block is placed as the body - of a stateful widget, you will need to implement the `build()` method, and any + of a stateful widget, you will need to implement the `build()` method and any state variables. It also has a `preamble` in addition to the default code block, which will be placed at the top level of the Dart file, so bare method calls are not allowed in the preamble. The default code block is placed as the body of a stateful widget, so you will need to implement the `build()` method, and any state variables. It also has an `imports` section to import additional packages. Please only import things that are part - of flutter or part of default dependencies for a `flutter create` project. + of Flutter or part of default dependencies for a `flutter create` project. - [`stateful_widget_ticker`](stateful_widget_ticker.tmpl) : Identical to the `stateful_widget` template, with the addition of the `TickerProviderStateMixin` @@ -91,12 +91,12 @@ the widgets library. `stateful_widget` template, except that the default code block is inserted as a method (which should be the `build` method) in a `StatelessWidget`. The `@override` before the build method is added by - the template, so must be omitted from the sample code. + the template so must be omitted from the sample code. ### MaterialApp Templates -These templates follow the same conventions as the `WidgetsApp` templates above, but use a -`MaterialApp` instead. These templates import the material library. +These templates follow the same conventions as the `WidgetsApp` templates above but use a +`MaterialApp` instead. These templates import the material library. - [`stateful_widget_material`](stateful_widget_material.tmpl) @@ -125,8 +125,8 @@ These templates follow the same conventions as the `WidgetsApp` templates above, ### CupertinoApp Templates -These templates follow the same conventions as the `WidgetsApp` templates above, but use a -`CupertinoApp` instead. These templates import the cupertino library. +These templates follow the same conventions as the `WidgetsApp` templates above but use a +`CupertinoApp` instead. These templates import the Cupertino library. - [`stateful_widget_cupertino`](stateful_widget_cupertino.tmpl) diff --git a/dev/tools/gen_keycodes/README.md b/dev/tools/gen_keycodes/README.md index 9c81a23203e42..e4cfe237cec73 100644 --- a/dev/tools/gen_keycodes/README.md +++ b/dev/tools/gen_keycodes/README.md @@ -2,7 +2,7 @@ This directory contains a keycode generator that can generate Dart code for the `LogicalKeyboardKey` and `PhysicalKeyboardKey` classes. It draws information -from both the Chromium and Android source bases, and incorporates the +from both the Chromium and Android source bases and incorporates the information it finds in those sources into a single key database in JSON form. It then generates `keyboard_key.dart` (containing the `LogicalKeyboardKey` and @@ -11,27 +11,27 @@ platform-specific immutable maps for translating platform keycodes and information into the pre-defined key values in the `LogicalKeyboardKey` and `PhysicalKeyboardKey` classes. -The `data` subdirectory contains both some local data files, and the templates +The `data` subdirectory contains both some local data files and the templates used to generate the source files. - - `data/key_data.json`: contains the merged data from all the other sources. - This file will be regenerated if "--collect" is specified for the - gen_keycodes script. - - `data/key_name_to_android_name.json`: contains a mapping from Flutter key - names to Android keycode names (with the "KEY_" prefix stripped off). - - `data/keyboard_key.tmpl`: contains the template for the `keyboard_key.dart` - file. Markers that begin and end with "@@@" denote the locations where - generated data will be inserted. - - `data/keyboard_maps.tmpl`: contains the template for the `keyboard_maps.dart` - file. Markers that begin and end with "@@@" denote the locations where - generated data will be inserted. - - `data/printable.json`: contains a mapping between Flutter key name and its - printable character. This character is used as the key label. - - `data/synonyms.json`: contains a mapping between pseudo-keys that represent - other keys, and the sets of keys they represent. For example, this contains - the "shift" key that represents either a "shiftLeft" or "shiftRight" key. - - ## Running the tool +- `data/key_data.json`: contains the merged data from all the other sources. + This file will be regenerated if "--collect" is specified for the + gen_keycodes script. +- `data/key_name_to_android_name.json`: contains a mapping from Flutter key + names to Android keycode names (with the "KEY\_" prefix stripped off). +- `data/keyboard_key.tmpl`: contains the template for the `keyboard_key.dart` + file. Markers that begin and end with "@@@" denote the locations where + generated data will be inserted. +- `data/keyboard_maps.tmpl`: contains the template for the `keyboard_maps.dart` + file. Markers that begin and end with "@@@" denote the locations where + generated data will be inserted. +- `data/printable.json`: contains a mapping between Flutter key name and its + printable character. This character is used as the key label. +- `data/synonyms.json`: contains a mapping between pseudo-keys that represent + other keys and the sets of keys they represent. For example, this contains + the "shift" key that represents either a "shiftLeft" or "shiftRight" key. + +## Running the tool To run the `gen_keycodes` tool using the checked in `key_data.json` file, run it like so: @@ -59,14 +59,14 @@ checked in. ## Key Code ID Scheme -In order to provide logical keys with unique ID codes, Flutter uses a scheme -to assign logical key codes which keeps us out of the business of minting new +To provide logical keys with unique ID codes, Flutter uses a scheme +to assign logical keycodes which keeps us out of the business of minting new codes ourselves. This only applies to logical key codes: Flutter's physical key codes are just defined as USB HID codes. The logical codes are meant to be opaque to the user, and should never be -unpacked for meaning, since the code scheme could change at any time, and the -meaning is likely to be retrievable in a more reliable and correct manner from +unpacked for meaning, since the coding scheme could change at any time and the +meaning is likely to be retrievable more reliably and correctly from the API. However, if you are porting Flutter to a new platform, you should follow the @@ -75,74 +75,74 @@ following guidelines for specifying logical key codes. The logical key code is a 37-bit integer in a namespace that we control and define. It has values in the following ranges. - - **0x00 0000 0000 - 0x0 0010 FFFF**: For keys that generate Unicode - characters when pressed (this includes dead keys, but not e.g. function keys - or shift keys), the logical key code is the Unicode code point corresponding - to the representation of the key in the current keyboard mapping. The - Unicode code point might not actually match the string that is generated for - an unshifted key press of that key, for example we would use U+0034 for the - “4 $” key in the US layout, and also the “4 ;” key in the Russian layout, - and also, maybe less intuitively, for the “' 4 {“ in French layout (where in - the latter case, an unshifted press gets you a ', not a 4). Similarly, the Q - key in the US layout outputs a q in normal usage, but its code would be 0x0 - 0000 0051 (U+00051 being the code for the uppercase Q). - - - **0x01 0000 0000 - 0x01 FFFF FFFF**: For keys that are defined by the [USB HID - standard](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf), - the key code consists of the 32 bit USB extended usage code. For - example, the Enter key would have code 0x01 0007 0028. Only keys that fall - into collections "Keyboard", "Keypad", and "Tablet PC System Controls" are - considered for this API; for example, a mixing desk with multiple - collections of volume controls would not be exposed via DOWN and UP events, - nor would a mouse, joystick, or golf simulator control. - - - **0x02 0000 0000 - 0xFF FFFF FFFF**: For keys that aren't defined in USB at the - time of implementation, but that we need to support. For example, if Flutter - were ever ported to the Symbolics LM-2, the "thumb up" key might be given - the code 0x14 0000 0001, where 0x14 is defined as the “Symbolics” platform - range. Where possible, we will use specific subranges of this space to reuse - keys from other platforms. When this is not possible, the prefix 0xFF is - reserved for “Custom” codes. Each platform from which we take codes will get - a unique prefix in the range 0x2-0xFE. If multiple systems define keys with - the same usage (not the same number), then the value with the lowest prefix - is used as the defining code. - - Prefixes will be: - - |Code|Platform| - |----|--------| - |0x02| Android| - |0x03|Fuchsia | - |0x04|iOS | - |0x05|macOS | - |0x06|Linux | - |0x07|Windows | - |0x08|Web | - |0xFF|Custom | - - Further ranges will be added as platforms are added. The platform prefix - does not define the platform it is used on, it is just the platform that - decides what the value is: the codes are mapped to the same value on all - platforms. - - - **0x100 0000 0000 - 0x1FF FFFF FFFF**: For keys that have no definition yet in - Flutter, but that are encountered in the field, this range is used to embed - the platform-specific keycode in an ID that must be tested for in a platform - specific way. For instance, if a platform generates a new USB HID code 0x07 - 00E8 that a Flutter app wasn’t compiled with, then it would appear in the - app as 0x100 0007 00E8, and the app could test against that code. Yes, this - also means that once they recompile with a version of Flutter that supports - this new HID code, apps looking for this code will break. This situation is - only meant to provide a fallback ability for apps to handle esoteric codes - that their version of Flutter doesn’t support yet. The prefix for this code - is the platform prefix from the previous sections, plus 0x100. - - - **0x200 0000 0000 - 0x2FF FFFF FFFF**: For pseudo-keys which represent - combinations of other keys, and conceptual keys which don't have a physical - representation. This is where things like key synonyms are defined (e.g. - "shiftLeft" is a synonym for "shift": the "shift" key is a pseudo-key - representing either the left or right shift key). - +- **0x00 0000 0000 - 0x0 0010 FFFF**: For keys that generate Unicode + characters when pressed (this includes dead keys, but not e.g. function keys + or shift keys), the logical key code is the Unicode code point corresponding + to the representation of the key in the current keyboard mapping. The + Unicode code point might not match the string that is generated for + an unshifted keypress of that key, for example, we would use U+0034 for the + “4 \$” key in the US layout, and also the “4 ;” key in the Russian layout, + and also, maybe less intuitively, for the “' 4 {“ in French layout (wherein + the latter case, an unshifted press gets you a ', not a 4). Similarly, the Q + key in the US layout outputs a q in normal usage, but its code would be 0x0 + 0000 0051 (U+00051 being the code for the uppercase Q). + +- **0x01 0000 0000 - 0x01 FFFF FFFF**: For keys that are defined by the [USB HID + standard](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf), + the key code consists of the 32 bit USB extended usage code. For + example, the Enter key would have code 0x01 0007 0028. Only keys that fall + into collections "Keyboard", "Keypad", and "Tablet PC System Controls" are + considered for this API; for example, a mixing desk with multiple + collections of volume controls would not be exposed via DOWN and UP events, + nor would a mouse, joystick, or golf simulator control. + +- **0x02 0000 0000 - 0xFF FFFF FFFF**: For keys that aren't defined in USB at the + time of implementation, but that we need to support. For example, if Flutter + were ever ported to the Symbolics LM-2, the "thumb up" key might be given + the code 0x14 0000 0001, where 0x14 is defined as the “Symbolics” platform + range. Where possible, we will use specific subranges of this space to reuse + keys from other platforms. When this is not possible, the prefix 0xFF is + reserved for “Custom” codes. Each platform from which we take codes will get + a unique prefix in the range 0x2-0xFE. If multiple systems define keys with + the same usage (not the same number), then the value with the lowest prefix + is used as the defining code. + + Prefixes will be: + + | Code | Platform | + | ---- | -------- | + | 0x02 | Android | + | 0x03 | Fuchsia | + | 0x04 | iOS | + | 0x05 | macOS | + | 0x06 | Linux | + | 0x07 | Windows | + | 0x08 | Web | + | 0xFF | Custom | + + Further ranges will be added as platforms are added. The platform prefix + does not define the platform it is used on, it is just the platform that + decides what the value is: the codes are mapped to the same value on all + platforms. + +- **0x100 0000 0000 - 0x1FF FFFF FFFF**: For keys that have no definition yet in + Flutter, but that are encountered in the field, this range is used to embed + the platform-specific keycode in an ID that must be tested for in a + platform-specific way. For instance, if a platform generates a new USB + HID code 0x07 00E8 that a Flutter app wasn’t compiled with, then it would + appear in the app as 0x100 0007 00E8, and the app could test against that + code. Yes, this also means that once they recompile with a version of + Flutter that supports this new HID code, apps looking for this code will + break. This situation is only meant to provide a fallback ability for apps + to handle esoteric codes that their version of Flutter doesn’t support yet. + The prefix for this code is the platform prefix from the previous sections, + plus 0x100. + +- **0x200 0000 0000 - 0x2FF FFFF FFFF**: For pseudo-keys which represent + combinations of other keys, and conceptual keys which don't have a physical + representation. This is where things like key synonyms are defined (e.g. + "shiftLeft" is a synonym for "shift": the "shift" key is a pseudo-key + representing either the left or right shift key). **This is intended to get us out of the business of defining key codes where possible.** We still have to have mapping tables, but at least the actual minting @@ -164,7 +164,7 @@ UP, code 0x0000000059 (Y UP)
UP, code 0x01000700E1 (LEFT SHIFT UP)
Here's another example. On a German keyboard layout, you press ^e (the ^ key is -at the top left of the keyboard and is a dead key) to produce a “ê”: +at the top left of the keyboard and is a dead key) to produce an “ê”: DOWN, code 0x0000000302 (CIRCUMFLEX DOWN) It produces no string, because it's a dead key. The key code is for "Combining circumflex accent U+0302" in Unicode.
@@ -175,6 +175,6 @@ UP, code 0x0000000065. (E UP).
It is an important point that even though we’re representing many keys with USB HID codes, these are not necessarily the same HID codes produced by the hardware and presented to the driver, since on most platforms we have to map the platform -representation back to a HID code because we don’t have access to the original +representation back to an HID code because we don’t have access to the original HID code. USB HID is simply a conveniently well-defined standard that includes many of the keys we would want. diff --git a/dev/tools/vitool/README.md b/dev/tools/vitool/README.md index adc2a07049718..06d0d4074a088 100644 --- a/dev/tools/vitool/README.md +++ b/dev/tools/vitool/README.md @@ -10,4 +10,4 @@ intended to be a general-purpose tool. - groups - group transforms - group opacities - - paths (strokes are not supported, only fills, eliptical arc curve commands are not supported) + - paths (strokes are not supported, only fills, elliptical arc curve commands are not supported) diff --git a/examples/catalog/README.md b/examples/catalog/README.md index 59d166e26d8d7..69848daf430ed 100644 --- a/examples/catalog/README.md +++ b/examples/catalog/README.md @@ -29,7 +29,7 @@ and saved in the `.generated` directory. The markdown file contains the text taken from the Sample Catalog comment found in the app's source file, followed by the source code itself. -This `sample_page.dart` command line app must be run from the `examples/catalog` +This `sample_page.dart` command-line app must be run from the `examples/catalog` directory. It relies on templates also found in the bin directory, and it generates and executes `test_driver` apps to collect the screenshots: diff --git a/examples/flutter_view/README.md b/examples/flutter_view/README.md index b6db10b8b0189..70146153945bb 100644 --- a/examples/flutter_view/README.md +++ b/examples/flutter_view/README.md @@ -3,7 +3,7 @@ This project demonstrates how to embed Flutter within an iOS or Android application. On iOS, the iOS and Flutter components are built with Xcode. On Android, the Android and Flutter components are built with Android Studio or -gradle. +Gradle. You can read more about [accessing platform and third-party services in Flutter](https://flutter.dev/platform-services/). diff --git a/examples/image_list/README.md b/examples/image_list/README.md index 4a25e66a555dd..109f142e9ca48 100644 --- a/examples/image_list/README.md +++ b/examples/image_list/README.md @@ -1,7 +1,7 @@ -# image_list +# Image List -An example that sets up local http server for serving single -image, creates single flutter widget with five copies of requested +An example that sets up a local HTTP server for serving one +image then creates a single flutter widget with five copies of requested image and prints how long the loading took. This is used in [$FH/flutter/devicelab/bin/tasks/image_list_reported_duration.dart] test. diff --git a/examples/layers/README.md b/examples/layers/README.md index 76eae5ec3e27f..d888e5e260055 100644 --- a/examples/layers/README.md +++ b/examples/layers/README.md @@ -1,6 +1,6 @@ # Examples of Flutter's layered architecture -This directory contains a number of self-contained examples that illustrate +This directory contains several self-contained examples that illustrate Flutter's layered architecture. * [*raw/*](raw/) These examples show how to program against the lowest layer of diff --git a/examples/platform_channel/README.md b/examples/platform_channel/README.md index 87053b00c7471..439dde89be2f6 100644 --- a/examples/platform_channel/README.md +++ b/examples/platform_channel/README.md @@ -1,6 +1,6 @@ # Example of calling platform services from Flutter -This project demonstrates how to connect a Flutter app to platform specific services. +This project demonstrates how to connect a Flutter app to platform-specific services. You can read more about [accessing platform and third-party services in Flutter](https://flutter.dev/platform-channels/). diff --git a/examples/platform_channel_swift/README.md b/examples/platform_channel_swift/README.md index 3c541387e315c..da415d80ba0d3 100644 --- a/examples/platform_channel_swift/README.md +++ b/examples/platform_channel_swift/README.md @@ -1,16 +1,18 @@ # Example of calling platform services from Flutter -This project demonstrates how to connect a Flutter app to platform -specific services on iOS using Swift. The equivalent version of this -project in Objective C is found in examples/platform_channel. +This project demonstrates how to connect a Flutter app to platform-specific +services on iOS using Swift. The equivalent version of this project in +Objective C is found in examples/platform_channel. You can read more about [accessing platform and third-party services in Flutter](https://flutter.dev/platform-channels/). ## iOS + You can use the commands `flutter build` and `flutter run` from the app's root directory to build/run the app or you can open `ios/Runner.xcworkspace` in Xcode and build/run the project as usual. ## Android + We refer to the platform_channel project. diff --git a/examples/platform_view/README.md b/examples/platform_view/README.md index e13dec4f82169..c1a95888e18f1 100644 --- a/examples/platform_view/README.md +++ b/examples/platform_view/README.md @@ -3,7 +3,7 @@ This project demonstrates how to bring up a full-screen iOS/Android view from a full-screen Flutter view along with passing data back and forth between the two. -On iOS we use a CocoaPods dependency to add a Material Design button, and so +On iOS, we use a CocoaPods dependency to add a Material Design button, and so `pod install` needs to be invoked in the `ios/` folder before `flutter run`: ``` diff --git a/packages/_flutter_web_build_script/README.md b/packages/_flutter_web_build_script/README.md index b0580c273ca59..8ee1f92005e56 100644 --- a/packages/_flutter_web_build_script/README.md +++ b/packages/_flutter_web_build_script/README.md @@ -1 +1 @@ -This package contains the custom build script used to compile Flutter for Web applications before support for JavaScript was added into the frontend_server. It is still used for test compilation today, and is hosted here to reduce the number of dependencies that the flutter_tool has. For more information on the plans for flutter test --platform=chrome, see https://github.com/flutter/flutter/issues/50594 +This package contains the custom build script used to compile Flutter for Web applications before support for JavaScript was added into the frontend_server. It is still used for test compilation today and is hosted here to reduce the number of dependencies that the flutter_tool has. For more information on the plans for flutter test --platform=chrome, see https://github.com/flutter/flutter/issues/50594 diff --git a/packages/flutter_localizations/README.md b/packages/flutter_localizations/README.md index 075ba759428ad..9082bd54fc33c 100644 --- a/packages/flutter_localizations/README.md +++ b/packages/flutter_localizations/README.md @@ -33,7 +33,7 @@ and `WidgetsLocalizations`, with appropriate name substitutions): ``` dart dev/tools/localization/bin/gen_missing_localizations.dart ``` - Which will copy the english strings into the other locales as placeholders + 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: diff --git a/packages/flutter_tools/README.md b/packages/flutter_tools/README.md index 567db7a1410bd..bccbfe5715fcb 100644 --- a/packages/flutter_tools/README.md +++ b/packages/flutter_tools/README.md @@ -24,7 +24,7 @@ To run Flutter Tools from source, in this directory run: ```shell $ ../../bin/cache/dart-sdk/bin/dart bin/flutter_tools.dart ``` -followed by command line arguments, as usual. +followed by command-line arguments, as usual. ### Running the analyzer @@ -51,8 +51,8 @@ file called `file_test.dart` in the subdirectory that matches the behavior of the test. We measure [test coverage](https://codecov.io/gh/flutter/flutter) post-submit. -A change that deletes code might decrease test coverage, however most changes -that add new code should aim to increase coverage. In particular the coverage +A change that deletes code might decrease test coverage, however, most changes +that add new code should aim to increase coverage. In particular, the coverage of the diff should be close to the average coverage, and should ideally be better. diff --git a/packages/flutter_tools/doc/daemon.md b/packages/flutter_tools/doc/daemon.md index 72078faa9b311..ddfc0d358980e 100644 --- a/packages/flutter_tools/doc/daemon.md +++ b/packages/flutter_tools/doc/daemon.md @@ -14,7 +14,7 @@ A set of `flutter daemon` commands/events are also exposed via `flutter run --ma ## Protocol -The daemon speaks [JSON-RPC](http://json-rpc.org/) to clients. It uses stdin and stdout as the protocol transport. To send a command to the server, create your command as a JSON-RPC message, encode it to json, surround the encoded text with square brackets, and write it as one line of text to the stdin of the process: +The daemon speaks [JSON-RPC](http://json-rpc.org/) to clients. It uses stdin and stdout as the transport protocol. To send a command to the server, create your command as a JSON-RPC message, encode it to JSON, surround the encoded text with square brackets, and write it as one line of text to the stdin of the process: ``` [{"method":"daemon.version","id":0}] @@ -32,7 +32,7 @@ All requests and responses should be wrapped in square brackets. This ensures th Each command should have a `method` field. This is in the form '`domain.command`'. -Any params for that command should be passed in through a `params` field. Here's a example request/response for the `device.getDevices` method: +Any params for that command should be passed in through a `params` field. Here's an example request/response for the `device.getDevices` method: ``` [{"method":"device.getDevices","id":2}] @@ -86,13 +86,13 @@ This is sent when user-facing output is received. The `params` field will be a m #### daemon.showMessage -The `daemon.showMessage` event is sent by the daemon when some if would be useful to show a message to the user. This could be an error notification or a notification that some development tools are not configured or not installed. The JSON message will contain an `event` field with the value `daemon.showMessage`, and an `params` field containing a map with `level`, `title`, and `message` fields. The valid options for `level` are `info`, `warning`, and `error`. +The `daemon.showMessage` event is sent by the daemon when some if would be useful to show a message to the user. This could be an error notification or a notification that some development tools are not configured or not installed. The JSON message will contain an `event` field with the value `daemon.showMessage`, and a `params` field containing a map with `level`, `title`, and `message` fields. The valid options for `level` are `info`, `warning`, and `error`. -It is up to the client to decide how best to display the message; for some clients, it may map well to a toast style notification. There is an implicit contract that the daemon will not send too many messages over some reasonable period of time. +It is up to the client to decide how best to display the message; for some clients, it may map well to a toast style notification. There is an implicit contract that the daemon will not send too many messages over a reasonable period of time. #### daemon.logMessage -The `daemon.logMessage` event is sent whenever a log message is created - either a status level message or an error. The JSON message will contain an `event` field with the value `daemon.logMessage`, and an `params` field containing a map with `level`, `message`, and (optionally) `stackTrace` fields. +The `daemon.logMessage` event is sent whenever a log message is created - either a status level message or an error. The JSON message will contain an `event` field with the value `daemon.logMessage`, and a `params` field containing a map with `level`, `message`, and (optionally) `stackTrace` fields. Generally, clients won't display content from `daemon.logMessage` events unless they're set to a more verbose output mode. @@ -146,7 +146,7 @@ This is sent when an app is starting. The `params` field will be a map with the #### app.debugPort -This is sent when an observatory port is available for a started app. The `params` field will be a map with the fields `appId`, `port`, and `wsUri`. Clients should prefer using the `wsUri` field in preference to synthesizing a uri using the `port` field. An optional field, `baseUri`, is populated if a path prefix is required for setting breakpoints on the target device. +This is sent when an observatory port is available for a started app. The `params` field will be a map with the fields `appId`, `port`, and `wsUri`. Clients should prefer using the `wsUri` field in preference to synthesizing a URI using the `port` field. An optional field, `baseUri`, is populated if a path prefix is required for setting breakpoints on the target device. #### app.started @@ -176,7 +176,7 @@ These requests come _from_ the Flutter daemon and should be responded to by the This request is enabled only if `flutter run` is run with the `--web-allow-expose-url` flag. -This request is sent by the server when it has a local URL that needs to be exposed to the end user. This is to support running on a remote machine where a URL (for example `http://localhost:1234`) may not be directly accessible to the end user. With this URL clients can perform tunnelling and then provide the tunneled URL back to Flutter so that it can be used in code that will be executed on the end users machine (for example wehen a web application needs to be able to connect back to a service like the DWDS debugging service). +This request is sent by the server when it has a local URL that needs to be exposed to the end-user. This is to support running on a remote machine where a URL (for example `http://localhost:1234`) may not be directly accessible to the end-user. With this URL clients can perform tunneling and then provide the tunneled URL back to Flutter so that it can be used in code that will be executed on the end-users machine (for example when a web application needs to be able to connect back to a service like the DWDS debugging service). This request will only be sent if a web application was run in a mode that requires mapped URLs (such as using `--no-web-browser-launch` for browser devices or the headless `web-server` device when debugging). @@ -190,7 +190,7 @@ The response should be sent using the same `id` as the request with a `result` m Return a list of all connected devices. The `params` field will be a List; each item is a map with the fields `id`, `name`, `platform`, `category`, `platformType`, `ephemeral`, `emulator` (a boolean) and `emulatorId`. -`category` is string description of the kind of workflow the device supports. The current categories are "mobile", "web" and "desktop", or null if none. +`category` is a string description of the kind of workflow the device supports. The current categories are "mobile", "web" and "desktop", or null if none. `platformType` is a string description of the platform sub-folder the device supports. The current catgetories are "android", "ios", "linux", "macos", @@ -198,7 +198,7 @@ supports. The current catgetories are "android", "ios", "linux", "macos", `ephemeral` is a boolean which indicates where the device needs to be manually connected to a development machine. For example, a physical Android device is ephemeral, but the "web" device (that is always present) is not. -`emulatorId` is an string ID that matches the ID from `getEmulators` to allow clients to match running devices to the emulators that started them (for example to hide emulators that are already running). This field is not guaranteed to be populated even if a device was spawned from an emulator as it may require a successful connection to the device to retrieve it. In the case of a failed connection or the device is not an emulator, this field will be null. +`emulatorId` is a string ID that matches the ID from `getEmulators` to allow clients to match running devices to the emulators that started them (for example to hide emulators that are already running). This field is not guaranteed to be populated even if a device was spawned from an emulator as it may require a successful connection to the device to retrieve it. In the case of a failed connection or the device is not an emulator, this field will be null. #### device.enable @@ -212,7 +212,7 @@ Turn off device polling. Forward a host port to a device port. This call takes two required arguments, `deviceId` and `devicePort`, and one optional argument, `hostPort`. If `hostPort` is not specified, the host port will be any available port. -This method returns a map with a `hostPort` field set. +This method returns a map with a `hostPort` fieldset. #### device.unforward diff --git a/packages/flutter_tools/fuchsia_entrypoint_shim/README.md b/packages/flutter_tools/fuchsia_entrypoint_shim/README.md index 778c5456c4705..5b89d10996d34 100644 --- a/packages/flutter_tools/fuchsia_entrypoint_shim/README.md +++ b/packages/flutter_tools/fuchsia_entrypoint_shim/README.md @@ -6,13 +6,13 @@ When this directory is not present the various tools specified in the `dart_tool` directives in the flutter_tools/BUILD.gn file will end up having the same package root entry written in the .packages file. This causes the build to fail because the dart compiler has a requirement that -libraries must have a unique package uri. By specifying a package root which +libraries must have a unique package URI. By specifying a package root which is a subdirectory of this directory for these tools we avoid having the build system create duplicate package roots for the generated libraries for these tools. Note that we cannot move the location of the main files for these tools because -the paths are hard coded in the fuchsia tree. +the paths are hardcoded in the fuchsia tree. Tracking Bugs: