Window class

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 WidgetsBinding.instance.window.

There is also a window singleton object in dart:ui if WidgetsBinding 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

In this diagram, the black areas represent system UI that the app cannot draw over. The red area represents view padding that the application may not be able to detect gestures in and may not want to draw in. The grey area represents the system keyboard, which can cover over the bottom view padding when visible.

The Window.viewInsets are the physical pixels which the operating system reserves for system UI, such as the keyboard, which would fully obscure any content drawn in that area.

The Window.viewPadding are the physical pixels on each side of the display that may be partially obscured by system UI or by physical intrusions into the display, such as an overscan region on a television or a "notch" on a phone. Unlike the insets, these areas may have portions that show the user application painted pixels without being obscured, such as a notch at the top of a phone that covers only a subset of the area. Insets, on the other hand, either partially or fully obscure the window, such as an opaque keyboard or a partially transluscent statusbar, which cover an area without gaps.

The Window.padding property is computed from both Window.viewInsets and Window.viewPadding. It will allow a view inset to consume view padding where appropriate, such as when a phone's keyboard is covering the bottom view padding and so "absorbs" it.

Clients that want to position elements relative to the view padding regardless of the view insets should use the Window.viewPadding property, e.g. if you wish to draw a widget at the center of the screen with respect to the iPhone "safe area" regardless of whether the keyboard is showing.

Window.padding is useful for clients that want to know how much padding should be accounted for without concern for the current inset(s) state, e.g. determining whether a gesture should be considered for scrolling purposes. This value varies based on the current state of the insets. For example, a visible keyboard will consume all gestures in the bottom part of the Window.viewPadding anyway, so there is no need to account for that in the Window.padding, which is always safe to use for such calculations.

Implementers

Properties

accessibilityFeatures AccessibilityFeatures
Additional accessibility features that may be enabled by the platform.
read-only
alwaysUse24HourFormat bool
The setting indicating whether time should always be shown in the 24-hour format. [...]
read-only
defaultRouteName String
The route or path that the embedder requested when the application was launched. [...]
read-only
devicePixelRatio double
The number of device pixels for each logical pixel. This number might not be a power of two. Indeed, it might not even be an integer. For example, the Nexus 6 has a device pixel ratio of 3.5. [...]
read-only
initialLifecycleState String
The lifecycle state immediately after dart isolate initialization. [...]
read-only
locale Locale
The system-reported default locale of the device. [...]
read-only
locales List<Locale>
The full system-reported supported locales of the device. [...]
read-only
onAccessibilityFeaturesChanged VoidCallback
A callback that is invoked when the value of accessibilityFeatures changes. [...]
read / write
onBeginFrame FrameCallback
A callback that is invoked to notify the application that it is an appropriate time to provide a scene using the SceneBuilder API and the render method. When possible, this is driven by the hardware VSync signal. This is only called if scheduleFrame has been called since the last time this callback was invoked. [...]
read / write
onDrawFrame VoidCallback
A callback that is invoked for each frame after onBeginFrame has completed and after the microtask queue has been drained. This can be used to implement a second phase of frame rendering that happens after any deferred work queued by the onBeginFrame phase. [...]
read / write
onLocaleChanged VoidCallback
A callback that is invoked whenever locale changes value. [...]
read / write
onMetricsChanged VoidCallback
A callback that is invoked whenever the devicePixelRatio, physicalSize, padding, viewInsets, or systemGestureInsets values change, for example when the device is rotated or when the application is resized (e.g. when showing applications side-by-side on Android). [...]
read / write
onPlatformBrightnessChanged VoidCallback
A callback that is invoked whenever platformBrightness changes value. [...]
read / write
onPlatformMessage PlatformMessageCallback
Called whenever this window receives a message from a platform-specific plugin. [...]
read / write
onPointerDataPacket PointerDataPacketCallback
A callback that is invoked when pointer data is available. [...]
read / write
onReportTimings TimingsCallback
A callback that is invoked to report the FrameTiming of recently rasterized frames. [...]
read / write
onSemanticsAction SemanticsActionCallback
A callback that is invoked whenever the user requests an action to be performed. [...]
read / write
onSemanticsEnabledChanged VoidCallback
A callback that is invoked when the value of semanticsEnabled changes. [...]
read / write
onTextScaleFactorChanged VoidCallback
A callback that is invoked whenever textScaleFactor changes value. [...]
read / write
padding WindowPadding
The number of physical pixels on each side of the display rectangle into which the application can render, but which may be partially obscured by system UI (such as the system notification area), or or physical intrusions in the display (e.g. overscan regions on television screens or phone sensor housings). [...]
read-only
physicalDepth double
The physical depth is the maximum elevation that the Window allows. [...]
read-only
physicalSize Size
The dimensions of the rectangle into which the application will be drawn, in physical pixels. [...]
read-only
platformBrightness Brightness
The setting indicating the current brightness mode of the host platform. If the platform has no preference, platformBrightness defaults to Brightness.light.
read-only
semanticsEnabled bool
Whether the user has requested that updateSemantics be called when the semantic contents of window changes. [...]
read-only
systemGestureInsets WindowPadding
The number of physical pixels on each side of the display rectangle into which the application can render, but where the operating system will consume input gestures for the sake of system navigation. [...]
read-only
textScaleFactor double
The system-reported text scale. [...]
read-only
viewInsets WindowPadding
The number of physical pixels on each side of the display rectangle into which the application can render, but over which the operating system will likely place system UI, such as the keyboard, that fully obscures any content. [...]
read-only
viewPadding WindowPadding
The number of physical pixels on each side of the display rectangle into which the application can render, but which may be partially obscured by system UI (such as the system notification area), or or physical intrusions in the display (e.g. overscan regions on television screens or phone sensor housings). [...]
read-only
hashCode int
The hash code for this object. [...]
read-only, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited

Methods

render(Scene scene) → void
Updates the application's rendering on the GPU with the newly provided Scene. This function must be called within the scope of the onBeginFrame or onDrawFrame callbacks being invoked. If this function is called a second time during a single onBeginFrame/onDrawFrame callback sequence or called outside the scope of those callbacks, the call will be ignored. [...]
scheduleFrame() → void
Requests that, at the next appropriate opportunity, the onBeginFrame and onDrawFrame callbacks be invoked. [...]
sendPlatformMessage(String name, ByteData data, PlatformMessageResponseCallback callback) → void
Sends a message to a platform-specific plugin. [...]
setIsolateDebugName(String name) → void
Set the debug name associated with this window's root isolate. [...]
updateSemantics(SemanticsUpdate update) → void
Change the retained semantics data about this window. [...]
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
toString() String
Returns a string representation of this object.
inherited

Operators

operator ==(dynamic other) bool
The equality operator. [...]
inherited