Display mask API
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.