1# @ohos.screen (Screen) 2 3The **Screen** module implements basic screen management. You can use the APIs of this module to obtain a **Screen** object, listen for screen changes, and create and destroy virtual screens. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> The APIs provided by this module are system APIs. 10 11## Modules to Import 12 13```js 14import screen from '@ohos.screen'; 15``` 16 17## screen.getAllScreens 18 19getAllScreens(callback: AsyncCallback<Array<Screen>>): void 20 21Obtains all screens. This API uses an asynchronous callback to return the result. 22 23**System capability**: SystemCapability.WindowManager.WindowManager.Core 24 25**Parameters** 26 27| Name | Type | Mandatory| Description | 28| -------- | --------------------------------------------------- | ---- | -------------------------------------- | 29| callback | AsyncCallback<Array<[Screen](#screen)>> | Yes | Callback used to return all the **Screen** objects obtained.| 30 31**Error codes** 32 33For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 34 35| ID| Error Message| 36| ------- | ----------------------- | 37| 1400001 | Invalid display or screen. | 38 39**Example** 40 41```js 42let screenClass = null; 43screen.getAllScreens((err, data) => { 44 if (err.code) { 45 console.error('Failed to get all screens. Cause: ' + JSON.stringify(err)); 46 return; 47 } 48 console.info('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 49 screenClass = data[0]; 50}); 51``` 52 53## screen.getAllScreens 54 55getAllScreens(): Promise<Array<Screen>> 56 57Obtains all screens. This API uses a promise to return the result. 58 59**System capability**: SystemCapability.WindowManager.WindowManager.Core 60 61**Return value** 62 63| Type | Description | 64| --------------------------------------------- | ----------------------------------------- | 65| Promise<Array<[Screen](#screen)>> | Promise used to return all the **Screen** objects obtained.| 66 67**Error codes** 68 69For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 70 71| ID| Error Message| 72| ------- | ----------------------- | 73| 1400001 | Invalid display or screen. | 74 75**Example** 76 77```js 78let screenClass = null; 79let promise = screen.getAllScreens(); 80promise.then((data) => { 81 screenClass = data[0]; 82 console.log('Succeeded in getting all screens. Data:'+ JSON.stringify(data)); 83}).catch((err) => { 84 console.log('Failed to get all screens. Cause: ' + JSON.stringify(err)); 85}); 86``` 87 88## screen.on('connect' | 'disconnect' | 'change') 89 90on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void 91 92Subscribes to events related to the screen state. 93 94**System capability**: SystemCapability.WindowManager.WindowManager.Core 95 96**Parameters** 97 98| Name | Type | Mandatory| Description | 99| --------- | ---------------------- | ---- | ------------------------------------------------------------ | 100| eventType | string | Yes | Event type.<br>- **connect**: an event indicating that the screen is connected.<br>- **disconnect**: an event indicating that the screen is disconnected.<br>- **change**: an event indicating that the screen state changes.| 101| callback | Callback<number> | Yes | Callback used to return the screen ID. | 102 103**Example** 104 105```js 106try { 107 let callback = (data) => { 108 console.info('Succeeded in registering the callback for screen changes. Data: ' + JSON.stringify(data)) 109 }; 110 screen.on('connect', callback); 111} catch (exception) { 112 console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception)); 113}; 114``` 115 116## screen.off('connect' | 'disconnect' | 'change') 117 118off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void 119 120Unsubscribes from events related to the screen state. 121 122**System capability**: SystemCapability.WindowManager.WindowManager.Core 123 124**Parameters** 125 126| Name | Type | Mandatory| Description | 127| --------- | ---------------------- | ---- | ------------------------------------------------------------ | 128| eventType | string | Yes | Event type.<br>- **connect**: an event indicating that the screen is connected.<br>- **disconnect**: an event indicating that the screen is disconnected.<br>- **change**: an event indicating that the screen state changes.| 129| callback | Callback<number> | No | Callback used to return the screen ID. | 130 131**Example** 132 133```js 134try { 135 let callback = (data) => { 136 console.info('Succeeded in unregistering the callback for screen changes. Data: ' + JSON.stringify(data)) 137 }; 138 screen.off('connect', callback); 139} catch (exception) { 140 console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception)); 141}; 142``` 143 144## screen.makeExpand 145 146makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void 147 148Sets the screen to the expanded mode. This API uses an asynchronous callback to return the result. 149 150**System capability**: SystemCapability.WindowManager.WindowManager.Core 151 152**Parameters** 153 154| Name | Type | Mandatory| Description | 155| -------- | ------------------------------------------ | ---- | -------------------------------- | 156| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen. | 157| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the expanded screens.| 158 159**Error codes** 160 161For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 162 163| ID| Error Message| 164| ------- | ----------------------- | 165| 1400001 | Invalid display or screen. | 166 167**Example** 168 169```js 170try { 171 let groupId = null; 172 screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 1080, startY: 0}], (err, data) => { 173 if (err.code) { 174 console.error('Failed to expand the screen. Code:' + JSON.stringify(err)); 175 return; 176 } 177 groupId = data; 178 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 179 }); 180} catch (exception) { 181 console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception)); 182}; 183``` 184 185## screen.makeExpand 186 187makeExpand(options:Array<ExpandOption>): Promise<number> 188 189Sets the screen to the expanded mode. This API uses a promise to return the result. 190 191**System capability**: SystemCapability.WindowManager.WindowManager.Core 192 193**Parameters** 194 195| Name | Type | Mandatory| Description | 196| ------- | ------------------------------------------ | ---- | ------------------------ | 197| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen.| 198 199**Return value** 200 201| Type | Description | 202| --------------------- | ----------------------------------- | 203| Promise<number> | Promise used to return the group ID of the expanded screens.| 204 205**Error codes** 206 207For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 208 209| ID| Error Message| 210| ------- | ----------------------- | 211| 1400001 | Invalid display or screen. | 212 213**Example** 214 215```js 216try { 217 screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 1080, startY: 0}]).then((data) => { 218 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 219 }).catch((err) => { 220 console.error('Failed to expand the screen. Code:' + JSON.stringify(err)); 221 }); 222} catch (exception) { 223 console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception)); 224}; 225``` 226 227## screen.makeMirror 228 229makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void 230 231Sets screen mirroring. This API uses an asynchronous callback to return the result. 232 233**System capability**: SystemCapability.WindowManager.WindowManager.Core 234 235**Parameters** 236 237| Name | Type | Mandatory| Description | 238| ------------ | --------------------------- | ---- |-----------------| 239| mainScreen | number | Yes | ID of the primary screen. | 240| mirrorScreen | Array<number> | Yes | IDs of secondary screens. | 241| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the secondary screens.| 242 243**Error codes** 244 245For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 246 247| ID| Error Message| 248| ------- | ----------------------- | 249| 1400001 | Invalid display or screen. | 250 251**Example** 252 253```js 254let mainScreenId = 0; 255let mirrorScreenIds = [1, 2, 3]; 256try { 257 screen.makeMirror(mainScreenId, mirrorScreenIds, (err, data) => { 258 if (err.code) { 259 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err)); 260 return; 261 } 262 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 263 }); 264} catch (exception) { 265 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception)); 266}; 267``` 268 269## screen.makeMirror 270 271makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number> 272 273Sets screen mirroring. This API uses a promise to return the result. 274 275**System capability**: SystemCapability.WindowManager.WindowManager.Core 276 277**Parameters** 278 279| Name | Type | Mandatory| Description | 280| ------------ | ------------------- | ---- |-----------| 281| mainScreen | number | Yes | ID of the primary screen. | 282| mirrorScreen | Array<number> | Yes | IDs of secondary screens.| 283 284**Return value** 285 286| Type | Description | 287| --------------------- | ----------------------------------- | 288| Promise<number> | Promise used to return the group ID of the secondary screens.| 289 290**Error codes** 291 292For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 293 294| ID| Error Message| 295| ------- | ----------------------- | 296| 1400001 | Invalid display or screen. | 297 298**Example** 299 300```js 301let mainScreenId = 0; 302let mirrorScreenIds = [1, 2, 3]; 303try { 304 screen.makeMirror(mainScreenId, mirrorScreenIds).then((data) => { 305 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 306 }).catch((err) => { 307 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err)); 308 }); 309} catch (exception) { 310 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception)); 311}; 312``` 313 314## screen.createVirtualScreen 315 316createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void 317 318Creates a virtual screen. This API uses an asynchronous callback to return the result. 319 320**System capability**: SystemCapability.WindowManager.WindowManager.Core 321 322**Required permissions**: ohos.permission.CAPTURE_SCREEN (mandatory when **VirtualScreenOption.surfaceId** is valid; available only to system applications) 323 324**Parameters** 325 326| Name | Type | Mandatory| Description | 327| -------- | ------------------------------------------- | ---- | ---------------------------------- | 328| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters. | 329| callback | AsyncCallback<[Screen](#screen)> | Yes | Callback used to return the created virtual screen.| 330 331**Error codes** 332 333For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 334 335| ID| Error Message| 336| ------- | ----------------------- | 337| 1400001 | Invalid display or screen. | 338 339**Example** 340 341```js 342let screenClass = null; 343try { 344 screen.createVirtualScreen({ 345 name: 'screen01', 346 width: 1080, 347 height: 2340, 348 density: 2, 349 surfaceId: '' 350 }, (err, data) => { 351 if (err.code) { 352 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err)); 353 return; 354 } 355 screenClass = data; 356 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 357 }); 358} catch (exception) { 359 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception)); 360}; 361``` 362 363## screen.createVirtualScreen 364 365createVirtualScreen(options:VirtualScreenOption): Promise<Screen> 366 367Creates a virtual screen. This API uses a promise to return the result. 368 369**System capability**: SystemCapability.WindowManager.WindowManager.Core 370 371**Required permissions**: ohos.permission.CAPTURE_SCREEN (mandatory when **VirtualScreenOption.surfaceId** is valid; available only to system applications) 372 373**Parameters** 374 375| Name | Type | Mandatory| Description | 376| ------- | ------------------------------------------- | ---- | ------------------------ | 377| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters.| 378 379**Return value** 380 381| Type | Description | 382| -------------------------------- | ------------------------------------- | 383| Promise<[Screen](#screen)> | Promise used to return the created virtual screen.| 384 385**Error codes** 386 387For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 388 389| ID| Error Message| 390| ------- | ----------------------- | 391| 1400001 | Invalid display or screen. | 392 393**Example** 394 395```js 396let screenClass = null; 397try { 398 screen.createVirtualScreen({ 399 name: 'screen01', 400 width: 1080, 401 height: 2340, 402 density: 2, 403 surfaceId: '' 404 }).then((data) => { 405 screenClass = data; 406 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 407 }).catch((err) => { 408 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err)); 409 }); 410} catch (exception) { 411 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception)); 412}; 413``` 414 415## screen.destroyVirtualScreen 416 417destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void 418 419Destroys a virtual screen. This API uses an asynchronous callback to return the result. 420 421**System capability**: SystemCapability.WindowManager.WindowManager.Core 422 423**Parameters** 424 425| Name | Type | Mandatory| Description | 426| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 427| screenId | number | Yes | Screen ID. | 428| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the virtual screen is destroyed, **err** is **undefined**; otherwise, **err** is an error object.| 429 430**Error codes** 431 432For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 433 434| ID| Error Message| 435| ------- | ----------------------------- | 436| 1400002 | Unauthorized operation. | 437 438**Example** 439 440```js 441let screenId = 1; 442try { 443 screen.destroyVirtualScreen(screenId, (err,data) => { 444 if (err.code) { 445 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err)); 446 return; 447 } 448 console.info('Succeeded in destroying the virtual screen.'); 449 }); 450} catch (exception) { 451 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception)); 452}; 453``` 454 455## screen.destroyVirtualScreen 456 457destroyVirtualScreen(screenId:number): Promise<void> 458 459Destroys a virtual screen. This API uses a promise to return the result. 460 461**System capability**: SystemCapability.WindowManager.WindowManager.Core 462 463**Parameters** 464 465| Name | Type | Mandatory| Description | 466| -------- | ------ | ---- | ---------- | 467| screenId | number | Yes | Screen ID.| 468 469**Return value** 470 471| Type | Description | 472| ------------------- | ------------------------- | 473| Promise<void> | Promise that returns no value.| 474 475**Error codes** 476 477For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 478 479| ID| Error Message| 480| ------- | ----------------------------- | 481| 1400002 | Unauthorized operation. | 482 483**Example** 484 485```js 486let screenId = 1; 487try { 488 screen.destroyVirtualScreen(screenId).then((data) => { 489 console.info('Succeeded in destroying the virtual screen.'); 490 }).catch((err) => { 491 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err)); 492 }); 493} catch (exception) { 494 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception)); 495}; 496``` 497 498## screen.setVirtualScreenSurface 499 500setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void 501 502Sets the surface for a virtual screen. This API uses an asynchronous callback to return the result. 503 504**System capability**: SystemCapability.WindowManager.WindowManager.Core 505 506**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 507 508**Parameters** 509 510| Name | Type | Mandatory| Description | 511| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 512| screenId | number | Yes | Screen ID. | 513| surfaceId | string | Yes | Surface ID. | 514| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the virtual screen surface is successfully set, **err** is **undefined**; otherwise, **err** is an error object.| 515 516**Error codes** 517 518For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 519 520| ID| Error Message| 521| ------- | ----------------------- | 522| 1400001 | Invalid display or screen. | 523 524**Example** 525 526```js 527let screenId = 1; 528let surfaceId = '2048'; 529try { 530 screen.setVirtualScreenSurface(screenId, surfaceId, (err,data) => { 531 if (err.code) { 532 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err)); 533 return; 534 } 535 console.info('Succeeded in setting the surface for the virtual screen.'); 536 }); 537} catch (exception) { 538 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception)); 539}; 540``` 541 542## screen.setVirtualScreenSurface 543 544setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 545 546Sets the surface for a virtual screen. This API uses a promise to return the result. 547 548**System capability**: SystemCapability.WindowManager.WindowManager.Core 549 550**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 551 552**Parameters** 553 554| Name | Type | Mandatory| Description | 555| --------- | ------ | ---- | ------------- | 556| screenId | number | Yes | Screen ID. | 557| surfaceId | string | Yes | Surface ID.| 558 559**Return value** 560 561| Type | Description | 562| ------------------- | ------------------------- | 563| Promise<void> | Promise that returns no value.| 564 565**Error codes** 566 567For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 568 569| ID| Error Message| 570| ------- | ----------------------- | 571| 1400001 | Invalid display or screen. | 572 573**Example** 574 575```js 576let screenId = 1; 577let surfaceId = '2048'; 578try { 579 screen.setVirtualScreenSurface(screenId, surfaceId).then((data) => { 580 console.info('Succeeded in setting the surface for the virtual screen.'); 581 }).catch((err) => { 582 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err)); 583 }); 584} catch (exception) { 585 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception)); 586}; 587``` 588 589## screen.isScreenRotationLocked 590 591isScreenRotationLocked(): Promise<boolean> 592 593Checks whether auto rotate is locked. This API uses a promise to return the result. 594 595**System capability**: SystemCapability.WindowManager.WindowManager.Core 596 597**Return value** 598 599| Type | Description | 600| ---------------------- | ------------------------------------- | 601| Promise<boolean> | Promise used to return the result. If **true** is returned, auto rotate is locked. If **false** is returned, auto rotate is unlocked.| 602 603**Example** 604 605```js 606screen.isScreenRotationLocked().then((isLocked) => { 607 console.info('Succeeded in getting the screen rotation lock status. isLocked:'+ JSON.stringify(isLocked)); 608}).catch((err) => { 609 console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err)); 610}); 611``` 612 613## screen.isScreenRotationLocked 614 615isScreenRotationLocked(callback: AsyncCallback<boolean>): void 616 617Checks whether auto rotate is locked. This API uses an asynchronous callback to return the result. 618 619**System capability**: SystemCapability.WindowManager.WindowManager.Core 620 621**Parameters** 622 623| Name | Type | Mandatory| Description | 624| --------- | ---------------------------- | ---- | ------------------------------------------------------------ | 625| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If **true** is returned, auto rotate is locked. If **false** is returned, auto rotate is unlocked.| 626 627**Example** 628 629```js 630screen.isScreenRotationLocked((err, isLocked) => { 631 if (err.code) { 632 console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err)); 633 return; 634 } 635 console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 636}); 637``` 638 639## screen.setScreenRotationLocked 640 641setScreenRotationLocked(isLocked: boolean): Promise<void> 642 643Sets whether to lock auto rotate. This API uses a promise to return the result. 644 645**System capability**: SystemCapability.WindowManager.WindowManager.Core 646 647**Parameters** 648 649| Name | Type | Mandatory| Description | 650| --------- | ------ | ---- | ------------- | 651| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite.| 652 653**Return value** 654 655| Type | Description | 656| ------------------- | ------------------------- | 657| Promise<void> | Promise that returns no value.| 658 659**Example** 660 661```js 662let isLocked = false; 663try { 664 screen.setScreenRotationLocked(isLocked).then((data) => { 665 console.info('Succeeded in unlocking auto rotate'); 666 }).catch((err) => { 667 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(err)); 668 }); 669} catch (exception) { 670 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception)); 671}; 672``` 673 674## screen.setScreenRotationLocked 675 676setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void 677 678Sets whether to lock auto rotate. This API uses an asynchronous callback to return the result. 679 680**System capability**: SystemCapability.WindowManager.WindowManager.Core 681 682**Parameters** 683 684| Name | Type | Mandatory| Description | 685| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 686| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite. | 687| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 688 689**Example** 690 691```js 692let isLocked = false; 693try { 694 screen.setScreenRotationLocked(isLocked, (err, data) => { 695 if (err.code) { 696 console.error('Failed to unlock auto rotate. Cause:' + JSON.stringify(err)); 697 return; 698 } 699 console.info('Succeeded in unlocking auto rotate.'); 700 }); 701} catch (exception) { 702 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception)); 703}; 704``` 705 706## ExpandOption 707 708Defines the parameters for expanding a screen. 709 710**System capability**: SystemCapability.WindowManager.WindowManager.Core 711 712| Name | Type| Readable| Writable| Description | 713| -------- | -------- | ---- | ---- | ------------------- | 714| screenId | number | Yes | Yes | Screen ID. | 715| startX | number | Yes | Yes | Start X coordinate of the screen.| 716| startY | number | Yes | Yes | Start Y coordinate of the screen.| 717 718## VirtualScreenOption 719 720Defines virtual screen parameters. 721 722**System capability**: SystemCapability.WindowManager.WindowManager.Core 723 724| Name | Type| Readable| Writable| Description | 725| --------- | -------- | ---- | ---- | ------------------------- | 726| name | string | Yes | Yes | Name of a virtual screen. | 727| width | number | Yes | Yes | Width of the virtual screen, in pixels.| 728| height | number | Yes | Yes | Height of the virtual screen, in pixels.| 729| density | number | Yes | Yes | Density of the virtual screen. | 730| surfaceId | string | Yes | Yes | Surface ID of the virtual screen.| 731 732## Screen 733 734Implements a **Screen** instance. 735 736Before calling any API in **Screen**, you must use **[getAllScreens()](#screengetallscreens)** or **[createVirtualScreen()](#screencreatevirtualscreen)** to obtain a **Screen** instance. 737 738**System capability**: SystemCapability.WindowManager.WindowManager.Core 739 740| Name | Type | Readable| Writable| Description | 741| ----------------- | ---------------------------------------------- | ---- | ---- | ---------------------- | 742| id | number | Yes | No | Screen ID. | 743| parent | number | Yes | No | ID of the group to which a screen belongs. | 744| supportedModeInfo | Array<[ScreenModeInfo](#screenmodeinfo)> | Yes | No | Mode set supported by the screen. | 745| activeModeIndex | number | Yes | No | Index of the active screen mode.| 746| orientation | [Orientation](#orientation) | Yes | No | Screen orientation. | 747 748### setOrientation 749 750setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 751 752Sets the screen orientation. This API uses an asynchronous callback to return the result. 753 754**System capability**: SystemCapability.WindowManager.WindowManager.Core 755 756| Name | Type | Mandatory| Description | 757| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 758| orientation | [Orientation](#orientation) | Yes | Screen orientation. | 759| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the screen orientation is successfully set, **err** is **undefined**; otherwise, **err** is an error object.| 760 761**Error codes** 762 763For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 764 765| ID| Error Message| 766| ------- | -------------------------------------------- | 767| 1400003 | This display manager service works abnormally. | 768 769**Example** 770 771```js 772try { 773 screenClass.setOrientation(screen.Orientation.VERTICAL, (err, data) => { 774 if (err.code) { 775 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(err)); 776 return; 777 } 778 console.info('Succeeded in setting the vertical orientation. data: ' + JSON.stringify(data)); 779 }); 780} catch (exception) { 781 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception)); 782}; 783``` 784 785### setOrientation 786 787setOrientation(orientation: Orientation): Promise<void> 788 789Sets the screen orientation. This API uses a promise to return the result. 790 791**System capability**: SystemCapability.WindowManager.WindowManager.Core 792 793| Name | Type | Mandatory| Description | 794| ----------- | --------------------------- | ---- | ---------- | 795| orientation | [Orientation](#orientation) | Yes | Screen orientation.| 796 797**Return value** 798 799| Type | Description | 800| ------------------- | ------------------------- | 801| Promise<void> | Promise that returns no value.| 802 803**Error codes** 804 805For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 806 807| ID| Error Message| 808| ------- | -------------------------------------------- | 809| 1400003 | This display manager service works abnormally. | 810 811**Example** 812 813```js 814try { 815 let promise = screenClass.setOrientation(screen.Orientation.VERTICAL); 816 promise.then((data) => { 817 console.info('Succeeded in setting the vertical orientation. Data: ' + JSON.stringify(data)); 818 }).catch((err) => { 819 console.error('Failed to set the vertical orientation. Cause: ' + JSON.stringify(err)); 820 }); 821} catch (exception) { 822 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception)); 823}; 824``` 825 826### setScreenActiveMode 827 828setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void 829 830Sets the active mode of the screen. This API uses an asynchronous callback to return the result. 831 832**System capability**: SystemCapability.WindowManager.WindowManager.Core 833 834| Name | Type | Mandatory| Description | 835| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 836| modeIndex | number | Yes | Index of the mode to set. | 837| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the active mode is successfully set, **err** is **undefined**; otherwise, **err** is an error object.| 838 839**Error codes** 840 841For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 842 843| ID| Error Message| 844| ------- | -------------------------------------------- | 845| 1400003 | This display manager service works abnormally. | 846 847**Example** 848 849```js 850let modeIndex = 0; 851try { 852 screenClass.setScreenActiveMode(modeIndex, (err, data) => { 853 if (err.code) { 854 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err)); 855 return; 856 } 857 console.info('Succeeded in setting screen active mode 0. data: ' + JSON.stringify(data)); 858 }); 859} catch (exception) { 860 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception)); 861}; 862``` 863 864### setScreenActiveMode 865 866setScreenActiveMode(modeIndex: number): Promise<void> 867 868Sets the active mode of the screen. This API uses a promise to return the result. 869 870**System capability**: SystemCapability.WindowManager.WindowManager.Core 871 872| Name | Type | Mandatory| Description | 873| --------- | ------ | ---- | ---------- | 874| modeIndex | number | Yes | Index of the mode to set.| 875 876**Return value** 877 878| Type | Description | 879| ------------------- | ------------------------- | 880| Promise<void> | Promise that returns no value.| 881 882**Error codes** 883 884For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 885 886| ID| Error Message| 887| ------- | -------------------------------------------- | 888| 1400003 | This display manager service works abnormally. | 889 890**Example** 891 892```js 893let modeIndex = 0; 894try { 895 let promise = screenClass.setScreenActiveMode(modeIndex); 896 promise.then((data) => { 897 console.info('Succeeded in setting screen active mode 0. Data: ' + JSON.stringify(data)); 898 }).catch((err) => { 899 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err)); 900 }); 901} catch (exception) { 902 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception)); 903}; 904``` 905 906### setDensityDpi 907 908setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; 909 910Sets the pixel density of the screen. This API uses an asynchronous callback to return the result. 911 912**System capability**: SystemCapability.WindowManager.WindowManager.Core 913 914| Name | Type | Mandatory| Description | 915| ---------- | ------------------------- | ---- | ------------------------------------------------------------ | 916| densityDpi | number | Yes | Pixel density. The value ranges from 80 to 640. | 917| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the pixel density is successfully set, **err** is **undefined**; otherwise, **err** is an error object.| 918 919**Error codes** 920 921For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 922 923| ID| Error Message| 924| ------- | -------------------------------------------- | 925| 1400003 | This display manager service works abnormally. | 926 927**Example** 928 929```js 930let densityDpi = 320; 931try { 932 screenClass.setDensityDpi(densityDpi, (err, data) => { 933 if (err.code) { 934 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err)); 935 return; 936 } 937 console.info('Succeed in setting the pixel density of the screen to 320. data: ' + JSON.stringify(data)); 938 }); 939} catch (exception) { 940 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception)); 941}; 942``` 943 944### setDensityDpi 945 946setDensityDpi(densityDpi: number): Promise<void> 947 948Sets the pixel density of the screen. This API uses a promise to return the result. 949 950**System capability**: SystemCapability.WindowManager.WindowManager.Core 951 952| Name | Type | Mandatory| Description | 953| ---------- | ------ | ---- | ---------------------------------- | 954| densityDpi | number | Yes | Pixel density. The value ranges from 80 to 640.| 955 956**Return value** 957 958| Type | Description | 959| ------------------- | ------------------------- | 960| Promise<void> | Promise that returns no value.| 961 962**Error codes** 963 964For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 965 966| ID| Error Message| 967| ------- | -------------------------------------------- | 968| 1400003 | This display manager service works abnormally. | 969 970**Example** 971 972```js 973let densityDpi = 320; 974try { 975 let promise = screenClass.setDensityDpi(densityDpi); 976 promise.then((data) => { 977 console.info('Succeeded in setting the pixel density of the screen to 320. Data: ' + JSON.stringify(data)); 978 }).catch((err) => { 979 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err)); 980 }); 981} catch (exception) { 982 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception)); 983}; 984``` 985 986## Orientation 987 988Enumerates the screen orientations. 989 990**System capability**: SystemCapability.WindowManager.WindowManager.Core 991 992| Name | Value | Description | 993| ------------------ | ---- | -------------------------------- | 994| UNSPECIFIED | 0 | Unspecified. The screen orientation is determined by the system.| 995| VERTICAL | 1 | Vertical. | 996| HORIZONTAL | 2 | Horizontal. | 997| REVERSE_VERTICAL | 3 | Reverse vertical. | 998| REVERSE_HORIZONTAL | 4 | Reverse horizontal. | 999 1000## ScreenModeInfo 1001 1002Defines the screen mode information. 1003 1004**System capability**: SystemCapability.WindowManager.WindowManager.Core 1005 1006| Name | Type| Readable| Writable| Description | 1007| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1008| id | number | Yes | Yes | Mode ID. The supported mode is determined by the device resolution and refresh rate.| 1009| width | number | Yes | Yes | Width of the screen, in pixels. | 1010| height | number | Yes | Yes | Height of the screen, in pixels. | 1011| refreshRate | number | Yes | Yes | Screen refresh rate. | 1012