1# @ohos.display (Display) 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @oh_wangxk; @logn--> 5<!--Designer: @hejunfei1991--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9The 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. 10 11> **NOTE** 12> 13> 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. 14 15## Modules to Import 16 17```ts 18import { display } from '@kit.ArkUI'; 19``` 20 21## DisplayState 22 23Enumerates the states of a display. 24 25**Atomic service API**: This API can be used in atomic services since API version 12. 26 27**System capability**: SystemCapability.WindowManager.WindowManager.Core 28 29| Name| Value| Description| 30| -------- | -------- | -------- | 31| STATE_UNKNOWN | 0 | Unknown.| 32| STATE_OFF | 1 | The display is shut down.| 33| STATE_ON | 2 | The display is powered on.| 34| STATE_DOZE | 3 | The display is in sleep mode.| 35| STATE_DOZE_SUSPEND | 4 | The display is in sleep mode, and the CPU is suspended.| 36| STATE_VR | 5 | The display is in VR mode.| 37| STATE_ON_SUSPEND | 6 | The display is powered on, and the CPU is suspended.| 38 39## Orientation<sup>10+</sup> 40 41Enumerates the orientations of a display. 42 43**Atomic service API**: This API can be used in atomic services since API version 12. 44 45**System capability**: SystemCapability.WindowManager.WindowManager.Core 46 47| Name| Value| Description| 48| -------- | -------- | -------- | 49| PORTRAIT | 0 | The display is in portrait mode.| 50| LANDSCAPE | 1 | The display is in landscape mode.| 51| PORTRAIT_INVERTED | 2 | The display is in reverse portrait mode.| 52| LANDSCAPE_INVERTED | 3 | The display is in reverse landscape mode.| 53 54## DisplaySourceMode<sup>19+</sup> 55 56Enumerates the display modes for screen content. 57 58**Atomic service API**: This API can be used in atomic services since API version 19. 59 60**System capability**: SystemCapability.Window.SessionManager 61 62| Name| Value| Description| 63| -------- | -------- | -------- | 64| NONE | 0 | The device is currently not in use.| 65| MAIN | 1 | The primary screen of the device is currently in use.| 66| MIRROR | 2 | The device is currently in mirror display mode.| 67| EXTEND | 3 | The device is currently in extended display mode.| 68| ALONE | 4 | The device is currently in independent display mode.| 69 70## FoldStatus<sup>10+</sup> 71 72Enumerates 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. 73 74**System capability**: SystemCapability.Window.SessionManager 75 76| Name| Value| Description| 77| -------- | -------- | -------- | 78| FOLD_STATUS_UNKNOWN | 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.| 79| FOLD_STATUS_EXPANDED | 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.| 80| FOLD_STATUS_FOLDED | 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.| 81| FOLD_STATUS_HALF_FOLDED | 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.| 82| 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.| 83| 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.| 84| 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.| 85| 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.| 86| 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.| 87| 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.| 88 89>**NOTE** 90 91> Devices with only one fold axis can be in the **FOLD_STATUS_EXPANDED**, **FOLD_STATUS_FOLDED**, or **FOLD_STATUS_HALF_FOLDED** state. 92 93> 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. 94 95## FoldDisplayMode<sup>10+</sup> 96 97Enumerates the display modes of a foldable device. 98 99**Atomic service API**: This API can be used in atomic services since API version 12. 100 101**System capability**: SystemCapability.Window.SessionManager 102 103| Name| Value| Description| 104| -------- | -------- | -------- | 105| FOLD_DISPLAY_MODE_UNKNOWN | 0 | The display mode of the device is unknown.| 106| FOLD_DISPLAY_MODE_FULL | 1 | The device is displayed in full screen.| 107| FOLD_DISPLAY_MODE_MAIN | 2 | The primary screen of the device is displayed.| 108| FOLD_DISPLAY_MODE_SUB | 3 | The secondary screen of the device is displayed.| 109| FOLD_DISPLAY_MODE_COORDINATION | 4 | Both screens of the device are displayed in collaborative mode.| 110 111>**NOTE** 112>For foldable devices where both the inner and outer screens can serve as the primary screen — like large or wide-folding models — the inner screen's display mode is **FOLD_DISPLAY_MODE_FULL**, and the outer screen's display mode is **FOLD_DISPLAY_MODE_MAIN**.<br> 113> 114>For foldable devices where the outer screen serves only as an auxiliary display — like small-folding models — the inner screen's display mode is **FOLD_DISPLAY_MODE_MAIN**, and the outer screen's display mode is **FOLD_DISPLAY_MODE_SUB**. 115 116## FoldCreaseRegion<sup>10+</sup> 117 118Describes the crease region of a foldable device. 119 120**Atomic service API**: This API can be used in atomic services since API version 12. 121 122**System capability**: SystemCapability.Window.SessionManager 123 124| Name | Type| Read-Only| Optional| Description | 125| ------ | -------- | ---- | ---- | ------------------ | 126| displayId | number | Yes | No | ID of the display where the crease is located.| 127| creaseRects | Array\<[Rect](#rect9)> | Yes | No | Crease region.| 128 129## Rect<sup>9+</sup> 130 131Describes a rectangle on the display. 132 133**Atomic service API**: This API can be used in atomic services since API version 12. 134 135**System capability**: SystemCapability.WindowManager.WindowManager.Core 136 137| Name | Type| Read-Only| Optional| Description | 138| ------ | -------- | ---- | ---- | ------------------ | 139| left | number | No | No | Left boundary of the rectangle, in px. The value is an integer.| 140| top | number | No | No | Top boundary of the rectangle, in px. The value is an integer.| 141| width | number | No | No | Width of the rectangle, in px. The value is an integer. | 142| height | number | No | No | Height of the rectangle, in px. The value is an integer. | 143 144## WaterfallDisplayAreaRects<sup>9+</sup> 145 146Describes the curved area on a waterfall display. 147 148**Atomic service API**: This API can be used in atomic services since API version 12. 149 150**System capability**: SystemCapability.WindowManager.WindowManager.Core 151 152| Name | Type | Read-Only| Optional| Description | 153| ------ | ------------- | ---- | ---- | ------------------ | 154| left | [Rect](#rect9) | Yes | No | Rectangle of the curved area on the left of the waterfall display.| 155| top | [Rect](#rect9) | Yes | No | Rectangle of the curved area on the top of the waterfall display.| 156| right | [Rect](#rect9) | Yes | No | Rectangle of the curved area on the right of the waterfall display.| 157| bottom | [Rect](#rect9) | Yes | No | Rectangle of the curved area at the bottom of the waterfall display.| 158 159## CutoutInfo<sup>9+</sup> 160 161Describes the unusable area of a display, including punch hole, notch, and curved area of a waterfall display. 162 163**Atomic service API**: This API can be used in atomic services since API version 12. 164 165**System capability**: SystemCapability.WindowManager.WindowManager.Core 166 167| Name | Type | Read-Only| Optional| Description | 168| --------------------------- | ------------- | ---- | ---- | ------------------ | 169| 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.| 170| waterfallDisplayAreaRects | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | Yes| No| Curved area on a waterfall display.| 171 172## DisplayPhysicalResolution<sup>12+</sup> 173Describes the display mode of a device and the corresponding physical screen resolution information. 174 175**Atomic service API**: This API can be used in atomic services since API version 12. 176 177**System capability**: SystemCapability.WindowManager.WindowManager.Core 178 179| Name | Type | Read-Only| Optional| Description | 180| --------------------------- | ------------- | ---- | ---- | ------------------ | 181| foldDisplayMode | [FoldDisplayMode](#folddisplaymode10) | Yes | No | Display mode of the device. The value is **0** for non-foldable devices.| 182| physicalWidth | number | Yes| No| Width of the device, in px. The value is an integer greater than 0.| 183| physicalHeight | number | Yes| No| Height of the device, in px. The value is an integer greater than 0.| 184 185## ScreenShape<sup>18+</sup> 186 187Enumerates the screen shapes of a display. 188 189**System capability**: SystemCapability.WindowManager.WindowManager.Core 190 191| Name| Value| Description| 192| -------- | -------- | -------- | 193| RECTANGLE | 0 | The screen is in the shape of a rectangle.| 194| ROUND | 1 | The screen is in the shape of a circle.| 195 196## VirtualScreenConfig<sup>16+</sup> 197 198Describes the virtual screen parameters. 199 200**System capability**: SystemCapability.Window.SessionManager 201 202| Name | Type| Read-Only| Optional| Description | 203| --------- | -------- | ---- | ---- |--------------------------| 204| name | string | No | No | Name of the virtual screen, which can be customized. | 205| width | number | No | No | Width of the virtual screen, in px. The value must be a positive integer.| 206| height | number | No | No | Height of the virtual screen, in px. The value must be a positive integer.| 207| density | number | No | No | Density of the virtual screen, in px. The value is a floating-point number.| 208| surfaceId | string | No | No | Surface ID of the virtual screen, which can be customized. The maximum length for this parameter is 4096 bytes. If it goes beyond that, only the first 4096 bytes are used. | 209 210## Position<sup>20+</sup> 211 212Describes a coordinate position. In the global coordinate system, the origin is the upper-left corner of the primary screen. In the relative coordinate system, the origin is the upper-left corner of the specified screen. 213 214**System capability**: SystemCapability.Window.SessionManager 215 216| Name | Type| Read-Only| Optional| Description | 217| --------- | -------- | ---- | ---- |--------------------------| 218| x | number | No | No | X coordinate relative to the origin, measured in px. The value must be a 32-bit signed integer, and floating-point numbers are rounded down.| 219| y | number | No | No | Y coordinate relative to the origin, measured in px. The value must be a 32-bit signed integer, and floating-point numbers are rounded down.| 220 221## RelativePosition<sup>20+</sup> 222 223Describes a coordinate position in the relative coordinate system, with the origin in the upper-left corner of the screen specified by **displayId**. 224 225**System capability**: SystemCapability.Window.SessionManager 226 227| Name | Type| Read-Only| Optional| Description | 228| --------- | -------- | ---- | ---- |--------------------------| 229| displayId | number | No | No | Display ID for the relative coordinates. Only integers are supported, and the value must be greater than or equal to 0.| 230| position | [Position](#position20) | No | No | Coordinates with the upper-left corner of the screen specified by **displayId** as the origin.| 231 232## display.getDisplayByIdSync<sup>12+</sup> 233 234getDisplayByIdSync(displayId: number): Display 235 236Obtains a Display object based on the display ID. 237 238**Atomic service API**: This API can be used in atomic services since API version 12. 239 240**System capability**: SystemCapability.WindowManager.WindowManager.Core 241 242**Parameters** 243 244| Name| Type | Mandatory| Description | 245| ------ | ------------------------- | ---- |----------| 246| 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](arkts-apis-window-i.md#windowproperties) as the input parameter.| 247 248**Return value** 249 250| Type | Description | 251| ------------------------------| ----------------------------------------------| 252| [Display](#display) | Display object.| 253 254**Error codes** 255 256For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 257 258| ID| Error Message| 259| ------- | ----------------------- | 260| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types. 3. Parameter verification failed.| 261| 1400003 | This display manager service works abnormally. | 262 263**Example** 264 265```ts 266import { display } from '@kit.ArkUI'; 267 268let displayClass: display.Display | null = null; 269 270try { 271 // Use the value of the displayId property in WindowProperties as the input parameter. 272 let displayId = 0; 273 displayClass = display.getDisplayByIdSync(displayId); 274} catch (exception) { 275 console.error(`Failed to get display. Code: ${exception.code}, message: ${exception.message}`); 276} 277``` 278 279## display.getAllDisplayPhysicalResolution<sup>12+</sup> 280 281getAllDisplayPhysicalResolution(): Promise<Array<DisplayPhysicalResolution>> 282 283Obtains all the display modes supported by the current device, along with the physical screen resolutions for each mode. This API uses a promise to return the result. 284 285**Atomic service API**: This API can be used in atomic services since API version 12. 286 287**System capability**: SystemCapability.WindowManager.WindowManager.Core 288 289**Return value** 290 291| Type| Description| 292| ----------------------------------------------- | ------------------------------------------------------- | 293| Promise<Array<[DisplayPhysicalResolution](#displayphysicalresolution12)>> | Promise used to return all the DisplayPhysicalResolution objects.| 294 295**Error codes** 296 297For details about the error codes, see [Display Error Codes](errorcode-display.md). 298 299| ID| Error Message| 300| ------- | ----------------------- | 301| 1400003 | This display manager service works abnormally. | 302 303**Example** 304 305```ts 306import { BusinessError } from '@kit.BasicServicesKit'; 307import { display } from '@kit.ArkUI'; 308 309let promise = display.getAllDisplayPhysicalResolution(); 310promise.then((resolutionObjects) => { 311 console.info('Obtaining physical resolution length: ' + resolutionObjects.length); 312 for (let i = 0; i < resolutionObjects.length; i++) { 313 console.info(`resolutionObjects[${i}].foldDisplayMode: ${resolutionObjects[i].foldDisplayMode}`); 314 console.info(`resolutionObjects[${i}].physicalWidth: ${resolutionObjects[i].physicalWidth}`); 315 console.info(`resolutionObjects[${i}].physicalHeight: ${resolutionObjects[i].physicalHeight}`); 316 } 317}).catch((err: BusinessError) => { 318 console.error(`Failed to obtain physical resolution. Code: ${err.code}, message: ${err.message}`); 319}); 320``` 321 322## display.getDefaultDisplaySync<sup>9+</sup> 323 324getDefaultDisplaySync(): Display 325 326Obtains the default display object. This API returns the result synchronously. 327 328**Atomic service API**: This API can be used in atomic services since API version 11. 329 330**System capability**: SystemCapability.WindowManager.WindowManager.Core 331 332**Return value** 333 334| Type | Description | 335| ------------------------------| ----------------------------------------------| 336| [Display](#display) | Default display object.| 337 338**Error codes** 339 340For details about the error codes, see [Display Error Codes](errorcode-display.md). 341 342| ID| Error Message| 343| ------- | ----------------------- | 344| 1400001 | Invalid display or screen. | 345 346**Example** 347 348```ts 349import { display } from '@kit.ArkUI'; 350 351let displayClass: display.Display | null = null; 352try { 353 displayClass = display.getDefaultDisplaySync(); 354} catch (exception) { 355 console.error(`Failed to get default display. Code: ${exception.code}, message: ${exception.message}`); 356} 357``` 358 359## display.getPrimaryDisplaySync<sup>14+</sup> 360 361getPrimaryDisplaySync(): Display 362 363Obtains 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. 364 365**Atomic service API**: This API can be used in atomic services since API version 14. 366 367**System capability**: SystemCapability.WindowManager.WindowManager.Core 368 369**Return value** 370 371| Type | Description | 372| ------------------------------| ----------------------------------------------| 373| [Display](#display) | Display object of the primary screen.| 374 375**Error codes** 376 377For details about the error codes, see [Display Error Codes](errorcode-display.md). 378 379| ID| Error Message| 380| ------- | ----------------------- | 381| 1400001 | Invalid display or screen. | 382 383**Example** 384 385```ts 386import { display } from '@kit.ArkUI'; 387 388let displayClass: display.Display | null = null; 389 390displayClass = display.getPrimaryDisplaySync(); 391``` 392 393## display.getAllDisplays<sup>9+</sup> 394 395getAllDisplays(callback: AsyncCallback<Array<Display>>): void 396 397Obtains all display objects. This API uses an asynchronous callback to return the result. 398 399**Atomic service API**: This API can be used in atomic services since API version 12. 400 401**System capability**: SystemCapability.WindowManager.WindowManager.Core 402 403**Parameters** 404 405| Name| Type| Mandatory| Description| 406| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 407| callback | AsyncCallback<Array<[Display](#display)>> | Yes| Callback used to return all the display objects.| 408 409**Error codes** 410 411For details about the error codes, see [Display Error Codes](errorcode-display.md). 412 413| ID| Error Message| 414| ------- | ----------------------- | 415| 1400001 | Invalid display or screen. | 416 417**Example** 418 419```ts 420import { BusinessError } from '@kit.BasicServicesKit'; 421import { display } from '@kit.ArkUI'; 422 423let displayClass: Array<display.Display> = []; 424display.getAllDisplays((err: BusinessError, data: Array<display.Display>) => { 425 displayClass = data; 426 const errCode: number = err.code; 427 if (errCode) { 428 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 429 return; 430 } 431 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 432}); 433``` 434 435## display.getAllDisplays<sup>9+</sup> 436 437getAllDisplays(): Promise<Array<Display>> 438 439Obtains all display objects. This API uses a promise to return the result. 440 441**Atomic service API**: This API can be used in atomic services since API version 12. 442 443**System capability**: SystemCapability.WindowManager.WindowManager.Core 444 445**Return value** 446 447| Type| Description| 448| ----------------------------------------------- | ------------------------------------------------------- | 449| Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| 450 451**Error codes** 452 453For details about the error codes, see [Display Error Codes](errorcode-display.md). 454 455| ID| Error Message| 456| ------- | ----------------------- | 457| 1400001 | Invalid display or screen. | 458 459**Example** 460 461```ts 462import { BusinessError } from '@kit.BasicServicesKit'; 463import { display } from '@kit.ArkUI'; 464 465let displayClass: Array<display.Display> =[]; 466let promise: Promise<Array<display.Display>> = display.getAllDisplays(); 467promise.then((data: Array<display.Display>) => { 468 displayClass = data; 469 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 470}).catch((err: BusinessError) => { 471 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 472}); 473``` 474 475## display.on('add'|'remove'|'change') 476 477on(type: 'add'|'remove'|'change', callback: Callback<number>): void 478 479Subscribes to display changes. 480 481**Atomic service API**: This API can be used in atomic services since API version 12. 482 483**System capability**: SystemCapability.WindowManager.WindowManager.Core 484 485**Parameters** 486 487| Name| Type| Mandatory| Description | 488| -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------------------------| 489| 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.| 490| callback | Callback<number> | Yes| Callback used to return the ID of the display, which is an integer. | 491 492**Error codes** 493 494For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 495 496| ID| Error Message| 497| ------- | ----------------------- | 498| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 499 500**Example** 501 502```ts 503import { Callback } from '@kit.BasicServicesKit'; 504 505let callback: Callback<number> = (data: number) => { 506 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 507}; 508 509display.on("add", callback); 510``` 511 512## display.off('add'|'remove'|'change') 513 514off(type: 'add'|'remove'|'change', callback?: Callback<number>): void 515 516Unsubscribes from display changes. 517 518**Atomic service API**: This API can be used in atomic services since API version 12. 519 520**System capability**: SystemCapability.WindowManager.WindowManager.Core 521 522**Parameters** 523 524| Name| Type| Mandatory| Description| 525| -------- | -------- | -------- | -------- | 526| 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.| 527| callback | Callback<number> | No| Callback used to return the ID of the display, which is an integer. If this parameter is not specified, all subscriptions to the specified event are canceled.| 528 529**Error codes** 530 531For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 532 533| ID| Error Message| 534| ------- | ----------------------- | 535| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 536 537**Example** 538 539```ts 540 541// Unregister all the callbacks that have been registered through on(). 542display.off("remove"); 543 544let callback: Callback<number> = (data: number) => { 545 console.info('Succeeded in unregistering the callback for display remove. Data: ' + JSON.stringify(data)) 546}; 547// Unregister the specified callback. 548display.off('remove', callback); 549``` 550 551## display.isFoldable<sup>10+</sup> 552isFoldable(): boolean 553 554Checks whether the current device is foldable. 555 556**Atomic service API**: This API can be used in atomic services since API version 12. 557 558**System capability**: SystemCapability.Window.SessionManager 559 560**Return value** 561 562| Type| Description| 563| ----------------------------------------------- | ------------------------------------------------------- | 564| boolean | Check result for whether the device is foldable. **true** if foldable, **false** otherwise. For small-screen foldable devices where the outer screen serves only as an auxiliary display (and cannot be customized by applications), the return value is always **false**. For other foldable devices, the return value is always **true**.| 565 566**Error codes** 567 568For details about the error codes, see [Display Error Codes](errorcode-display.md). 569 570| ID| Error Message| 571| ------- | ----------------------- | 572| 1400003 | This display manager service works abnormally. | 573 574**Example** 575 576```ts 577import { display } from '@kit.ArkUI'; 578 579let ret: boolean = false; 580ret = display.isFoldable(); 581``` 582 583## display.getFoldStatus<sup>10+</sup> 584getFoldStatus(): FoldStatus 585 586Obtains the fold status of the foldable device. 587 588**Atomic service API**: This API can be used in atomic services since API version 12. 589 590**System capability**: SystemCapability.Window.SessionManager 591 592**Return value** 593 594| Type| Description| 595| ----------------------------------------------- | ------------------------------------------------------- | 596| [FoldStatus](#foldstatus10) | Fold status of the device.| 597 598**Error codes** 599 600For details about the error codes, see [Display Error Codes](errorcode-display.md). 601 602| ID| Error Message| 603| ------- | ----------------------- | 604| 1400003 | This display manager service works abnormally. | 605 606**Example** 607 608```ts 609import { display } from '@kit.ArkUI'; 610 611let data: display.FoldStatus = display.getFoldStatus(); 612console.info('Succeeded in obtaining fold status. Data: ' + JSON.stringify(data)); 613``` 614 615## display.getFoldDisplayMode<sup>10+</sup> 616getFoldDisplayMode(): FoldDisplayMode 617 618Obtains the display mode of the foldable device. 619 620**Atomic service API**: This API can be used in atomic services since API version 12. 621 622**System capability**: SystemCapability.Window.SessionManager 623 624**Device behavior differences**: This API returns **0** for 2-in-1 devices and non-foldable devices. For other devices, this API can be called properly. 625 626**Return value** 627 628| Type| Description| 629| ----------------------------------------------- | ------------------------------------------------------- | 630| [FoldDisplayMode](#folddisplaymode10) | Display mode of the device.| 631 632**Error codes** 633 634For details about the error codes, see [Display Error Codes](errorcode-display.md). 635 636| ID| Error Message| 637| ------- | ----------------------- | 638| 1400003 | This display manager service works abnormally. | 639 640**Example** 641 642```ts 643import { display } from '@kit.ArkUI'; 644 645let data: display.FoldDisplayMode = display.getFoldDisplayMode(); 646console.info('Succeeded in obtaining fold display mode. Data: ' + JSON.stringify(data)); 647``` 648 649## display.getCurrentFoldCreaseRegion<sup>10+</sup> 650getCurrentFoldCreaseRegion(): FoldCreaseRegion 651 652Obtains the crease region of the foldable device in the current display mode. 653 654**Atomic service API**: This API can be used in atomic services since API version 12. 655 656**System capability**: SystemCapability.Window.SessionManager 657 658**Return value** 659 660| Type| Description| 661| ----------------------------------------------- | ------------------------------------------------------- | 662| [FoldCreaseRegion](#foldcreaseregion10) | Crease region of the device.| 663 664**Error codes** 665 666For details about the error codes, see [Display Error Codes](errorcode-display.md). 667 668| ID| Error Message| 669| ------- | ----------------------- | 670| 1400003 | This display manager service works abnormally. | 671 672**Example** 673 674```ts 675import { display } from '@kit.ArkUI'; 676 677let data: display.FoldCreaseRegion = display.getCurrentFoldCreaseRegion(); 678console.info('Succeeded in obtaining current fold crease region. Data: ' + JSON.stringify(data)); 679``` 680 681## display.on('foldStatusChange')<sup>10+</sup> 682 683on(type: 'foldStatusChange', callback: Callback<FoldStatus>): void 684 685Subscribes to fold status change events of the foldable device. 686 687To subscribe to display mode change events of foldable devices, use [display.on('foldDisplayModeChange')](#displayonfolddisplaymodechange10). 688 689The two are different. In terms of timing, the fold status changes first, and the bottom layer matches the display mode status based on the fold status. 690 691To check whether the content is displayed on the inner or outer screen of the foldable device, use [display.on('foldDisplayModeChange')](#displayonfolddisplaymodechange10). 692 693**Atomic service API**: This API can be used in atomic services since API version 12. 694 695**System capability**: SystemCapability.Window.SessionManager 696 697**Parameters** 698 699| Name | Type | Mandatory| Description | 700| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 701| type | string | Yes | Event type. The event **'foldStatusChange'** is triggered when the fold status of the device changes.| 702| callback | Callback<[FoldStatus](#foldstatus10)> | Yes | Callback used to return the fold status.| 703 704**Error codes** 705 706For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 707 708| ID| Error Message| 709| ------- | ----------------------- | 710| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 711| 1400003 | This display manager service works abnormally. | 712 713**Example** 714 715```ts 716import { Callback } from '@kit.BasicServicesKit'; 717 718/** 719 * The callback parameter used for subscription must be passed as an object. 720 * If an anonymous function is used for registration, a new underlying object is created each time the function is called, causing memory leakage. 721*/ 722let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 723 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 724}; 725display.on('foldStatusChange', callback); 726``` 727 728## display.off('foldStatusChange')<sup>10+</sup> 729 730off(type: 'foldStatusChange', callback?: Callback<FoldStatus>): void 731 732Unsubscribes from fold status change events of the foldable device. 733 734**Atomic service API**: This API can be used in atomic services since API version 12. 735 736**System capability**: SystemCapability.Window.SessionManager 737 738**Parameters** 739 740| Name | Type | Mandatory| Description | 741| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 742| type | string | Yes | Event type. The event **'foldStatusChange'** is triggered when the fold status of the device changes.| 743| callback | Callback<[FoldStatus](#foldstatus10)> | No | Callback used to return the fold status. If this parameter is not specified, all subscriptions to the specified event are canceled.| 744 745**Error codes** 746 747For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 748 749| ID| Error Message| 750| ------- | ----------------------- | 751| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 752| 1400003 | This display manager service works abnormally. | 753 754**Example** 755 756```ts 757 758// Unregister all the callbacks that have been registered through on(). 759display.off('foldStatusChange'); 760 761let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 762 console.info('unregistering FoldStatus changes callback. Data: ' + JSON.stringify(data)); 763}; 764// Unregister the specified callback. 765display.off('foldStatusChange', callback); 766``` 767 768## display.on('foldAngleChange')<sup>12+</sup> 769 770on(type: 'foldAngleChange', callback: Callback<Array<number>>): void 771 772Subscribes 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. 773 774**Atomic service API**: This API can be used in atomic services since API version 12. 775 776**System capability**: SystemCapability.Window.SessionManager 777 778**Parameters** 779 780| Name | Type | Mandatory| Description | 781| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 782| type | string | Yes| Event type. The event **'foldAngleChange'** is triggered when the folding angle of the device changes.| 783| 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.| 784 785**Error codes** 786 787For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 788 789| ID| Error Message| 790| ------- | ----------------------- | 791| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 792| 1400003 | This display manager service works abnormally. | 793 794**Example** 795 796```ts 797import { Callback } from '@kit.BasicServicesKit'; 798 799let callback: Callback<Array<number>> = (angles: Array<number>) => { 800 console.info('Listening fold angles length: ' + angles.length); 801}; 802display.on('foldAngleChange', callback); 803``` 804 805## display.off('foldAngleChange')<sup>12+</sup> 806 807off(type: 'foldAngleChange', callback?: Callback<Array<number>>): void 808 809Unsubscribes from folding angle change events of the foldable device. 810 811**Atomic service API**: This API can be used in atomic services since API version 12. 812 813**System capability**: SystemCapability.Window.SessionManager 814 815**Parameters** 816 817| Name | Type | Mandatory| Description | 818| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 819| type | string | Yes | Event type. The event **'foldAngleChange'** is triggered when the folding angle of the device changes.| 820| callback | Callback<Array<number>> | No | Callback used to return the folding angle (0–180 degrees). If this parameter is not specified, all subscriptions to the specified event are canceled.| 821 822**Error codes** 823 824For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 825 826| ID| Error Message| 827| ------- | ----------------------- | 828| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 829| 1400003 | This display manager service works abnormally. | 830 831**Example** 832 833```ts 834 835// Unregister all the callbacks that have been registered through on(). 836display.off('foldAngleChange'); 837 838let callback: Callback<Array<number>> = (angles: Array<number>) => { 839 console.info('Listening fold angles length: ' + angles.length); 840}; 841// Unregister the specified callback. 842display.off('foldAngleChange', callback); 843``` 844 845## display.on('captureStatusChange')<sup>12+</sup> 846 847on(type: 'captureStatusChange', callback: Callback<boolean>): void 848 849Subscribes to screen capture, casting, or recording status changes. 850 851**Atomic service API**: This API can be used in atomic services since API version 12. 852 853**System capability**: SystemCapability.Window.SessionManager 854 855**Parameters** 856 857| Name | Type | Mandatory| Description | 858| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 859| type | string | Yes| Event type. The event **'captureStatusChange'** is triggered when the screen capture, casting, or recording status changes.| 860| callback | Callback<boolean> | Yes| Callback used to return the status change during screen capture, casting, or recording. The value **true** means the start of screen casting or recording, and **false** means the end of screen casting or recording. In the case of screen capture, only **true** is returned once.| 861 862**Error codes** 863 864For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 865 866| ID| Error Message| 867| ------- | ----------------------- | 868| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 869| 1400003 | This display manager service works abnormally. | 870 871**Example** 872 873```ts 874import { Callback } from '@kit.BasicServicesKit'; 875 876let callback: Callback<boolean> = (captureStatus: boolean) => { 877 console.info('Listening capture status: ' + captureStatus); 878}; 879display.on('captureStatusChange', callback); 880``` 881 882## display.off('captureStatusChange')<sup>12+</sup> 883 884off(type: 'captureStatusChange', callback?: Callback<boolean>): void 885 886Unsubscribes from screen capture, casting, or recording status changes. 887 888**Atomic service API**: This API can be used in atomic services since API version 12. 889 890**System capability**: SystemCapability.Window.SessionManager 891 892**Parameters** 893 894| Name | Type | Mandatory| Description | 895| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 896| type | string | Yes| Event type. The event **'captureStatusChange'** is triggered when the screen capture, casting, or recording status changes.| 897| callback | Callback<boolean> | No| Callback used to return the status change during screen capture, casting, or recording. The value **true** means the start of screen casting or recording, and **false** means the end of screen casting or recording. In the case of screen capture, only **true** is returned once. If this parameter is not specified, all subscriptions to the specified event are canceled.| 898 899**Error codes** 900 901For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 902 903| ID| Error Message| 904| ------- | ----------------------- | 905| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 906| 1400003 | This display manager service works abnormally. | 907 908**Example** 909 910```ts 911 912// Unregister all the callbacks that have been registered through on(). 913display.off('captureStatusChange'); 914 915let callback: Callback<boolean> = (captureStatus: boolean) => { 916 console.info('Listening capture status: ' + captureStatus); 917}; 918// Unregister the specified callback. 919display.off('captureStatusChange', callback); 920``` 921 922## display.isCaptured<sup>12+</sup> 923isCaptured(): boolean 924 925Checks whether the display is being captured, projected, or recorded. 926 927**Atomic service API**: This API can be used in atomic services since API version 12. 928 929**System capability**: SystemCapability.Window.SessionManager 930 931**Return value** 932 933| Type| Description| 934| ----------------------------------------------- | ------------------------------------------------------- | 935| boolean | **true**: The display is being captured, projected, or recorded.<br> **false**: The display is not being captured, projected, or recorded.| 936 937**Error codes** 938 939For details about the error codes, see [Display Error Codes](errorcode-display.md). 940 941| ID| Error Message| 942| ------- | ----------------------- | 943| 1400003 | This display manager service works abnormally. | 944 945**Example** 946 947```ts 948import { display } from '@kit.ArkUI'; 949 950let ret: boolean = false; 951ret = display.isCaptured(); 952``` 953 954## display.on('foldDisplayModeChange')<sup>10+</sup> 955 956on(type: 'foldDisplayModeChange', callback: Callback<FoldDisplayMode>): void 957 958Subscribes to display mode change events of the foldable device. 959 960To subscribe to fold status change events of foldable devices, use [display.on('foldStatusChange')](#displayonfoldstatuschange10). 961 962The two are different. In terms of timing, the fold status changes first, and the bottom layer matches the display mode status based on the fold status. 963 964**Atomic service API**: This API can be used in atomic services since API version 12. 965 966**System capability**: SystemCapability.Window.SessionManager 967 968**Device behavior differences**: This API has no effect and does not report errors for 2-in-1 devices and non-foldable devices. For other devices, this API can be called properly. 969 970**Parameters** 971 972| Name | Type | Mandatory| Description | 973| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 974| type | string | Yes | Event type. The event **'foldDisplayModeChange'** is triggered when the display mode of the device changes.| 975| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | Yes | Callback used to return the display mode.| 976 977**Error codes** 978 979For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 980 981| ID| Error Message| 982| ------- | ----------------------- | 983| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 984| 1400003 | This display manager service works abnormally. | 985 986**Example** 987 988```ts 989import { Callback } from '@kit.BasicServicesKit'; 990 991/** 992 * The callback parameter used for subscription must be passed as an object. 993 * If an anonymous function is used for registration, a new underlying object is created each time the function is called, causing memory leakage. 994*/ 995let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 996 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 997}; 998display.on('foldDisplayModeChange', callback); 999``` 1000 1001## display.off('foldDisplayModeChange')<sup>10+</sup> 1002 1003off(type: 'foldDisplayModeChange', callback?: Callback<FoldDisplayMode>): void 1004 1005Unsubscribes from display mode change events of the foldable device. 1006 1007**Atomic service API**: This API can be used in atomic services since API version 12. 1008 1009**System capability**: SystemCapability.Window.SessionManager 1010 1011**Device behavior differences**: This API has no effect and does not report errors for 2-in-1 devices and non-foldable devices. For other devices, this API can be called properly. 1012 1013**Parameters** 1014 1015| Name | Type | Mandatory| Description | 1016| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1017| type | string | Yes | Event type. The event **'foldDisplayModeChange'** is triggered when the display mode of the device changes.| 1018| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | No | Callback used to return the display mode. If this parameter is not specified, all subscriptions to the specified event are canceled.| 1019 1020**Error codes** 1021 1022For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1023 1024| ID| Error Message| 1025| ------- | ----------------------- | 1026| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1027| 1400003 | This display manager service works abnormally. | 1028 1029**Example** 1030 1031```ts 1032 1033// Unregister all the callbacks that have been registered through on(). 1034display.off('foldDisplayModeChange'); 1035 1036let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 1037 console.info('unregistering FoldDisplayMode changes callback. Data: ' + JSON.stringify(data)); 1038}; 1039// Unregister the specified callback. 1040display.off('foldDisplayModeChange', callback); 1041``` 1042 1043 1044## display.getDefaultDisplay<sup>(deprecated)</sup> 1045 1046getDefaultDisplay(callback: AsyncCallback<Display>): void 1047 1048Obtains the default display object. This API uses an asynchronous callback to return the result. 1049 1050> **NOTE** 1051> 1052> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) instead. 1053 1054**System capability**: SystemCapability.WindowManager.WindowManager.Core 1055 1056**Parameters** 1057 1058| Name| Type| Mandatory| Description| 1059| -------- | -------- | -------- | -------- | 1060| callback | AsyncCallback<[Display](#display)> | Yes| Callback used to return the default display object.| 1061 1062**Example** 1063 1064```ts 1065import { BusinessError } from '@kit.BasicServicesKit'; 1066 1067let displayClass: display.Display | null = null; 1068display.getDefaultDisplay((err: BusinessError, data: display.Display) => { 1069 const errCode: number = err.code; 1070 if (errCode) { 1071 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 1072 return; 1073 } 1074 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 1075 displayClass = data; 1076}); 1077``` 1078 1079## display.getDefaultDisplay<sup>(deprecated)</sup> 1080 1081getDefaultDisplay(): Promise<Display> 1082 1083Obtains the default display object. This API uses a promise to return the result. 1084 1085> **NOTE** 1086> 1087> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) instead. 1088 1089**System capability**: SystemCapability.WindowManager.WindowManager.Core 1090 1091**Return value** 1092 1093| Type | Description | 1094| ---------------------------------- | ---------------------------------------------- | 1095| Promise<[Display](#display)> | Promise used to return the default display object.| 1096 1097**Example** 1098 1099```ts 1100import { BusinessError } from '@kit.BasicServicesKit'; 1101 1102let displayClass: display.Display | null = null; 1103let promise: Promise<display.Display> = display.getDefaultDisplay(); 1104promise.then((data: display.Display) => { 1105 displayClass = data; 1106 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 1107}).catch((err: BusinessError) => { 1108 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 1109}); 1110``` 1111 1112## display.getAllDisplay<sup>(deprecated)</sup> 1113 1114getAllDisplay(callback: AsyncCallback<Array<Display>>): void 1115 1116Obtains all display objects. This API uses an asynchronous callback to return the result. 1117 1118> **NOTE** 1119> 1120> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getAllDisplays()](#displaygetalldisplays9) instead. 1121 1122**System capability**: SystemCapability.WindowManager.WindowManager.Core 1123 1124**Parameters** 1125 1126| Name | Type | Mandatory| Description | 1127| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 1128| callback | AsyncCallback<Array<[Display](#display)>> | Yes | Callback used to return all the display objects.| 1129 1130**Example** 1131 1132```ts 1133import { BusinessError } from '@kit.BasicServicesKit'; 1134 1135display.getAllDisplay((err: BusinessError, data: Array<display.Display>) => { 1136 const errCode: number = err.code; 1137 if (errCode) { 1138 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1139 return; 1140 } 1141 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1142}); 1143``` 1144 1145## display.getAllDisplay<sup>(deprecated)</sup> 1146 1147getAllDisplay(): Promise<Array<Display>> 1148 1149Obtains all display objects. This API uses a promise to return the result. 1150 1151> **NOTE** 1152> 1153> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getAllDisplays()](#displaygetalldisplays9-1) instead. 1154 1155**System capability**: SystemCapability.WindowManager.WindowManager.Core 1156 1157**Return value** 1158 1159| Type | Description | 1160| ----------------------------------------------- | ------------------------------------------------------- | 1161| Promise<Array<[Display](#display)>> | Promise used to return all the display objects.| 1162 1163**Example** 1164 1165```ts 1166import { BusinessError } from '@kit.BasicServicesKit'; 1167 1168let promise: Promise<Array<display.Display>> = display.getAllDisplay(); 1169promise.then((data: Array<display.Display>) => { 1170 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1171}).catch((err: BusinessError) => { 1172 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1173}); 1174``` 1175 1176## display.createVirtualScreen<sup>16+</sup> 1177 1178createVirtualScreen(config:VirtualScreenConfig): Promise<number> 1179 1180Creates a virtual screen. This API uses a promise to return the result. 1181 1182**System capability**: SystemCapability.Window.SessionManager 1183 1184**Required permissions**: ohos.permission.ACCESS_VIRTUAL_SCREEN 1185 1186**Parameters** 1187 1188| Name | Type | Mandatory| Description | 1189| ------- | ------------------------------------------- | ---- | ------------------------ | 1190| config | [VirtualScreenConfig](#virtualscreenconfig16) | Yes | Virtual screen parameters.| 1191 1192**Return value** 1193 1194| Type | Description | 1195| -------------------------------- | ------------------------------------- | 1196| Promise<number> | Promise used to return the screen ID of the created virtual screen.| 1197 1198**Error codes** 1199 1200For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1201 1202| ID| Error Message| 1203| ------- | ----------------------- | 1204| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1205| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1206| 801 | Capability not supported.function createVirtualScreen can not work correctly due to limited device capabilities. | 1207| 1400001 | Invalid display or screen. | 1208 1209**Example** 1210 1211```ts 1212import { BusinessError } from '@kit.BasicServicesKit'; 1213 1214class VirtualScreenConfig { 1215 name : string = ''; 1216 width : number = 0; 1217 height : number = 0; 1218 density : number = 0; 1219 surfaceId : string = ''; 1220} 1221 1222let config : VirtualScreenConfig = { 1223 name: 'screen01', 1224 width: 1080, 1225 height: 2340, 1226 density: 2, 1227 surfaceId: '' 1228}; 1229 1230display.createVirtualScreen(config).then((screenId: number) => { 1231 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(screenId)); 1232}).catch((err: BusinessError) => { 1233 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1234}); 1235``` 1236 1237## display.destroyVirtualScreen<sup>16+</sup> 1238 1239destroyVirtualScreen(screenId:number): Promise<void> 1240 1241Destroys a virtual screen. This API uses a promise to return the result. 1242 1243**System capability**: SystemCapability.Window.SessionManager 1244 1245**Required permissions**: ohos.permission.ACCESS_VIRTUAL_SCREEN 1246 1247**Parameters** 1248 1249| Name | Type | Mandatory| Description | 1250| -------- | ------ | ---- | ---------- | 1251| screenId | number | Yes | Screen ID, which must match the ID of the virtual screen created by calling the **createVirtualScreen()** API. This parameter only accepts integer values.| 1252 1253**Return value** 1254 1255| Type | Description | 1256| ------------------- | ------------------------- | 1257| Promise<void> | Promise that returns no value.| 1258 1259**Error codes** 1260 1261For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1262 1263| ID| Error Message| 1264| ------- | ----------------------- | 1265| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1266| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1267| 801 | Capability not supported.function destroyVirtualScreen can not work correctly due to limited device capabilities. | 1268| 1400001 | Invalid display or screen. | 1269| 1400003 | This display manager service works abnormally. | 1270 1271**Example** 1272 1273```ts 1274import { BusinessError } from '@kit.BasicServicesKit'; 1275 1276let screenId: number = 1; 1277display.destroyVirtualScreen(screenId).then(() => { 1278 console.info('Succeeded in destroying the virtual screen.'); 1279}).catch((err: BusinessError) => { 1280 console.error(`Failed to destroy the virtual screen.Code:${err.code},message is ${err.message}`); 1281}); 1282``` 1283 1284## display.setVirtualScreenSurface<sup>16+</sup> 1285 1286setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 1287 1288Sets a surface ID for a virtual screen. This API uses a promise to return the result. 1289 1290**System capability**: SystemCapability.Window.SessionManager 1291 1292**Required permissions**: ohos.permission.ACCESS_VIRTUAL_SCREEN 1293 1294**Parameters** 1295 1296| Name | Type | Mandatory| Description | 1297| --------- | ------ | ---- | ------------- | 1298| screenId | number | Yes | Screen ID, which must match the ID of the virtual screen created by calling the **createVirtualScreen()** API. This parameter only accepts integer values. | 1299| surfaceId | string | Yes | Surface ID of the virtual screen. The value can be customized. The maximum length for this parameter is 4096 bytes. If it goes beyond that, only the first 4096 bytes are used.| 1300 1301**Return value** 1302 1303| Type | Description | 1304| ------------------- | ------------------------- | 1305| Promise<void> | Promise that returns no value.| 1306 1307**Error codes** 1308 1309For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1310 1311| ID| Error Message| 1312| ------- | ----------------------- | 1313| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1314| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1315| 801 | Capability not supported.function setVirtualScreenSurface can not work correctly due to limited device capabilities. | 1316| 1400001 | Invalid display or screen. | 1317| 1400003 | This display manager service works abnormally. | 1318 1319**Example** 1320 1321```ts 1322import { BusinessError } from '@kit.BasicServicesKit'; 1323 1324let screenId: number = 1; 1325let surfaceId: string = '2048'; 1326display.setVirtualScreenSurface(screenId, surfaceId).then(() => { 1327 console.info('Succeeded in setting the surface for the virtual screen.'); 1328}).catch((err: BusinessError) => { 1329 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 1330}); 1331``` 1332 1333## display.makeUnique<sup>16+</sup> 1334 1335makeUnique(screenId:number): Promise<void> 1336 1337Sets the screen to independent display mode. This API uses a promise to return the result. 1338 1339**System capability**: SystemCapability.Window.SessionManager 1340 1341**Required permissions**: ohos.permission.ACCESS_VIRTUAL_SCREEN 1342 1343**Parameters** 1344 1345| Name | Type | Mandatory| Description | 1346| --------- | ------ | ---- | ------------- | 1347| screenId | number | Yes | ID of the screen. Each ID must be an integer greater than 0; otherwise, error code 401 is returned.| 1348 1349**Return value** 1350 1351| Type | Description | 1352| ------------------- | ------------------------- | 1353| Promise<void> | Promise that returns no value.| 1354 1355**Error codes** 1356 1357For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1358 1359| ID| Error Message| 1360| ------- | ----------------------- | 1361| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1362| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1363| 801 | Capability not supported.function makeUnique can not work correctly due to limited device capabilities. | 1364| 1400001 | Invalid display or screen. | 1365| 1400003 | This display manager service works abnormally. | 1366 1367**Example** 1368 1369```ts 1370import { BusinessError } from '@kit.BasicServicesKit'; 1371 1372let screenId: number = 0; 1373display.makeUnique(screenId).then(() => { 1374 console.info('Succeeded in making unique screens.'); 1375}).catch((err: BusinessError) => { 1376 console.error(`Failed to make unique screens. Code:${err.code},message is ${err.message}`); 1377}); 1378``` 1379 1380## display.convertRelativeToGlobalCoordinate<sup>20+</sup> 1381 1382convertRelativeToGlobalCoordinate(relativePosition: RelativePosition): Position 1383 1384Converts relative coordinates (based on the upper-left corner of the screen) into global coordinates (based on the upper-left corner of the primary screen). This API supports only coordinate conversion between the primary screen and extended screen. 1385 1386**Atomic service API**: This API can be used in atomic services since API version 20. 1387 1388**System capability**: SystemCapability.Window.SessionManager 1389 1390**Parameters** 1391 1392| Name | Type | Mandatory| Description | 1393| --------- | ------ | ---- | ------------- | 1394| relativePosition | [RelativePosition](#relativeposition20) | Yes| Relative coordinates to convert.| 1395 1396**Return value** 1397 1398| Type | Description | 1399| ------------------- | ------------------------- | 1400| [Position](#position20) | Global coordinates based on the upper-left corner of the primary screen.| 1401 1402**Error codes** 1403 1404For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1405 1406| ID| Error Message| 1407| ------- | ----------------------- | 1408| 801 | Capability not supported. | 1409| 1400003 | This display manager service works abnormally. | 1410| 1400004 | Parameter error. Possible cause: 1.Invalid parameter range. | 1411 1412**Example** 1413 1414```ts 1415import { display } from '@kit.ArkUI'; 1416 1417let relativePosition: display.RelativePosition = { 1418 displayId: 0, 1419 position: { 1420 x: 100, 1421 y: 200 1422 } 1423}; 1424 1425try { 1426 let position: display.Position = display.convertRelativeToGlobalCoordinate(relativePosition); 1427 console.info(`The global coordinate is ${position.x}, ${position.y}`) 1428} catch (exception) { 1429 console.error(`Failed to convert the relative coordinate to the global coordinate. Code: ${exception.code}, message: ${exception.message}`); 1430} 1431``` 1432 1433## display.convertGlobalToRelativeCoordinate<sup>20+</sup> 1434 1435convertGlobalToRelativeCoordinate(position: Position, displayId?: number): RelativePosition 1436 1437Converts global coordinates (based on the upper-left corner of the primary screen) into relative coordinates (based on the upper-left corner of the screen specified by **displayId**). If **displayId** is not passed, the coordinates are converted relative to the screen where the global coordinates are located. If the global coordinates are not on any screen, the coordinates are converted relative to the primary screen by default. 1438 1439**Atomic service API**: This API can be used in atomic services since API version 20. 1440 1441**System capability**: SystemCapability.Window.SessionManager 1442 1443**Parameters** 1444 1445| Name | Type | Mandatory| Description | 1446| --------- | ------ | ---- | ------------- | 1447| position | [Position](#position20) | Yes| Global coordinates to convert.| 1448| displayId | number | No| Display ID for the relative coordinates. If this parameter is passed, the coordinates are converted relative to this screen. If it is not provided, the coordinates are converted to the screen where the global coordinates are located, or the primary screen if they are not on any screen.| 1449 1450**Return value** 1451 1452| Type | Description | 1453| ------------------- | ------------------------- | 1454| [RelativePosition](#relativeposition20) | Relative coordinates for the specified screen.| 1455 1456**Error codes** 1457 1458For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1459 1460| ID| Error Message| 1461| ------- | ----------------------- | 1462| 801 | Capability not supported. | 1463| 1400003 | This display manager service works abnormally. | 1464| 1400004 | Parameter error. Possible cause: 1.Invalid parameter range. | 1465 1466**Example** 1467 1468```ts 1469import { display } from '@kit.ArkUI'; 1470 1471let position: display.Position = { 1472 x: 100, 1473 y: 200 1474}; 1475 1476try { 1477 let relPos: display.RelativePosition = display.convertGlobalToRelativeCoordinate(position, 0); 1478 console.info(`The relative coordinate is ${relPos.displayId}, ${relPos.position.x}, ${relPos.position.y}`) 1479} catch (exception) { 1480 console.error(`Failed to convert the global coordinate to the relative coordinate. Code: ${exception.code}, message: ${exception.message}`); 1481} 1482``` 1483 1484## Display 1485Implements a Display instance, with properties and APIs defined. 1486 1487Before calling any API in Display, you must use [getAllDisplays()](#displaygetalldisplays9) or [getDefaultDisplaySync()](#displaygetdefaultdisplaysync9) to obtain a Display instance. 1488 1489### Properties 1490 1491| Name| Type| Read-Only| Optional| Description | 1492| -------- | -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------| 1493| id | number | Yes| No| Display ID. The value is an integer greater than or equal to 0.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1494| name | string | Yes| No| Name of the display.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1495| alive | boolean | Yes| No| Whether the display is alive. **true** if alive, **false** otherwise.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1496| state | [DisplayState](#displaystate) | Yes| No| State of the display.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1497| refreshRate | number | Yes| No| Refresh rate of the display, in Hz. The value is an integer.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1498| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 1499| width | number | Yes| No| Width of the display, in px. The value is an integer.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 1500| height | number | Yes| No| Height of the display, in px. The value is an integer.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 1501| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1502| orientation<sup>10+</sup> | [Orientation](#orientation10) | Yes| No| Orientation of the display.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1503| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 1504| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1505| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1506| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1507| colorSpaces<sup>11+</sup> | Array<[colorSpaceManager.ColorSpace](../apis-arkgraphics2d/js-apis-colorSpaceManager.md)> | Yes| No| All color spaces supported by the display.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1508| hdrFormats<sup>11+</sup> | Array<[hdrCapability.HDRFormat](../apis-arkgraphics2d/js-apis-hdrCapability.md)> | Yes| No| All HDR formats supported by the display.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1509| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1510| 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>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 1511| screenShape<sup>18+</sup> | [ScreenShape](#screenshape18) | Yes| Yes| Screen shape of the display. The default value is **RECTANGLE**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 1512| sourceMode<sup>19+</sup> | [DisplaySourceMode](#displaysourcemode19) | Yes| Yes| Display mode for screen content. The default value is **DisplaySourceMode.NONE**.<br>**System capability**: SystemCapability.Window.SessionManager<br>**Atomic service API**: This API can be used in atomic services since API version 19. | 1513| x<sup>19+</sup> | number | Yes| Yes| X coordinate of the upper-left corner of the screen relative to the origin, which is the upper-left corner of the primary screen, measured in px. The value is an integer. The default value is **0**. It is returned only when **DisplaySourceMode** is set to **MAIN** or **EXTEND**.<br>**System capability**: SystemCapability.Window.SessionManager<br>**Atomic service API**: This API can be used in atomic services since API version 19. | 1514| y<sup>19+</sup> | number | Yes| Yes| Y coordinate of the upper-left corner of the screen relative to the origin, which is the upper-left corner of the primary screen, measured in px. The value is an integer. The default value is **0**. It is returned only when **DisplaySourceMode** is set to **MAIN** or **EXTEND**.<br>**System capability**: SystemCapability.Window.SessionManager<br>**Atomic service API**: This API can be used in atomic services since API version 19. | 1515| supportedRefreshRates<sup>20+</sup> | Array<number> | Yes| Yes| All refresh rates supported by the display, sorted in ascending order. The refresh rate is a positive integer, in Hz. The default value is empty.<br>**System capability**: SystemCapability.Window.SessionManager<br>**Atomic service API**: This API can be used in atomic services since API version 20. | 1516 1517 1518### getCutoutInfo<sup>9+</sup> 1519getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void 1520 1521Obtains 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. 1522 1523**Atomic service API**: This API can be used in atomic services since API version 12. 1524 1525**System capability**: SystemCapability.WindowManager.WindowManager.Core 1526 1527**Parameters** 1528 1529| Name | Type | Mandatory| Description | 1530| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1531| callback | AsyncCallback<[CutoutInfo](#cutoutinfo9)> | Yes | Callback used to return the CutoutInfo object.| 1532 1533**Error codes** 1534 1535For details about the error codes, see [Display Error Codes](errorcode-display.md). 1536 1537| ID| Error Message| 1538| ------- | ----------------------- | 1539| 1400001 | Invalid display or screen. | 1540 1541**Example** 1542 1543```ts 1544import { BusinessError } from '@kit.BasicServicesKit'; 1545 1546let displayClass: display.Display | null = null; 1547displayClass = display.getDefaultDisplaySync(); 1548 1549displayClass.getCutoutInfo((err: BusinessError, data: display.CutoutInfo) => { 1550 const errCode: number = err.code; 1551 if (errCode) { 1552 console.error(`Failed to get cutoutInfo. Code: ${err.code}, message: ${err.message}`); 1553 return; 1554 } 1555 console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data)); 1556}); 1557``` 1558### getCutoutInfo<sup>9+</sup> 1559getCutoutInfo(): Promise<CutoutInfo> 1560 1561Obtains 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. 1562 1563**Atomic service API**: This API can be used in atomic services since API version 12. 1564 1565**System capability**: SystemCapability.WindowManager.WindowManager.Core 1566 1567**Return value** 1568 1569| Type | Description | 1570| ------------------- | ------------------------- | 1571| Promise<[CutoutInfo](#cutoutinfo9)> | Promise used to return the CutoutInfo object.| 1572 1573**Error codes** 1574 1575For details about the error codes, see [Display Error Codes](errorcode-display.md). 1576 1577| ID| Error Message| 1578| ------- | ----------------------- | 1579| 1400001 | Invalid display or screen. | 1580 1581**Example** 1582 1583```ts 1584import { BusinessError } from '@kit.BasicServicesKit'; 1585 1586let displayClass: display.Display | null = null; 1587displayClass = display.getDefaultDisplaySync(); 1588let promise: Promise<display.CutoutInfo> = displayClass.getCutoutInfo(); 1589promise.then((data: display.CutoutInfo) => { 1590 console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data)); 1591}).catch((err: BusinessError) => { 1592 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1593}); 1594``` 1595 1596### getAvailableArea<sup>12+</sup> 1597getAvailableArea(): Promise<Rect> 1598 1599Obtains the available area of the display of the current device. This API uses a promise to return the result. 1600 1601**Atomic service API**: This API can be used in atomic services since API version 12. 1602 1603**System capability**: SystemCapability.Window.SessionManager 1604 1605**Device behavior differences**: This API can be properly called on 2-in-1 devices and tablets. It does not work for other device types. To obtain the available screen area on the current device, you can use the width and height in [display properties](#properties). 1606 1607**Return value** 1608 1609| Type | Description | 1610| ------------------- | ------------------------- | 1611| Promise<[Rect](#rect9)> | Promise used to return the available area, which is a rectangle.| 1612 1613**Error codes** 1614 1615For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1616 1617| ID| Error Message| 1618| ------- | ----------------------- | 1619| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1620| 1400001 | Invalid display or screen. | 1621 1622**Example** 1623 1624```ts 1625import { BusinessError } from '@kit.BasicServicesKit'; 1626import { display } from '@kit.ArkUI'; 1627 1628let displayClass: display.Display | null = null; 1629try { 1630 displayClass = display.getDefaultDisplaySync(); 1631 let promise = displayClass.getAvailableArea(); 1632 promise.then((data) => { 1633 console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(data)); 1634 }).catch((err: BusinessError) => { 1635 console.error(`Failed to get the available area in this display. Code: ${err.code}, message: ${err.message}`); 1636 }) 1637} catch (exception) { 1638 console.error(`Failed to obtain the default display object. Code: ${exception.code}, message: ${exception.message}`); 1639} 1640``` 1641 1642### on('availableAreaChange')<sup>12+</sup> 1643on(type: 'availableAreaChange', callback: Callback<Rect>): void 1644 1645Subscribes to changes of the available area on the display of the current device. This API uses an asynchronous callback to return the result. 1646 1647**Atomic service API**: This API can be used in atomic services since API version 12. 1648 1649**System capability**: SystemCapability.Window.SessionManager 1650 1651**Device behavior differences**: This API can be properly called on 2-in-1 devices and tablets. If it is called on other device types, it has no effect and does not report errors. 1652 1653**Parameters** 1654 1655| Name | Type | Mandatory| Description | 1656| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1657| type | string | Yes | Event type. The event **'availableAreaChange'** is triggered when the available area of the display changes.| 1658| callback | Callback<[Rect](#rect9)> | Yes | Callback used to return the new available area.| 1659 1660**Error codes** 1661 1662For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1663 1664| ID| Error Message| 1665| ------- | ----------------------- | 1666| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1667| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1668| 1400003 | This display manager service works abnormally. | 1669 1670**Example** 1671 1672```ts 1673import { Callback } from '@kit.BasicServicesKit'; 1674import { display } from '@kit.ArkUI'; 1675 1676let callback: Callback<display.Rect> = (data: display.Rect) => { 1677 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1678}; 1679let displayClass: display.Display | null = null; 1680try { 1681 displayClass = display.getDefaultDisplaySync(); 1682 displayClass.on("availableAreaChange", callback); 1683} catch (exception) { 1684 console.error(`Failed to register callback. Code: ${exception.code}, message: ${exception.message}`); 1685} 1686``` 1687 1688### off('availableAreaChange')<sup>12+</sup> 1689 1690off(type: 'availableAreaChange', callback?: Callback<Rect>): void 1691 1692Unsubscribes from changes of the available area on the display of the current device. 1693 1694**Atomic service API**: This API can be used in atomic services since API version 12. 1695 1696**System capability**: SystemCapability.Window.SessionManager 1697 1698**Device behavior differences**: This API can be properly called on 2-in-1 devices and tablets. If it is called on other device types, it has no effect and does not report errors. 1699 1700**Parameters** 1701 1702| Name | Type | Mandatory| Description | 1703| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1704| type | string | Yes | Event type. The event **'availableAreaChange'** is triggered when the available area of the display changes.| 1705| callback | Callback<[Rect](#rect9)> | No | Callback used to return the new available area. If this parameter is not specified, all subscriptions to the specified event are canceled.| 1706 1707**Error codes** 1708 1709For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1710 1711| ID| Error Message| 1712| ------- | ----------------------- | 1713| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1714| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1715| 1400003 | This display manager service works abnormally. | 1716 1717**Example** 1718 1719```ts 1720import { Callback } from '@kit.BasicServicesKit'; 1721import { display } from '@kit.ArkUI'; 1722 1723let callback: Callback<display.Rect> = (data: display.Rect) => { 1724 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1725}; 1726let displayClass: display.Display | null = null; 1727try { 1728 displayClass = display.getDefaultDisplaySync(); 1729 displayClass.off("availableAreaChange", callback); 1730} catch (exception) { 1731 console.error(`Failed to unregister callback. Code: ${exception.code}, message: ${exception.message}`); 1732} 1733``` 1734 1735### getLiveCreaseRegion<sup>20+</sup> 1736getLiveCreaseRegion(): FoldCreaseRegion 1737 1738Obtains the live crease region of the foldable device in the current display mode. 1739 1740**System capability**: SystemCapability.Window.SessionManager 1741 1742**Return value** 1743 1744| Type | Description | 1745| ------------------- | ------------------------- | 1746| [FoldCreaseRegion](#foldcreaseregion10) | Live crease region of the device.| 1747 1748**Error codes** 1749 1750For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1751 1752| ID| Error Message| 1753| ------- | ----------------------- | 1754| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1755| 1400003 | This display manager service works abnormally. | 1756 1757**Example** 1758 1759```ts 1760import { display } from '@kit.ArkUI'; 1761 1762let displayClass: display.Display | null = null; 1763try { 1764 displayClass = display.getDefaultDisplaySync(); 1765 let data: display.FoldCreaseRegion = displayClass.getLiveCreaseRegion(); 1766 console.info('Succeeded in getting the live crease region. Data: ' + JSON.stringify(data)); 1767} catch (exception) { 1768 console.error(`Failed to get the live crease region. Code: ${exception.code}, message: ${exception.message}`); 1769} 1770``` 1771
