From 690bfdfc3ed7c4ac7ef3fc0991ea23ba4e52bf9e Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Fri, 15 Mar 2024 12:50:51 -0700 Subject: [PATCH] First draft of the FWE index page (#10282) Since we'd like to see this page staged, I made sure that there weren't any broken links. Files that aren't yet present just link back to this index page. New page staged here: https://flutter-docs-prod--pr10282-fwe-index-d041ol16.web.app/get-started/fwe --- src/get-started/fwe/fundamentals.md | 70 ++++++--- src/get-started/fwe/index.md | 84 +++++++++++ src/get-started/fwe/layout.md | 218 +++++++++++++++------------ src/get-started/fwe/local-caching.md | 15 +- src/get-started/fwe/networking.md | 80 ++++++---- src/get-started/fwe/user-input.md | 206 ++++++++++++++++--------- 6 files changed, 456 insertions(+), 217 deletions(-) create mode 100644 src/get-started/fwe/index.md diff --git a/src/get-started/fwe/fundamentals.md b/src/get-started/fwe/fundamentals.md index 32c4a70a09..70324c749d 100644 --- a/src/get-started/fwe/fundamentals.md +++ b/src/get-started/fwe/fundamentals.md @@ -9,15 +9,19 @@ next: permalink: /get-started/fwe/layout --- -Welcome to Flutter! On this page, there are a few videos, articles, and a short -tutorial that introduce many of the foundational concepts used by +On this page, there are a few videos, +articles, and a short tutorial that introduce many +of the foundational concepts used by Flutter developers on a daily basis. ## Welcome to Flutter -The following tutorial is a gentle introduction in building UIs with Flutter. It -starts with a 'hello world' app, and walks you through building a simple -shopping list application. If you're exploring Flutter for the first time, it's +The following tutorial is a gentle introduction +in building UIs with Flutter. +It starts with a 'hello world' app, +and walks you through building a simple +shopping list application. +If you're exploring Flutter for the first time, it's the perfect place to begin. @@ -25,8 +29,10 @@ Tutorial: [Building user interfaces with Flutter][] ## Dart -Flutter applications are built in [Dart][], a language that will look familiar -to anyone who's written Java, Javascript, or any other C-like language. The first +Flutter applications are built in [Dart][], +a language that will look familiar +to anyone who's written Java, Javascript, +or any other C-like language. The first resource listed here is a tutorial about writing Dart code. {{site.alert.note}} @@ -46,24 +52,33 @@ The other link has more resources for learning Dart. ## Anatomy of a widget -In regard to Flutter, you'll often hear "everything is a widget". This isn't -exactly true, but it is safe to say that "_almost_ everything is a widget". -Widgets are the UI building blocks that are combined to create a fully +In regard to Flutter, you'll often hear +"everything is a widget". This isn't +exactly true, but it is safe to say that +"_almost_ everything is a widget". +Widgets are the UI building blocks that +are combined to create a fully functional application. -In the first tutorial, [Building user interfaces with Flutter][], you saw some -built-in widgets, and created some custom widgets. The following videos expand -on what you learned by explaining in detail the two types of widgets that you -use the most in Flutter: stateless widgets and stateful widgets. +In the first tutorial, +[Building user interfaces with Flutter][], +you saw some built-in widgets, +and created some custom widgets. +The following videos expand +on what you learned by explaining in detail +the two types of widgets that you use the +most in Flutter: stateless widgets and stateful widgets. * [Flutter widgets 101 episode 1: Stateless widgets][] * [Flutter widgets 101 episode 2: Stateful widgets][] ## Important widgets to know -The Flutter SDK includes many built-in widgets, from the smallest pieces of UI, -like `Text`, to layout widgets, and widgets that style your application. The -following widgets are the most important to be aware of as you move onto the +The Flutter SDK includes many built-in widgets, +from the smallest pieces of UI, like `Text`, +to layout widgets, and widgets that style +your application. The following widgets are +the most important to be aware of as you move onto the next lesson in the learning pathway. * [`Container`][] @@ -77,11 +92,14 @@ next lesson in the learning pathway. ## Next: Layouts -This page is an introduction to foundational Flutter concepts, like -widgets, and helps you become familiar with reading Flutter and Dart code. It's -okay if you don't feel clear on every topic you encountered, as every page after -this is a deep-dive on specific topics. In the next section, you'll start -building more interesting UIs by creating more complex layouts in Flutter. +This page is an introduction to foundational +Flutter concepts, like widgets, +and helps you become familiar with reading +Flutter and Dart code. It's okay if you don't +feel clear on every topic you encountered, as every page after +this is a deep-dive on specific topics. +In the next section, you'll start building more +interesting UIs by creating more complex layouts in Flutter. [Building user interfaces with Flutter]:{{site.url}}/ui [Bootstrap into Dart]: {{site.url}}/resources/bootstrap-into-dart @@ -100,3 +118,11 @@ building more interesting UIs by creating more complex layouts in Flutter. [`Row`]: {{site.api}}/flutter/widgets/Row-class.html [`Scaffold`]: {{site.api}}/flutter/material/Scaffold-class.html [`Text`]: {{site.api}}/flutter/widgets/Text-class.html + +## Feedback + +As this section of the website is evolving, +we [welcome your feedback][]! + +[welcome your feedback]: {{site.url}}/get-started/fwe + diff --git a/src/get-started/fwe/index.md b/src/get-started/fwe/index.md new file mode 100644 index 0000000000..c737bc5bc1 --- /dev/null +++ b/src/get-started/fwe/index.md @@ -0,0 +1,84 @@ +--- +title: First week experience of Flutter +description: > + You've gotten a taste of using the Flutter framework; + now go beyond to learn the basics of Flutter. +--- + +## Welcome to the next level of Flutter! + +If you are new to Flutter, and have already worked +through [your first Flutter codelab][], +this section of the website is for you! + +The goal here is to guide you through some next +steps of learning Flutter. It's not about teaching +you how to _program_, it's about teaching you +how Flutter works. + +{{site.alert.note}} + This first week experience is still a work + in progress and we welcome your feedback! + Please consider filling out the survey + listed at the bottom of this page and on the + new subject pages in this section. +{{site.alert.end}} + +As you might know, Flutter uses the [Dart language][]. +If you have experience with other object-oriented +languages, like Java, C++, or Swift, +Dart should feel familiar to you. +As of this writing, +[Dart is one of the fastest growing languages][dart-lang], +in part, thanks to Flutter. + +[Dart language]: {{site.dart-site}} +[dart-lang]: https://twitter.com/MiSvTh/status/1732002450641400276?cxt +[your first Flutter codelab]: {{site.codelabs}}/codelabs/flutter-codelab-first + +We suggest that you work through the +following subjects in the listed order. + +1. [Widget fundamentals][] +: Learn about one of the primary building blocks + of a Flutter application, `Widgets`. +2. [Layout][] +: Flutter is different from other UI frameworks + in that you create the layout programmatically. + This allows you to compose widgets, + Flutter's basic building blocks, + to realize your own layout vision. + It also facilitates designing a UI to + optimize any screen where your app might be used. +3. [State management][] +: Learn how to manage state. xxx +4. [Handling user input][] +: Learn about Flutter's widgets that support + interactivity, like buttons and text. + Also, learn how to add interactivity to + a widget that doesn't already support it. +5. [Networking and data][] +: Networking is a very large topic, + so this section focuses on basic networking + functionality, such as how to retrieve + or submit data using HTTP, + how to convert to and from JSON, + how to use authentication, + how to implement asynchronicity, and more. +6. [Local data and caching][] +: Learn about different techniques for caching + local data. + +[Widget fundamentals]: {{site.url}}/get-started/fwe/fundamentals +[Layout]: {{site.url}}/get-started/fwe/layout +[State management]: {{site.url}}/get-started/fwe +[Handling user input]: {{site.url}}/get-started/fwe/user-input +[Networking and data]: {{site.url}}/networking +[Local data and caching]: {{site.url}}/get-started/fwe/local-caching + +## Feedback + +As this section of the website is evolving, +we [welcome your feedback][]! + +[welcome your feedback]: {{site.url}}/get-started/fwe diff --git a/src/get-started/fwe/layout.md b/src/get-started/fwe/layout.md index ef30433d31..cc8397e35c 100644 --- a/src/get-started/fwe/layout.md +++ b/src/get-started/fwe/layout.md @@ -8,37 +8,45 @@ next: title: State management --- -Given that Flutter is a UI toolkit, you’ll spend a lot of time creating layouts -with Flutter widgets. In this section, you’ll learn how to build simple and +Given that Flutter is a UI toolkit, +you’ll spend a lot of time creating layouts +with Flutter widgets. In this section, +you’ll learn how to build simple and complex layouts with some of the most common layout widgets. -You’ll use DevTools to understand how Flutter is creating your layout. -Finally, you'll encounter and debug one of Flutter's most common layout errors, +You’ll use DevTools to understand how +Flutter is creating your layout. +Finally, you'll encounter and debug one of +Flutter's most common layout errors, the dreaded "unbounded constraints" error. ### Introduction to layouts -The following tutorial introduces you to layouts in Flutter, and gives you an -opportunity to work with the most common layout widgets, like rows and columns. +The following tutorial introduces you to layouts +in Flutter, and gives you an opportunity to work +with the most common layout widgets, like rows and columns. Tutorial: [Layouts in Flutter][] ### Constraints -Understanding “constraints” in Flutter are an important part of understanding +Understanding “constraints” in Flutter is an +important part of understanding how Flutter’s layout algorithm works. -The following resources teach you what constraints are and some widgets that +The following resources teach you what +constraints are and some widgets that allow you to work with constraints. -* Article: [Understanding Constraints][] -* Video: [Expanded - Flutter Widget of the Week][] -* Video: [Flexible - Flutter Widget of the Week][] -* Video: [Intrinsic widgets - Decoding Flutter][] +* Article: [Understanding constraints][] +* Video: [Expanded—Flutter Widget of the Week][] +* Video: [Flexible—Flutter Widget of the Week][] +* Video: [Intrinsic widgets—Decoding Flutter][] ### Intermediate layout tutorial -Now that you understand layouts and some tools for working with them, -check out the following tutorial, which goes a bit deeper into common layout +Now that you understand layouts and some tools +for working with them, check out the following tutorial, +which goes a bit deeper into common layout widgets than the starting tutorial. Tutorial: [Build a Flutter Layout][] @@ -50,114 +58,138 @@ that are a bit more involved than using rows and columns. #### Scrollable widgets -Several Flutter widgets facilitate scrolling through content in -your application. First, you’ll see how to use the most common widget for -making any page scrollable, as well as a widget for creating scrollable -lists. You’ll also be introduced to a common pattern in Flutter - the builder -pattern. Many Flutter widgets use the builder pattern, including some -scrolling widgets. +Several Flutter widgets facilitate scrolling through +content in your application. +First, you’ll see how to use the most common widget for +making any page scrollable, +as well as a widget for creating scrollable lists. +You’ll also be introduced to a common pattern in +Flutter—the builder pattern. +Many Flutter widgets use the builder pattern, +including some scrolling widgets. * Documentation: [Basic scrolling][] -* Video: [Builder - Flutter Widget of the Week][] -* Video: [ListView - Flutter Widget of the Week][] +* Video: [Builder—Flutter Widget of the Week][] +* Video: [ListView—Flutter Widget of the Week][] * Example code: [Work with long lists][] * Example code: [Create a horizontal list][] * Example code: [Create a grid list][] -* Video: [PageView - Flutter Widget of the Week][] +* Video: [PageView—Flutter Widget of the Week][] #### Stacks -Stacks give you more flexibility in placing widgets in Flutter by allowing you -to specify exact locations of widgets within their parent, including on top of -each other. If you’re coming from the web, `Stacks` solve the same problem -as `z-index`. +Stacks give you more flexibility in placing widgets +in Flutter by allowing you to specify exact locations +of widgets within their parent, +including on top of each other. +If you’re coming from the web, +`Stacks` solve the same problem as `z-index`. -If you followed the previous tutorials mentioned on this page, you’ve already -worked with `Stack`s. If not, these resources provide an overview. +If you followed the previous tutorials mentioned +on this page, you’ve already worked with `Stack`s. +If not, these resources provide an overview. -* Video: [Stack - Flutter Widget of the Week][] +* Video: [Stack—Flutter Widget of the Week][] * Documentation: [Stack documentation][] #### Overlays -Use an `Overlay`` when you have widgets that are logically related to each -other but visually separate, such as tooltips. +Use an `Overlay`` when you have widgets that are +logically related to each other but visually separate, +such as tooltips. -* Video: [OverlayPortal - Flutter Widget of the Week][] +* Video: [OverlayPortal—Flutter Widget of the Week][] ### Adaptive layouts -Because Flutter is used to create mobile, tablet, desktop, _and_ web apps, it’s -likely you’ll need to adjust your application to behave differently depending on -things like screen-size or input device. This is referred to as making an app -_adaptive_ and _responsive_. The following resources start by -showing the most important widgets when building adaptive layouts, and finish -with a codelab that has you build an adaptive layout yourself. - -* Video: [LayoutBuilder - Flutter Widget of the Week][] -* Video: [MediaQuery - Flutter Widget of the Week][] +Because Flutter is used to create mobile, +tablet, desktop, _and_ web apps, +it’s likely you’ll need to adjust your +application to behave differently depending on +things like screen size or input device. +This is referred to as making an app +_adaptive_ and _responsive_. +The following resources start by +showing the most important widgets when +building adaptive layouts, +and finish with a codelab that has you +build an adaptive layout yourself. + +* Video: [LayoutBuilder—Flutter Widget of the Week][] +* Video: [MediaQuery—Flutter Widget of the Week][] * Video: [Building platform adaptive apps][] Tutorial: [Adaptive Apps codelab][] ### DevTools and debugging layout -Flutter has a robust suite of DevTools that help you work with any number -of aspects of Flutter development. The “Widget Inspector” tool is particularly +Flutter has a robust suite of DevTools that +help you work with any number of aspects of +Flutter development. +The "Widget Inspector" tool is particularly useful when building layouts (and working with widgets in general). -Additionally, perhaps the most common error you’ll run into while building a -Flutter application is due to incorrectly using layout widgets, and is referred -to as the “unbounded constraints” error. If there was only one type error you -should be prepared to confront before you start building Flutter apps, it would be -this type. +Additionally, perhaps the most common error +you’ll run into while building a Flutter application +is due to incorrectly using layout widgets, +and is referred to as the “unbounded constraints” error. +If there was only one type error you should be prepared +to confront when you first start building Flutter apps, +it would be this one. -* Article: [DevTools - Widget Inspector][] -* Video: [Unbounded height and width - Decoding Flutter][] +* Article: [DevTools—Widget inspector][] +* Video: [Unbounded height and width—Decoding Flutter][] ### Reference material The following resources explain individual APIs. -- [Builder][] -- [Row][] -- [Column][] -- [Expanded][] -- [Flexible][] -- [ListView][] -- [Stack][] -- [Positioned][] -- [MediaQuery][] - -[Layouts in Flutter]: /ui/layout -[Understanding Constraints]: /ui/layout/constraints -[Expanded - Flutter Widget of the Week]: https://www.youtube.com/watch?v=_rnZaagadyo -[Flexible - Flutter Widget of the Week]: https://www.youtube.com/watch?v=CI7x0mAZiY0 -[Intrinsic widgets - Decoding Flutter]: https://www.youtube.com/watch?v=Si5XJ_IocEs -[Build a Flutter Layout]: /ui/layout/tutorial -[Basic scrolling]: /ui/layout/scrolling#basic-scrolling -[Builder - Flutter Widget of the Week]: https://www.youtube.com/watch?v=xXNOkIuSYuA -[ListView - Flutter Widget of the Week]: https://www.youtube.com/watch?v=KJpkjHGiI5A -[Work with long lists]: /cookbook/lists/long-lists -[Create a horizontal list]: /cookbook/lists/horizontal-list -[Create a grid list]: /cookbook/lists/grid-lists -[PageView - Flutter Widget of the Week]: https://www.youtube.com/watch?v=J1gE9xvph-A -[Stack - Flutter Widget of the Week]: https://www.youtube.com/watch?v=liEGSeD3Zt8 -[Stack documentation]: /ui/layout#stack -[OverlayPortal - Flutter Widget of the Week]: https://www.youtube.com/watch?v=S0Ylpa44OAQ -[LayoutBuilder - Flutter Widget of the Week]: https://www.youtube.com/watch?v=IYDVcriKjsw -[MediaQuery - Flutter Widget of the Week]: https://www.youtube.com/watch?v=A3WrA4zAaPw -[Adaptive Apps codelab]: https://codelabs.developers.google.com/codelabs/flutter-adaptive-app -[Building platform adaptive apps]: https://www.youtube.com/watch?v=RCdeSKVt7LI -[DevTools - Widget Inspector]: /tools/devtools/inspector -[Unbounded height and width - Decoding Flutter]: https://www.youtube.com/watch?v=jckqXR5CrPI -[2D Scrolling]: https://www.youtube.com/watch?v=ppEdTo-VGcg -[Builder]: {{site.api}}/flutter/widgets/Builder-class.html -[Row]: {{site.api}}flutter/widgets/Row-class.html -[Column]: {{site.api}}flutter/widgets/Column-class.html -[Expanded]: {{site.api}}flutter/widgets/Expanded-class.html -[Flexible]: {{site.api}}flutter/widgets/Flexible-class.html -[ListView]: {{site.api}}flutter/widgets/ListView-class.html -[Stack]: {{site.api}}flutter/widgets/Stack-class.html -[Positioned]: {{site.api}}flutter/widgets/Positioned-class.html -[MediaQuery]: {{site.api}}flutter/widgets/MediaQuery-class.html \ No newline at end of file +* [`Builder`][] +* [`Row`][] +* [`Column`][] +* [`Expanded`][] +* [`Flexible`][] +* [`ListView`][] +* [`Stack`][] +* [`Positioned`][] +* [`MediaQuery`][] + +[Layouts in Flutter]: {{site.url}}/ui/layout +[Understanding constraints]: {{site.url}}/ui/layout/constraints +[Expanded—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=_rnZaagadyo +[Flexible—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=CI7x0mAZiY0 +[Intrinsic widgets—Decoding Flutter]: {{site.youtube-site}}/watch?v=Si5XJ_IocEs +[Build a Flutter Layout]: {{site.url}}/ui/layout/tutorial +[Basic scrolling]: {{site.url}}/ui/layout/scrolling#basic-scrolling +[Builder—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=xXNOkIuSYuA +[ListView—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=KJpkjHGiI5A +[Work with long lists]: {{site.url}}/cookbook/lists/long-lists +[Create a horizontal list]: {{site.url}}/cookbook/lists/horizontal-list +[Create a grid list]: {{site.url}}/cookbook/lists/grid-lists +[PageView—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=J1gE9xvph-A +[Stack—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=liEGSeD3Zt8 +[Stack documentation]: {{site.url}}/ui/layout#stack +[OverlayPortal—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=S0Ylpa44OAQ +[LayoutBuilder—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=IYDVcriKjsw +[MediaQuery—Flutter Widget of the Week]: {{site.youtube-site}}/watch?v=A3WrA4zAaPw +[Adaptive apps codelab]: {{site.codelabs}}/codelabs/flutter-adaptive-app +[Building platform adaptive apps]: {{site.youtube-site}}/watch?v=RCdeSKVt7LI +[DevTools—Widget inspector]: {{site.url}}/tools/devtools/inspector +[Unbounded height and width—Decoding Flutter]: {{site.youtube-site}}/watch?v=jckqXR5CrPI +[2D Scrolling]: {{site.youtube-site}}/watch?v=ppEdTo-VGcg +[`Builder`]: {{site.api}}/flutter/widgets/Builder-class.html +[`Row`]: {{site.api}}flutter/widgets/Row-class.html +[`Column`]: {{site.api}}flutter/widgets/Column-class.html +[`Expanded`]: {{site.api}}flutter/widgets/Expanded-class.html +[`Flexible`]: {{site.api}}flutter/widgets/Flexible-class.html +[`ListView`]: {{site.api}}flutter/widgets/ListView-class.html +[`Stack`]: {{site.api}}flutter/widgets/Stack-class.html +[`Positioned`]: {{site.api}}flutter/widgets/Positioned-class.html +[`MediaQuery`]: {{site.api}}flutter/widgets/MediaQuery-class.html + +## Feedback + +As this section of the website is evolving, +we [welcome your feedback][]! + +[welcome your feedback]: {{site.url}}/get-started/fwe diff --git a/src/get-started/fwe/local-caching.md b/src/get-started/fwe/local-caching.md index 1dd782a83c..93910e649d 100644 --- a/src/get-started/fwe/local-caching.md +++ b/src/get-started/fwe/local-caching.md @@ -164,7 +164,7 @@ For a complete guide, see our other resources on using key-value stores. ### Caching data with the file system If your Flutter app outgrows the low-throughput scenarios -ideal for `shared_preferences`, you may be ready to explore +ideal for `shared_preferences`, you might be ready to explore caching data with your device's file system. For a more thorough guide, see our other resources on file system caching. @@ -196,9 +196,11 @@ use the [`cached_network_image` package][]. * Video: [Package of the Week: `cached_network_image`][] +[PENDING: My understanding is that we now recommend `Image.network` instead of cache_network_image. + ## State restoration -Along with application data, you may also want to persist other +Along with application data, you might also want to persist other aspects of a user's session, like their navigation stack, scroll positions, and even partial progress filling out forms. This pattern is called "state restoration", and is built in to Flutter. @@ -207,11 +209,18 @@ State restoration works by instructing the Flutter framework to sync data from its Element tree with the Flutter engine, which then caches it in platform-specific storage for future sessions. To enable state restoration on Flutter for Android -and iOS, see the documentation below: +and iOS, see the following documentation: * Android documentation: [Android state restoration][] * iOS documentation: [iOS state restoration][] +## Feedback + +As this section of the website is evolving, +we [welcome your feedback][]! + +[welcome your feedback]: {{site.url}}/get-started/fwe + [Android state restoration]: /platform-integration/android/restore-state-android [`cached_network_image` package]: {{site.pub-pkg}}/cached_network_image [dependency injection]: https://en.wikipedia.org/wiki/Dependency_injection diff --git a/src/get-started/fwe/networking.md b/src/get-started/fwe/networking.md index 7a361e5a00..2ae3868812 100644 --- a/src/get-started/fwe/networking.md +++ b/src/get-started/fwe/networking.md @@ -8,20 +8,26 @@ next: --- While it's said that "no man is an island", -a Flutter app without any networking capability can feel a tad disconnected. -This page covers how to add networking features to your Flutter app. -Your app will retrieve data, parse JSON into usable in memory representations, +a Flutter app without any networking capability +can feel a tad disconnected. +This page covers how to add networking features +to your Flutter app. Your app will retrieve data, +parse JSON into usable in memory representations, and then send data out again. ## Introduction to retrieving data over the network The following two tutorials introduce you to the [`http`][] package, which enables your app to make -[HTTP][] requests with ease, whether you are running on Android, -iOS, inside a web browser, or natively on Windows, macOS, or Linux. -The first tutorial shows you how to make an unauthenticated `GET` request -to a website, parse the retrieved data as `JSON` and then display the resulting data. -The second tutorial builds on the first by adding authentication headers, +[HTTP][] requests with ease, +whether you are running on Android, +iOS, inside a web browser, or natively on Windows, +macOS, or Linux. +The first tutorial shows you how to make an +unauthenticated `GET` request to a website, +parse the retrieved data as `JSON` and then +display the resulting data. The second tutorial +builds on the first by adding authentication headers, enabling access to web servers requiring authorization. The article by the Mozilla Developer Network (MDN) gives more background on how authorization works on the web. @@ -37,29 +43,35 @@ you need a way to convert the data from the network into something that you can easily work with in Dart. The tutorials in the previous section used hand rolled Dart to convert network data into an in-memory representation. -In this section, you'll see other options for handling this conversion. -The first links to a YouTube video showing an overview of the [`freezed` package][]. -The second links to a codelab that covers patterns and records -using a case study of parsing JSON. +In this section, +you'll see other options for handling this conversion. +The first links to a YouTube video showing an overview +of the [`freezed` package][]. +The second links to a codelab that covers patterns +and records using a case study of parsing JSON. * YouTube video: [Freezed (Package of the Week)][] * Codelab: [Dive into Dart's patterns and records][] ## Going both ways, getting data out again -Now that you've mastered the art of retrieving data, it's time to look at pushing data out. -This information starts with sending data to the network, but then dives into asynchronicity. -The truth is, once you are in a conversation over the network, -you'll need to deal with the fact that web servers that are physically far away -can take a while to respond, and you can't stop rendering to the screen +Now that you've mastered the art of retrieving data, +it's time to look at pushing data out. +This information starts with sending data to the network, +but then dives into asynchronicity. The truth is, +once you are in a conversation over the network, +you'll need to deal with the fact that web servers +that are physically far away can take a while to respond, +and you can't stop rendering to the screen while you wait for packets to round trip. -Dart has really great support for asynchronicity, as does Flutter. +Dart has great support for asynchronicity, +as does Flutter. You'll learn all about Dart's support in a tutorial, -then see Flutter's capability covered in a Widget of the Week video. +then see Flutter's capability covered in a +Widget of the Week video. Once you complete that, you'll learn how to debug network traffic using DevTool's Network View. - * Tutorial: [Send data to the internet][] * Tutorial: [Asynchronous programming: futures, async, await][] * YouTube video: [FutureBuilder (Widget of the Week)][] @@ -69,20 +81,29 @@ network traffic using DevTool's Network View. Now that you've mastered using Flutter's networking APIs, it helps to see Flutter's network usage in context. -The first codelab (ostensibly on creating Adaptive Apps in Flutter), +The first codelab (ostensibly on creating Adaptive apps in Flutter), uses a web server written in Dart to work around the web browsers' [Cross-Origin Resource Sharing (CORS) restrictions][]. -Next, a long-form YouTube video where Flutter DevRel alumnus, -Fitz, talks about how the location of data matters for Flutter apps. + +{{site.alert.note}} + If you've already worked through this codelab + on the [layout][] page, feel free to skip this step. +{{site.alert.end}} + +[layout]: {{site.url}}/get-started/fwe/layout + +Next, a long-form YouTube video where +Flutter DevRel alumnus, Fitz, +talks about how the location of data matters for Flutter apps. Finally, a really useful series of articles by Flutter GDE Anna (Domashych) Leushchenko covering advanced networking in Flutter. -* Codelab: [Adaptive Apps in Flutter][] +* Codelab: [Adaptive apps in Flutter][] * Video: [Keeping it local: Managing a Flutter app's data][] * Article series: [Basic and advanced networking in Dart and Flutter][] -[Adaptive Apps in Flutter]: {{site.codelabs}}/codelabs/flutter-adaptive-app +[Adaptive apps in Flutter]: {{site.codelabs}}/codelabs/flutter-adaptive-app [Asynchronous programming: futures, async, await]: {{site.dart-site}}/codelabs/async-await [Basic and advanced networking in Dart and Flutter]: {{site.medium}}/tide-engineering-team/basic-and-advanced-networking-in-dart-and-flutter-the-tide-way-part-0-introduction-33ac040a4a1c [Cross-Origin Resource Sharing (CORS) restrictions]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS @@ -97,4 +118,11 @@ Anna (Domashych) Leushchenko covering advanced networking in Flutter. [Make authenticated requests]: /cookbook/networking/authenticated-requests [MDN's article on Authorization for websites]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization [Using the Network View]: https://docs.flutter.dev/tools/devtools/network -[Send data to the internet]: https://docs.flutter.dev/cookbook/networking/send-data \ No newline at end of file +[Send data to the internet]: https://docs.flutter.dev/cookbook/networking/send-data + +## Feedback + +As this section of the website is evolving, +we [welcome your feedback][]! + +[welcome your feedback]: {{site.url}}/get-started/fwe diff --git a/src/get-started/fwe/user-input.md b/src/get-started/fwe/user-input.md index 5575cbc43f..c72ae64a33 100644 --- a/src/get-started/fwe/user-input.md +++ b/src/get-started/fwe/user-input.md @@ -9,63 +9,108 @@ next: path: /get-started/fwe/networking --- -Now that you know how to manage state in your Flutter app, how can you let users interact with your app and change its state? +Now that you know how to manage state in your +Flutter app, how can you let users interact +with your app and change its state? ## Introduction to user input -As a multi-platform UI framework, there are many different ways for users to interact with a Flutter app. The resources in this section will introduce you to some of the common widgets used for enabling user interaction. +As a multi-platform UI framework, +there are many different ways for users +to interact with a Flutter app. +The resources in this section introduce +you to some of the common widgets used +for enabling user interaction. -Some user input types, like [scrolling], have already been covered in previous sections. +Some user input types, like [scrolling], +have already been covered in [Layouts][]. -For an introduction to how you can change app state in response to user interactions, -check out the following tutorial that teaches you how to build a "favorite" button: +For an introduction to how you can change app +state in response to user interactions, +check out the following tutorial that +teaches you how to build a "favorite" button: Tutorial: [Add interactivity to your Flutter app][] +[Layouts]: {{site.url}}/get-started/fwe/layout + ## Material 3 demo -Now that you've gotten a feel for how user interaction works, -check out the [Material 3 Demo][], which samples some of the -user input widgets available in the Material 3 component library. +Next, check out the [Material 3 Demo][], +which samples some of the user input widgets +available in the Material 3 component library. {{site.alert.note}} - This page focuses on Material 3 widgets because it's the library - that many developers start with when learning Flutter. - However, Flutter also supports [Cupertino][] for iOS-styled widgets, + This page focuses on Material 3 widgets because + it's the library that many developers start with + when learning Flutter. However, + Flutter also supports [Cupertino][] for iOS-styled widgets, or you can build your own widget library. {{site.alert.end}} +[Cupertino]: {{site.api}}flutter/cupertino/cupertino-library.html + ## Get user input This section covers widgets that help you build the most common user input methods into your Flutter app. ### Click or tap (Buttons) + Let a user prompt action in a UI by clicking or tapping. The following Material 3 button types are functionally similar, but are styled differently: -[ElevatedButton][]: A button with some depth. Use elevated buttons to add dimension to otherwise mostly flat layouts. +[`ElevatedButton]`[] +: A button with some depth. + Use elevated buttons to add dimension + to otherwise mostly flat layouts. -[FilledButton][]: A filled button that should be used for important, final actions that complete a flow, like Save, Join now, or Confirm. +[`FilledButton`][] +: A filled button that should be used for important, + final actions that complete a flow, + like **Save**, **Join now**, or **Confirm**. -[OutlinedButton][]: A button with text and a visible border. They contain actions that are important, but they aren’t the primary action in an app. +[`OutlinedButton`][] +: A button with text and a visible border. + These buttons contain actions that are important, + but aren’t the primary action in an app. -[TextButton][]: Clickable text, without a border. Text buttons do not have visible borders and must therefore rely on their position relative to other content for context. +[`TextButton`][] +: Clickable text, without a border. + Since text buttons don't have visible borders + and they must therefore rely on their position + relative to other content for context. -[IconButton][]: A button with an icon. +[`IconButton`][]: A button with an icon. -[FloatingActionButton][]: A circular icon button that hovers over content to promote a primary action. - * Video: [FloatingActionButton (Widget of the Week)][] +[`FloatingActionButton`][] +: A circular icon button that hovers over + content to promote a primary action. + +* Video: [FloatingActionButton (Widget of the Week)][] + +[`ElevatedButton`]: {{site.api}}flutter/material/ElevatedButton-class.html +[`FilledButton`]: {{site.api}}flutter/material/FilledButton-class.html +[`FloatingActionButton`]: {{site.api}}flutter/material/FloatingActionButton-class.html +[FloatingActionButton (Widget of the Week)]: https://youtu.be/2uaoEDOgk_I?si=MQZcSp24oRaS_kiY +[`IconButton`]: {{site.api}}flutter/material/IconButton-class.html +[`OutlinedButton`]: {{site.api}}flutter/material/OutlinedButton-class.html +[`TextButton`]: {{site.api}}flutter/material/TextButton-class.html ### Text + Several widgets support text input. -[`TextField`][]: Let users enter text, either with hardware keyboard or with an onscreen keyboard. +[`TextField`][] +: Let users enter text, either with hardware + keyboard or with an onscreen keyboard. + +The following series of cookbook articles walk +you through every step on how to build a text field, +retrieve its value, and handle state changes: -This series of cookbook articles walk you through every stop -on how to build a text field, retrieve its value, and handle state changes: 1. Article: [Create and style a text field][] 1. Article: [Retrieve the value of a text field][] 1. Article: [Handle changes to a text field][] @@ -84,11 +129,28 @@ on how to build a text field, retrieve its value, and handle state changes: * Video: [SelectableText (Widget of the Week)][] [`Form`][] -: An optional container for grouping together multiple form field widgets. +: An optional container for grouping together + multiple form field widgets. * Article: [Build a form with validation][] -* Demo: [Form App][] -* Sample code: [Form App Code][] +* Demo: [Form app][] +* Sample code: [Form app code][] + +[Build a form with validation]: {{site.url}}/cookbook/forms/validation +[Create and style a text field]: {{site.url}}/cookbook/forms/text-input +[Focus and text fields]: {{site.url}}/cookbook/forms/focus +[`Form`]: {{site.api}}flutter/widgets/Form-class.html +[Form app]: https://flutter.github.io/samples/web/form_app/ +[Form app code]: https://github.com/flutter/samples/tree/main/form_app +[Handle changes to a text field]: {{site.url}}/cookbook/forms/text-field-changes +[Retrieve the value of a text field]: {{site.url}}/cookbook/forms/retrieve-input +[`RichText`]: {{site.api}}flutter/widgets/RichText-class.html +[Rich Text (Widget of the Week)]: https://www.youtube.com/watch?v=rykDVh-QFfw +[Rich Text Editor]: https://flutter.github.io/samples/rich_text_editor.html +[Rich Text Editor code]: https://github.com/flutter/samples/tree/main/simplistic_editor +[`SelectableText`]: {{site.api}}flutter/material/SelectableText-class.html +[SelectableText (Widget of the Week)]: https://www.youtube.com/watch?v=ZSU3ZXOs6hc +[`TextField`]: {{site.api}}flutter/material/TextField-class.html ### Select a value from a group of options @@ -106,10 +168,17 @@ on how to build a text field, retrieve its value, and handle state changes: * Video: [Slider, RangeSlider, CupertinoSlider (Widget of the Week)][] +[`DropdownMenu`]: {{site.api}}flutter/material/DropdownMenu-class.html +[DropdownMenu (Widget of the Week)]: https://youtu.be/giV9AbM2gd8?si=E23hjg72cjMTe_mz +[`SegmentedButton`]: {{site.api}}flutter/material/SegmentedButton-class.html +[`Slider`]: {{site.api}}flutter/material/Slider-class.html +[Slider, RangeSlider, CupertinoSlider (Widget of the Week)]: https://www.youtube.com/watch?v=ufb4gIPDmEss + ### Toggle values [`Checkbox`][] -: Select one or more items from a list, or toggle an item. +: Select one or more items from a list, + or toggle an item. [`CheckboxListTile`][] : A checkbox with a label. @@ -136,10 +205,12 @@ on how to build a text field, retrieve its value, and handle state changes: ### Select a date or time [`showDatePicker`][] -: Shows a dialog containing a [Material Design date picker][]. +: Shows a dialog containing a + [Material Design date picker][]. [`showTimePicker`][] -: Shows a dialog containing a [Material Design time picker][]. +: Shows a dialog containing a + [Material Design time picker][]. ### Swipe and slide @@ -150,14 +221,17 @@ on how to build a text field, retrieve its value, and handle state changes: * Article: [Implement swipe to dismiss][] [pkg:`flutter_slidable`][] -: A list item with directional slide actions that can be dismissed. +: A list item with directional slide actions + that can be dismissed. * Video: [flutter_slidable (Package of the Week)][] -## Build your own interactive widget with GestureDetector +## Add interactivity with GestureDetector -If none of Flutter's widgets fit the functionality for what you're looking for, -you can add interactivity to your own widget using `GestureDetector`. +If none of Flutter's widgets fit the functionality +for what you're looking for, +you can add interactivity to your own widget +using `GestureDetector`. * Video: [GestureDetector (Widget of the Week)][] * Documentation: [Taps, drags, and other gestures][] @@ -167,7 +241,8 @@ Don't forget about accessibility! If you're building your own custom widget, you can annotate its meaning with the `Semantics` widget. It lets you provide descriptions, metadata, -and more to screen readers and other semantic analysis-based tools. +and more to screen readers and other semantic +analysis-based tools. * Video: [Semantics (Flutter Widget of the Week)][] @@ -179,52 +254,37 @@ check out the following video: * Video: [GestureArena (Decoding Flutter)][] ## Testing -Once you have finished building user interactions into your app, -don't forget to write tests to make sure that everything works as expected! + +Once you have finished building user interactions +into your app, don't forget to write tests to +ensure that everything works as expected! * Article: [Tap, drag, and enter text][] * Article: [Handle scrolling][] +[GestureArena (Decoding Flutter)]: https://www.youtube.com/watch?v=Q85LBtBdi0U +[GestureDetector (Widget of the Week)]: https://www.youtube.com/watch?v=WhVXkCFPmK4 +[Handle taps]: {{site.url}}/cookbook/gestures/handling-taps +[Semantics (Flutter Widget of the Week)]: https://youtu.be/NvtMt_DtFrQ?si=o79BqAg9NAl8EE8_ +[Tap, drag, and enter text]: {{site.url}}/cookbook/testing/widget/tap-drag +[Taps, drags, and other gestures]: {{site.url}}/ui/interactivity/gestures#gestures + ## Next: Networking -This page was an introduction to handling user input. Now that you know how to accept input from app's users, you can make your app even more interesting by adding external data. In the next section, you will learn now to fetch data for your app over a network. +This page was an introduction to handling user input. +Now that you know how to accept input from app's users, +you can make your app even more interesting by adding +external data. In the next section, +you'll learn now to fetch data for your app over a network, +how to convert data to and from JSON, authentication, +and other networking features. [scrolling]: /get-started/fwe/layout#scrollable-widgets [Add interactivity to your Flutter app]: /ui/interactivity -[Cupertino]: {{site.api}}flutter/cupertino/cupertino-library.html [Material 3 Demo]: https://flutter.github.io/samples/web/material_3_demo/ -[ElevatedButton]: {{site.api}}flutter/material/ElevatedButton-class.html -[FilledButton]: {{site.api}}flutter/material/FilledButton-class.html -[TextButton]: {{site.api}}flutter/material/TextButton-class.html -[OutlinedButton]: {{site.api}}flutter/material/OutlinedButton-class.html -[IconButton]: {{site.api}}flutter/material/IconButton-class.html -[FloatingActionButton]: {{site.api}}flutter/material/FloatingActionButton-class.html -[FloatingActionButton (Widget of the Week)]: https://youtu.be/2uaoEDOgk_I?si=MQZcSp24oRaS_kiY - -[`TextField`]: {{site.api}}flutter/material/TextField-class.html -[Create and style a text field]: /cookbook/forms/text-input -[Retrieve the value of a text field]: /cookbook/forms/retrieve-input -[Handle changes to a text field]: /cookbook/forms/text-field-changes -[Focus and text fields]: /cookbook/forms/focus -[`RichText`]: {{site.api}}flutter/widgets/RichText-class.html -[Rich Text (Widget of the Week)]: https://www.youtube.com/watch?v=rykDVh-QFfw -[Rich Text Editor]: https://flutter.github.io/samples/rich_text_editor.html -[Rich Text Editor code]: https://github.com/flutter/samples/tree/main/simplistic_editor -[`Form`]: {{site.api}}flutter/widgets/Form-class.html -[Build a form with validation]: /cookbook/forms/validation -[Form App]: https://flutter.github.io/samples/web/form_app/ -[Form App Code]: https://github.com/flutter/samples/tree/main/form_app -[`SelectableText`]: {{site.api}}flutter/material/SelectableText-class.html -[SelectableText (Widget of the Week)]: https://www.youtube.com/watch?v=ZSU3ZXOs6hc - -[`SegmentedButton`]: {{site.api}}flutter/material/SegmentedButton-class.html -[`DropdownMenu`]: {{site.api}}flutter/material/DropdownMenu-class.html -[DropdownMenu (Widget of the Week)]: https://youtu.be/giV9AbM2gd8?si=E23hjg72cjMTe_mz -[`Slider`]: {{site.api}}flutter/material/Slider-class.html -[Slider, RangeSlider, CupertinoSlider (Widget of the Week)]: https://www.youtube.com/watch?v=ufb4gIPDmEss [`Checkbox`]: {{site.api}}flutter/material/Checkbox-class.html @@ -243,15 +303,15 @@ This page was an introduction to handling user input. Now that you know how to a [`Dismissible`]: {{site.api}}flutter/widgets/Dismissible-class.html [Dismissible (Widget of the Week)]: https://youtu.be/iEMgjrfuc58?si=f0S7IdaA9PIWIYvl -[Implement swipe to dismiss]: /cookbook/gestures/dismissible +[Implement swipe to dismiss]: {{site.url}}/cookbook/gestures/dismissible [pkg:`flutter_slidable`]: https://pub.dev/packages/flutter_slidable [flutter_slidable (Package of the Week)]: https://www.youtube.com/watch?v=QFcFEpFmNJ8 -[GestureDetector (Widget of the Week)]: https://www.youtube.com/watch?v=WhVXkCFPmK4 -[Taps, drags, and other gestures]: /ui/interactivity/gestures#gestures -[Handle taps]: /cookbook/gestures/handling-taps -[Semantics (Flutter Widget of the Week)]: https://youtu.be/NvtMt_DtFrQ?si=o79BqAg9NAl8EE8_ -[GestureArena (Decoding Flutter)]: https://www.youtube.com/watch?v=Q85LBtBdi0U +[Handle scrolling]: {{site.url}}/cookbook/testing/widget/scrolling + +## Feedback + +As this section of the website is evolving, +we [welcome your feedback][]! -[Tap, drag, and enter text]: /cookbook/testing/widget/tap-drag -[Handle scrolling]: /cookbook/testing/widget/scrolling \ No newline at end of file +[welcome your feedback]: {{site.url}}/get-started/fwe