diff --git a/en/application-dev/reference/apis/js-apis-display.md b/en/application-dev/reference/apis/js-apis-display.md index 372e6feb7c832d873bd98ed238d5cf474df10a5d..b086b03319ec20ebcdfdb30b7d9cbb4561de5038 100644 --- a/en/application-dev/reference/apis/js-apis-display.md +++ b/en/application-dev/reference/apis/js-apis-display.md @@ -28,29 +28,42 @@ Enumerates the display states. | STATE_VR | 5 | The display is in VR mode.| | STATE_ON_SUSPEND | 6 | The display is powered on, and the CPU is suspended.| +## Rect9+ -## Display +Describes a rectangle on the display. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core -Describes the attributes of a display. +| Name | Type| Readable| Writable| Description | +| ------ | -------- | ---- | ---- | ------------------ | +| left | number | Yes | Yes | Left boundary of the rectangle.| +| top | number | Yes | Yes | Top boundary of the rectangle.| +| width | number | Yes | Yes | Width of the rectangle. | +| height | number | Yes | Yes | Height of the rectangle. | + +## WaterfallDisplayAreaRects9+ + +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| -| -------- | -------- | -------- | -------- | -------- | -| 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](#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.| -| 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, in DPI.| -| densityPixels | number | Yes| No| Screen density of the display, in pixels.| -| scaledDensity | number | Yes| No| Scaling factor for fonts displayed on the display.| -| 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.| +| Name | Type | Readable| Writable| Description | +| ------ | ------------- | ---- | ---- | ------------------ | +| left | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located on the left of the display surface.| +| top | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located at the top of the display surface.| +| right | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located on the right of the display surface.| +| bottom | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located at the bottom of the display surface.| + +## CutoutInfo9+ + +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](#rect9)> | Yes | No | Bounding rectangle for punch holes and notches.| +| waterfallDisplayAreaRects | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | Yes| No| Curved area on the waterfall display.| ## display.getDefaultDisplay @@ -61,22 +74,24 @@ Obtains the default display object. This API uses an asynchronous callback to re **System capability**: SystemCapability.WindowManager.WindowManager.Core **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | callback | AsyncCallback<[Display](#display)> | Yes| Callback used to return the default display object.| **Example** - ```js - var 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; - }); - ``` + +```js +var 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 @@ -94,14 +109,16 @@ Obtains the default display object. This API uses a promise to return the result **Example** - ```js - let promise = display.getDefaultDisplay(); - promise.then(() => { - console.log('getDefaultDisplay success'); - }).catch((err) => { - console.log('getDefaultDisplay fail: ' + JSON.stringify(err)); - }); - ``` +```js +var 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.getDefaultDisplaySync9+ @@ -139,15 +156,15 @@ Obtains all display objects. This API uses an asynchronous callback to return th **Example** - ```js - 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)) - }); - ``` +```js +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 @@ -165,22 +182,22 @@ Obtains all display objects. This API uses a promise to return the result. **Example** - ```js - let promise = display.getAllDisplay(); - promise.then(() => { - console.log('getAllDisplay success'); - }).catch((err) => { - console.log('getAllDisplay fail: ' + JSON.stringify(err)); - }); - ``` +```js +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.hasPrivateWindow9+ hasPrivateWindow(displayId: number): boolean -Checks whether there is a visible privacy window on a display. The privacy window can be set by calling **[setPrivacyMode](js-apis-window.md#setprivacymode7)**. The content in the privacy window cannot be captured or recorded. +Checks whether there is a visible privacy window on a display. The privacy window can be set by calling `[setPrivacyMode](js-apis-window.md#setprivacymode7)`. The content in the privacy window cannot be captured or recorded. -This is a system API. +**System API**: This is a system API. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -194,21 +211,31 @@ This is a system API. | 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.
| +|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.
| **Example** - ```js - var ret = display.hasPrivateWindow(displayClass.id); - if (ret == undefined) { - console.log("HasPrivateWindow undefined."); - } - if (ret) { - console.log("HasPrivateWindow."); - } else if (!ret) { - console.log("Don't HasPrivateWindow."); +```js +var 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; +}); + +var ret = display.hasPrivateWindow(displayClass.id); +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."); +} +``` ## display.on('add'|'remove'|'change') @@ -219,19 +246,20 @@ 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.
- **remove**, indicating the display removal event.
- **change**, indicating the display change event.| | callback | Callback<number> | Yes| Callback used to return the ID of the display.| **Example** - ```js - var callback = (data) => { - console.info('Listening enabled. Data: ' + JSON.stringify(data)) - } - display.on("add", callback); - ``` +```js +var callback = (data) => { + console.info('Listening enabled. Data: ' + JSON.stringify(data)) +} +display.on("add", callback); +``` ## display.off('add'|'remove'|'change') @@ -242,12 +270,81 @@ 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.
- **remove**, indicating the display removal event.
- **change**, indicating the display change event.| | callback | Callback<number> | No| Callback used to return the ID of the display.| **Example** - ```js - display.off("remove"); - ``` + +```js +display.off("remove"); +``` + +## Display +Implements a `Display` instance, with properties and APIs defined. + +To call an API in the following API examples, you must first use `[getAllDisplay()](#displaygetalldisplay)`, `[getDefaultDisplay()](#displaygetdefaultdisplay)`, or `[getDefaultDisplaySync()](#displaygetdefaultdisplaysync)` to obtain a `Display` instance. + +**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](#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.| +| 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, in DPI.| +| densityPixels | number | Yes| No| Screen density of the display, in pixels.| +| scaledDensity | number | Yes| No| Scaling factor for fonts displayed on the display.| +| 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.| + +### getCutoutInfo9+ +getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void + +Obtains the cutout information of the display. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +| Name | Type | Mandatory| Description | +| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback<[CutoutInfo](#cutoutinfo9)> | Yes | Callback used to If the operation is successful, `err` is `undefined` and `data` is the `CutoutInfo` object obtained. Otherwise, `err` is an error object.| + +**Example** + +```js +displayClass.getCutoutInfo((err, data) => { + if (err.code) { + console.error('Failed to get cutoutInfo. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data)); +}) +``` +### getCutoutInfo9+ +getCutoutInfo(): Promise<CutoutInfo> + +Obtains the cutout information of the display. This API uses a promise to return the result. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<[CutoutInfo](#cutoutinfo9)> | Promise used to return the `CutoutInfo` object.| + +**Example** + +```js +let promise = displayClass.getCutoutInfo(); +promise.then((data) => { + console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data)); +}); +```