From 608b03c79b04c028ab2613f56a658947b7560b5e Mon Sep 17 00:00:00 2001 From: Dan Field Date: Wed, 6 Mar 2019 10:51:15 -0800 Subject: [PATCH] Update docs for ancestorWidgetOfExactType (#28675) * doc update --- packages/flutter/lib/src/material/about.dart | 6 ++++++ packages/flutter/lib/src/widgets/framework.dart | 12 ++++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/packages/flutter/lib/src/material/about.dart b/packages/flutter/lib/src/material/about.dart index 31a5d6c2c3..6a48587c55 100644 --- a/packages/flutter/lib/src/material/about.dart +++ b/packages/flutter/lib/src/material/about.dart @@ -488,6 +488,12 @@ class _LicensePageState extends State { } String _defaultApplicationName(BuildContext context) { + // This doesn't handle the case of the application's title dynamically + // changing. In theory, we should make Title expose the current application + // title using an InheritedWidget, and so forth. However, in practice, if + // someone really wants their application title to change dynamically, they + // can provide an explicit applicationName to the widgets defined in this + // file, instead of relying on the default. final Title ancestorTitle = context.ancestorWidgetOfExactType(Title); return ancestorTitle?.title ?? Platform.resolvedExecutable.split(Platform.pathSeparator).last; } diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 9c61fa5667..131bac7035 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -1942,11 +1942,15 @@ abstract class BuildContext { /// Returns the nearest ancestor widget of the given type, which must be the /// type of a concrete [Widget] subclass. /// - /// This should not be used from build methods, because the build context will - /// not be rebuilt if the value that would be returned by this method changes. - /// In general, [inheritFromWidgetOfExactType] is more useful. This method is + /// In general, [inheritFromWidgetOfExactType] is more useful, since inherited + /// widgets will trigger consumers to rebuild when they change. This method is /// appropriate when used in interaction event handlers (e.g. gesture - /// callbacks), or for performing one-off tasks. + /// callbacks) or for performing one-off tasks such as asserting that you have + /// or don't have a widget of a specific type as an ancestor. The return value + /// of a Widget's build method should not depend on the value returned by this + /// method, because the build context will not rebuild if the return value of + /// this method changes. This could lead to a situation where data used in the + /// build method changes, but the widget is not rebuilt. /// /// Calling this method is relatively expensive (O(N) in the depth of the /// tree). Only call this method if the distance from this widget to the