Skip to content
This repository was archived by the owner on Feb 25, 2025. It is now read-only.

Commit 92c4469

Browse files
authored
Improve window documentation (#9669)
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.
1 parent 7a22323 commit 92c4469

File tree

1 file changed

+23
-4
lines changed

1 file changed

+23
-4
lines changed

lib/ui/window.dart

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -515,8 +515,15 @@ class Locale {
515515

516516
/// The most basic interface to the host operating system's user interface.
517517
///
518+
/// It exposes the size of the display, the core scheduler API, the input event
519+
/// callback, the graphics drawing API, and other such core services.
520+
///
518521
/// There is a single Window instance in the system, which you can
519-
/// obtain from the [window] property.
522+
/// obtain from `WidgetsBinding.instance.window`.
523+
///
524+
/// There is also a [window] singleton object in `dart:ui` if `WidgetsBinding`
525+
/// is unavailable. But we strongly advise to avoid statically referencing it.
526+
/// See the document of [window] for more details of why it should be avoided.
520527
///
521528
/// ## Insets and Padding
522529
///
@@ -1220,7 +1227,19 @@ enum Brightness {
12201227
light,
12211228
}
12221229

1223-
/// The [Window] singleton. This object exposes the size of the display, the
1224-
/// core scheduler API, the input event callback, the graphics drawing API, and
1225-
/// other such core services.
1230+
/// The [Window] singleton.
1231+
///
1232+
/// Please try to avoid statically referencing this and instead use a
1233+
/// binding for dependency resolution such as `WidgetsBinding.instance.window`.
1234+
///
1235+
/// Static access of this "window" object means that Flutter has few, if any
1236+
/// options to fake or mock the given object in tests. Even in cases where Dart
1237+
/// offers special language constructs to forcefully shadow such properties,
1238+
/// those mechanisms would only be reasonable for tests and they would not be
1239+
/// reasonable for a future of Flutter where we legitimately want to select an
1240+
/// appropriate implementation at runtime.
1241+
///
1242+
/// The only place that `WidgetsBinding.instance.window` is inappropriate is if
1243+
/// a `Window` is required before invoking `runApp()`. In that case, it is
1244+
/// acceptable (though unfortunate) to use this object statically.
12261245
final Window window = Window._();

0 commit comments

Comments
 (0)