From 3a6af38d9126dacf85f8a0a8d09100d56c3d710a Mon Sep 17 00:00:00 2001 From: Brandon DeRosier Date: Tue, 21 Mar 2023 17:00:10 -0700 Subject: [PATCH] Revert "Deprecate SingletonFlutterWindow and global window singleton (#39302)" This reverts commit e916277e4e97aa97afee9f62e1272cb57bc8c5e8. --- lib/ui/window.dart | 101 ++++++++++++++++----------------------------- 1 file changed, 36 insertions(+), 65 deletions(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 1810ef58234e5..185f183baef9d 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -308,36 +308,22 @@ class FlutterView { external static void _updateSemantics(SemanticsUpdate update); } -/// Deprecated. Will be removed in a future version of Flutter. +/// A [FlutterView] that includes access to setting callbacks and retrieving +/// properties that reside on the [PlatformDispatcher]. /// -/// This class is deprecated to prepare for Flutter's upcoming support for -/// multiple views and eventually multiple windows. +/// It is the type of the global [window] singleton used by applications that +/// only have a single main window. /// -/// This class has been split into two classes: [FlutterView] and -/// [PlatformDispatcher]. A [FlutterView] gives an application access to -/// view-specific functionality while the [PlatformDispatcher] contains -/// platform-specific functionality that applies to all views. +/// In addition to the properties of [FlutterView], this class provides access +/// to platform-specific properties. To modify or retrieve these properties, +/// applications designed for more than one main window should prefer using +/// `WidgetsBinding.instance.platformDispatcher` instead. /// -/// This class backs the global [window] singleton, which is also deprecated. -/// See the docs on [window] for migration options. -/// -/// See also: -/// -/// * [FlutterView], which gives an application access to view-specific -/// functionality. -/// * [PlatformDispatcher], which gives an application access to -/// platform-specific functionality. -@Deprecated( - 'Use FlutterView or PlatformDispatcher instead. ' - 'Deprecated to prepare for the upcoming multi-window support. ' - 'This feature was deprecated after v3.7.0-32.0.pre.' -) +/// Prefer access through `WidgetsBinding.instance.window` or +/// `WidgetsBinding.instance.platformDispatcher` over a static reference to +/// [window], or [PlatformDispatcher.instance]. See the documentation for +/// [PlatformDispatcher.instance] for more details about this recommendation. class SingletonFlutterWindow extends FlutterView { - @Deprecated( - 'Use FlutterView or PlatformDispatcher instead. ' - 'Deprecated to prepare for the upcoming multi-window support. ' - 'This feature was deprecated after v3.7.0-32.0.pre.' - ) SingletonFlutterWindow._(super.windowId, super.platformDispatcher) : super._(); @@ -590,7 +576,7 @@ class SingletonFlutterWindow extends FlutterView { /// {@macro dart.ui.window.accessorForwardWarning} /// /// It's preferred to use [SchedulerBinding.addTimingsCallback] than to use - /// [PlatformDispatcher.onReportTimings] directly because + /// [SingletonFlutterWindow.onReportTimings] directly because /// [SchedulerBinding.addTimingsCallback] allows multiple callbacks. /// /// This can be used to see if the window has missed frames (through @@ -905,51 +891,36 @@ enum Brightness { light, } -/// Deprecated. Will be removed in a future version of Flutter. -/// -/// This global property is deprecated to prepare for Flutter's upcoming support -/// for multiple views and multiple windows. +/// The [SingletonFlutterWindow] representing the main window for applications +/// where there is only one window, such as applications designed for +/// single-display mobile devices. /// -/// 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. +/// Applications that are designed to use more than one window should interact +/// with the `WidgetsBinding.instance.platformDispatcher` instead. /// -/// The following options exists to migrate code that relies on accessing -/// this deprecated property: +/// Consider avoiding static references to this singleton through +/// [PlatformDispatcher.instance] and instead prefer using a binding for +/// dependency resolution such as `WidgetsBinding.instance.window`. /// -/// 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. +/// Static access of this `window` object means that Flutter has few, if any +/// options to fake or mock the given object in tests. Even in cases where Dart +/// offers special language constructs to forcefully shadow such properties, +/// those mechanisms would only be reasonable for tests and they would not be +/// reasonable for a future of Flutter where we legitimately want to select an +/// appropriate implementation at runtime. /// -/// If no context is available to look up a [FlutterView], the -/// [PlatformDispatcher] 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. If possible, consider accessing the [PlatformDispatcher] via the -/// binding (e.g. `WidgetsBinding.instance.platformDispatcher`) instead of the -/// static singleton [PlatformDispatcher.instance]. See -/// [PlatformDispatcher.instance] for more information about why this is -/// preferred. +/// The only place that `WidgetsBinding.instance.window` is inappropriate is if +/// access to these APIs is required before the binding is initialized by +/// invoking `runApp()` or `WidgetsFlutterBinding.instance.ensureInitialized()`. +/// In that case, it is necessary (though unfortunate) to use the +/// [PlatformDispatcher.instance] object statically. /// /// See also: /// -/// * [FlutterView], which gives an application access to view-specific -/// functionality. -/// * [PlatformDispatcher], which gives an application access to -/// platform-specific functionality. -/// * [PlatformDispatcher.views], for a list of all available views. -@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.' -) +/// * [PlatformDispatcher.views], contains the current list of Flutter windows +/// belonging to the application, including top level application windows like +/// this one. +/// * [PlatformDispatcher.implicitView], this window's view. final SingletonFlutterWindow window = SingletonFlutterWindow._(0, PlatformDispatcher.instance); /// Additional data available on each flutter frame.