From d571257a9916714b86fe6ac8daab1acbb27a00b4 Mon Sep 17 00:00:00 2001 From: Alberto Date: Tue, 21 Dec 2021 02:44:10 +0100 Subject: [PATCH] Updated Stateless and Stateful widget docstrings (#95407) --- .../flutter/lib/src/widgets/framework.dart | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 1ad1e6d1783..ca248ba8a63 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -438,6 +438,14 @@ abstract class Widget extends DiagnosticableTree { /// * Use `const` widgets where possible, and provide a `const` constructor for /// the widget so that users of the widget can also do so. /// +/// * When trying to create a reusable piece of UI, prefer using a widget +/// rather than a helper method. For example, if there was a function used to +/// build a widget, a [State.setState] call would require Flutter to entirely +/// rebuild the returned wrapping widget. If a [Widget] was used instead, +/// Flutter would be able to efficiently re-render only those parts that +/// really need to be updated. Even better, if the created widget is `const`, +/// Flutter would short-circuit most of the rebuild work. +/// /// * Consider refactoring the stateless widget into a stateful widget so that /// it can use some of the techniques described at [StatefulWidget], such as /// caching common parts of subtrees and using [GlobalKey]s when changing the @@ -646,11 +654,20 @@ abstract class StatelessWidget extends Widget { /// efficient for a widget to be re-used than for a new (but /// identically-configured) widget to be created. Factoring out the stateful /// part into a widget that takes a child argument is a common way of doing -/// this. +/// this. Another caching strategy consists of assigning a widget to a +/// `final` state variable which can be used in the build method. /// /// * Use `const` widgets where possible. (This is equivalent to caching a /// widget and re-using it.) /// +/// * When trying to create a reusable piece of UI, prefer using a widget +/// rather than a helper method. For example, if there was a function used to +/// build a widget, a [State.setState] call would require Flutter to entirely +/// rebuild the returned wrapping widget. If a [Widget] was used instead, +/// Flutter would be able to efficiently re-render only those parts that +/// really need to be updated. Even better, if the created widget is `const`, +/// Flutter would short-circuit most of the rebuild work. +/// /// * Avoid changing the depth of any created subtrees or changing the type of /// any widgets in the subtree. For example, rather than returning either the /// child or the child wrapped in an [IgnorePointer], always wrap the child