From 351466aea62c300599fd08286ae22ce6777a124e Mon Sep 17 00:00:00 2001 From: Todd Volkert Date: Tue, 24 Jan 2023 21:46:24 -0800 Subject: [PATCH] Add Decoding Flutter videos to API docs (#116454) * Add Decoding Flutter videos to API docs * Review comments * Update widget of the week videos too --- packages/flutter/lib/src/foundation/diagnostics.dart | 2 ++ packages/flutter/lib/src/gestures/arena.dart | 4 ++++ packages/flutter/lib/src/material/material_state.dart | 2 ++ packages/flutter/lib/src/material/navigation_bar.dart | 2 ++ packages/flutter/lib/src/material/theme_data.dart | 2 ++ packages/flutter/lib/src/widgets/async.dart | 8 +++++--- packages/flutter/lib/src/widgets/framework.dart | 2 ++ packages/flutter/lib/src/widgets/media_query.dart | 6 ++++++ .../lib/src/widgets/primary_scroll_controller.dart | 2 ++ packages/flutter/lib/src/widgets/scroll_view.dart | 6 ++++++ 10 files changed, 33 insertions(+), 3 deletions(-) diff --git a/packages/flutter/lib/src/foundation/diagnostics.dart b/packages/flutter/lib/src/foundation/diagnostics.dart index 48e4161bc5..debcb62c78 100644 --- a/packages/flutter/lib/src/foundation/diagnostics.dart +++ b/packages/flutter/lib/src/foundation/diagnostics.dart @@ -3088,6 +3088,8 @@ mixin Diagnosticable { /// Add additional properties associated with the node. /// + /// {@youtube 560 315 https://www.youtube.com/watch?v=DnC7eT-vh1k} + /// /// Use the most specific [DiagnosticsProperty] existing subclass to describe /// each property instead of the [DiagnosticsProperty] base class. There are /// only a small number of [DiagnosticsProperty] subclasses each covering a diff --git a/packages/flutter/lib/src/gestures/arena.dart b/packages/flutter/lib/src/gestures/arena.dart index e50adbe999..243f0691c7 100644 --- a/packages/flutter/lib/src/gestures/arena.dart +++ b/packages/flutter/lib/src/gestures/arena.dart @@ -97,6 +97,10 @@ class _GestureArena { } } +/// Used for disambiguating the meaning of sequences of pointer events. +/// +/// {@youtube 560 315 https://www.youtube.com/watch?v=Q85LBtBdi0U} +/// /// The first member to accept or the last member to not reject wins. /// /// See for more diff --git a/packages/flutter/lib/src/material/material_state.dart b/packages/flutter/lib/src/material/material_state.dart index dd6a9a136a..a704c7720b 100644 --- a/packages/flutter/lib/src/material/material_state.dart +++ b/packages/flutter/lib/src/material/material_state.dart @@ -602,6 +602,8 @@ class _MaterialStateUnderlineInputBorder extends MaterialStateUnderlineInputBord /// on a widget's interactive "state", which is defined as a set /// of [MaterialState]s. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=CylXr3AF3uU} +/// /// Material state properties represent values that depend on a widget's material /// "state". The state is encoded as a set of [MaterialState] values, like /// [MaterialState.focused], [MaterialState.hovered], [MaterialState.pressed]. For diff --git a/packages/flutter/lib/src/material/navigation_bar.dart b/packages/flutter/lib/src/material/navigation_bar.dart index f338a7cee0..40488d5b9c 100644 --- a/packages/flutter/lib/src/material/navigation_bar.dart +++ b/packages/flutter/lib/src/material/navigation_bar.dart @@ -26,6 +26,8 @@ const double _kIndicatorWidth = 64; /// Material 3 Navigation Bar component. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=DVGYddFaLv0} +/// /// Navigation bars offer a persistent and convenient way to switch between /// primary destinations in an app. /// diff --git a/packages/flutter/lib/src/material/theme_data.dart b/packages/flutter/lib/src/material/theme_data.dart index 28ab6c61eb..0341ed9fe2 100644 --- a/packages/flutter/lib/src/material/theme_data.dart +++ b/packages/flutter/lib/src/material/theme_data.dart @@ -70,6 +70,8 @@ export 'package:flutter/services.dart' show Brightness; /// An interface that defines custom additions to a [ThemeData] object. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=8-szcYzFVao} +/// /// Typically used for custom colors. To use, subclass [ThemeExtension], /// define a number of fields (e.g. [Color]s), and implement the [copyWith] and /// [lerp] methods. The latter will ensure smooth transitions of properties when diff --git a/packages/flutter/lib/src/widgets/async.dart b/packages/flutter/lib/src/widgets/async.dart index aaf730f4c5..5fa699ae1f 100644 --- a/packages/flutter/lib/src/widgets/async.dart +++ b/packages/flutter/lib/src/widgets/async.dart @@ -439,11 +439,15 @@ class StreamBuilder extends StreamBuilderBase> { Widget build(BuildContext context, AsyncSnapshot currentSummary) => builder(context, currentSummary); } -/// Widget that builds itself based on the latest snapshot of interaction with +/// A widget that builds itself based on the latest snapshot of interaction with /// a [Future]. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=ek8ZPdWj4Qo} +/// /// {@youtube 560 315 https://www.youtube.com/watch?v=zEdw_1B7JHY} /// +/// ## Managing the future +/// /// The [future] must have been obtained earlier, e.g. during [State.initState], /// [State.didUpdateWidget], or [State.didChangeDependencies]. It must not be /// created during the [State.build] or [StatelessWidget.build] method call when @@ -454,8 +458,6 @@ class StreamBuilder extends StreamBuilderBase> { /// A general guideline is to assume that every `build` method could get called /// every frame, and to treat omitted calls as an optimization. /// -/// {@youtube 560 315 https://www.youtube.com/watch?v=ek8ZPdWj4Qo} -/// /// ## Timing /// /// Widget rebuilding is scheduled by the completion of the future, using diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 271c79fd5a..b37c33fc25 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -1581,6 +1581,8 @@ abstract class ParentDataWidget extends ProxyWidget { /// Base class for widgets that efficiently propagate information down the tree. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=og-vJqLzg2c} +/// /// To obtain the nearest instance of a particular type of inherited widget from /// a build context, use [BuildContext.dependOnInheritedWidgetOfExactType]. /// diff --git a/packages/flutter/lib/src/widgets/media_query.dart b/packages/flutter/lib/src/widgets/media_query.dart index 4c63159157..890dd98186 100644 --- a/packages/flutter/lib/src/widgets/media_query.dart +++ b/packages/flutter/lib/src/widgets/media_query.dart @@ -255,6 +255,8 @@ class MediaQueryData { /// level MediaQuery created by [WidgetsApp] are the same as the window /// (often the mobile device screen) that contains the app. /// + /// {@youtube 560 315 https://www.youtube.com/watch?v=ceCo8U0XHqw} + /// /// See also: /// /// * [ui.window], which provides some additional detail about this property @@ -272,6 +274,8 @@ class MediaQueryData { /// /// Padding is derived from the values of [viewInsets] and [viewPadding]. /// + /// {@youtube 560 315 https://www.youtube.com/watch?v=ceCo8U0XHqw} + /// /// See also: /// /// * [ui.window], which provides some additional detail about this @@ -294,6 +298,8 @@ class MediaQueryData { /// same as the window that contains the app. On mobile devices, this will /// typically be the full screen. /// + /// {@youtube 560 315 https://www.youtube.com/watch?v=ceCo8U0XHqw} + /// /// See also: /// /// * [ui.window], which provides some additional detail about this diff --git a/packages/flutter/lib/src/widgets/primary_scroll_controller.dart b/packages/flutter/lib/src/widgets/primary_scroll_controller.dart index 71596bab15..73fa42f0c0 100644 --- a/packages/flutter/lib/src/widgets/primary_scroll_controller.dart +++ b/packages/flutter/lib/src/widgets/primary_scroll_controller.dart @@ -17,6 +17,8 @@ const Set _kMobilePlatforms = { /// Associates a [ScrollController] with a subtree. /// +/// {@youtube 560 315 https://www.youtube.com/watch?v=33_0ABjFJUU} +/// /// When a [ScrollView] has [ScrollView.primary] set to true, the [ScrollView] /// uses [of] to inherit the [PrimaryScrollController] associated with its /// subtree. diff --git a/packages/flutter/lib/src/widgets/scroll_view.dart b/packages/flutter/lib/src/widgets/scroll_view.dart index eba2817dde..ce3812abf1 100644 --- a/packages/flutter/lib/src/widgets/scroll_view.dart +++ b/packages/flutter/lib/src/widgets/scroll_view.dart @@ -180,6 +180,12 @@ abstract class ScrollView extends StatelessWidget { /// [TargetPlatformVariant.mobile] for ScrollViews in the [Axis.vertical] /// scroll direction. Adding another to your app will override the /// PrimaryScrollController above it. + /// + /// The following video contains more information about scroll controllers, + /// the PrimaryScrollController widget, and their impact on your apps: + /// + /// {@youtube 560 315 https://www.youtube.com/watch?v=33_0ABjFJUU} + /// /// {@endtemplate} final bool? primary;