Deprecate BindingBase.window (#120998)

Deprecate BindingBase.window

packages/flutter/lib/src/foundation/binding.dart

@@ -6,7 +6,7 @@ import 'dart:async';
 import 'dart:convert' show json;
 import 'dart:developer' as developer;
 import 'dart:io' show exit;
-import 'dart:ui' as ui show Brightness, PlatformDispatcher, SingletonFlutterWindow, window;
+import 'dart:ui' as ui show Brightness, PlatformDispatcher, SingletonFlutterWindow, window; // ignore: deprecated_member_use
 
 // Before adding any more dart:ui imports, please read the README.
 
@@ -21,7 +21,7 @@ import 'platform.dart';
 import 'print.dart';
 import 'service_extensions.dart';
 
-export 'dart:ui' show PlatformDispatcher, SingletonFlutterWindow;
+export 'dart:ui' show PlatformDispatcher, SingletonFlutterWindow; // ignore: deprecated_member_use
 
 export 'basic_types.dart' show AsyncCallback, AsyncValueGetter, AsyncValueSetter;
 
@@ -171,35 +171,48 @@ abstract class BindingBase {
   ///  * [DebugReassembleConfig], which describes the configuration.
   static DebugReassembleConfig? debugReassembleConfig;
 
-  /// The main window to which this binding is bound.
+  /// Deprecated. Will be removed in a future version of Flutter.
   ///
-  /// A number of additional bindings are defined as extensions of
-  /// [BindingBase], e.g., [ServicesBinding], [RendererBinding], and
-  /// [WidgetsBinding]. Each of these bindings define behaviors that interact
-  /// with a [ui.SingletonFlutterWindow].
+  /// This property has been deprecated to prepare for Flutter's upcoming
+  /// support for multiple views and multiple windows.
   ///
-  /// Each of these other bindings could individually access a
-  /// [ui.SingletonFlutterWindow] statically, but that would preclude the
-  /// ability to test its behaviors with a fake window for verification
-  /// purposes. Therefore, [BindingBase] exposes this
-  /// [ui.SingletonFlutterWindow] for use by other bindings. A subclass of
-  /// [BindingBase], such as [TestWidgetsFlutterBinding], can override this
-  /// accessor to return a different [ui.SingletonFlutterWindow] implementation,
-  /// such as a [TestWindow].
+  /// It represents the main view for applications where there is only one
+  /// view, such as applications designed for single-display mobile devices.
+  /// If the embedder supports multiple views, it points to the first view
+  /// created which is assumed to be the main view. It throws if no view has
+  /// been created yet or if the first view has been removed again.
   ///
-  /// The [window] is a singleton meant for use by applications that only have a
-  /// single main window. In addition to the properties of [ui.FlutterView],
-  /// [window] provides access to platform-specific properties and callbacks
-  /// available on the [platformDispatcher].
+  /// The following options exists to migrate code that relies on accessing
+  /// this deprecated property:
   ///
-  /// For applications designed for more than one main window, prefer using the
-  /// [platformDispatcher] to access available views via
-  /// [ui.PlatformDispatcher.views].
+  /// If a [BuildContext] is available, consider looking up the current
+  /// [FlutterView] associated with that context via [View.of]. It gives access
+  /// to the same functionality as this deprecated property. However, the
+  /// platform-specific functionality has moved to the [PlatformDispatcher],
+  /// which may be accessed from the view returned by [View.of] via
+  /// [FlutterView.platformDispatcher]. Using [View.of] with a [BuildContext] is
+  /// the preferred option to migrate away from this deprecated [window]
+  /// property.
   ///
-  /// However, multiple window support is not yet implemented, so currently this
-  /// provides access to the one and only window.
-  // TODO(gspencergoog): remove the preceding note once multi-window support is
-  // active.
+  /// If no context is available to look up a [FlutterView], the
+  /// [platformDispatcher] exposed by this binding can be used directly for
+  /// platform-specific functionality. It also maintains a list of all available
+  /// [FlutterView]s in [PlatformDispatcher.views] to access view-specific
+  /// functionality without a context.
+  ///
+  /// See also:
+  ///
+  /// * [View.of] to access view-specific functionality on the [FlutterView]
+  ///   associated with the provided [BuildContext].
+  /// * [FlutterView.platformDispatcher] to access platform-specific
+  ///   functionality from a given [FlutterView].
+  /// * [platformDispatcher] on this binding to access the [PlatformDispatcher],
+  ///   which provides platform-specific functionality.
+  @Deprecated(
+    'Look up the current FlutterView from the context via View.of(context) or consult the PlatformDispatcher directly instead. '
+    'Deprecated to prepare for the upcoming multi-window support. '
+    'This feature was deprecated after v3.7.0-32.0.pre.'
+  )
   ui.SingletonFlutterWindow get window => ui.window;
 
   /// The [ui.PlatformDispatcher] to which this binding is bound.

packages/flutter/test/painting/binding_test.dart

@@ -91,7 +91,7 @@ class TestBindingBase implements BindingBase {
   void unlocked() {}
 
   @override
-  ui.SingletonFlutterWindow get window => throw UnimplementedError();
+  ui.SingletonFlutterWindow get window => throw UnimplementedError(); // ignore: deprecated_member_use
 
   @override
   ui.PlatformDispatcher get platformDispatcher => throw UnimplementedError();

packages/flutter_test/lib/src/window.dart

@@ -147,8 +147,6 @@ class FakeViewPadding implements ViewPadding {
 ///
 ///   * [TestFlutterView], which wraps a [FlutterView] for testing and
 ///     mocking purposes.
-///   * [TestWindow], which wraps a [SingletonFlutterWindow] for
-///     testing and mocking purposes.
 class TestPlatformDispatcher implements PlatformDispatcher {
   /// Constructs a [TestPlatformDispatcher] that defers all behavior to the given
   /// [PlatformDispatcher] unless explicitly overridden for test purposes.

packages/flutter_test/test/window_test.dart

@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// TODO(goderbauer): Delete these tests when the deprecated window property is removed.
+// ignore_for_file: deprecated_member_use
+
 import 'dart:ui' as ui show window;
 import 'dart:ui';