Add more points to [MediaQuery]. (#43649)

See flutter/flutter#11697

Author: Hixie

lib/ui/window.dart

@@ -126,7 +126,12 @@ class FlutterView {
   /// The Flutter framework operates in logical pixels, so it is rarely
   /// necessary to directly deal with this property.
   ///
-  /// When this changes, [PlatformDispatcher.onMetricsChanged] is called.
+  /// When this changes, [PlatformDispatcher.onMetricsChanged] is called. When
+  /// using the Flutter framework, using [MediaQuery.of] to obtain the device
+  /// pixel ratio (via [MediaQueryData.devicePixelRatio]), instead of directly
+  /// obtaining the [devicePixelRatio] from a [FlutterView], will automatically
+  /// cause any widgets dependent on this value to rebuild when it changes,
+  /// without having to listen to [PlatformDispatcher.onMetricsChanged].
   ///
   /// See also:
   ///
@@ -158,7 +163,12 @@ class FlutterView {
   /// The dimensions of the rectangle into which the scene rendered in this view
   /// will be drawn on the screen, in physical pixels.
   ///
-  /// When this changes, [PlatformDispatcher.onMetricsChanged] is called.
+  /// When this changes, [PlatformDispatcher.onMetricsChanged] is called. When
+  /// using the Flutter framework, using [MediaQuery.of] to obtain the size (via
+  /// [MediaQueryData.size]), instead of directly obtaining the [physicalSize]
+  /// from a [FlutterView], will automatically cause any widgets dependent on the
+  /// size to rebuild when the size changes, without having to listen to
+  /// [PlatformDispatcher.onMetricsChanged].
   ///
   /// At startup, the size of the view may not be known before Dart code runs.
   /// If this value is observed early in the application lifecycle, it may
@@ -182,7 +192,12 @@ class FlutterView {
   /// which the view can render, but over which the operating system will likely
   /// place system UI, such as the keyboard, that fully obscures any content.
   ///
-  /// When this property changes, [PlatformDispatcher.onMetricsChanged] is called.
+  /// When this property changes, [PlatformDispatcher.onMetricsChanged] is
+  /// called. When using the Flutter framework, using [MediaQuery.of] to obtain
+  /// the insets (via [MediaQueryData.viewInsets]), instead of directly
+  /// obtaining the [viewInsets] from a [FlutterView], will automatically cause
+  /// any widgets dependent on the insets to rebuild when they change, without
+  /// having to listen to [PlatformDispatcher.onMetricsChanged].
   ///
   /// The relationship between this [viewInsets],
   /// [viewPadding], and [padding] are described in
@@ -208,7 +223,12 @@ class FlutterView {
   /// change in response to the soft keyboard being visible or hidden, whereas
   /// [padding] will.
   ///
-  /// When this property changes, [PlatformDispatcher.onMetricsChanged] is called.
+  /// When this property changes, [PlatformDispatcher.onMetricsChanged] is
+  /// called. When using the Flutter framework, using [MediaQuery.of] to obtain
+  /// the padding (via [MediaQueryData.viewPadding]), instead of directly
+  /// obtaining the [viewPadding] from a [FlutterView], will automatically cause
+  /// any widgets dependent on the padding to rebuild when it changes, without
+  /// having to listen to [PlatformDispatcher.onMetricsChanged].
   ///
   /// The relationship between this [viewInsets],
   /// [viewPadding], and [padding] are described in
@@ -254,7 +274,12 @@ class FlutterView {
   /// not drawn (to account for the bottom soft button area), but will be `0.0`
   /// when the soft keyboard is visible.
   ///
-  /// When this changes, [PlatformDispatcher.onMetricsChanged] is called.
+  /// When this changes, [PlatformDispatcher.onMetricsChanged] is called. When
+  /// using the Flutter framework, using [MediaQuery.of] to obtain the padding
+  /// (via [MediaQueryData.padding]), instead of directly obtaining the
+  /// [padding] from a [FlutterView], will automatically cause any widgets
+  /// dependent on the padding to rebuild when it changes, without having to
+  /// listen to [PlatformDispatcher.onMetricsChanged].
   ///
   /// The relationship between this [viewInsets], [viewPadding], and [padding]
   /// are described in more detail in the documentation for [FlutterView].
@@ -389,6 +414,11 @@ class SingletonFlutterWindow extends FlutterView {
   ///
   /// {@macro dart.ui.window.accessorForwardWarning}
   ///
+  /// When using the Flutter framework, the [MediaQuery] widget exposes much of
+  /// these metrics. Using [MediaQuery.of] to obtain them allows the framework
+  /// to automatically rebuild widgets that depend on them, without having to
+  /// manage the [onMetricsChanged] callback.
+  ///
   /// See [PlatformDispatcher.onMetricsChanged] for more information.
   VoidCallback? get onMetricsChanged => platformDispatcher.onMetricsChanged;
   set onMetricsChanged(VoidCallback? callback) {
@@ -400,11 +430,11 @@ class SingletonFlutterWindow extends FlutterView {
   /// {@template dart.ui.window.accessorForwardWarning}
   /// Accessing this value returns the value contained in the
   /// [PlatformDispatcher] singleton, so instead of getting it from here, you
-  /// should consider getting it from `WidgetsBinding.instance.platformDispatcher` instead
-  /// (or, when `WidgetsBinding` isn't available, from
-  /// [PlatformDispatcher.instance]). The reason this value forwards to the
-  /// [PlatformDispatcher] is to provide convenience for applications that only
-  /// use a single main window.
+  /// should consider getting it from
+  /// `WidgetsBinding.instance.platformDispatcher` instead (or, when
+  /// `WidgetsBinding` isn't available, from [PlatformDispatcher.instance]). The
+  /// reason this value forwards to the [PlatformDispatcher] is to provide
+  /// convenience for applications that only use a single main window.
   /// {@endtemplate}
   ///
   /// This establishes the language and formatting conventions that window