InheritedModel - an InheritedWidget for data models (#19739)

Added InheritedModel:  An InheritedWidget that's intended to be used as the base class for models whose dependents may only depend on one part or "aspect" of the overall model.

packages/flutter/lib/src/widgets/inherited_model.dart

+// Copyright 2018 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:collection';
+
+import 'package:flutter/foundation.dart';
+
+import 'framework.dart';
+
+/// An [InheritedWidget] that's intended to be used as the base class for
+/// models whose dependents may only depend on one part or "aspect" of the
+/// overall model.
+///
+/// An inherited widget's dependents are unconditionally rebuilt when the
+/// inherited widget changes per [InheritedWidget.updateShouldNotify].
+/// This widget is similar except that dependents aren't rebuilt
+/// unconditionally.
+///
+/// Widgets that depend on an [InheritedModel] qualify their dependence
+/// with a value that indicates what "aspect" of the model they depend
+/// on. When the model is rebuilt, dependents will also be rebuilt, but
+/// only if there was a change in the model that corresponds to the aspect
+/// they provided.
+///
+/// The type parameter `T` is the type of the model aspect objects.
+///
+/// Widgets create a dependency on an [InheritedModel] with a static method:
+/// [InheritedModel.inheritFrom]. This method's `context` parameter
+/// defines the subtree that will be rebuilt when the model changes.
+/// Typically the `inheritFrom` method is called from a model-specific
+/// static `of` method. For example:
+///
+/// ```dart
+/// class MyModel extends InheritedModel<String> {
+///   // ...
+///   static MyModel of(BuildContext context, String aspect) {
+///     return InheritedModel.inheritFrom<MyModel>(context, aspect: aspect);
+///   }
+/// }
+/// ```
+///
+/// Calling `MyModel.of(context, 'foo')` means that `context` should only
+/// be rebuilt when the `foo` aspect of `MyModel` changes. If the aspect
+/// is null, then the model supports all aspects.
+///
+/// When the inherited model is rebuilt the [updateShouldNotify] and
+/// [updateShouldNotifyDependent] methods are used to decide what
+/// should be rebuilt.  If [updateShouldNotify] returns true, then the
+/// inherited model's [updateShouldNotifyDependent] method is tested for
+/// each dependent and the set of aspect objects it depends on.
+/// The [updateShouldNotifyDependent] method must compare the set of aspect
+/// dependencies with the changes in the model itself.
+///
+/// For example:
+///
+/// ```dart
+/// class ABModel extends InheritedModel<String> {
+///   ABModel({ this.a, this.b, Widget child }) : super(child: child);
+///
+///   final int a;
+///   final int b;
+///
+///   @override
+///   bool updateShouldNotify(ABCModel old) {
+///     return return super.updateShouldNotify(old) || a != old.a || b != old.b;
+///   }
+///
+///   @override
+///   bool updateShouldNotifyDependent(ABCModel old, Set<String> dependencies) {
+///     return (a != old.a && dependencies.contains('a'))
+///         || (b != old.b && dependencies.contains('b'))
+///   }
+///
+///   // ...
+/// }
+/// ```
+///
+/// In the previous example the dependencies checked by
+/// [updateShouldNotifyDependent] are just the aspect strings passed to
+/// `inheritFromWidgetOfExactType`. They're represented as a [Set] because
+/// one Widget can depend on more than one aspect of the model.
+/// If a widget depends on the model but doesn't specify an aspect,
+/// then changes in the model will cause the widget to be rebuilt
+/// unconditionally.
+abstract class InheritedModel<T> extends InheritedWidget {
+  /// Creates an inherited widget that supports dependencies qualified by
+  /// "aspects", i.e. a descendant widget can indicate that it should
+  /// only be rebuilt if a specific aspect of the model changes.
+  const InheritedModel({ Key key, Widget child }) : super(key: key, child: child);
+
+  @override
+  InheritedModelElement<T> createElement() => new InheritedModelElement<T>(this);
+
+  /// Return true if the changes between this model and [oldWidget] match any
+  /// of the [dependencies].
+  @protected
+  bool updateShouldNotifyDependent(covariant InheritedModel<T> oldWidget, Set<T> dependencies);
+
+  /// Returns true if this model supports the given [aspect].
+  ///
+  /// Returns true by default: this model supports all aspects.
+  ///
+  /// Subclasses may override this method to indicate that they do not support
+  /// all model aspects. This is typically done when a model can be used
+  /// to "shadow" some aspects of an ancestor.
+  @protected
+  bool isSupportedAspect(Object aspect) => true;
+
+  // The [result] will be a list of all of context's type T ancestors concluding
+  // with the one that supports the specified model [aspect].
+  static Iterable<InheritedElement> _findModels<T extends InheritedModel<Object>>(BuildContext context, Object aspect) sync* {
+    final InheritedElement model = context.ancestorInheritedElementForWidgetOfExactType(T);
+    if (model == null)
+      return;
+
+    yield model;
+
+    assert(model.widget is T);
+    final T modelWidget = model.widget;
+    if (modelWidget.isSupportedAspect(aspect))
+      return;
+
+    Element modelParent;
+    model.visitAncestorElements((Element ancestor) {
+      modelParent = ancestor;
+      return false;
+    });
+    if (modelParent == null)
+      return;
+
+    yield* _findModels<T>(modelParent, aspect);
+  }
+
+  /// Makes [context] dependent on the specified [aspect] of an [InheritedModel]
+  /// of type T.
+  ///
+  /// When the given [aspect] of the model changes, the [context] will be
+  /// rebuilt. The [updateShouldNotifyDependent] method must determine if a
+  /// change in the model widget corresponds to an [aspect] value.
+  ///
+  /// The dependencies created by this method target all [InheritedModel] ancestors
+  /// of type T up to and including the first one for which [isSupportedAspect]
+  /// returns true.
+  ///
+  /// If [aspect] is null this method is the same as
+  /// `context.inheritFromWidgetOfExactType(T)`.
+  static T inheritFrom<T extends InheritedModel<Object>>(BuildContext context, { Object aspect }) {
+    if (aspect == null)
+      return context.inheritFromWidgetOfExactType(T);
+
+    // Create a dependency on all of the type T ancestor models up until
+    // a model is found for which isSupportedAspect(aspect) is true.
+    final List<InheritedElement> models = _findModels<T>(context, aspect).toList();
+    final InheritedElement lastModel = models.last;
+    for (InheritedElement model in models) {
+      final T value = context.inheritFromElement(model, aspect: aspect);
+      if (model == lastModel)
+        return value;
+    }
+
+    assert(false);
+    return null;
+  }
+}
+
+/// An [Element] that uses a [InheritedModel] as its configuration.
+class InheritedModelElement<T> extends InheritedElement {
+  /// Creates an element that uses the given widget as its configuration.
+  InheritedModelElement(InheritedModel<T> widget) : super(widget);
+
+  @override
+  InheritedModel<T> get widget => super.widget;
+
+  @override
+  void updateDependencies(Element dependent, Object aspect) {
+    final Set<T> dependencies = getDependencies(dependent);
+    if (dependencies != null && dependencies.isEmpty)
+      return;
+
+    if (aspect == null) {
+      setDependencies(dependent, new HashSet<T>());
+    } else {
+      assert(aspect is T);
+      setDependencies(dependent, (dependencies ?? new HashSet<T>())..add(aspect));
+    }
+  }
+
+  @override
+  void notifyDependent(InheritedModel<T> oldWidget, Element dependent) {
+    final Set<T> dependencies = getDependencies(dependent);
+    if (dependencies == null)
+      return;
+    if (dependencies.isEmpty || widget.updateShouldNotifyDependent(oldWidget, dependencies))
+      dependent.didChangeDependencies();
+  }
+}

packages/flutter/lib/widgets.dart

@@ -46,6 +46,7 @@ export 'src/widgets/icon_theme_data.dart';
 export 'src/widgets/image.dart';
 export 'src/widgets/image_icon.dart';
 export 'src/widgets/implicit_animations.dart';
+export 'src/widgets/inherited_model.dart';
 export 'src/widgets/layout_builder.dart';
 export 'src/widgets/list_wheel_scroll_view.dart';
 export 'src/widgets/localizations.dart';