From 6cc2b93dd1c09a616b08e3dbe91a551d20fd5819 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Tue, 31 Jan 2023 15:12:08 -0800 Subject: [PATCH 1/6] Deprecate SingletonFlutterWindow and global window singleton --- lib/ui/window.dart | 90 +++++++++++++++++++++++++++------------------- 1 file changed, 54 insertions(+), 36 deletions(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 185f183baef9d..127df196e012a 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -308,21 +308,30 @@ class FlutterView { external static void _updateSemantics(SemanticsUpdate update); } -/// A [FlutterView] that includes access to setting callbacks and retrieving -/// properties that reside on the [PlatformDispatcher]. +/// Deprecated. Will be removed in a future version of Flutter. /// -/// It is the type of the global [window] singleton used by applications that -/// only have a single main window. +/// This class has been deprecated to prepare for Flutter's upcoming support +/// for multiple views and eventually multiple windows. /// -/// 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 has been split into two classes: [FlutterView] and +/// [PlatformDispatcher]. The [FlutterView] gives an application access to +/// view-specific functionality while the [PlatformDispatcher] contains +/// platform-specific functionality that applies to all views. /// -/// 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. +/// This class is used to back 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.' +) class SingletonFlutterWindow extends FlutterView { SingletonFlutterWindow._(super.windowId, super.platformDispatcher) : super._(); @@ -576,7 +585,7 @@ class SingletonFlutterWindow extends FlutterView { /// {@macro dart.ui.window.accessorForwardWarning} /// /// It's preferred to use [SchedulerBinding.addTimingsCallback] than to use - /// [SingletonFlutterWindow.onReportTimings] directly because + /// [PlatformDispatcher.onReportTimings] directly because /// [SchedulerBinding.addTimingsCallback] allows multiple callbacks. /// /// This can be used to see if the window has missed frames (through @@ -891,36 +900,45 @@ enum Brightness { light, } -/// The [SingletonFlutterWindow] representing the main window for applications -/// where there is only one window, such as applications designed for -/// single-display mobile devices. +/// Deprecated. Will be removed in a future version of Flutter. +/// +/// This property has been deprecated to prepare for Flutter's upcoming support +/// for multiple views and eventually multiple windows. /// -/// Applications that are designed to use more than one window should interact -/// with the `WidgetsBinding.instance.platformDispatcher` instead. +/// It used to represent the only window into which an application could draw +/// content while giving the application access to window- and platform-specific +/// functionality. /// -/// Consider avoiding static references to this singleton through -/// [PlatformDispatcher.instance] and instead prefer using a binding for -/// dependency resolution such as `WidgetsBinding.instance.window`. +/// Several options exist to migrate code that relies on this property. They are +/// listed below in order of preference: /// -/// 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. +/// The current [FlutterView] can be obtained from the context via [View.of]. It +/// gives access to the same functionality as this deprecated global [window] +/// property. However, some functionality has moved to the [PlatformDispatcher], +/// which is exposed via [FlutterView.platformDispatcher]. /// -/// 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. +/// If no context is available to look up a [FlutterView], the +/// [PlatformDispatcher] can be consulted 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. /// /// See also: /// -/// * [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. +/// * [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 availalbe 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.' +) final SingletonFlutterWindow window = SingletonFlutterWindow._(0, PlatformDispatcher.instance); /// Additional data available on each flutter frame. From 7b8ef6ca4ee78a3edbbb73142d66a25ce89d29b8 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Tue, 31 Jan 2023 15:31:49 -0800 Subject: [PATCH 2/6] review --- lib/ui/window.dart | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 127df196e012a..df8db9781a9be 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -310,16 +310,16 @@ class FlutterView { /// Deprecated. Will be removed in a future version of Flutter. /// -/// This class has been deprecated to prepare for Flutter's upcoming support -/// for multiple views and eventually multiple windows. +/// This class is deprecated to prepare for Flutter's upcoming support for +/// multiple views and eventually multiple windows. /// /// This class has been split into two classes: [FlutterView] and /// [PlatformDispatcher]. The [FlutterView] gives an application access to /// view-specific functionality while the [PlatformDispatcher] contains /// platform-specific functionality that applies to all views. /// -/// This class is used to back the global [window] singleton, which is also -/// deprecated. See the docs on [window] for migration options. +/// This class backs the global [window] singleton, which is also deprecated. +/// See the docs on [window] for migration options. /// /// See also: /// @@ -902,15 +902,14 @@ enum Brightness { /// Deprecated. Will be removed in a future version of Flutter. /// -/// This property has been deprecated to prepare for Flutter's upcoming support -/// for multiple views and eventually multiple windows. +/// This global property is deprecated to prepare for Flutter's upcoming support +/// for multiple views and multiple windows. /// -/// It used to represent the only window into which an application could draw -/// content while giving the application access to window- and platform-specific -/// functionality. +/// It represents the main window for applications where there is only one +/// window, such as applications designed for single-display mobile devices. /// -/// Several options exist to migrate code that relies on this property. They are -/// listed below in order of preference: +/// Several options exist to migrate code that relies on this global singleton. +/// They are listed below in order of preference: /// /// The current [FlutterView] can be obtained from the context via [View.of]. It /// gives access to the same functionality as this deprecated global [window] From 4e3df79c0f03d9f2b5ee602f47407adbbb2f814f Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Tue, 31 Jan 2023 16:16:42 -0800 Subject: [PATCH 3/6] analyzer --- lib/ui/window.dart | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index df8db9781a9be..80fccfe5af573 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -333,6 +333,11 @@ class FlutterView { 'This feature was deprecated after v3.7.0-32.0.pre.' ) 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._(); From 83d2f28ed78eb838e14796ad960022a7800c7e66 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Fri, 17 Feb 2023 12:59:05 -0800 Subject: [PATCH 4/6] update --- lib/ui/window.dart | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 80fccfe5af573..1038f77c8f71e 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -314,7 +314,7 @@ class FlutterView { /// multiple views and eventually multiple windows. /// /// This class has been split into two classes: [FlutterView] and -/// [PlatformDispatcher]. The [FlutterView] gives an application access to +/// [PlatformDispatcher]. A [FlutterView] gives an application access to /// view-specific functionality while the [PlatformDispatcher] contains /// platform-specific functionality that applies to all views. /// @@ -910,16 +910,23 @@ enum Brightness { /// This global property is deprecated to prepare for Flutter's upcoming support /// for multiple views and multiple windows. /// -/// It represents 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. /// -/// Several options exist to migrate code that relies on this global singleton. -/// They are listed below in order of preference: +/// The following options exists to migrate code that relies on accessing +/// this deprecated property: /// -/// The current [FlutterView] can be obtained from the context via [View.of]. It -/// gives access to the same functionality as this deprecated global [window] -/// property. However, some functionality has moved to the [PlatformDispatcher], -/// which is exposed via [FlutterView.platformDispatcher]. +/// 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, some +/// functionality has moved to the [PlatformDispatcher], which should 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. /// /// If no context is available to look up a [FlutterView], the /// [PlatformDispatcher] can be consulted directly for platform-specific @@ -939,7 +946,7 @@ enum Brightness { /// platform-specific functionality. /// * [PlatformDispatcher.views], for a list of all availalbe views. @Deprecated( - 'Look up the current FlutterView from the context via View.of(context) or consult the PlatformDispatcher directly instead.' + '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.' ) From 0c9ddd0ab5da43b985958cbdc778c27b1a19eccf Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Fri, 17 Feb 2023 13:22:33 -0800 Subject: [PATCH 5/6] typo --- lib/ui/window.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 1038f77c8f71e..9280762c277d7 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -944,7 +944,7 @@ enum Brightness { /// functionality. /// * [PlatformDispatcher], which gives an application access to /// platform-specific functionality. -/// * [PlatformDispatcher.views], for a list of all availalbe views. +/// * [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. ' From 6ae71605126276a290d1fe733767a600d8418c7f Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Wed, 15 Mar 2023 14:43:02 -0700 Subject: [PATCH 6/6] review --- lib/ui/window.dart | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 9280762c277d7..1810ef58234e5 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -921,15 +921,15 @@ enum Brightness { /// /// 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, some -/// functionality has moved to the [PlatformDispatcher], which should be -/// accessed from the view returned by [View.of] via +/// 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. /// /// If no context is available to look up a [FlutterView], the -/// [PlatformDispatcher] can be consulted directly for platform-specific +/// [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