@ohos.display (Display)

The Display module provides APIs for managing displays, such as obtaining information about the default display, obtaining information about all displays, and listening for the addition and removal of displays.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import display from '@ohos.display';

DisplayState

Enumerates the display states.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Value	Description
STATE_UNKNOWN	0	Unknown.
STATE_OFF	1	The display is shut down.
STATE_ON	2	The display is powered on.
STATE_DOZE	3	The display is in sleep mode.
STATE_DOZE_SUSPEND	4	The display is in sleep mode, and the CPU is suspended.
STATE_VR	5	The display is in VR mode.
STATE_ON_SUSPEND	6	The display is powered on, and the CPU is suspended.

Rect⁹⁺

Describes a rectangle on the display.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Readable	Writable	Description
left	number	Yes	Yes	Left boundary of the rectangle, in pixels.
top	number	Yes	Yes	Top boundary of the rectangle, in pixels.
width	number	Yes	Yes	Width of the rectangle, in pixels.
height	number	Yes	Yes	Height of the rectangle, in pixels.

WaterfallDisplayAreaRects⁹⁺

Describes the curved area (an area that is not intended for displaying content) on the waterfall display.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Readable	Writable	Description
left	Rect	Yes	No	Bounding rectangle for the curved area, which is located on the left of the display surface.
top	Rect	Yes	No	Bounding rectangle for the curved area, which is located at the top of the display surface.
right	Rect	Yes	No	Bounding rectangle for the curved area, which is located on the right of the display surface.
bottom	Rect	Yes	No	Bounding rectangle for the curved area, which is located at the bottom of the display surface.

CutoutInfo⁹⁺

Describes the cutout, which is an area that is not intended for displaying content on the display.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Readable	Writable	Description
boundingRects	Array<Rect>	Yes	No	Bounding rectangle for punch holes and notches.
waterfallDisplayAreaRects	WaterfallDisplayAreaRects	Yes	No	Curved area on the waterfall display.

display.getDefaultDisplaySync⁹⁺

getDefaultDisplaySync(): Display

Obtains the default display object. This API returns the result synchronously.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Display	Default display object.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

let displayClass = null;
try {
    displayClass = display.getDefaultDisplaySync();
} catch (exception) {
    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

display.getAllDisplays⁹⁺

getAllDisplays(callback: AsyncCallback<Array<Display>>): void

Obtains all display objects. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<Display>>	Yes	Callback used to return all the display objects.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

let displayClass = null;
display.getAllDisplays((err, data) => {
    displayClass = data;
    if (err.code) {
        console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
        return;
    }
    console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
});

display.getAllDisplays⁹⁺

getAllDisplays(): Promise<Array<Display>>

Obtains all display objects. This API uses a promise to return the result.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<Array<Display>>	Promise used to return all the display objects.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

let displayClass = null;
let promise = display.getAllDisplays();
promise.then((data) => {
    displayClass = data;
    console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
});

display.hasPrivateWindow⁹⁺

hasPrivateWindow(displayId: number): boolean

Checks whether there is a visible privacy window on a display. The privacy window can be set by calling setWindowPrivacyMode(). The content in the privacy window cannot be captured or recorded.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
id	number	Yes	ID of the display.

Return value

Type	Description
boolean	Whether there is a visible privacy window on the display. The value true means that there is a visible privacy window on the display, and false means the opposite.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400003	This display manager service works abnormally.

Example

let displayClass = null;
try {
    displayClass = display.getDefaultDisplaySync();

    let ret = undefined;
    try {
        ret = display.hasPrivateWindow(displayClass.id);
    } catch (exception) {
        console.error('Failed to check has privateWindow or not. Code: ' + JSON.stringify(exception));
    }
    if (ret == undefined) {
        console.log("Failed to check has privateWindow or not.");
    }
    if (ret) {
        console.log("There has privateWindow.");
    } else if (!ret) {
        console.log("There has no privateWindow.");
    }
} catch (exception) {
    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

display.on('add'|'remove'|'change')

on(type: 'add'|'remove'|'change', callback: Callback<number>): void

Subscribes to display changes.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - add, indicating the display addition event. Example: event that a display is connected. - remove, indicating the display removal event. Example: event that a display is disconnected. - change, indicating the display change event. Example: event that the display orientation is changed.
callback	Callback<number>	Yes	Callback used to return the ID of the display.

Example

let callback = (data) => {
    console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
try {
    display.on("add", callback);
} catch (exception) {
    console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
}

display.off('add'|'remove'|'change')

off(type: 'add'|'remove'|'change', callback?: Callback<number>): void

Unsubscribes from display changes.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - add, indicating the display addition event. Example: event that a display is connected. - remove, indicating the display removal event. Example: event that a display is disconnected. - change, indicating the display change event. Example: event that the display orientation is changed.
callback	Callback<number>	No	Callback used to return the ID of the display.

Example

try {
    display.off("remove");
} catch (exception) {
    console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
}

display.getDefaultDisplay^(deprecated)

getDefaultDisplay(callback: AsyncCallback<Display>): void

Obtains the default display object. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use getDefaultDisplaySync() instead.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Display>	Yes	Callback used to return the default display object.

Example

let displayClass = null;
display.getDefaultDisplay((err, data) => {
    if (err.code) {
        console.error('Failed to obtain the default display object. Code:  ' + JSON.stringify(err));
        return;
    }
    console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
    displayClass = data;
});

display.getDefaultDisplay^(deprecated)

getDefaultDisplay(): Promise<Display>

Obtains the default display object. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use getDefaultDisplaySync() instead.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<Display>	Promise used to return the default display object.

Example

let displayClass = null;
let promise = display.getDefaultDisplay();
promise.then((data) => {
    displayClass = data;
    console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to obtain the default display object. Code:  ' + JSON.stringify(err));
});

display.getAllDisplay^(deprecated)

getAllDisplay(callback: AsyncCallback<Array<Display>>): void

Obtains all display objects. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use getAllDisplays() instead.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<Display>>	Yes	Callback used to return all the display objects.

Example

display.getAllDisplay((err, data) => {
    if (err.code) {
        console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
        return;
    }
    console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
});

display.getAllDisplay^(deprecated)

getAllDisplay(): Promise<Array<Display>>

Obtains all display objects. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use getAllDisplays() instead.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<Array<Display>>	Promise used to return all the display objects.

Example

let promise = display.getAllDisplay();
promise.then((data) => {
    console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
});

Display

Implements a Display instance, with properties and APIs defined.

Before calling any API in Display, you must use getAllDisplays() or getDefaultDisplaySync() to obtain a Display instance.

Attributes

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Readable	Writable	Description
id	number	Yes	No	ID of the display.
name	string	Yes	No	Name of the display.
alive	boolean	Yes	No	Whether the display is alive.
state	DisplayState	Yes	No	State of the display.
refreshRate	number	Yes	No	Refresh rate of the display.
rotation	number	Yes	No	Screen rotation angle of the display. The value 0 indicates that the screen of the display rotates by 0°. The value 1 indicates that the screen of the display rotates by 90°. The value 2 indicates that the screen of the display rotates by 180°. The value 3 indicates that the screen of the display rotates by 270°.
width	number	Yes	No	Width of the display, in pixels.
height	number	Yes	No	Height of the display, in pixels.
densityDPI	number	Yes	No	Screen density of the display, that is, the number of dots per inch. Generally, the value is 160 or 480.
densityPixels	number	Yes	No	Logical density of the display, which is a scaling coefficient independent of the pixel unit. Generally, the value is 1 or 3.
scaledDensity	number	Yes	No	Scaling factor for fonts displayed on the display. Generally, the value is the same as that of densityPixels.
xDPI	number	Yes	No	Exact physical dots per inch of the screen in the horizontal direction.
yDPI	number	Yes	No	Exact physical dots per inch of the screen in the vertical direction.

getCutoutInfo⁹⁺

getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void

Obtains the cutout information of the display. This API uses an asynchronous callback to return the result. You are advised not to use the cutout area during application layout.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<CutoutInfo>	Yes	Callback used to return the CutoutInfo object.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

let displayClass = null;
try {
    displayClass = display.getDefaultDisplaySync();

    displayClass.getCutoutInfo((err, data) => {
        if (err.code) {
            console.error('Failed to get cutoutInfo. Code: ' + JSON.stringify(err));
            return;
        }
        console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data));
    });
} catch (exception) {
    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

getCutoutInfo⁹⁺

getCutoutInfo(): Promise<CutoutInfo>

Obtains the cutout information of the display. This API uses a promise to return the result. You are advised not to use the cutout area during application layout.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<CutoutInfo>	Promise used to return the CutoutInfo object.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

let displayClass = null;
try {
    displayClass = display.getDefaultDisplaySync();

    let promise = displayClass.getCutoutInfo();
    promise.then((data) => {
        console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data));
    }).catch((err) => {
        console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

@ohos.display (Display)

Modules to Import

DisplayState

Rect9+

WaterfallDisplayAreaRects9+

CutoutInfo9+

display.getDefaultDisplaySync9+

display.getAllDisplays9+

display.getAllDisplays9+

display.hasPrivateWindow9+

display.on('add'|'remove'|'change')

display.off('add'|'remove'|'change')

display.getDefaultDisplay(deprecated)

display.getDefaultDisplay(deprecated)

display.getAllDisplay(deprecated)

display.getAllDisplay(deprecated)

Display

Attributes

getCutoutInfo9+

getCutoutInfo9+

Rect⁹⁺

WaterfallDisplayAreaRects⁹⁺

CutoutInfo⁹⁺

display.getDefaultDisplaySync⁹⁺

display.getAllDisplays⁹⁺

display.getAllDisplays⁹⁺

display.hasPrivateWindow⁹⁺

display.getDefaultDisplay^(deprecated)

display.getDefaultDisplay^(deprecated)

display.getAllDisplay^(deprecated)

display.getAllDisplay^(deprecated)

getCutoutInfo⁹⁺

getCutoutInfo⁹⁺