From 46eacc546268bf7cd33874608934d51dffa8a7db Mon Sep 17 00:00:00 2001
From: Alex Fourman <5362998+fourman-alex@users.noreply.github.com>
Date: Tue, 8 Sep 2020 22:50:04 +0300
Subject: [PATCH] adds additional guidance on how to use `of` correctly.
 (#64791)

---
 .../flutter/lib/src/widgets/framework.dart    | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart
index 9c2e9235e22..b73c51716bc 100644
--- a/packages/flutter/lib/src/widgets/framework.dart
+++ b/packages/flutter/lib/src/widgets/framework.dart
@@ -1679,6 +1679,8 @@ abstract class ParentDataWidget<T extends ParentData> extends ProxyWidget {
 /// ```
 /// {@end-tool}
 ///
+/// ## Implementing the `of` method
+///
 /// The convention is to provide a static method `of` on the [InheritedWidget]
 /// which does the call to [BuildContext.dependOnInheritedWidgetOfExactType]. This
 /// allows the class to define its own fallback logic in case there isn't
@@ -1696,6 +1698,61 @@ abstract class ParentDataWidget<T extends ParentData> extends ProxyWidget {
 /// for that inherited widget using [BuildContext.dependOnInheritedWidgetOfExactType]
 /// and then returns the [ThemeData].
 ///
+/// ## Calling the `of` method
+///
+/// When using the `of` method, the `context` must be a descendant of the
+/// [InheritedWidget], meaning it must be "below" the [InheritedWidget] in the
+/// tree.
+///
+/// {@tool snippet}
+///
+/// In this example, the `context` used is the one from the [Builder], which is
+/// a child of the FrogColor widget, so this works.
+///
+/// ```dart
+/// class MyPage extends StatelessWidget {
+///   @override
+///   Widget build(BuildContext context) {
+///     return Scaffold(
+///       body: FrogColor(
+///         color: Colors.green,
+///         child: Builder(
+///           builder: (BuildContext innerContext) {
+///             return Text(
+///               'Hello Frog',
+///               style: TextStyle(color: FrogColor.of(innerContext).color),
+///             );
+///           },
+///         ),
+///       ),
+///     );
+///   }
+/// }
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet}
+///
+/// In this example, the `context` used is the one from the MyOtherPage widget,
+/// which is a parent of the FrogColor widget, so this does not work.
+///
+/// ```dart
+/// class MyOtherPage extends StatelessWidget {
+///   @override
+///   Widget build(BuildContext context) {
+///     return Scaffold(
+///       body: FrogColor(
+///         color: Colors.green,
+///         child: Text(
+///           'Hello Frog',
+///           style: TextStyle(color: FrogColor.of(context).color),
+///         ),
+///       ),
+///     );
+///   }
+/// }
+/// ```
+/// {@end-tool}
 /// {@youtube 560 315 https://www.youtube.com/watch?v=1t-8rBCGBYw}
 ///
 /// See also: