From 75e2fd6c714b459e73d2cb84e299ce41d823d1f9 Mon Sep 17 00:00:00 2001 From: Yuqian Li Date: Wed, 3 Jul 2019 15:40:15 -0700 Subject: [PATCH 1/3] Improve window documentation To reflect Matt Carroll's recent (02/06/2019) email about promoting `WidgetsBinding.instance.window` and demoting `ui.window`. I have to manually search for Matt's email several times when I need to access the Window object. Having it in the documentation would help me do that much faster. --- lib/ui/window.dart | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 403ec5110fa82..56f9996e12465 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -515,8 +515,12 @@ class Locale { /// The most basic interface to the host operating system's user interface. /// +/// It exposes the size of the display, the core scheduler API, the input event +/// callback, the graphics drawing API, and other such core services. +/// /// There is a single Window instance in the system, which you can -/// obtain from the [window] property. +/// obtain from `WidgetsBinding.instance.window`, or `window` in `dart:ui` if +/// `WidgetsBinding` is unavailable. /// /// ## Insets and Padding /// @@ -1220,7 +1224,19 @@ enum Brightness { light, } -/// The [Window] singleton. This object exposes the size of the display, the -/// core scheduler API, the input event callback, the graphics drawing API, and -/// other such core services. +/// The [Window] singleton. +/// +/// Please try to avoid statically referencing this and instead use a +/// binding for dependency resolution such as `WidgetsBinding.instance.window`. +/// +/// 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 only place that `WidgetsBinding.instance.window` is inappropriate is if +/// a `Window` is required before invoking `runApp()`. In that case, it is +/// acceptable (though unfortunate) to use this object statically. final Window window = Window._(); From 4a7c60111ad0aba78ab13671b1592b357a538fe6 Mon Sep 17 00:00:00 2001 From: Yuqian Li Date: Mon, 8 Jul 2019 11:03:09 -0700 Subject: [PATCH 2/3] Improve language according to comments --- lib/ui/window.dart | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/lib/ui/window.dart b/lib/ui/window.dart index 56f9996e12465..176de86c7d82f 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -519,8 +519,11 @@ class Locale { /// callback, the graphics drawing API, and other such core services. /// /// There is a single Window instance in the system, which you can -/// obtain from `WidgetsBinding.instance.window`, or `window` in `dart:ui` if -/// `WidgetsBinding` is unavailable. +/// obtain from `WidgetsBinding.instance.window`. +/// +/// There is also a [window] singleton object in `dart:ui` if `WidgetsBinding` +/// is unavailable. But we strongly advice to avoid statically referencing it. +/// See the document of [window] for more details of why it should be avoided. /// /// ## Insets and Padding /// From 381403ebbaeccd55f18c51db3f745ba38fe382c2 Mon Sep 17 00:00:00 2001 From: liyuqian Date: Mon, 8 Jul 2019 13:09:54 -0700 Subject: [PATCH 3/3] 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 176de86c7d82f..dee2d16647077 100644 --- a/lib/ui/window.dart +++ b/lib/ui/window.dart @@ -522,7 +522,7 @@ class Locale { /// obtain from `WidgetsBinding.instance.window`. /// /// There is also a [window] singleton object in `dart:ui` if `WidgetsBinding` -/// is unavailable. But we strongly advice to avoid statically referencing it. +/// is unavailable. But we strongly advise to avoid statically referencing it. /// See the document of [window] for more details of why it should be avoided. /// /// ## Insets and Padding