From 83357dd63138f35bd2bacfc4bfe57c337ff26329 Mon Sep 17 00:00:00 2001 From: Alex Li Date: Sat, 23 Apr 2022 12:58:55 +0800 Subject: [PATCH 1/8] =?UTF-8?q?=F0=9F=93=9D=20Update=20AUTHORS?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AUTHORS | 1 + 1 file changed, 1 insertion(+) diff --git a/AUTHORS b/AUTHORS index 346513453e..f5c6d8b4df 100644 --- a/AUTHORS +++ b/AUTHORS @@ -15,3 +15,4 @@ Novoda Ltd. — www.novoda.com (Niamh Power, Sebastiano Poggi) Gianluca Cesari Hidenori Matsubayashi Pradumna Saraf +Alex Li From 3ba13d70b86afff464f90b50e43f278c2329ee2e Mon Sep 17 00:00:00 2001 From: Alex Li Date: Sat, 23 Apr 2022 13:04:13 +0800 Subject: [PATCH 2/8] =?UTF-8?q?=F0=9F=93=9D=20Update=20multiple=20document?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/desktop/index.md | 8 +-- .../ui/navigation/url-strategies.md | 2 +- src/get-started/flutter-for/ios-devs.md | 5 +- src/get-started/test-drive/_restart-vscode.md | 4 +- src/get-started/test-drive/_terminal.md | 31 +++++------ src/get-started/test-drive/_vscode.md | 51 ++++++++++--------- src/get-started/web.md | 6 +-- src/perf/best-practices.md | 36 ++++++------- 8 files changed, 74 insertions(+), 69 deletions(-) diff --git a/src/desktop/index.md b/src/desktop/index.md index dcc6bf53da..5e4a0fbf07 100644 --- a/src/desktop/index.md +++ b/src/desktop/index.md @@ -220,11 +220,11 @@ and run your application to see it launch on the desktop. To create a new application that includes desktop support (in addition to mobile and web support), run the following commands, -substituting `myapp` with the name of your project: +substituting `my_app` with the name of your project: ```terminal -$ flutter create myapp -$ cd myapp +$ flutter create my_app +$ cd my_app ``` To launch your application from the command line, enter one of the following commands from the top @@ -379,7 +379,7 @@ In addition to that executable, you need the following: Release │ flutter_windows.dll │ msvcp140.dll - │ myapp.exe + │ my_app.exe │ vcruntime140.dll │ vcruntime140_1.dll │ diff --git a/src/development/ui/navigation/url-strategies.md b/src/development/ui/navigation/url-strategies.md index fb3b08ac90..b652e64975 100644 --- a/src/development/ui/navigation/url-strategies.md +++ b/src/development/ui/navigation/url-strategies.md @@ -123,7 +123,7 @@ handle any path gracefully and fallback to your app's `index.html` file. Update the `` tag in `web/index.html` to the path where your app is hosted. For example, to host your Flutter app at -`myapp.dev/flutter_app`, change +`my_app.dev/flutter_app`, change this tag to ``. diff --git a/src/get-started/flutter-for/ios-devs.md b/src/get-started/flutter-for/ios-devs.md index 10e4d6b601..ec1251f398 100644 --- a/src/get-started/flutter-for/ios-devs.md +++ b/src/get-started/flutter-for/ios-devs.md @@ -827,12 +827,11 @@ Future>> sendReceive(SendPort port, String msg) { port.send([msg, response.sendPort]); return response.first as Future>>; } - ``` Here, `dataLoader()` is the `Isolate` that runs in its own separate execution thread. -In the isolate you can perform more CPU intensive +In the isolate, you can perform more CPU intensive processing (parsing a big JSON, for example), or perform computationally intensive math, such as encryption or signal processing. @@ -1245,7 +1244,7 @@ for your own app's localizable copy, if you want those to be localized too. When initialized, the `WidgetsApp` (or `MaterialApp`) -creates a[`Localizations`][] widget for you, +creates a [`Localizations`][] widget for you, with the delegates you specify. The current locale for the device is always accessible from the `Localizations` widget from the current context diff --git a/src/get-started/test-drive/_restart-vscode.md b/src/get-started/test-drive/_restart-vscode.md index f26e0cc4ab..456a82b2ba 100644 --- a/src/get-started/test-drive/_restart-vscode.md +++ b/src/get-started/test-drive/_restart-vscode.md @@ -1,4 +1,4 @@ {{site.alert.warning}} -If VS Code was running during your initial Flutter setup, -you may need to restart it for VS Code's Flutter plugin to detect the Flutter SDK. + If VS Code was running during your initial Flutter setup, + you may need to restart it for VS Code's Flutter plugin to detect the Flutter SDK. {{site.alert.end}} diff --git a/src/get-started/test-drive/_terminal.md b/src/get-started/test-drive/_terminal.md index d06c33e142..83860c8330 100644 --- a/src/get-started/test-drive/_terminal.md +++ b/src/get-started/test-drive/_terminal.md @@ -1,12 +1,12 @@
-## Create the app {#create-app} +## Create the app {#create-app} Use the `flutter create` command to create a new project: ```terminal -$ flutter create myapp -$ cd myapp +$ flutter create my_app +$ cd my_app ``` It is also possible to pass other arguments to `flutter create`, @@ -14,29 +14,30 @@ such as the project name (*pubspec.yml*), the organization name, or to specify the programming language used for the native platform: ```terminal -$ flutter create --project-name myapp --org dev.flutter --android-language java --ios-language objc myapp -$ cd myapp +$ flutter create --project-name my_app --org dev.flutter --android-language java --ios-language objc my_app +$ cd my_app ``` -The command creates a Flutter project directory called `myapp` that +The command creates a Flutter project directory called `my_app` that contains a simple demo app that uses [Material Components][]. {% include_relative _main-code-note.md %} ## Run the app - 1. Check that an Android device is running. If none are shown, follow the - device-specific instructions on the [Install][] page for your OS. +1. Check that an Android device is running. + If none are shown, follow the device-specific instructions + on the [Install][] page for your OS. - ```terminal - $ flutter devices - ``` + ```terminal + $ flutter devices + ``` - 2. Run the app with the following command: +2. Run the app with the following command: - ```terminal - $ flutter run - ``` + ```terminal + $ flutter run + ``` {% capture save_changes -%} . diff --git a/src/get-started/test-drive/_vscode.md b/src/get-started/test-drive/_vscode.md index b6485b7733..6dc9739404 100644 --- a/src/get-started/test-drive/_vscode.md +++ b/src/get-started/test-drive/_vscode.md @@ -6,11 +6,11 @@ 1. Type "flutter", and select the **Flutter: New Project**. 1. Select **Application**. 1. Create or select the parent directory for the new project folder. - 1. Enter a project name, such as `myapp`, and press **Enter**. + 1. Enter a project name, such as `my_app`, and press **Enter**. 1. Wait for project creation to complete and the `main.dart` file to appear. -The above commands create a Flutter project directory called `myapp` that +The above commands create a Flutter project directory called `my_app` that contains a simple demo app that uses [Material Components][]. {% include_relative _package-name.md %} @@ -21,27 +21,32 @@ contains a simple demo app that uses [Material Components][]. ## Run the app - 1. Locate the VS Code status bar (the blue bar at the bottom of the - window):
![status bar][]{:.mw-100.pt-1.pb-2} - 1. Select a device from the **Device Selector** area. - For details, see [Quickly switching between Flutter devices][]. - - If no device is available and you want to use a device simulator, - click **No Devices** and launch a simulator. - - {{site.alert.warning}} - You may not see **Start iOS Simulator** option when you click **No Devices** in VS Code. If you are on Mac then you may have to run following command in terminal to launch a simulator. - ``` - open -a simulator - ``` - - On Windows or Linux it is not possible to launch iOS simulator. - {{site.alert.end}} - - - To setup a real device, follow the device-specific instructions on the - [Install][] page for your OS. - 1. Invoke **Run > Start Debugging** or press F5. - 1. Wait for the app to launch — progress is printed - in the **Debug Console** view. +1. Locate the VS Code status bar + (the blue bar at the bottom of the window):
+ ![status bar][]{:.mw-100.pt-1.pb-2} +1. Select a device from the **Device Selector** area. + For details, see [Quickly switching between Flutter devices][]. + - If no device is available and you want to use a device simulator, + click **No Devices** and launch a simulator. + + {{site.alert.warning}} + You may not see **Start iOS Simulator** option + when you click **No Devices** in VS Code. + If you are on Mac then you may have to run following command + in terminal to launch a simulator. + + ```terminal + $ open -a simulator + ``` + + On Windows or Linux it is not possible to launch iOS simulator. + {{site.alert.end}} + + - To setup a real device, follow the device-specific instructions + on the [Install][] page for your OS. +1. Invoke **Run > Start Debugging** or press F5. +1. Wait for the app to launch — progress is printed + in the **Debug Console** view. {% capture save_changes -%} : invoke **Save All**, or click **Hot Reload** diff --git a/src/get-started/web.md b/src/get-started/web.md index d0cb9b23b1..d5a1ed0d86 100644 --- a/src/get-started/web.md +++ b/src/get-started/web.md @@ -89,11 +89,11 @@ and run your app to see it launch in Chrome. To create a new app that includes web support (in addition to mobile support), run the following commands, -substituting `myapp` with the name of your project: +substituting `my_app` with the name of your project: ```terminal -$ flutter create myapp -$ cd myapp +$ flutter create my_app +$ cd my_app ``` To serve your app from `localhost` in Chrome, diff --git a/src/perf/best-practices.md b/src/perf/best-practices.md index 7f44d94719..56a3bcb57c 100644 --- a/src/perf/best-practices.md +++ b/src/perf/best-practices.md @@ -38,7 +38,7 @@ to be slow, but can't always be avoided. They should be used thoughtfully, following the guidance below. -# Minimize expensive operations +## Minimize expensive operations Some operations are more expensive than others, meaning that they consume more resources. @@ -46,7 +46,7 @@ Obviously, you want to only use these operations when necessary. How you design and implement your app's UI can have a big impact on how efficiently it runs. -## Control build() cost +### Control build() cost Here are some things to keep in mind when designing your UI: @@ -103,7 +103,7 @@ For more information, check out: --- -## Use saveLayer() thoughtfully +### Use saveLayer() thoughtfully Some Flutter code uses `saveLayer()`, an expensive operation, to implement various visual effects in the UI. @@ -112,7 +112,7 @@ other widgets or packages that you use might call it behind the scenes. Perhaps your app is calling `saveLayer()` more than necessary; excessive calls to `saveLayer()` can cause jank. -### Why is saveLayer expensive? +#### Why is saveLayer expensive? Calling `saveLayer()` allocates an offscreen buffer and drawing content into the offscreen buffer might @@ -123,14 +123,14 @@ to redirect that stream temporarily and then direct it back again. On mobile GPUs this is particularly disruptive to rendering throughput. -### When is saveLayer required? +#### When is saveLayer required? At runtime, if you need to dynamically display various shapes coming from a server (for example), each with some transparency, that might (or might not) overlap, then you pretty much have to use `saveLayer()`. -### Debugging calls to saveLayer +#### Debugging calls to saveLayer How can you tell how often your app calls `saveLayer()`, either directly or indirectly? @@ -142,7 +142,7 @@ switch in the [DevTools Performance view][]. [DevTools timeline]: {{site.url}}/development/tools/devtools/performance#timeline-events-chart -### Minimizing calls to saveLayer +#### Minimizing calls to saveLayer Can you avoid calls to `saveLayer`? It might require rethinking of how you @@ -200,7 +200,7 @@ and are potentially costly: --- -## Minimize use of opacity and clipping +### Minimize use of opacity and clipping Opacity is another expensive operation, as is clipping. Here are some tips you might find to be useful: @@ -232,7 +232,7 @@ Here are some tips you might find to be useful: --- -## Implement grids and lists thoughtfully +### Implement grids and lists thoughtfully How your grids and lists are implemented might be causing performance problems for your app. @@ -241,7 +241,7 @@ practice when creating grids and lists, and how to determine whether your app uses excessive layout passes. -### Be lazy! +#### Be lazy! When building a large grid or list, use the lazy builder methods, with callbacks. @@ -260,14 +260,14 @@ For more information and examples, check out: [`Listview.builder`]: {{site.api}}/flutter/widgets/ListView/ListView.builder.html [Working with long lists]: {{site.url}}/cookbook/lists/long-lists -### Avoid intrinsics +#### Avoid intrinsics For information on how intrinsic passes might be causing problems with your grids and lists, see the next section. --- -## Minimize layout passes caused by intrinsic operations +### Minimize layout passes caused by intrinsic operations If you've done much Flutter programming, you are probably familiar with [how layout and constraints work][] @@ -282,7 +282,7 @@ over the widgets but, sometimes, a second pass (called an _intrinsic pass_) is needed, and that can slow performance. -### What is an intrinsic pass? +#### What is an intrinsic pass? An intrinsic pass happens when, for example, you want all cells to have the size @@ -302,7 +302,7 @@ the framework determines a uniform cell size, and re-visits all grid cells a second time, telling each card what size to use. -### Debugging intrinsic passes +#### Debugging intrinsic passes To determine whether you have excessive intrinsic passes, enable the **[Track layouts option][]** @@ -312,7 +312,7 @@ to learn how many layout passes were performed. Once you enable tracking, intrinsic timeline events are labeled as '$runtimeType intrinsics'. -### Avoiding intrinsic passes +#### Avoiding intrinsic passes You have a couple options for avoiding the intrinsic pass: @@ -337,7 +337,7 @@ section in the [Flutter architectural overview][]. --- -## Build and display frames in 16ms +### Build and display frames in 16ms Since there are two separate threads for building and rendering, you have 16ms for building, @@ -369,7 +369,7 @@ check out the video [Why 60fps?][] [profile mode]: {{site.url}}/testing/build-modes#profile [Why 60fps?]: {{site.youtube-site}}/watch?v=CaMTIgxCSqU -# Pitfalls +## Pitfalls If you need to tune your app’s performance, or perhaps the UI isn't as smooth as you expect, @@ -410,7 +410,7 @@ your app's performance. if most of the children are not visible on screen to avoid the build cost. -# Resources +## Resources For more performance info, check out the following resources: From 0d33a17e191d15bf9911abdfc59f17e3582bc0e0 Mon Sep 17 00:00:00 2001 From: Alex Li Date: Sat, 23 Apr 2022 13:16:03 +0800 Subject: [PATCH 3/8] src/get-started/test-drive/_vscode.md --- src/get-started/test-drive/_vscode.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/get-started/test-drive/_vscode.md b/src/get-started/test-drive/_vscode.md index 6dc9739404..09efc7815b 100644 --- a/src/get-started/test-drive/_vscode.md +++ b/src/get-started/test-drive/_vscode.md @@ -26,8 +26,9 @@ contains a simple demo app that uses [Material Components][]. ![status bar][]{:.mw-100.pt-1.pb-2} 1. Select a device from the **Device Selector** area. For details, see [Quickly switching between Flutter devices][]. - - If no device is available and you want to use a device simulator, - click **No Devices** and launch a simulator. + - If no device is available, and you want to use a device simulator, + click **No Devices** and click + **Start iOS Simulator** to launch a simulator. {{site.alert.warning}} You may not see **Start iOS Simulator** option From 9d8d247ef88bf19535279ef8d06008da91a4a262 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Tue, 26 Apr 2022 07:46:18 -0700 Subject: [PATCH 4/8] Update src/get-started/test-drive/_restart-vscode.md --- src/get-started/test-drive/_restart-vscode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/get-started/test-drive/_restart-vscode.md b/src/get-started/test-drive/_restart-vscode.md index 456a82b2ba..5e30a58db0 100644 --- a/src/get-started/test-drive/_restart-vscode.md +++ b/src/get-started/test-drive/_restart-vscode.md @@ -1,4 +1,4 @@ {{site.alert.warning}} If VS Code was running during your initial Flutter setup, - you may need to restart it for VS Code's Flutter plugin to detect the Flutter SDK. + you might need to restart it for VS Code's Flutter plugin to detect the Flutter SDK. {{site.alert.end}} From a5fb7144d1361e88e1b41b47b37a17ae42cd710b Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Tue, 26 Apr 2022 07:46:26 -0700 Subject: [PATCH 5/8] Update src/get-started/test-drive/_vscode.md --- src/get-started/test-drive/_vscode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/get-started/test-drive/_vscode.md b/src/get-started/test-drive/_vscode.md index 09efc7815b..e8a8262468 100644 --- a/src/get-started/test-drive/_vscode.md +++ b/src/get-started/test-drive/_vscode.md @@ -33,7 +33,7 @@ contains a simple demo app that uses [Material Components][]. {{site.alert.warning}} You may not see **Start iOS Simulator** option when you click **No Devices** in VS Code. - If you are on Mac then you may have to run following command + If you're on Mac, then you might have to run following command in terminal to launch a simulator. ```terminal From 4e202b84efbcaa075d30352c28db52d8045e7b1a Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Tue, 26 Apr 2022 07:46:32 -0700 Subject: [PATCH 6/8] Update src/get-started/test-drive/_vscode.md --- src/get-started/test-drive/_vscode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/get-started/test-drive/_vscode.md b/src/get-started/test-drive/_vscode.md index e8a8262468..dfb92ef469 100644 --- a/src/get-started/test-drive/_vscode.md +++ b/src/get-started/test-drive/_vscode.md @@ -31,7 +31,7 @@ contains a simple demo app that uses [Material Components][]. **Start iOS Simulator** to launch a simulator. {{site.alert.warning}} - You may not see **Start iOS Simulator** option + You might not see **Start iOS Simulator** option when you click **No Devices** in VS Code. If you're on Mac, then you might have to run following command in terminal to launch a simulator. From abb228192208c9ecd48ffe3455935e193a0ed6b6 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Tue, 26 Apr 2022 07:46:39 -0700 Subject: [PATCH 7/8] Update src/get-started/test-drive/_vscode.md --- src/get-started/test-drive/_vscode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/get-started/test-drive/_vscode.md b/src/get-started/test-drive/_vscode.md index dfb92ef469..427eb3360c 100644 --- a/src/get-started/test-drive/_vscode.md +++ b/src/get-started/test-drive/_vscode.md @@ -46,7 +46,7 @@ contains a simple demo app that uses [Material Components][]. - To setup a real device, follow the device-specific instructions on the [Install][] page for your OS. 1. Invoke **Run > Start Debugging** or press F5. -1. Wait for the app to launch — progress is printed +1. Wait for the app to launch—progress is printed in the **Debug Console** view. {% capture save_changes -%} From 6902f0cbcce663c1eede1bf664634206807a7af6 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Tue, 26 Apr 2022 07:46:50 -0700 Subject: [PATCH 8/8] Update src/get-started/test-drive/_vscode.md --- src/get-started/test-drive/_vscode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/get-started/test-drive/_vscode.md b/src/get-started/test-drive/_vscode.md index 427eb3360c..3433c93e61 100644 --- a/src/get-started/test-drive/_vscode.md +++ b/src/get-started/test-drive/_vscode.md @@ -40,7 +40,7 @@ contains a simple demo app that uses [Material Components][]. $ open -a simulator ``` - On Windows or Linux it is not possible to launch iOS simulator. + On Windows or Linux, it's not possible to launch an iOS simulator. {{site.alert.end}} - To setup a real device, follow the device-specific instructions