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 '@kit.ArkUI'; 13``` 14 15## DisplayState 16 17Enumerates the states of a display. 18 19**Atomic service API**: This API can be used in atomic services since API version 12. 20 21**System capability**: SystemCapability.WindowManager.WindowManager.Core 22 23| Name| Value| Description| 24| -------- | -------- | -------- | 25| STATE_UNKNOWN | 0 | Unknown.| 26| STATE_OFF | 1 | The display is shut down.| 27| STATE_ON | 2 | The display is powered on.| 28| STATE_DOZE | 3 | The display is in sleep mode.| 29| STATE_DOZE_SUSPEND | 4 | The display is in sleep mode, and the CPU is suspended.| 30| STATE_VR | 5 | The display is in VR mode.| 31| STATE_ON_SUSPEND | 6 | The display is powered on, and the CPU is suspended.| 32 33## Orientation<sup>10+</sup> 34 35Enumerates the orientations of a display. 36 37**Atomic service API**: This API can be used in atomic services since API version 12. 38 39**System capability**: SystemCapability.WindowManager.WindowManager.Core 40 41| Name| Value| Description| 42| -------- | -------- | -------- | 43| PORTRAIT | 0 | The display is in portrait mode.| 44| LANDSCAPE | 1 | The display is in landscape mode.| 45| PORTRAIT_INVERTED | 2 | The display is in reverse portrait mode.| 46| LANDSCAPE_INVERTED | 3 | The display is in reverse landscape mode.| 47 48## FoldStatus<sup>10+</sup> 49 50Enumerates the fold statuses of a foldable device. For dual-fold axis devices, when oriented with the charging port at the bottom, the hinges are identified from right to left as the first and second fold axes, respectively. 51 52**System capability**: SystemCapability.Window.SessionManager 53 54| Name| Value| Description| 55| -------- | -------- | -------- | 56| FOLD_STATUS_UNKNOWN<sup>10+</sup> | 0 | The fold status of the device is unknown.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 57| FOLD_STATUS_EXPANDED<sup>10+</sup> | 1 | The device is fully open. For dual-fold axis devices, the first fold axis is fully open, and the second fold axis is folded.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| FOLD_STATUS_FOLDED<sup>10+</sup> | 2 | The device is folded (completely closed). For dual-fold axis devices, the first fold axis is folded, and the second fold axis is folded.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 59| FOLD_STATUS_HALF_FOLDED<sup>10+</sup> | 3 | The device is half-folded, somehow between fully open and completely closed. For dual-fold axis devices, the first fold axis is half-folded, and the second fold axis is folded.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 60| FOLD_STATUS_EXPANDED_WITH_SECOND_EXPANDED<sup>15+</sup> | 11 | For dual-fold axis devices, the first fold axis is fully open, and the second fold axis is fully open.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 61| FOLD_STATUS_EXPANDED_WITH_SECOND_HALF_FOLDED<sup>15+</sup> | 21 | For dual-fold axis devices, the first fold axis is fully open, and the second fold axis is half-folded.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 62| FOLD_STATUS_FOLDED_WITH_SECOND_EXPANDED<sup>15+</sup> | 12 | For dual-fold axis devices, the first fold axis is folded, and the second fold axis is fully open.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 63| FOLD_STATUS_FOLDED_WITH_SECOND_HALF_FOLDED<sup>15+</sup> | 22 | For dual-fold axis devices, the first fold axis is folded, and the second fold axis is fully folded.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 64| FOLD_STATUS_HALF_FOLDED_WITH_SECOND_EXPANDED<sup>15+</sup> | 13 | For dual-fold axis devices, the first fold axis is half-folded, and the second fold axis is fully open.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 65| FOLD_STATUS_HALF_FOLDED_WITH_SECOND_HALF_FOLDED<sup>15+</sup> | 23 | For dual-fold axis devices, the first fold axis is half-folded, and the second fold axis is half-folded.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 66 67>**NOTE** 68 69> Devices with only one fold axis can be in the **FOLD_STATUS_EXPANDED**, **FOLD_STATUS_FOLDED**, or **FOLD_STATUS_HALF_FOLDED** state. 70 71> Devices with two fold axes can be in any of the states provided in the table above, except for **FOLD_STATUS_UNKNOWN**, which indicates an unusable fold status. 72 73## FoldDisplayMode<sup>10+</sup> 74 75Enumerates the display modes of a foldable device. 76 77**Atomic service API**: This API can be used in atomic services since API version 12. 78 79**System capability**: SystemCapability.Window.SessionManager 80 81| Name| Value| Description| 82| -------- | -------- | -------- | 83| FOLD_DISPLAY_MODE_UNKNOWN | 0 | The display mode of the device is unknown.| 84| FOLD_DISPLAY_MODE_FULL | 1 | The device is displayed in full screen.| 85| FOLD_DISPLAY_MODE_MAIN | 2 | The primary screen of the device is displayed.| 86| FOLD_DISPLAY_MODE_SUB | 3 | The secondary screen of the device is displayed.| 87| FOLD_DISPLAY_MODE_COORDINATION | 4 | Both screens of the device are displayed in collaborative mode.| 88 89>**NOTE** 90>For foldable devices where both the inner and outer screens can serve as the primary screen, the inner screen's display mode is **FOLD_DISPLAY_MODE_FULL**, and the outer screen's display mode is **FOLD_DISPLAY_MODE_MAIN**.<br> 91> 92>For foldable devices where the outer screen serves only as an auxiliary display, the inner screen's display mode is **FOLD_DISPLAY_MODE_MAIN**, and the outer screen's display mode is **FOLD_DISPLAY_MODE_SUB**. 93 94## FoldCreaseRegion<sup>10+</sup> 95 96Defines the crease region of a foldable device. 97 98**Atomic service API**: This API can be used in atomic services since API version 12. 99 100**System capability**: SystemCapability.Window.SessionManager 101 102| Name | Type| Readable| Writable| Description | 103| ------ | -------- | ---- | ---- | ------------------ | 104| displayId | number | Yes | No | ID of the display where the crease is located.| 105| creaseRects | Array\<[Rect](#rect9)> | Yes | No | Crease region.| 106 107## Rect<sup>9+</sup> 108 109Describes a rectangle on the display. 110 111**Atomic service API**: This API can be used in atomic services since API version 12. 112 113**System capability**: SystemCapability.WindowManager.WindowManager.Core 114 115| Name | Type| Readable| Writable| Description | 116| ------ | -------- | ---- | ---- | ------------------ | 117| left | number | Yes | Yes | Left boundary of the rectangle, in px. The value must be an integer.| 118| top | number | Yes | Yes | Top boundary of the rectangle, in px. The value must be an integer.| 119| width | number | Yes | Yes | Width of the rectangle, in px. The value must be an integer. | 120| height | number | Yes | Yes | Height of the rectangle, in px. The value must be an integer. | 121 122## WaterfallDisplayAreaRects<sup>9+</sup> 123 124Describes the curved area on a waterfall display. 125 126**Atomic service API**: This API can be used in atomic services since API version 12. 127 128**System capability**: SystemCapability.WindowManager.WindowManager.Core 129 130| Name | Type | Readable| Writable| Description | 131| ------ | ------------- | ---- | ---- | ------------------ | 132| left | [Rect](#rect9) | Yes | No | Rectangle of the curved area on the left of the waterfall display.| 133| top | [Rect](#rect9) | Yes | No | Rectangle of the curved area on the top of the waterfall display.| 134| right | [Rect](#rect9) | Yes | No | Rectangle of the curved area on the right of the waterfall display.| 135| bottom | [Rect](#rect9) | Yes | No | Rectangle of the curved area at the bottom of the waterfall display.| 136 137## CutoutInfo<sup>9+</sup> 138 139Describes the unusable area of a display, including punch hole, notch, and curved area of a waterfall display. 140 141**Atomic service API**: This API can be used in atomic services since API version 12. 142 143**System capability**: SystemCapability.WindowManager.WindowManager.Core 144 145| Name | Type | Readable| Writable| Description | 146| --------------------------- | ------------- | ---- | ---- | ------------------ | 147| boundingRects | Array\<[Rect](#rect9)> | Yes | No | Unusable areas (bounding rectangles) designed for punch holes and notches. If there are no punch holes or notches, an empty array is returned.| 148| waterfallDisplayAreaRects | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | Yes| No| Curved area on a waterfall display.| 149 150## DisplayPhysicalResolution<sup>12+</sup> 151Describes the display mode of a foldable device and the corresponding physical screen resolution information. 152 153**Atomic service API**: This API can be used in atomic services since API version 12. 154 155**System capability**: SystemCapability.WindowManager.WindowManager.Core 156 157| Name | Type | Read-Only| Optional| Description | 158| --------------------------- | ------------- | ---- | ---- | ------------------ | 159| foldDisplayMode | [FoldDisplayMode](#folddisplaymode10) | Yes | No | Display mode of the foldable device.| 160| physicalWidth | number | Yes| No| Width of the foldable device, in px. The value must be an integer greater than 0.| 161| physicalHeight | number | Yes| No| Height of the foldable device, in px. The value must be an integer greater than 0.| 162 163## display.getDisplayByIdSync<sup>12+</sup> 164 165getDisplayByIdSync(displayId: number): Display 166 167Obtains a **Display** object based on the display ID. 168 169**Atomic service API**: This API can be used in atomic services since API version 12. 170 171**System capability**: SystemCapability.WindowManager.WindowManager.Core 172 173**Parameters** 174 175| Name| Type | Mandatory| Description | 176| ------ | ------------------------- | ---- |----------| 177| displayId | number | Yes | Display ID. The value must be an integer greater than or equal to 0. An object can be obtained only when the passed-in display ID is correct. You can use the value of the **displayId** property in [WindowProperties](js-apis-window.md#windowproperties) as the input parameter.| 178 179**Return value** 180 181| Type | Description | 182| ------------------------------| ----------------------------------------------| 183| [Display](#display) | **Display** object.| 184 185**Error codes** 186 187For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 188 189| ID| Error Message| 190| ------- | ----------------------- | 191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types. 3. Parameter verification failed.| 192| 1400003 | This display manager service works abnormally. | 193 194**Example** 195 196```ts 197import { display } from '@kit.ArkUI'; 198 199let displayClass: display.Display | null = null; 200 201try { 202 // Use the value of the displayId property in WindowProperties as the input parameter. 203 let displayId = 0; 204 displayClass = display.getDisplayByIdSync(displayId); 205} catch (exception) { 206 console.error(`Failed to get display. Code: ${exception.code}, message: ${exception.message}`); 207} 208``` 209 210## display.getAllDisplayPhysicalResolution<sup>12+</sup> 211 212getAllDisplayPhysicalResolution(): Promise<Array<DisplayPhysicalResolution>> 213 214Obtains the display mode of the current foldable device and the corresponding physical screen resolution information. 215 216**Atomic service API**: This API can be used in atomic services since API version 12. 217 218**System capability**: SystemCapability.WindowManager.WindowManager.Core 219 220**Return value** 221 222| Type| Description| 223| ----------------------------------------------- | ------------------------------------------------------- | 224| Promise<Array<[DisplayPhysicalResolution](#displayphysicalresolution12)>> | Promise used to return all the **DisplayPhysicalResolution** objects.| 225 226**Error codes** 227 228For details about the error codes, see [Display Error Codes](errorcode-display.md). 229 230| ID| Error Message| 231| ------- | ----------------------- | 232| 1400003 | This display manager service works abnormally. | 233 234**Example** 235 236```ts 237import { BusinessError } from '@kit.BasicServicesKit'; 238import { display } from '@kit.ArkUI'; 239 240let promise = display.getAllDisplayPhysicalResolution(); 241promise.then((resolutionObjects) => { 242 console.info('Obtaining physical resolution length: ' + resolutionObjects.length); 243 for (let i = 0; i < resolutionObjects.length; i++) { 244 console.info(`resolutionObjects[${i}].foldDisplayMode: ${resolutionObjects[i].foldDisplayMode}`); 245 console.info(`resolutionObjects[${i}].physicalWidth: ${resolutionObjects[i].physicalWidth}`); 246 console.info(`resolutionObjects[${i}].physicalHeight: ${resolutionObjects[i].physicalHeight}`); 247 } 248}).catch((err: BusinessError) => { 249 console.error(`Failed to obtain physical resolution. Code: ${err.code}, message: ${err.message}`); 250}); 251``` 252 253## display.getDefaultDisplaySync<sup>9+</sup> 254 255getDefaultDisplaySync(): Display 256 257Obtains the default display object. This API returns the result synchronously. 258 259**System capability**: SystemCapability.WindowManager.WindowManager.Core 260 261**Atomic service API**: This API can be used in atomic services since API version 11. 262 263**Return value** 264 265| Type | Description | 266| ------------------------------| ----------------------------------------------| 267| [Display](#display) | Default display object.| 268 269**Error codes** 270 271For details about the error codes, see [Display Error Codes](errorcode-display.md). 272 273| ID| Error Message| 274| ------- | ----------------------- | 275| 1400001 | Invalid display or screen. | 276 277**Example** 278 279```ts 280import { display } from '@kit.ArkUI'; 281 282let displayClass: display.Display | null = null; 283 284displayClass = display.getDefaultDisplaySync(); 285``` 286 287## display.getPrimaryDisplaySync<sup>14+</sup> 288 289getPrimaryDisplaySync(): Display 290 291Obtains the information about the primary display. For devices other than 2-in-1 devices, the **Display** object obtained is the built-in screen. For 2-in-1 devices with an external screen, the **Display** object obtained is the primary screen. For 2-in-1 devices without an external screen, the Display object obtained is the built-in screen. 292 293**System capability**: SystemCapability.WindowManager.WindowManager.Core 294 295**Atomic service API**: This API can be used in atomic services since API version 14. 296 297**Return value** 298 299| Type | Description | 300| ------------------------------| ----------------------------------------------| 301| [Display](#display) | **Display** object of the primary screen.| 302 303**Error codes** 304 305For details about the error codes, see [Display Error Codes](errorcode-display.md). 306 307| ID| Error Message| 308| ------- | ----------------------- | 309| 1400001 | Invalid display or screen. | 310 311**Example** 312 313```ts 314import { display } from '@kit.ArkUI'; 315 316let displayClass: display.Display | null = null; 317 318displayClass = display.getPrimaryDisplaySync(); 319``` 320 321## display.getAllDisplays<sup>9+</sup> 322 323getAllDisplays(callback: AsyncCallback<Array<Display>>): void 324 325Obtains all display objects. This API uses an asynchronous callback to return the result. 326 327**Atomic service API**: This API can be used in atomic services since API version 12. 328 329**System capability**: SystemCapability.WindowManager.WindowManager.Core 330 331**Parameters** 332 333| Name| Type| Mandatory| Description| 334| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 335| callback | AsyncCallback<Array<[Display](#display)>> | Yes| Callback used to return all the display objects.| 336 337**Error codes** 338 339For details about the error codes, see [Display Error Codes](errorcode-display.md). 340 341| ID| Error Message| 342| ------- | ----------------------- | 343| 1400001 | Invalid display or screen. | 344 345**Example** 346 347```ts 348import { BusinessError } from '@kit.BasicServicesKit'; 349import { display } from '@kit.ArkUI'; 350 351let displayClass: Array<display.Display> = []; 352display.getAllDisplays((err: BusinessError, data: Array<display.Display>) => { 353 displayClass = data; 354 const errCode: number = err.code; 355 if (errCode) { 356 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 357 return; 358 } 359 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 360}); 361``` 362 363## display.getAllDisplays<sup>9+</sup> 364 365getAllDisplays(): Promise<Array<Display>> 366 367Obtains all display objects. This API uses a promise to return the result. 368 369**Atomic service API**: This API can be used in atomic services since API version 12. 370 371**System capability**: SystemCapability.WindowManager.WindowManager.Core 372 373**Return value** 374 375| Type| Description| 376| ----------------------------------------------- | ------------------------------------------------------- | 377| Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| 378 379**Error codes** 380 381For details about the error codes, see [Display Error Codes](errorcode-display.md). 382 383| ID| Error Message| 384| ------- | ----------------------- | 385| 1400001 | Invalid display or screen. | 386 387**Example** 388 389```ts 390import { BusinessError } from '@kit.BasicServicesKit'; 391import { display } from '@kit.ArkUI'; 392 393let displayClass: Array<display.Display> =[]; 394let promise: Promise<Array<display.Display>> = display.getAllDisplays(); 395promise.then((data: Array<display.Display>) => { 396 displayClass = data; 397 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 398}).catch((err: BusinessError) => { 399 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 400}); 401``` 402 403## display.on('add'|'remove'|'change') 404 405on(type: 'add'|'remove'|'change', callback: Callback<number>): void 406 407Subscribes to display changes. 408 409**Atomic service API**: This API can be used in atomic services since API version 12. 410 411**System capability**: SystemCapability.WindowManager.WindowManager.Core 412 413**Parameters** 414 415| Name| Type| Mandatory| Description | 416| -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------------------------| 417| 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.| 418| callback | Callback<number> | Yes| Callback used to return the ID of the display, which is an integer. | 419 420**Error codes** 421 422For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 423 424| ID| Error Message| 425| ------- | ----------------------- | 426| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 427 428**Example** 429 430```ts 431import { Callback } from '@kit.BasicServicesKit'; 432 433let callback: Callback<number> = (data: number) => { 434 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 435}; 436 437display.on("add", callback); 438``` 439 440## display.off('add'|'remove'|'change') 441 442off(type: 'add'|'remove'|'change', callback?: Callback<number>): void 443 444Unsubscribes from display changes. 445 446**Atomic service API**: This API can be used in atomic services since API version 12. 447 448**System capability**: SystemCapability.WindowManager.WindowManager.Core 449 450**Parameters** 451 452| Name| Type| Mandatory| Description| 453| -------- | -------- | -------- | -------- | 454| 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.| 455| callback | Callback<number> | No| Callback used for unsubscription. If this parameter is not specified, all subscriptions to the specified event are canceled.| 456 457**Error codes** 458 459For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 460 461| ID| Error Message| 462| ------- | ----------------------- | 463| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 464 465**Example** 466 467```ts 468 469// Unregister all the callbacks that have been registered through on(). 470display.off("remove"); 471 472let callback: Callback<number> = (data: number) => { 473 console.info('Succeeded in unregistering the callback for display remove. Data: ' + JSON.stringify(data)) 474}; 475// Unregister the specified callback. 476display.off('remove', callback); 477``` 478 479## display.isFoldable<sup>10+</sup> 480isFoldable(): boolean 481 482Checks whether the current device is foldable. 483 484**Atomic service API**: This API can be used in atomic services since API version 12. 485 486**System capability**: SystemCapability.Window.SessionManager 487 488**Return value** 489 490| Type| Description| 491| ----------------------------------------------- | ------------------------------------------------------- | 492| boolean | Returns **true** if the device is foldable, and returns **false** otherwise.| 493 494**Error codes** 495 496For details about the error codes, see [Display Error Codes](errorcode-display.md). 497 498| ID| Error Message| 499| ------- | ----------------------- | 500| 1400003 | This display manager service works abnormally. | 501 502**Example** 503 504```ts 505import { display } from '@kit.ArkUI'; 506 507let ret: boolean = false; 508ret = display.isFoldable(); 509``` 510 511## display.getFoldStatus<sup>10+</sup> 512getFoldStatus(): FoldStatus 513 514Obtains the fold status of the foldable device. 515 516**Atomic service API**: This API can be used in atomic services since API version 12. 517 518**System capability**: SystemCapability.Window.SessionManager 519 520**Return value** 521 522| Type| Description| 523| ----------------------------------------------- | ------------------------------------------------------- | 524| [FoldStatus](#foldstatus10) | Fold status of the device.| 525 526**Error codes** 527 528For details about the error codes, see [Display Error Codes](errorcode-display.md). 529 530| ID| Error Message| 531| ------- | ----------------------- | 532| 1400003 | This display manager service works abnormally. | 533 534**Example** 535 536```ts 537import { display } from '@kit.ArkUI'; 538 539let data: display.FoldStatus = display.getFoldStatus(); 540console.info('Succeeded in obtaining fold status. Data: ' + JSON.stringify(data)); 541``` 542 543## display.getFoldDisplayMode<sup>10+</sup> 544getFoldDisplayMode(): FoldDisplayMode 545 546Obtains the display mode of the foldable device. 547 548**Atomic service API**: This API can be used in atomic services since API version 12. 549 550**System capability**: SystemCapability.Window.SessionManager 551 552**Return value** 553 554| Type| Description| 555| ----------------------------------------------- | ------------------------------------------------------- | 556| [FoldDisplayMode](#folddisplaymode10) | Display mode of the device.| 557 558**Error codes** 559 560For details about the error codes, see [Display Error Codes](errorcode-display.md). 561 562| ID| Error Message| 563| ------- | ----------------------- | 564| 1400003 | This display manager service works abnormally. | 565 566**Example** 567 568```ts 569import { display } from '@kit.ArkUI'; 570 571let data: display.FoldDisplayMode = display.getFoldDisplayMode(); 572console.info('Succeeded in obtaining fold display mode. Data: ' + JSON.stringify(data)); 573``` 574 575## display.getCurrentFoldCreaseRegion<sup>10+</sup> 576getCurrentFoldCreaseRegion(): FoldCreaseRegion 577 578Obtains the crease region of the foldable device in the current display mode. 579 580**Atomic service API**: This API can be used in atomic services since API version 12. 581 582**System capability**: SystemCapability.Window.SessionManager 583 584**Return value** 585 586| Type| Description| 587| ----------------------------------------------- | ------------------------------------------------------- | 588| [FoldCreaseRegion](#foldcreaseregion10) | Crease region of the device.| 589 590**Error codes** 591 592For details about the error codes, see [Display Error Codes](errorcode-display.md). 593 594| ID| Error Message| 595| ------- | ----------------------- | 596| 1400003 | This display manager service works abnormally. | 597 598**Example** 599 600```ts 601import { display } from '@kit.ArkUI'; 602 603let data: display.FoldCreaseRegion = display.getCurrentFoldCreaseRegion(); 604console.info('Succeeded in obtaining current fold crease region. Data: ' + JSON.stringify(data)); 605``` 606 607## display.on('foldStatusChange')<sup>10+</sup> 608 609on(type: 'foldStatusChange', callback: Callback<FoldStatus>): void 610 611Subscribes to fold status change events of the foldable device. 612 613Note that [display.on('foldDisplayModeChange')](#displayonfolddisplaymodechange10) subscribes to display mode change events of the foldable device. 614 615The two are different. In terms of time sequence, the fold status changes first, and the bottom layer matches the display mode status based on the fold status. 616 617To check whether the content is displayed on the inner or outer screen of the foldable device, use [display.on('foldDisplayModeChange')](#displayonfolddisplaymodechange10). 618 619**Atomic service API**: This API can be used in atomic services since API version 12. 620 621**System capability**: SystemCapability.Window.SessionManager 622 623**Parameters** 624 625| Name | Type | Mandatory| Description | 626| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 627| type | string | Yes | Event type. The event **'foldStatusChange'** is triggered when the fold status of the device changes.| 628| callback | Callback<[FoldStatus](#foldstatus10)> | Yes | Callback used to return the fold status.| 629 630**Error codes** 631 632For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 633 634| ID| Error Message| 635| ------- | ----------------------- | 636| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 637| 1400003 | This display manager service works abnormally. | 638 639**Example** 640 641```ts 642import { Callback } from '@kit.BasicServicesKit'; 643 644/** 645 * The callback parameter used for subscription must be passed as an object. 646 * If an anonymous function is used for registration, a new underlying object is created each time the function is called, causing memory leakage. 647*/ 648let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 649 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 650}; 651display.on('foldStatusChange', callback); 652``` 653 654## display.off('foldStatusChange')<sup>10+</sup> 655 656off(type: 'foldStatusChange', callback?: Callback<FoldStatus>): void 657 658Unsubscribes from fold status change events of the foldable device. 659 660**Atomic service API**: This API can be used in atomic services since API version 12. 661 662**System capability**: SystemCapability.Window.SessionManager 663 664**Parameters** 665 666| Name | Type | Mandatory| Description | 667| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 668| type | string | Yes | Event type. The event **'foldStatusChange'** is triggered when the fold status of the device changes.| 669| callback | Callback<[FoldStatus](#foldstatus10)> | No | Callback used for unsubscription. If this parameter is not specified, all subscriptions to the specified event are canceled.| 670 671**Error codes** 672 673For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 674 675| ID| Error Message| 676| ------- | ----------------------- | 677| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 678| 1400003 | This display manager service works abnormally. | 679 680**Example** 681 682```ts 683 684// Unregister all the callbacks that have been registered through on(). 685display.off('foldStatusChange'); 686 687let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 688 console.info('unregistering FoldStatus changes callback. Data: ' + JSON.stringify(data)); 689}; 690// Unregister the specified callback. 691display.off('foldStatusChange', callback); 692``` 693 694## display.on('foldAngleChange')<sup>12+</sup> 695 696on(type: 'foldAngleChange', callback: Callback<Array<number>>): void 697 698Subscribes to folding angle change events of the foldable device. Note that there are two folding angles for dual-fold axis devices. When oriented with the charging port at the bottom, the hinges are identified from right to left as the first and second fold axes, respectively. 699 700**Atomic service API**: This API can be used in atomic services since API version 12. 701 702**System capability**: SystemCapability.Window.SessionManager 703 704**Parameters** 705 706| Name | Type | Mandatory| Description | 707| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 708| type | string | Yes| Event type. The event **'foldAngleChange'** is triggered when the folding angle of the device changes.| 709| callback | Callback<Array<number>> | Yes| Callback used to return the folding angle (0–180 degrees). For dual-fold axis devices, the array contains two angles. The first value represents the folding angle of the first fold axis, while the second value represents the folding angle of the second fold axis.| 710 711**Error codes** 712 713For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 714 715| ID| Error Message| 716| ------- | ----------------------- | 717| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 718| 1400003 | This display manager service works abnormally. | 719 720**Example** 721 722```ts 723import { Callback } from '@kit.BasicServicesKit'; 724 725let callback: Callback<Array<number>> = (angles: Array<number>) => { 726 console.info('Listening fold angles length: ' + angles.length); 727}; 728display.on('foldAngleChange', callback); 729``` 730 731## display.off('foldAngleChange')<sup>12+</sup> 732 733off(type: 'foldAngleChange', callback?: Callback<Array<number>>): void 734 735Unsubscribes from folding angle change events of the foldable device. 736 737**Atomic service API**: This API can be used in atomic services since API version 12. 738 739**System capability**: SystemCapability.Window.SessionManager 740 741**Parameters** 742 743| Name | Type | Mandatory| Description | 744| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 745| type | string | Yes | Event type. The event **'foldAngleChange'** is triggered when the folding angle of the device changes.| 746| callback | Callback<Array<number>> | No | Callback used for unsubscription. If this parameter is not specified, all subscriptions to the specified event are canceled.| 747 748**Error codes** 749 750For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 751 752| ID| Error Message| 753| ------- | ----------------------- | 754| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 755| 1400003 | This display manager service works abnormally. | 756 757**Example** 758 759```ts 760display.off('foldAngleChange'); 761``` 762 763## display.on('captureStatusChange')<sup>12+</sup> 764 765on(type: 'captureStatusChange', callback: Callback<boolean>): void 766 767Subscribes to screen capture, casting, or recording status changes. 768 769**Atomic service API**: This API can be used in atomic services since API version 12. 770 771**System capability**: SystemCapability.Window.SessionManager 772 773**Parameters** 774 775| Name | Type | Mandatory| Description | 776| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 777| type | string | Yes| Event type. The event **'captureStatusChange'** is triggered when the screen capture, casting, or recording status changes.| 778| callback | Callback<boolean> | Yes| Callback used to return the screen capture, casting, or recording status change. The value **true** means that the device starts screen capture, casting, or recording, and **false** means that the device stops screen capture, casting, or recording.| 779 780**Error codes** 781 782For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 783 784| ID| Error Message| 785| ------- | ----------------------- | 786| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 787| 1400003 | This display manager service works abnormally. | 788 789**Example** 790 791```ts 792import { Callback } from '@kit.BasicServicesKit'; 793 794let callback: Callback<boolean> = (captureStatus: boolean) => { 795 console.info('Listening capture status: ' + captureStatus); 796}; 797display.on('captureStatusChange', callback); 798``` 799 800## display.off('captureStatusChange')<sup>12+</sup> 801 802off(type: 'captureStatusChange', callback?: Callback<boolean>): void 803 804Unsubscribes from screen capture, casting, or recording status changes. 805 806**Atomic service API**: This API can be used in atomic services since API version 12. 807 808**System capability**: SystemCapability.Window.SessionManager 809 810**Parameters** 811 812| Name | Type | Mandatory| Description | 813| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 814| type | string | Yes| Event type. The event **'captureStatusChange'** is triggered when the screen capture, casting, or recording status changes.| 815| callback | Callback<boolean> | No| Callback used for unsubscription. If this parameter is not specified, all subscriptions to the specified event are canceled.| 816 817**Error codes** 818 819For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 820 821| ID| Error Message| 822| ------- | ----------------------- | 823| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 824| 1400003 | This display manager service works abnormally. | 825 826**Example** 827 828```ts 829display.off('captureStatusChange'); 830``` 831 832## display.isCaptured<sup>12+</sup> 833isCaptured(): boolean 834 835Checks whether the display is being captured, projected, or recorded. 836 837**Atomic service API**: This API can be used in atomic services since API version 12. 838 839**System capability**: SystemCapability.Window.SessionManager 840 841**Return value** 842 843| Type| Description| 844| ----------------------------------------------- | ------------------------------------------------------- | 845| boolean | **true**: The display is being captured, projected, or recorded.<br> **false**: The display is not being captured, projected, or recorded.| 846 847**Error codes** 848 849For details about the error codes, see [Display Error Codes](errorcode-display.md). 850 851| ID| Error Message| 852| ------- | ----------------------- | 853| 1400003 | This display manager service works abnormally. | 854 855**Example** 856 857```ts 858import { display } from '@kit.ArkUI'; 859 860let ret: boolean = false; 861ret = display.isCaptured(); 862``` 863 864## display.on('foldDisplayModeChange')<sup>10+</sup> 865 866on(type: 'foldDisplayModeChange', callback: Callback<FoldDisplayMode>): void 867 868Subscribes to display mode change events of the foldable device. 869 870Subscribes to display mode change events of the foldable device. Note that [display.on('foldStatusChange')](#displayonfoldstatuschange10) subscribes to fold status change events of the foldable device. 871 872The two are different. In terms of time sequence, the fold status changes first, and the bottom layer matches the display mode status based on the fold status. 873 874**Atomic service API**: This API can be used in atomic services since API version 12. 875 876**System capability**: SystemCapability.Window.SessionManager 877 878**Parameters** 879 880| Name | Type | Mandatory| Description | 881| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 882| type | string | Yes | Event type. The event **'foldDisplayModeChange'** is triggered when the display mode of the device changes.| 883| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | Yes | Callback used to return the display mode.| 884 885**Error codes** 886 887For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 888 889| ID| Error Message| 890| ------- | ----------------------- | 891| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 892| 1400003 | This display manager service works abnormally. | 893 894**Example** 895 896```ts 897import { Callback } from '@kit.BasicServicesKit'; 898 899/** 900 * The callback parameter used for subscription must be passed as an object. 901 * If an anonymous function is used for registration, a new underlying object is created each time the function is called, causing memory leakage. 902*/ 903let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 904 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 905}; 906display.on('foldDisplayModeChange', callback); 907``` 908 909## display.off('foldDisplayModeChange')<sup>10+</sup> 910 911off(type: 'foldDisplayModeChange', callback?: Callback<FoldDisplayMode>): void 912 913Unsubscribes from display mode change events of the foldable device. 914 915**Atomic service API**: This API can be used in atomic services since API version 12. 916 917**System capability**: SystemCapability.Window.SessionManager 918 919**Parameters** 920 921| Name | Type | Mandatory| Description | 922| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 923| type | string | Yes | Event type. The event **'foldDisplayModeChange'** is triggered when the display mode of the device changes.| 924| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | No | Callback used for unsubscription. If this parameter is not specified, all subscriptions to the specified event are canceled.| 925 926**Error codes** 927 928For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 929 930| ID| Error Message| 931| ------- | ----------------------- | 932| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 933| 1400003 | This display manager service works abnormally. | 934 935**Example** 936 937```ts 938 939// Unregister all the callbacks that have been registered through on(). 940display.off('foldDisplayModeChange'); 941 942let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 943 console.info('unregistering FoldDisplayMode changes callback. Data: ' + JSON.stringify(data)); 944}; 945// Unregister the specified callback. 946display.off('foldDisplayModeChange', callback); 947``` 948 949 950## display.getDefaultDisplay<sup>(deprecated)</sup> 951 952getDefaultDisplay(callback: AsyncCallback<Display>): void 953 954Obtains the default display object. This API uses an asynchronous callback to return the result. 955 956> **NOTE** 957> 958> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) instead. 959 960**System capability**: SystemCapability.WindowManager.WindowManager.Core 961 962**Parameters** 963 964| Name| Type| Mandatory| Description| 965| -------- | -------- | -------- | -------- | 966| callback | AsyncCallback<[Display](#display)> | Yes| Callback used to return the default display object.| 967 968**Example** 969 970```ts 971import { BusinessError } from '@kit.BasicServicesKit'; 972 973let displayClass: display.Display | null = null; 974display.getDefaultDisplay((err: BusinessError, data: display.Display) => { 975 const errCode: number = err.code; 976 if (errCode) { 977 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 978 return; 979 } 980 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 981 displayClass = data; 982}); 983``` 984 985## display.getDefaultDisplay<sup>(deprecated)</sup> 986 987getDefaultDisplay(): Promise<Display> 988 989Obtains the default display object. This API uses a promise to return the result. 990 991> **NOTE** 992> 993> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) instead. 994 995**System capability**: SystemCapability.WindowManager.WindowManager.Core 996 997**Return value** 998 999| Type | Description | 1000| ---------------------------------- | ---------------------------------------------- | 1001| Promise<[Display](#display)> | Promise used to return the default display object.| 1002 1003**Example** 1004 1005```ts 1006import { BusinessError } from '@kit.BasicServicesKit'; 1007 1008let displayClass: display.Display | null = null; 1009let promise: Promise<display.Display> = display.getDefaultDisplay(); 1010promise.then((data: display.Display) => { 1011 displayClass = data; 1012 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 1013}).catch((err: BusinessError) => { 1014 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 1015}); 1016``` 1017 1018## display.getAllDisplay<sup>(deprecated)</sup> 1019 1020getAllDisplay(callback: AsyncCallback<Array<Display>>): void 1021 1022Obtains all display objects. This API uses an asynchronous callback to return the result. 1023 1024> **NOTE** 1025> 1026> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getAllDisplays()](#displaygetalldisplays9) instead. 1027 1028**System capability**: SystemCapability.WindowManager.WindowManager.Core 1029 1030**Parameters** 1031 1032| Name | Type | Mandatory| Description | 1033| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 1034| callback | AsyncCallback<Array<[Display](#display)>> | Yes | Callback used to return all the display objects.| 1035 1036**Example** 1037 1038```ts 1039import { BusinessError } from '@kit.BasicServicesKit'; 1040 1041display.getAllDisplay((err: BusinessError, data: Array<display.Display>) => { 1042 const errCode: number = err.code; 1043 if (errCode) { 1044 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1045 return; 1046 } 1047 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1048}); 1049``` 1050 1051## display.getAllDisplay<sup>(deprecated)</sup> 1052 1053getAllDisplay(): Promise<Array<Display>> 1054 1055Obtains all display objects. This API uses a promise to return the result. 1056 1057> **NOTE** 1058> 1059> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getAllDisplays()](#displaygetalldisplays9-1) instead. 1060 1061**System capability**: SystemCapability.WindowManager.WindowManager.Core 1062 1063**Return value** 1064 1065| Type | Description | 1066| ----------------------------------------------- | ------------------------------------------------------- | 1067| Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| 1068 1069**Example** 1070 1071```ts 1072import { BusinessError } from '@kit.BasicServicesKit'; 1073 1074let promise: Promise<Array<display.Display>> = display.getAllDisplay(); 1075promise.then((data: Array<display.Display>) => { 1076 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1077}).catch((err: BusinessError) => { 1078 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1079}); 1080``` 1081 1082## Display 1083Implements a **Display** instance, with properties and APIs defined. 1084 1085Before calling any API in **Display**, you must use [getAllDisplays()](#displaygetalldisplays9) or [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) to obtain a **Display** instance. 1086 1087### Properties 1088 1089**System capability**: SystemCapability.WindowManager.WindowManager.Core 1090 1091| Name| Type| Read-Only| Optional| Description | 1092| -------- | -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------| 1093| id | number | Yes| No| ID of the display. The value must be an integer.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1094| name | string | Yes| No| Name of the display.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1095| alive | boolean | Yes| No| Whether the display is alive.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1096| state | [DisplayState](#displaystate) | Yes| No| State of the display.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1097| refreshRate | number | Yes| No| Refresh rate of the display, in hz. The value must be an integer.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1098| rotation | number | Yes| No| Clockwise rotation angle of the display.<br>The value **0** indicates that the display rotates clockwise by 0°.<br>The value **1** indicates that the display rotates clockwise by 90°.<br>The value **2** indicates that the display rotates clockwise by 180°.<br>The value **3** indicates that the display rotates clockwise by 270°.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1099| width | number | Yes| No| Width of the display, in px. The value must be an integer.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 1100| height | number | Yes| No| Height of the display, in px. The value must be an integer.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 1101| densityDPI | number | Yes| No| Physical pixel density of the display, that is, the number of pixels per inch. The value is a floating point number, in px. Generally, the value is **160.0** or **480.0**. The actual value depends on the optional values provided by the device in use.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1102| orientation<sup>10+</sup> | [Orientation](#orientation10) | Yes| No| Orientation of the display.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1103| densityPixels | number | Yes| No| Logical pixel density of the display, which is the scaling coefficient between physical pixels and logical pixels. The calculation method is as follows:<br><br>The value is a floating point number and is restricted by the range of **densityDPI**. The value range is [0.5, 4.0]. Generally, the value is **1.0** or **3.0**. The actual value depends on the density DPI provided by the device in use.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 1104| 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**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1105| xDPI | number | Yes| No| Exact physical pixels per inch of the display in the X dimension. The value must be a floating point number.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1106| yDPI | number | Yes| No| Exact physical pixels per inch of the display in the Y dimension. The value must be a floating point number.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1107| colorSpaces<sup>11+</sup> | Array<[colorSpaceManager.ColorSpace](../apis-arkgraphics2d/js-apis-colorSpaceManager.md)> | Yes| No| All color spaces supported by the display.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1108| hdrFormats<sup>11+</sup> | Array<[hdrCapability.HDRFormat](../apis-arkgraphics2d/js-apis-hdrCapability.md)> | Yes| No| All HDR formats supported by the display.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1109| availableWidth<sup>12+</sup> | number | Yes| No| Width of the available area on a 2-in-1 device, in px. The value is an integer greater than 0.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1110| availableHeight<sup>12+</sup> | number | Yes| No| Height of the available area on a 2-in-1 device, in px. The value is an integer greater than 0.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1111 1112### getCutoutInfo<sup>9+</sup> 1113getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void 1114 1115Obtains 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. 1116 1117**Atomic service API**: This API can be used in atomic services since API version 12. 1118 1119**System capability**: SystemCapability.WindowManager.WindowManager.Core 1120 1121**Parameters** 1122 1123| Name | Type | Mandatory| Description | 1124| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1125| callback | AsyncCallback<[CutoutInfo](#cutoutinfo9)> | Yes | Callback used to return the **CutoutInfo** object.| 1126 1127**Error codes** 1128 1129For details about the error codes, see [Display Error Codes](errorcode-display.md). 1130 1131| ID| Error Message| 1132| ------- | ----------------------- | 1133| 1400001 | Invalid display or screen. | 1134 1135**Example** 1136 1137```ts 1138import { BusinessError } from '@kit.BasicServicesKit'; 1139 1140let displayClass: display.Display | null = null; 1141displayClass = display.getDefaultDisplaySync(); 1142 1143displayClass.getCutoutInfo((err: BusinessError, data: display.CutoutInfo) => { 1144 const errCode: number = err.code; 1145 if (errCode) { 1146 console.error(`Failed to get cutoutInfo. Code: ${err.code}, message: ${err.message}`); 1147 return; 1148 } 1149 console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data)); 1150}); 1151``` 1152### getCutoutInfo<sup>9+</sup> 1153getCutoutInfo(): Promise<CutoutInfo> 1154 1155Obtains 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. 1156 1157**Atomic service API**: This API can be used in atomic services since API version 12. 1158 1159**System capability**: SystemCapability.WindowManager.WindowManager.Core 1160 1161**Return value** 1162 1163| Type | Description | 1164| ------------------- | ------------------------- | 1165| Promise<[CutoutInfo](#cutoutinfo9)> | Promise used to return the **CutoutInfo** object.| 1166 1167**Error codes** 1168 1169For details about the error codes, see [Display Error Codes](errorcode-display.md). 1170 1171| ID| Error Message| 1172| ------- | ----------------------- | 1173| 1400001 | Invalid display or screen. | 1174 1175**Example** 1176 1177```ts 1178import { BusinessError } from '@kit.BasicServicesKit'; 1179 1180let displayClass: display.Display | null = null; 1181displayClass = display.getDefaultDisplaySync(); 1182let promise: Promise<display.CutoutInfo> = displayClass.getCutoutInfo(); 1183promise.then((data: display.CutoutInfo) => { 1184 console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data)); 1185}).catch((err: BusinessError) => { 1186 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1187}); 1188``` 1189 1190### getAvailableArea<sup>12+</sup> 1191getAvailableArea(): Promise<Rect> 1192 1193Obtains the available area of the display of the current device. This API uses a promise to return the result. 1194 1195**Atomic service API**: This API can be used in atomic services since API version 12. 1196 1197**System capability**: SystemCapability.Window.SessionManager 1198 1199**Return value** 1200 1201| Type | Description | 1202| ------------------- | ------------------------- | 1203| Promise<[Rect](#rect9)> | Promise used to return the available area, which is a rectangle.| 1204 1205**Error codes** 1206 1207For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1208 1209| ID| Error Message| 1210| ------- | ----------------------- | 1211| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1212| 1400001 | Invalid display or screen. | 1213 1214**Example** 1215 1216```ts 1217import { BusinessError } from '@kit.BasicServicesKit'; 1218import { display } from '@kit.ArkUI'; 1219 1220let displayClass: display.Display | null = null; 1221try { 1222 displayClass = display.getDefaultDisplaySync(); 1223 let promise = displayClass.getAvailableArea(); 1224 promise.then((data) => { 1225 console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(data)); 1226 }).catch((err: BusinessError) => { 1227 console.error(`Failed to get the available area in this display. Code: ${err.code}, message: ${err.message}`); 1228 }) 1229} catch (exception) { 1230 console.error(`Failed to obtain the default display object. Code: ${exception.code}, message: ${exception.message}`); 1231} 1232``` 1233 1234### on('availableAreaChange')<sup>12+</sup> 1235on(type: 'availableAreaChange', callback: Callback<Rect>): void 1236 1237Subscribes to changes of the available area on the display of the current device. This API uses an asynchronous callback to return the result. 1238 1239**Atomic service API**: This API can be used in atomic services since API version 12. 1240 1241**System capability**: SystemCapability.Window.SessionManager 1242 1243**Parameters** 1244 1245| Name | Type | Mandatory| Description | 1246| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1247| type | string | Yes | Event type. The event **'availableAreaChange'** is triggered when the available area of the display changes.| 1248| callback | Callback<[Rect](#rect9)> | Yes | Callback used to return the new available area.| 1249 1250**Error codes** 1251 1252For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1253 1254| ID| Error Message| 1255| ------- | ----------------------- | 1256| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1257| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1258| 1400003 | This display manager service works abnormally. | 1259 1260**Example** 1261 1262```ts 1263import { Callback } from '@kit.BasicServicesKit'; 1264import { display } from '@kit.ArkUI'; 1265 1266let callback: Callback<display.Rect> = (data: display.Rect) => { 1267 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1268}; 1269let displayClass: display.Display | null = null; 1270try { 1271 displayClass = display.getDefaultDisplaySync(); 1272 displayClass.on("availableAreaChange", callback); 1273} catch (exception) { 1274 console.error(`Failed to register callback. Code: ${exception.code}, message: ${exception.message}`); 1275} 1276``` 1277 1278### off('availableAreaChange')<sup>12+</sup> 1279 1280off(type: 'availableAreaChange', callback?: Callback<Rect>): void 1281 1282Unsubscribes from changes of the available area on the display of the current device. 1283 1284**Atomic service API**: This API can be used in atomic services since API version 12. 1285 1286**System capability**: SystemCapability.Window.SessionManager 1287 1288**Parameters** 1289 1290| Name | Type | Mandatory| Description | 1291| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1292| type | string | Yes | Event type. The event **'availableAreaChange'** is triggered when the available area of the display changes.| 1293| callback | Callback<[Rect](#rect9)> | No | Callback used for unsubscription. If no value is passed in, all subscriptions to the specified event are canceled.| 1294 1295**Error codes** 1296 1297For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1298 1299| ID| Error Message| 1300| ------- | ----------------------- | 1301| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1302| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1303| 1400003 | This display manager service works abnormally. | 1304 1305**Example** 1306 1307```ts 1308import { Callback } from '@kit.BasicServicesKit'; 1309import { display } from '@kit.ArkUI'; 1310 1311let callback: Callback<display.Rect> = (data: display.Rect) => { 1312 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1313}; 1314let displayClass: display.Display | null = null; 1315try { 1316 displayClass = display.getDefaultDisplaySync(); 1317 displayClass.off("availableAreaChange", callback); 1318} catch (exception) { 1319 console.error(`Failed to unregister callback. Code: ${exception.code}, message: ${exception.message}`); 1320} 1321``` 1322
