WindowManager

PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE

public static final String PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE

Application-level PackageManager.Property tag that specifies whether OEMs are permitted to provide activity embedding split-rule configurations on behalf of the app.

If true, the system is permitted to override the app's windowing behavior and implement activity embedding split rules, such as displaying activities side by side. A system override informs the app that the activity embedding APIs are disabled so the app will not provide its own activity embedding rules, which would conflict with the system's rules.

If false, the system is not permitted to override the windowing behavior of the app. Set the property to false if the app provides its own activity embedding split rules, or if you want to prevent the system override for any other reason.

The default value is false.

Note: Refusal to permit the system override is not enforceable. OEMs can override the app's activity embedding implementation whether or not this property is specified and set to false. The property is, in effect, a hint to OEMs.

OEMs can implement activity embedding on any API level. The best practice for apps is to always explicitly set this property in the app manifest file regardless of targeted API level rather than rely on the default value.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE"

PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED

public static final String PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED

Application level PackageManager .Property that an app can specify to inform the system that the app is ActivityEmbedding split feature enabled.

With this property, the system could provide custom behaviors for the apps that are ActivityEmbedding split feature enabled. For example, the fixed-portrait orientation requests of the activities could be ignored by the system in order to provide seamless ActivityEmbedding split experiences while holding the large-screen devices in landscape mode.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_ACTIVITY_EMBEDDING_SPLITS_ENABLED"

PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION

public static final String PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION

Application level PackageManager .Property for an app to inform the system that the app should be excluded from the camera compatibility force rotation treatment.

The camera compatibility treatment aligns orientations of portrait app window and natural orientation of the device and set opposite to natural orientation for a landscape app window. Mismatch between them can lead to camera issues like sideways or stretched viewfinder since this is one of the strongest assumptions that apps make when they implement camera previews. Since app and natural display orientations aren't guaranteed to match, the rotation can cause letterboxing. The forced rotation is triggered as soon as app opens to camera and is removed once camera is closed.

The camera compatibility can be enabled by device manufacturers on the displays that have ignoreOrientationRequest display setting enabled (enables compatibility mode for fixed orientation, see Enhanced letterboxing for more details).

With this property set to true or unset, the system may apply the force rotation treatment to fixed orientation activities. Device manufacturers can exclude packages from the treatment using their discretion to improve display compatibility.

With this property set to false, the system will not apply the force rotation treatment.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION"

PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH

public static final String PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH

Application level PackageManager .Property for an app to inform the system that the app should be excluded from the activity "refresh" after the camera compatibility force rotation treatment.

The camera compatibility treatment aligns orientations of portrait app window and natural orientation of the device and set opposite to natural orientation for a landscape app window. Mismatch between them can lead to camera issues like sideways or stretched viewfinder since this is one of the strongest assumptions that apps make when they implement camera previews. Since app and natural display orientations aren't guaranteed to match, the rotation can cause letterboxing. The forced rotation is triggered as soon as app opens to camera and is removed once camera is closed.

Force rotation is followed by the "Refresh" of the activity by going through "resumed -> ... -> stopped -> ... -> resumed" cycle (by default) or "resumed -> paused -> resumed" cycle (if overridden, see PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE for context). This allows to clear cached values in apps (e.g. display or camera rotation) that influence camera preview and can lead to sideways or stretching issues persisting even after force rotation.

The camera compatibility can be enabled by device manufacturers on the displays that have ignoreOrientationRequest display setting enabled (enables compatibility mode for fixed orientation, see Enhanced letterboxing for more details).

With this property set to true or unset, the system may "refresh" activity after the force rotation treatment. Device manufacturers can exclude packages from the "refresh" using their discretion to improve display compatibility.

With this property set to false, the system will not "refresh" activity after the force rotation treatment.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH"

PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE

public static final String PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE

Application level PackageManager .Property for an app to inform the system that the activity should be or shouldn't be "refreshed" after the camera compatibility force rotation treatment using "paused -> resumed" cycle rather than "stopped -> resumed".

The camera compatibility treatment aligns orientations of portrait app window and natural orientation of the device and set opposite to natural orientation for a landscape app window. Mismatch between them can lead to camera issues like sideways or stretched viewfinder since this is one of the strongest assumptions that apps make when they implement camera previews. Since app and natural display orientations aren't guaranteed to match, the rotation can cause letterboxing. The forced rotation is triggered as soon as app opens to camera and is removed once camera is closed.

Force rotation is followed by the "Refresh" of the activity by going through "resumed -> ... -> stopped -> ... -> resumed" cycle (by default) or "resumed -> paused -> resumed" cycle (if overridden by device manufacturers or using this property). This allows to clear cached values in apps (e.g., display or camera rotation) that influence camera preview and can lead to sideways or stretching issues persisting even after force rotation.

The camera compatibility can be enabled by device manufacturers on the displays that have ignoreOrientationRequest display setting enabled (enables compatibility mode for fixed orientation, see Enhanced letterboxing for more details).

Device manufacturers can override packages to "refresh" via "resumed -> paused -> resumed" cycle using their discretion to improve display compatibility.

With this property set to true, the system will "refresh" activity after the force rotation treatment using "resumed -> paused -> resumed" cycle.

With this property set to false, the system will not "refresh" activity after the force rotation treatment using "resumed -> paused -> resumed" cycle even if the device manufacturer adds the corresponding override.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE"

PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE

public static final String PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE

Application level PackageManager .Property for an app to inform the system that the app should be opted-out from the compatibility override that fixes display orientation to landscape natural orientation when an activity is fullscreen.

When this compat override is enabled and while display is fixed to the landscape natural orientation, the orientation requested by the activity will be still respected by bounds resolution logic. For instance, if an activity requests portrait orientation, then activity will appear in the letterbox mode for fixed orientation with the display rotated to the lanscape natural orientation.

The treatment is disabled by default but device manufacturers can enable the treatment using their discretion to improve display compatibility on the displays that have ignoreOrientationRequest display setting enabled (enables compatibility mode for fixed orientation, see Enhanced letterboxing for more details).

With this property set to true or unset, the system wiil use landscape display orientation when the following conditions are met:

• Natural orientation of the display is landscape
• ignoreOrientationRequest display setting is enabled
• Activity is fullscreen.
• Device manufacturer enabled the treatment.

With this property set to false, device manufactured per-app override for display orientation won't be applied.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE"

PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE

public static final String PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE

Application level PackageManager .Property for an app to inform the system that the app should be excluded from the compatibility override for orientation set by the device manufacturer. When the orientation override is applied it can:

• Replace the specific orientation requested by the app with another selected by the device manufacturer, e.g. replace undefined requested by the app with portrait.
• Always use an orientation selected by the device manufacturer.
• Do one of the above but only when camera connection is open.

This property is different from ERROR(/PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION) (which is used to avoid orientation loops caused by the incorrect use of Activity.setRequestedOrientation(int)) because this property overrides the app to an orientation selected by the device manufacturer rather than ignoring one of orientation requests coming from the app while respecting the previous one.

With this property set to true or unset, device manufacturers can override orientation for the app using their discretion to improve display compatibility.

With this property set to false, device manufactured per-app override for orientation won't be applied.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"

PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS

public static final String PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS

Application level PackageManager .Property for an app to inform the system that it needs to be opted-out from the compatibility treatment that sandboxes View API.

The treatment can be enabled by device manufacturers for applications which misuse View APIs by expecting that View.getLocationOnScreen(int), ERROR(/android.view.View#getBoundsOnScreen), View.getWindowVisibleDisplayFrame(Rect), ERROR(/android.view.View#getWindowDisplayFrame) return coordinates as if an activity is positioned in the top-left corner of the screen, with left coordinate equal to 0. This may not be the case for applications in multi-window and in letterbox modes.

Setting this property to false informs the system that the application must be opted-out from the "Sandbox View API to Activity bounds" treatment even if the device manufacturer has opted the app into the treatment.

Not setting this property at all, or setting this property to true has no effect.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS"
     android:value="false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS"

PROPERTY_COMPAT_ENABLE_FAKE_FOCUS

public static final String PROPERTY_COMPAT_ENABLE_FAKE_FOCUS

Application level PackageManager .Property for an app to inform the system that the application can be opted-in or opted-out from the compatibility treatment that enables sending a fake focus event for unfocused resumed split screen activities. This is needed because some game engines wait to get focus before drawing the content of the app which isn't guaranteed by default in multi-window modes.

Device manufacturers can enable this treatment using their discretion on a per-device basis to improve display compatibility. The treatment also needs to be specifically enabled on a per-app basis afterwards. This can either be done by device manufacturers or developers.

With this property set to true, the system will apply the treatment only if the device manufacturer had previously enabled it on the device. A fake focus event will be sent to the app after it is resumed only if the app is in split-screen.

Setting this property to false informs the system that the activity must be opted-out from the compatibility treatment even if the device manufacturer has opted the app into the treatment.

If the property remains unset the system will apply the treatment only if it had previously been enabled both at the device and app level by the device manufacturer.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_COMPAT_ENABLE_FAKE_FOCUS"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_COMPAT_ENABLE_FAKE_FOCUS"

PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION

public static final String PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION

Application level PackageManager .Property for an app to inform the system that the app can be opted-in or opted-out from the compatibility treatment that avoids Activity.setRequestedOrientation(int) loops. The loop can be trigerred by ignoreRequestedOrientation display setting enabled on the device or by the landscape natural orientation of the device.

The treatment is disabled by default but device manufacturers can enable the treatment using their discretion to improve display compatibility.

With this property set to true, the system could ignore Activity.setRequestedOrientation(int) call from an app if one of the following conditions are true:

• Activity is relaunching due to the previous Activity.setRequestedOrientation(int) call.
• Camera compatibility force rotation treatment is active for the package.

Setting this property to false informs the system that the app must be opted-out from the compatibility treatment even if the device manufacturer has opted the app into the treatment.

Syntax:

 <application>
   <property
     android:name="android.window.PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION"
     android:value="true|false"/>
 </application>
 

Constant Value: "android.window.PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION"

addCrossWindowBlurEnabledListener

public void addCrossWindowBlurEnabledListener (Consumer<Boolean> listener)

Adds a listener, which will be called when cross-window blurs are enabled/disabled at runtime. This affects both window blur behind (see LayoutParams#setBlurBehindRadius) and window background blur (see Window#setBackgroundBlurRadius).

Cross-window blur might not be supported by some devices due to GPU limitations. It can also be disabled at runtime, e.g. during battery saving mode, when multimedia tunneling is used or when minimal post processing is requested. In such situations, no blur will be computed or drawn, so the blur target area will not be blurred. To handle this, the app might want to change its theme to one that does not use blurs.

The listener will be called on the main thread.

If the listener is added successfully, it will be called immediately with the current cross-window blur enabled state.

addCrossWindowBlurEnabledListener

public void addCrossWindowBlurEnabledListener (Executor executor, 
                Consumer<Boolean> listener)

Adds a listener, which will be called when cross-window blurs are enabled/disabled at runtime. This affects both window blur behind (see LayoutParams#setBlurBehindRadius) and window background blur (see Window#setBackgroundBlurRadius).

Cross-window blur might not be supported by some devices due to GPU limitations. It can also be disabled at runtime, e.g. during battery saving mode, when multimedia tunneling is used or when minimal post processing is requested. In such situations, no blur will be computed or drawn, so the blur target area will not be blurred. To handle this, the app might want to change its theme to one that does not use blurs.

If the listener is added successfully, it will be called immediately with the current cross-window blur enabled state.

addProposedRotationListener

public void addProposedRotationListener (Executor executor, 
                IntConsumer listener)

Adds a listener to start monitoring the proposed rotation of the current associated context. It reports the current recommendation for the rotation that takes various factors (e.g. sensor, context, device state, etc) into account. The proposed rotation might not be applied by the system automatically due to the application's active preference to lock the orientation (e.g. with Activity.setRequestedOrientation(int)). This listener gives application an opportunity to selectively react to device orientation changes. The newly added listener will be called with current proposed rotation. Note that the context of this window manager instance must be a UiContext.

getCurrentWindowMetrics

public WindowMetrics getCurrentWindowMetrics ()

Returns the WindowMetrics according to the current system state.

The metrics describe the size of the area the window would occupy with MATCH_PARENT width and height, and the WindowInsets such a window would have.

The value of this is based on the current windowing state of the system. For example, for activities in multi-window mode, the metrics returned are based on the current bounds that the user has selected for the Activity's task.

In most scenarios, getCurrentWindowMetrics() rather than getMaximumWindowMetrics() is the correct API to use, since it ensures values reflect window size when the app is not fullscreen.

getDefaultDisplay

public abstract Display getDefaultDisplay ()

This method was deprecated in API level 30.
Use Context#getDisplay() instead.

Returns the Display upon which this WindowManager instance will create new windows.

Despite the name of this method, the display that is returned is not necessarily the primary display of the system (see Display#DEFAULT_DISPLAY). The returned display could instead be a secondary display that this window manager instance is managing. Think of it as the display that this WindowManager instance uses by default.

To create windows on a different display, you need to obtain a WindowManager for that Display. (See the WindowManager class documentation for more information.)

getMaximumWindowMetrics

public WindowMetrics getMaximumWindowMetrics ()

Returns the largest WindowMetrics an app may expect in the current system state.

The value of this is based on the largest potential windowing state of the system. For example, for activities in multi-window mode, the metrics returned are based on the what the bounds would be if the user expanded the Activity's task to cover the entire screen.

The metrics describe the size of the largest potential area the window might occupy with MATCH_PARENT width and height, and the WindowInsets such a window would have.

Note that this might still be smaller than the size of the physical display if certain areas of the display are not available to windows created in this Context. For example, given that there's a device which have a multi-task mode to limit activities to a half screen. In this case, getMaximumWindowMetrics() reports the bounds of the half screen which the activity is located.

Generally getCurrentWindowMetrics() is the correct API to use for choosing UI layouts. getMaximumWindowMetrics() are only appropriate when the application needs to know the largest possible size it can occupy if the user expands/maximizes it on the screen.

isCrossWindowBlurEnabled

public boolean isCrossWindowBlurEnabled ()

Returns whether cross-window blur is currently enabled. This affects both window blur behind (see LayoutParams#setBlurBehindRadius) and window background blur (see Window#setBackgroundBlurRadius).

Cross-window blur might not be supported by some devices due to GPU limitations. It can also be disabled at runtime, e.g. during battery saving mode, when multimedia tunneling is used or when minimal post processing is requested. In such situations, no blur will be computed or drawn, so the blur target area will not be blurred. To handle this, the app might want to change its theme to one that does not use blurs. To listen for cross-window blur enabled/disabled events, use addCrossWindowBlurEnabledListener(Executor, Consumer).

removeCrossWindowBlurEnabledListener

public void removeCrossWindowBlurEnabledListener (Consumer<Boolean> listener)

Removes a listener, previously added with addCrossWindowBlurEnabledListener(Executor, Consumer)

removeProposedRotationListener

public void removeProposedRotationListener (IntConsumer listener)

Removes a listener, previously added with addProposedRotationListener(Executor, IntConsumer). It is recommended to call when the associated context no longer has visible components. No-op if the provided listener is not registered.

removeViewImmediate

public abstract void removeViewImmediate (View view)

Special variation of ViewManager.removeView(View) that immediately invokes the given view hierarchy's View.onDetachedFromWindow() methods before returning. This is not for normal applications; using it correctly requires great care.