1# @ohos.display (Display) 2 3The **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. 4 5> **NOTE** 6> 7> 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. 8 9## Modules to Import 10 11```js 12import display from '@ohos.display'; 13``` 14 15## DisplayState 16 17Enumerates the display states. 18 19**System capability**: SystemCapability.WindowManager.WindowManager.Core 20 21| Name| Value| Description| 22| -------- | -------- | -------- | 23| STATE_UNKNOWN | 0 | Unknown.| 24| STATE_OFF | 1 | The display is shut down.| 25| STATE_ON | 2 | The display is powered on.| 26| STATE_DOZE | 3 | The display is in sleep mode.| 27| STATE_DOZE_SUSPEND | 4 | The display is in sleep mode, and the CPU is suspended.| 28| STATE_VR | 5 | The display is in VR mode.| 29| STATE_ON_SUSPEND | 6 | The display is powered on, and the CPU is suspended.| 30 31## Rect<sup>9+</sup> 32 33Describes a rectangle on the display. 34 35**System capability**: SystemCapability.WindowManager.WindowManager.Core 36 37| Name | Type| Readable| Writable| Description | 38| ------ | -------- | ---- | ---- | ------------------ | 39| left | number | Yes | Yes | Left boundary of the rectangle, in pixels.| 40| top | number | Yes | Yes | Top boundary of the rectangle, in pixels.| 41| width | number | Yes | Yes | Width of the rectangle, in pixels. | 42| height | number | Yes | Yes | Height of the rectangle, in pixels. | 43 44## WaterfallDisplayAreaRects<sup>9+</sup> 45 46Describes the curved area (an area that is not intended for displaying content) on the waterfall display. 47 48**System capability**: SystemCapability.WindowManager.WindowManager.Core 49 50| Name | Type | Readable| Writable| Description | 51| ------ | ------------- | ---- | ---- | ------------------ | 52| left | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located on the left of the display surface.| 53| top | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located at the top of the display surface.| 54| right | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located on the right of the display surface.| 55| bottom | [Rect](#rect9) | Yes | No | Bounding rectangle for the curved area, which is located at the bottom of the display surface.| 56 57## CutoutInfo<sup>9+</sup> 58 59Describes the cutout, which is an area that is not intended for displaying content on the display. 60 61**System capability**: SystemCapability.WindowManager.WindowManager.Core 62 63| Name | Type | Readable| Writable| Description | 64| --------------------------- | ------------- | ---- | ---- | ------------------ | 65| boundingRects | Array\<[Rect](#rect9)> | Yes | No | Bounding rectangle for punch holes and notches.| 66| waterfallDisplayAreaRects | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | Yes| No| Curved area on the waterfall display.| 67 68## display.getDefaultDisplaySync<sup>9+</sup> 69 70getDefaultDisplaySync(): Display 71 72Obtains the default display object. This API returns the result synchronously. 73 74**System capability**: SystemCapability.WindowManager.WindowManager.Core 75 76**Return value** 77 78| Type | Description | 79| ------------------------------| ----------------------------------------------| 80| [Display](#display) | Default display object.| 81 82**Error codes** 83 84For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 85 86| ID| Error Message| 87| ------- | ----------------------- | 88| 1400001 | Invalid display or screen. | 89 90**Example** 91 92```js 93let displayClass = null; 94try { 95 displayClass = display.getDefaultDisplaySync(); 96} catch (exception) { 97 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 98} 99``` 100 101## display.getAllDisplays<sup>9+</sup> 102 103getAllDisplays(callback: AsyncCallback<Array<Display>>): void 104 105Obtains all display objects. This API uses an asynchronous callback to return the result. 106 107**System capability**: SystemCapability.WindowManager.WindowManager.Core 108 109**Parameters** 110 111| Name| Type| Mandatory| Description| 112| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 113| callback | AsyncCallback<Array<[Display](#display)>> | Yes| Callback used to return all the display objects.| 114 115**Error codes** 116 117For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 118 119| ID| Error Message| 120| ------- | ----------------------- | 121| 1400001 | Invalid display or screen. | 122 123**Example** 124 125```js 126let displayClass = null; 127display.getAllDisplays((err, data) => { 128 displayClass = data; 129 if (err.code) { 130 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 131 return; 132 } 133 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 134}); 135``` 136 137## display.getAllDisplays<sup>9+</sup> 138 139getAllDisplays(): Promise<Array<Display>> 140 141Obtains all display objects. This API uses a promise to return the result. 142 143**System capability**: SystemCapability.WindowManager.WindowManager.Core 144 145**Return value** 146 147| Type| Description| 148| ----------------------------------------------- | ------------------------------------------------------- | 149| Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| 150 151**Error codes** 152 153For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 154 155| ID| Error Message| 156| ------- | ----------------------- | 157| 1400001 | Invalid display or screen. | 158 159**Example** 160 161```js 162let displayClass = null; 163let promise = display.getAllDisplays(); 164promise.then((data) => { 165 displayClass = data; 166 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 167}).catch((err) => { 168 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 169}); 170``` 171 172## display.hasPrivateWindow<sup>9+</sup> 173 174hasPrivateWindow(displayId: number): boolean 175 176Checks whether there is a visible privacy window on a display. The privacy window can be set by calling [setWindowPrivacyMode()](js-apis-window.md#setwindowprivacymode9). The content in the privacy window cannot be captured or recorded. 177 178**System API**: This is a system API. 179 180**System capability**: SystemCapability.WindowManager.WindowManager.Core 181 182**Parameters** 183 184| Name| Type | Mandatory| Description | 185| ------ | ------------------------- | ---- |----------| 186| id | number | Yes | ID of the display.| 187 188**Return value** 189 190| Type | Description | 191| -------------------------------- |-----------------------------------------------------------------------| 192|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.| 193 194**Error codes** 195 196For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 197 198| ID| Error Message| 199| ------- | -------------------------------------------- | 200| 1400003 | This display manager service works abnormally. | 201 202**Example** 203 204```js 205let displayClass = null; 206try { 207 displayClass = display.getDefaultDisplaySync(); 208 209 let ret = undefined; 210 try { 211 ret = display.hasPrivateWindow(displayClass.id); 212 } catch (exception) { 213 console.error('Failed to check has privateWindow or not. Code: ' + JSON.stringify(exception)); 214 } 215 if (ret == undefined) { 216 console.log("Failed to check has privateWindow or not."); 217 } 218 if (ret) { 219 console.log("There has privateWindow."); 220 } else if (!ret) { 221 console.log("There has no privateWindow."); 222 } 223} catch (exception) { 224 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 225} 226``` 227 228## display.on('add'|'remove'|'change') 229 230on(type: 'add'|'remove'|'change', callback: Callback<number>): void 231 232Subscribes to display changes. 233 234**System capability**: SystemCapability.WindowManager.WindowManager.Core 235 236**Parameters** 237 238| Name| Type| Mandatory| Description| 239| -------- | -------- | -------- | -------- | 240| type | string | Yes| Event type.<br>- **add**, indicating the display addition event. Example: event that a display is connected.<br>- **remove**, indicating the display removal event. Example: event that a display is disconnected.<br>- **change**, indicating the display change event. Example: event that the display orientation is changed.| 241| callback | Callback<number> | Yes| Callback used to return the ID of the display.| 242 243**Example** 244 245```js 246let callback = (data) => { 247 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 248}; 249try { 250 display.on("add", callback); 251} catch (exception) { 252 console.error('Failed to register callback. Code: ' + JSON.stringify(exception)); 253} 254``` 255 256## display.off('add'|'remove'|'change') 257 258off(type: 'add'|'remove'|'change', callback?: Callback<number>): void 259 260Unsubscribes from display changes. 261 262**System capability**: SystemCapability.WindowManager.WindowManager.Core 263 264**Parameters** 265 266| Name| Type| Mandatory| Description| 267| -------- | -------- | -------- | -------- | 268| type | string | Yes| Event type.<br>- **add**, indicating the display addition event. Example: event that a display is connected.<br>- **remove**, indicating the display removal event. Example: event that a display is disconnected.<br>- **change**, indicating the display change event. Example: event that the display orientation is changed.| 269| callback | Callback<number> | No| Callback used to return the ID of the display.| 270 271**Example** 272 273```js 274try { 275 display.off("remove"); 276} catch (exception) { 277 console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception)); 278} 279``` 280 281## display.getDefaultDisplay<sup>(deprecated)</sup> 282 283getDefaultDisplay(callback: AsyncCallback<Display>): void 284 285Obtains the default display object. This API uses an asynchronous callback to return the result. 286 287> **NOTE** 288> 289> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) instead. 290 291**System capability**: SystemCapability.WindowManager.WindowManager.Core 292 293**Parameters** 294 295| Name| Type| Mandatory| Description| 296| -------- | -------- | -------- | -------- | 297| callback | AsyncCallback<[Display](#display)> | Yes| Callback used to return the default display object.| 298 299**Example** 300 301```js 302let displayClass = null; 303display.getDefaultDisplay((err, data) => { 304 if (err.code) { 305 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(err)); 306 return; 307 } 308 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 309 displayClass = data; 310}); 311``` 312 313## display.getDefaultDisplay<sup>(deprecated)</sup> 314 315getDefaultDisplay(): Promise<Display> 316 317Obtains the default display object. This API uses a promise to return the result. 318 319> **NOTE** 320> 321> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) instead. 322 323**System capability**: SystemCapability.WindowManager.WindowManager.Core 324 325**Return value** 326 327| Type | Description | 328| ---------------------------------- | ---------------------------------------------- | 329| Promise<[Display](#display)> | Promise used to return the default display object.| 330 331**Example** 332 333```js 334let displayClass = null; 335let promise = display.getDefaultDisplay(); 336promise.then((data) => { 337 displayClass = data; 338 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 339}).catch((err) => { 340 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(err)); 341}); 342``` 343 344## display.getAllDisplay<sup>(deprecated)</sup> 345 346getAllDisplay(callback: AsyncCallback<Array<Display>>): void 347 348Obtains all display objects. This API uses an asynchronous callback to return the result. 349 350> **NOTE** 351> 352> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getAllDisplays()](#displaygetalldisplays9) instead. 353 354**System capability**: SystemCapability.WindowManager.WindowManager.Core 355 356**Parameters** 357 358| Name | Type | Mandatory| Description | 359| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 360| callback | AsyncCallback<Array<[Display](#display)>> | Yes | Callback used to return all the display objects.| 361 362**Example** 363 364```js 365display.getAllDisplay((err, data) => { 366 if (err.code) { 367 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 368 return; 369 } 370 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 371}); 372``` 373 374## display.getAllDisplay<sup>(deprecated)</sup> 375 376getAllDisplay(): Promise<Array<Display>> 377 378Obtains all display objects. This API uses a promise to return the result. 379 380> **NOTE** 381> 382> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getAllDisplays()](#displaygetalldisplays9-1) instead. 383 384**System capability**: SystemCapability.WindowManager.WindowManager.Core 385 386**Return value** 387 388| Type | Description | 389| ----------------------------------------------- | ------------------------------------------------------- | 390| Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| 391 392**Example** 393 394```js 395let promise = display.getAllDisplay(); 396promise.then((data) => { 397 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 398}).catch((err) => { 399 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 400}); 401``` 402 403## Display 404Implements a **Display** instance, with properties and APIs defined. 405 406Before calling any API in **Display**, you must use [getAllDisplays()](#displaygetalldisplays9) or [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) to obtain a **Display** instance. 407 408### Attributes 409 410**System capability**: SystemCapability.WindowManager.WindowManager.Core 411 412| Name| Type| Readable| Writable| Description| 413| -------- | -------- | -------- | -------- | -------- | 414| id | number | Yes| No| ID of the display.| 415| name | string | Yes| No| Name of the display.| 416| alive | boolean | Yes| No| Whether the display is alive.| 417| state | [DisplayState](#displaystate) | Yes| No| State of the display.| 418| refreshRate | number | Yes| No| Refresh rate of the display.| 419| rotation | number | Yes| No| Screen rotation angle of the display.<br>The value **0** indicates that the screen of the display rotates by 0°.<br>The value **1** indicates that the screen of the display rotates by 90°.<br>The value **2** indicates that the screen of the display rotates by 180°.<br>The value **3** indicates that the screen of the display rotates by 270°.| 420| width | number | Yes| No| Width of the display, in pixels.| 421| height | number | Yes| No| Height of the display, in pixels.| 422| densityDPI | number | Yes| No| Screen density of the display, that is, the number of dots per inch. Generally, the value is **160** or **480**.| 423| 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**.| 424| scaledDensity | number | Yes| No| Scaling factor for fonts displayed on the display. Generally, the value is the same as that of **densityPixels**.| 425| xDPI | number | Yes| No| Exact physical dots per inch of the screen in the horizontal direction.| 426| yDPI | number | Yes| No| Exact physical dots per inch of the screen in the vertical direction.| 427 428### getCutoutInfo<sup>9+</sup> 429getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void 430 431Obtains 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. 432 433**System capability**: SystemCapability.WindowManager.WindowManager.Core 434 435**Parameters** 436 437| Name | Type | Mandatory| Description | 438| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 439| callback | AsyncCallback<[CutoutInfo](#cutoutinfo9)> | Yes | Callback used to return the **CutoutInfo** object.| 440 441**Error codes** 442 443For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 444 445| ID| Error Message| 446| ------- | ----------------------- | 447| 1400001 | Invalid display or screen. | 448 449**Example** 450 451```js 452let displayClass = null; 453try { 454 displayClass = display.getDefaultDisplaySync(); 455 456 displayClass.getCutoutInfo((err, data) => { 457 if (err.code) { 458 console.error('Failed to get cutoutInfo. Code: ' + JSON.stringify(err)); 459 return; 460 } 461 console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data)); 462 }); 463} catch (exception) { 464 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 465} 466``` 467### getCutoutInfo<sup>9+</sup> 468getCutoutInfo(): Promise<CutoutInfo> 469 470Obtains 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. 471 472**System capability**: SystemCapability.WindowManager.WindowManager.Core 473 474**Return value** 475 476| Type | Description | 477| ------------------- | ------------------------- | 478| Promise<[CutoutInfo](#cutoutinfo9)> | Promise used to return the **CutoutInfo** object.| 479 480**Error codes** 481 482For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 483 484| ID| Error Message| 485| ------- | ----------------------- | 486| 1400001 | Invalid display or screen. | 487 488**Example** 489 490```js 491let displayClass = null; 492try { 493 displayClass = display.getDefaultDisplaySync(); 494 495 let promise = displayClass.getCutoutInfo(); 496 promise.then((data) => { 497 console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data)); 498 }).catch((err) => { 499 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 500 }); 501} catch (exception) { 502 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 503} 504``` 505