From 1365b54f15ec07e22b5066a331a6467cf8ef2b59 Mon Sep 17 00:00:00 2001 From: Alberto Date: Fri, 14 Jan 2022 23:50:15 +0100 Subject: [PATCH] feat: Added more youtube refs to widgets docstrings (#96484) --- .../flutter/lib/src/cupertino/scrollbar.dart | 2 + .../flutter/lib/src/foundation/isolates.dart | 12 +++-- .../lib/src/material/expansion_panel.dart | 2 + .../lib/src/material/refresh_indicator.dart | 2 + .../flutter/lib/src/material/scrollbar.dart | 2 + packages/flutter/lib/src/material/tabs.dart | 2 + packages/flutter/lib/src/material/theme.dart | 2 + .../flutter/lib/src/rendering/object.dart | 2 + packages/flutter/lib/src/widgets/basic.dart | 4 ++ .../flutter/lib/src/widgets/framework.dart | 51 +++++++++++-------- .../lib/src/widgets/gesture_detector.dart | 2 + .../flutter/lib/src/widgets/scroll_view.dart | 2 + .../flutter/lib/src/widgets/scrollbar.dart | 2 + 13 files changed, 62 insertions(+), 25 deletions(-) diff --git a/packages/flutter/lib/src/cupertino/scrollbar.dart b/packages/flutter/lib/src/cupertino/scrollbar.dart index 7e468fbd97..30dfa519ad 100644 --- a/packages/flutter/lib/src/cupertino/scrollbar.dart +++ b/packages/flutter/lib/src/cupertino/scrollbar.dart @@ -32,6 +32,8 @@ const double _kScrollbarCrossAxisMargin = 3.0; /// To add a scrollbar to a [ScrollView], simply wrap the scroll view widget in /// a [CupertinoScrollbar] widget. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=DbkIQSvwnZc} +/// /// {@macro flutter.widgets.Scrollbar} /// /// When dragging a [CupertinoScrollbar] thumb, the thickness and radius will diff --git a/packages/flutter/lib/src/foundation/isolates.dart b/packages/flutter/lib/src/foundation/isolates.dart index 576207b692..8a1c151037 100644 --- a/packages/flutter/lib/src/foundation/isolates.dart +++ b/packages/flutter/lib/src/foundation/isolates.dart @@ -26,9 +26,11 @@ typedef ComputeCallback = FutureOr Function(Q message); /// few milliseconds, consider [SchedulerBinding.scheduleTask] instead. /// /// {@template flutter.foundation.compute.types} -/// `Q` is the type of the message that kicks off the computation. +/// The [compute] method accepts the following parameters: /// -/// `R` is the type of the value returned. +/// * `Q` is the type of the message that kicks off the computation. +/// +/// * `R` is the type of the value returned. /// {@endtemplate} /// /// The `callback` argument must be a top-level function, not a closure or an @@ -44,7 +46,11 @@ typedef ComputeCallback = FutureOr Function(Q message); /// [Timeline]. This is useful when profiling an application. typedef ComputeImpl = Future Function(ComputeCallback callback, Q message, { String? debugLabel }); -/// A function that spawns an isolate and runs a callback on that isolate. +/// A function that spawns an isolate and runs a callback on that isolate. This +/// method should be used to execute parallel tasks that reduce the risk of +/// skipping frames. +/// +/// {@youtube 560 315 https://www.youtube.com/watch?v=5AxWC49ZMzs} /// /// See also: /// diff --git a/packages/flutter/lib/src/material/expansion_panel.dart b/packages/flutter/lib/src/material/expansion_panel.dart index b82d76bcfc..60c558790f 100644 --- a/packages/flutter/lib/src/material/expansion_panel.dart +++ b/packages/flutter/lib/src/material/expansion_panel.dart @@ -58,6 +58,8 @@ typedef ExpansionPanelHeaderBuilder = Widget Function(BuildContext context, bool /// expanded or collapsed. The body of the panel is only visible when it is /// expanded. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=2aJZzRMziJc} +/// /// Expansion panels are only intended to be used as children for /// [ExpansionPanelList]. /// diff --git a/packages/flutter/lib/src/material/refresh_indicator.dart b/packages/flutter/lib/src/material/refresh_indicator.dart index 70e0795599..f76e6fe5e0 100644 --- a/packages/flutter/lib/src/material/refresh_indicator.dart +++ b/packages/flutter/lib/src/material/refresh_indicator.dart @@ -60,6 +60,8 @@ enum RefreshIndicatorTriggerMode { /// A widget that supports the Material "swipe to refresh" idiom. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=ORApMlzwMdM} +/// /// When the child's [Scrollable] descendant overscrolls, an animated circular /// progress indicator is faded into view. When the scroll ends, if the /// indicator has been dragged far enough for it to become completely opaque, diff --git a/packages/flutter/lib/src/material/scrollbar.dart b/packages/flutter/lib/src/material/scrollbar.dart index b56fa1a16b..98aac54e88 100644 --- a/packages/flutter/lib/src/material/scrollbar.dart +++ b/packages/flutter/lib/src/material/scrollbar.dart @@ -23,6 +23,8 @@ const Duration _kScrollbarTimeToFade = Duration(milliseconds: 600); /// To add a scrollbar to a [ScrollView], wrap the scroll view /// widget in a [Scrollbar] widget. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=DbkIQSvwnZc} +/// /// {@macro flutter.widgets.Scrollbar} /// /// Dynamically changes to an iOS style scrollbar that looks like diff --git a/packages/flutter/lib/src/material/tabs.dart b/packages/flutter/lib/src/material/tabs.dart index e1504a482c..469c254b4f 100644 --- a/packages/flutter/lib/src/material/tabs.dart +++ b/packages/flutter/lib/src/material/tabs.dart @@ -1551,6 +1551,8 @@ class TabPageSelectorIndicator extends StatelessWidget { /// Displays a row of small circular indicators, one per tab. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=Q628ue9Cq7U} +/// /// The selected tab's indicator is highlighted. Often used in conjunction with /// a [TabBarView]. /// diff --git a/packages/flutter/lib/src/material/theme.dart b/packages/flutter/lib/src/material/theme.dart index 4e717eda28..aec9612d1f 100644 --- a/packages/flutter/lib/src/material/theme.dart +++ b/packages/flutter/lib/src/material/theme.dart @@ -18,6 +18,8 @@ const Duration kThemeAnimationDuration = Duration(milliseconds: 200); /// /// A theme describes the colors and typographic choices of an application. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=oTvQDJOBXmM} +/// /// Descendant widgets obtain the current theme's [ThemeData] object using /// [Theme.of]. When a widget uses [Theme.of], it is automatically rebuilt if /// the theme later changes, so that the changes can be applied. diff --git a/packages/flutter/lib/src/rendering/object.dart b/packages/flutter/lib/src/rendering/object.dart index 851ad52fe7..b42ae2d983 100644 --- a/packages/flutter/lib/src/rendering/object.dart +++ b/packages/flutter/lib/src/rendering/object.dart @@ -1114,6 +1114,8 @@ class PipelineOwner { /// The [RenderObject] class hierarchy is the core of the rendering /// library's reason for being. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=zmbmrw07qBc} +/// /// [RenderObject]s have a [parent], and have a slot called [parentData] in /// which the parent [RenderObject] can store child-specific data, for example, /// the child position. The [RenderObject] class also implements the basic diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index cf2502663e..2b088176a2 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -4832,6 +4832,8 @@ class Row extends Flex { /// case is typically to remove the [Expanded] or [Flexible] widgets from around /// the inner children. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=jckqXR5CrPI} +/// /// For more discussion about constraints, see [BoxConstraints]. /// /// ### The yellow and black striped banner @@ -6155,6 +6157,8 @@ class Listener extends SingleChildRenderObjectWidget { /// A widget that tracks the movement of mice. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=1oF3pI5umck} +/// /// [MouseRegion] is used /// when it is needed to compare the list of objects that a mouse pointer is /// hovering over between this frame and the last frame. This means entering diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 27eb800f8f..08a6b45a0f 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -438,14 +438,6 @@ 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 @@ -459,6 +451,20 @@ abstract class Widget extends DiagnosticableTree { /// part of the build function that builds the inner-most widget into its own /// widget, so that only the inner-most widget needs to be rebuilt when the /// theme changes. +/// {@template flutter.flutter.widgets.framework.prefer_const_over_helper} +/// * 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. +/// {@endtemplate} +/// +/// This video gives more explainations on why `const` constructors are important +/// and why a [Widget] is better than a helper method. +/// +/// {@youtube 560 315 https://www.youtube.com/watch?v=IOyq-eTRhvo} /// /// {@tool snippet} /// @@ -650,24 +656,16 @@ abstract class StatelessWidget extends Widget { /// this ideal, the more efficient it will be.) /// /// * If a subtree does not change, cache the widget that represents that -/// subtree and re-use it each time it can be used. It is massively more -/// 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. Another caching strategy consists of assigning a widget to a -/// `final` state variable which can be used in the build method. +/// subtree and re-use it each time it can be used. To do this, simply assign +/// a widget to a `final` state variable and re-use it in the build method. It +/// is massively more efficient for a widget to be re-used than for a new (but +/// identically-configured) widget to be created. Another caching stragegy +/// consists in extracting the mutable part of the widget into a [StatefulWidget] +/// which accepts a child parameter. /// /// * 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 @@ -684,6 +682,13 @@ abstract class StatelessWidget extends Widget { /// [KeyedSubtree] widget may be useful for this purpose if no other widget /// can conveniently be assigned the key.) /// +/// {@macro flutter.flutter.widgets.framework.prefer_const_over_helper} +/// +/// This video gives more explainations on why `const` constructors are important +/// and why a [Widget] is better than a helper method. +/// +/// {@youtube 560 315 https://www.youtube.com/watch?v=IOyq-eTRhvo} +/// /// {@tool snippet} /// /// This is a skeleton of a stateful widget subclass called `YellowBird`. @@ -2065,6 +2070,8 @@ typedef ElementVisitor = void Function(Element element); /// the methods on this class should not be cached beyond the execution of a /// single synchronous function. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=rIaaH87z1-g} +/// /// [BuildContext] objects are actually [Element] objects. The [BuildContext] /// interface is used to discourage direct manipulation of [Element] objects. abstract class BuildContext { diff --git a/packages/flutter/lib/src/widgets/gesture_detector.dart b/packages/flutter/lib/src/widgets/gesture_detector.dart index bbdbbdda1e..67beb0ad38 100644 --- a/packages/flutter/lib/src/widgets/gesture_detector.dart +++ b/packages/flutter/lib/src/widgets/gesture_detector.dart @@ -114,6 +114,8 @@ class GestureRecognizerFactoryWithHandlers extends /// If this widget has a child, it defers to that child for its sizing behavior. /// If it does not have a child, it grows to fit the parent instead. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=WhVXkCFPmK4} +/// /// By default a GestureDetector with an invisible child ignores touches; /// this behavior can be controlled with [behavior]. /// diff --git a/packages/flutter/lib/src/widgets/scroll_view.dart b/packages/flutter/lib/src/widgets/scroll_view.dart index ad78e2b9ae..923a207b88 100644 --- a/packages/flutter/lib/src/widgets/scroll_view.dart +++ b/packages/flutter/lib/src/widgets/scroll_view.dart @@ -237,6 +237,8 @@ abstract class ScrollView extends StatelessWidget { /// scroll view needs to be recomputed whenever the scroll position changes. /// /// Defaults to false. + /// + /// {@youtube 560 315 https://www.youtube.com/watch?v=LUqDNnv_dh0} /// {@endtemplate} final bool shrinkWrap; diff --git a/packages/flutter/lib/src/widgets/scrollbar.dart b/packages/flutter/lib/src/widgets/scrollbar.dart index 48568c6624..488e36df0d 100644 --- a/packages/flutter/lib/src/widgets/scrollbar.dart +++ b/packages/flutter/lib/src/widgets/scrollbar.dart @@ -760,6 +760,8 @@ class ScrollbarPainter extends ChangeNotifier implements CustomPainter { /// To add a scrollbar to a [ScrollView], like a [ListView] or a /// [CustomScrollView], wrap the scroll view widget in a [RawScrollbar] widget. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=DbkIQSvwnZc} +/// /// {@template flutter.widgets.Scrollbar} /// A scrollbar thumb indicates which portion of a [ScrollView] is actually /// visible.