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