Share via

Display mask API

  • Article

Represents the area of the display that is not functional for displaying content.

APIs in the Surface Duo SDK interact with the Surface Duo device, and should not be called when your app is running on other devices. Before calling these APIs, you should check whether your app is running on a Surface Duo device. Use the IsDualScreenDevice code snippet to perform this check.

DisplayMask has been updated to return a bounding rectangle relative to the display metrics based on the app context. This affects how the API behaves when your app is running on a single screen vs. running spanned across two screens. (A service that created a view at any point will fall into one of these two categories.)

  • When running on a single screen:

    • Windows and display metrics are in relation to that single display.
    • The DisplayMask returns an empty list. It will not intersect with the window.

  • When running spanned across two screens:

    • Window and display metrics are in relation to both displays, including the display mask.
    • The DisplayMask bounding rectangle will identify the area under the hardware hinge in relation to the app window (DisplayMask = hinge mask rectangle).

    For more info, see the Surface Duo Blog.

Tip

The display-mask package only runs on Surface Duo.

Consider using Jetpack Window Manager to access a device agnostic API that works on foldable devices from other manufacturers (as well as the Surface Duo).

Update your gradle file with the display-mask package to use these APIs.

import com.microsoft.device.display.DisplayMask

Methods

Static methods

Method Description
fromResourcesRect(Context context) Creates the display mask according to config_mainBuiltInDisplayMaskRect.
fromResourcesRectApproximation(Context context) Creates the display mask according to config_mainBuiltInDisplayMaskRectApproximation, which is the closest rectangle-base approximation of the mask.

Object methods

Method Description
getBoundingRects() Returns a list of Rects, each of which is the bounding rectangle for a non-functional area on the display.
getBoundingRectsForRotation(int rotation) Returns a list of Rects with respect to the rotation, each of which is the bounding rectangle for a non-functional area on the display.
getBounds() Returns the bounding region of the mask.

Example

Getting a display mask rect

val displayMask: DisplayMask = DisplayMask.fromResourcesRect(this)
val masks: List<Rect> = displayMask.getBoundingRectsForRotation(rotation) // pass in orientation (test with 0)
var mask = Rect()
if (!masks.isEmpty()) {
    mask = masks[0]
    // layout around masked area
}

Public methods

fromResourcesRect

public static DisplayMask fromResourcesRect(Context context)

Creates the display mask according to config_mainBuiltInDisplayMaskRect.

Parameters

Context context

A context for the current activity.

Returns

DisplayMask

The new display mask.

fromResourcesRectApproximation

public static DisplayMask fromResourcesRectApproximation(Context context)

Creates the display mask according to config_mainBuiltInDisplayMaskRectApproximation, which is the closest rectangle-base approximation of the mask.

Parameters

Context context

A context for the current activity.

Returns

DisplayMask

The new display mask.

getBoundingRects

public List<Rect> getBoundingRects()

Returns a list of Rects, each of which is the bounding rectangle for a non-functional area on the display.

Returns

List<Rect>

A list of bounding Rects, one for each display mask area.

getBoundingRectsForRotation

public List<Rect> getBoundingRectsForRotation(int rotation)

Returns a list of Rects with respect to the rotation, each of which is the bounding rectangle for a non-functional area on the display.

Parameters

int rotation

The rotation mask should rotate. Possible values are Surface.ROTATION_0, Surface.ROTATION_90, Surface.ROTATION_180, Surface.ROTATION_270

Returns

List<Rect>

A list of bounding Rects, one for each display mask area.

getBounds

public Region getBounds()

Returns the bounding region of the mask.

There may be more than one mask, in which case the returned Region will be non-contiguous and its bounding rect will be meaningless without intersecting it first.

Returns

Region

The bounding region of the mask. Coordinates are relative to the top-left corner of the content view and in pixel units.