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```ts 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```ts 42import { BusinessError } from '@ohos.base'; 43 44let screenClass: screen.Screen | null = null; 45screen.getAllScreens((err: BusinessError, data: AsyncCallback<Array<Screen>>) => { 46 const errCode: number = err.code; 47 if (errCode) { 48 console.error('Failed to get all screens. Cause: ' + JSON.stringify(err)); 49 return; 50 } 51 console.info('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 52 screenClass = data[0]; 53}); 54``` 55 56## screen.getAllScreens 57 58getAllScreens(): Promise<Array<Screen>> 59 60Obtains all screens. This API uses a promise to return the result. 61 62**System capability**: SystemCapability.WindowManager.WindowManager.Core 63 64**Return value** 65 66| Type | Description | 67| --------------------------------------------- | ----------------------------------------- | 68| Promise<Array<[Screen](#screen)>> | Promise used to return all the **Screen** objects obtained.| 69 70**Error codes** 71 72For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 73 74| ID| Error Message| 75| ------- | ----------------------- | 76| 1400001 | Invalid display or screen. | 77 78**Example** 79 80```ts 81import { BusinessError } from '@ohos.base'; 82 83let screenClass: screen.Screen | null = null; 84let promise: Promise<Array<Screen>> = screen.getAllScreens(); 85promise.then((data: Array<Screen>) => { 86 screenClass = data[0]; 87 console.log('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 88}).catch((err: BusinessError) => { 89 console.log('Failed to get all screens. Cause: ' + JSON.stringify(err)); 90}); 91``` 92 93## screen.on('connect' | 'disconnect' | 'change') 94 95on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void 96 97Subscribes to events related to the screen state. 98 99**System capability**: SystemCapability.WindowManager.WindowManager.Core 100 101**Parameters** 102 103| Name | Type | Mandatory| Description | 104| --------- | ---------------------- | ---- | ----------------------------------------------------------- | 105| 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.| 106| callback | Callback<number> | Yes | Callback used to return the screen ID, which is an integer. | 107 108**Example** 109 110```ts 111try { 112 let callback: Callback<number> = (data: Callback<number>) => { 113 console.info('Succeeded in registering the callback for screen changes. Data: ' + JSON.stringify(data)) 114 }; 115 screen.on('connect', callback); 116} catch (exception) { 117 console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception)); 118}; 119``` 120 121## screen.off('connect' | 'disconnect' | 'change') 122 123off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void 124 125Unsubscribes from events related to the screen state. 126 127**System capability**: SystemCapability.WindowManager.WindowManager.Core 128 129**Parameters** 130 131| Name | Type | Mandatory| Description | 132| --------- | ---------------------- | ---- | ------------------------------------------------------------ | 133| 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.| 134| callback | Callback<number> | No | Callback used to return the screen ID, which is an integer. | 135 136**Example** 137 138```ts 139try { 140 let callback: Callback<number> = (data: Callback<number>) => { 141 console.info('Succeeded in unregistering the callback for screen changes. Data: ' + JSON.stringify(data)) 142 }; 143 screen.off('connect', callback); 144} catch (exception) { 145 console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception)); 146}; 147``` 148 149## screen.makeExpand 150 151makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void 152 153Sets the screen to the expanded mode. This API uses an asynchronous callback to return the result. 154 155**System capability**: SystemCapability.WindowManager.WindowManager.Core 156 157**Parameters** 158 159| Name | Type | Mandatory| Description | 160| -------- | ------------------------------------------ | ---- |----------------------------| 161| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen. | 162| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the expanded screens, which is an integer.| 163 164**Error codes** 165 166For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 167 168| ID| Error Message| 169| ------- | ----------------------- | 170| 1400001 | Invalid display or screen. | 171 172**Example** 173 174```ts 175import { BusinessError } from '@ohos.base'; 176 177try { 178 let groupId: number | null = null; 179 class ExpandOption { 180 screenId: number = 0; 181 startX: number = 0; 182 startY: number = 0; 183 } 184 let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 }; 185 let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 }; 186 let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ]; 187 screen.makeExpand(expandOptionArray, (err: BusinessError, data: AsyncCallback<number>) => { 188 const errCode: number = err.code; 189 if (errCode) { 190 console.error('Failed to expand the screen. Code:' + JSON.stringify(err)); 191 return; 192 } 193 groupId = data; 194 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 195 }); 196} catch (exception) { 197 console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception)); 198}; 199``` 200 201## screen.makeExpand 202 203makeExpand(options:Array<ExpandOption>): Promise<number> 204 205Sets the screen to the expanded mode. This API uses a promise to return the result. 206 207**System capability**: SystemCapability.WindowManager.WindowManager.Core 208 209**Parameters** 210 211| Name | Type | Mandatory| Description | 212| ------- | ------------------------------------------ | ---- | ------------------------ | 213| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen.| 214 215**Return value** 216 217| Type | Description | 218| --------------------- |---------------------------------| 219| Promise<number> | Promise used to return the group ID of the expanded screens, which is an integer.| 220 221**Error codes** 222 223For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 224 225| ID| Error Message| 226| ------- | ----------------------- | 227| 1400001 | Invalid display or screen. | 228 229**Example** 230 231```ts 232import { BusinessError } from '@ohos.base'; 233 234try { 235 class ExpandOption { 236 screenId: number = 0; 237 startX: number = 0; 238 startY: number = 0; 239 } 240 let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 }; 241 let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 }; 242 let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ]; 243 screen.makeExpand(expandOptionArray).then(( 244 data: Promise<number>) => { 245 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 246 }).catch((err: BusinessError) => { 247 console.error('Failed to expand the screen. Code:' + JSON.stringify(err)); 248 }); 249} catch (exception) { 250 console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception)); 251}; 252``` 253 254## screen.stopExpand<sup>10+</sup> 255 256stopExpand(expandScreen:Array<number>, callback: AsyncCallback<void>): void 257 258Stops the expanded mode. This API uses an asynchronous callback to return the result. 259 260**System capability**: SystemCapability.WindowManager.WindowManager.Core 261 262**Parameters** 263 264| Name| Type| Mandatory| Description | 265| ------------ | --------------------------- | --- |-----------------------------------------| 266| expandScreen | Array<number> | Yes | IDs of the expanded screens. Each ID must be an integer. | 267| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the expanded mode is stopped, **err** is **undefined**; otherwise, **err** is an error object.| 268 269**Error codes** 270 271For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 272 273| ID| Error Message| 274| ------- | ----------------------- | 275| 1400001 | Invalid display or screen. | 276 277**Example** 278 279```ts 280import { BusinessError } from '@ohos.base'; 281 282try { 283 let expandScreenIds: Array<number> = [1, 2, 3]; 284 screen.stopExpand(expandScreenIds, (err: BusinessError) => { 285 const errCode: number = err.code; 286 if (errCode) { 287 console.error('Failed to stop expand screens. Code:' + JSON.stringify(err)); 288 return; 289 } 290 console.info('Succeeded in stopping expand screens.'); 291 }); 292} catch (exception) { 293 console.error('Failed to stop expand screens. Code: ' + JSON.stringify(exception)); 294}; 295``` 296 297## screen.stopExpand<sup>10+</sup> 298 299stopExpand(expandScreen:Array<number>): Promise<void> 300 301Stops the expanded mode. This API uses a promise to return the result. 302 303**System capability**: SystemCapability.WindowManager.WindowManager.Core 304 305**Parameters** 306 307| Name| Type| Mandatory| Description | 308| ------------ | ------------------- | --- |--------------------| 309| expandScreen | Array<number> | Yes | IDs of the expanded screens. Each ID must be an integer.| 310 311**Return value** 312 313| Type| Description| 314| --------------------- | ----------------------- | 315| Promise<void> | Promise that returns no value.| 316 317**Error codes** 318 319For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 320 321| ID| Error Message| 322| ------- | ----------------------- | 323| 1400001 | Invalid display or screen. | 324 325**Example** 326 327```ts 328import { BusinessError } from '@ohos.base'; 329 330try { 331 let expandScreenIds: Array<number> = [1, 2, 3]; 332 screen.stopExpand(expandScreenIds).then(() => { 333 console.info('Succeeded in stopping expand screens.'); 334 }).catch((err: BusinessError) => { 335 console.error('Failed to stop expand screens. Code:' + JSON.stringify(err)); 336 }); 337} catch (exception) { 338 console.error('Failed to stop expand screens. Code:' + JSON.stringify(exception)); 339}; 340``` 341 342## screen.makeMirror 343 344makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void 345 346Sets screen mirroring. This API uses an asynchronous callback to return the result. 347 348**System capability**: SystemCapability.WindowManager.WindowManager.Core 349 350**Parameters** 351 352| Name | Type | Mandatory| Description | 353| ------------ | --------------------------- | ---- |--------------------| 354| mainScreen | number | Yes | ID of the primary screen. The value must be an integer. | 355| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer.| 356| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the secondary screens, which is an integer. | 357 358**Error codes** 359 360For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 361 362| ID| Error Message| 363| ------- | ----------------------- | 364| 1400001 | Invalid display or screen. | 365 366**Example** 367 368```ts 369import { BusinessError } from '@ohos.base'; 370 371let mainScreenId: number = 0; 372let mirrorScreenIds: Array<number> = [1, 2, 3]; 373try { 374 screen.makeMirror(mainScreenId, mirrorScreenIds, (err: BusinessError, data: AsyncCallback<number>) => { 375 const errCode: number = err.code; 376 if (errCode) { 377 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err)); 378 return; 379 } 380 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 381 }); 382} catch (exception) { 383 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception)); 384}; 385``` 386 387## screen.makeMirror 388 389makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number> 390 391Sets screen mirroring. This API uses a promise to return the result. 392 393**System capability**: SystemCapability.WindowManager.WindowManager.Core 394 395**Parameters** 396 397| Name | Type | Mandatory| Description | 398| ------------ | ------------------- | ---- |--------------------| 399| mainScreen | number | Yes | ID of the primary screen. The value must be an integer. | 400| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer.| 401 402**Return value** 403 404| Type | Description | 405| --------------------- |---------------------------------| 406| Promise<number> | Promise used to return the group ID of the secondary screens, which is an integer.| 407 408**Error codes** 409 410For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 411 412| ID| Error Message| 413| ------- | ----------------------- | 414| 1400001 | Invalid display or screen. | 415 416**Example** 417 418```ts 419import { BusinessError } from '@ohos.base'; 420 421let mainScreenId: number = 0; 422let mirrorScreenIds: Array<number> = [1, 2, 3]; 423try { 424 screen.makeMirror(mainScreenId, mirrorScreenIds).then((data: Promise<number>) => { 425 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 426 }).catch((err: BusinessError) => { 427 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err)); 428 }); 429} catch (exception) { 430 console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception)); 431}; 432``` 433 434## screen.stopMirror<sup>10+</sup> 435 436stopMirror(mirrorScreen:Array<number>, callback: AsyncCallback<void>): void 437 438Stops screen mirroring. This API uses an asynchronous callback to return the result. 439 440**System capability**: SystemCapability.WindowManager.WindowManager.Core 441 442**Parameters** 443 444| Name| Type| Mandatory| Description | 445| ------------ | --------------------------- | --- |-----------------------------------------| 446| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer. | 447| callback | AsyncCallback<void> | Yes | Callback used to return the result. If screen mirroring is stopped, **err** is **undefined**; otherwise, **err** is an error object.| 448 449**Error codes** 450 451For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 452 453| ID| Error Message| 454| ------- | ----------------------- | 455| 1400001 | Invalid display or screen. | 456 457**Example** 458 459```ts 460import { BusinessError } from '@ohos.base'; 461 462try { 463 let mirrorScreenIds: Array<number> = [1, 2, 3]; 464 screen.stopMirror(mirrorScreenIds, (err: BusinessError) => { 465 const errCode: number = err.code; 466 if (errCode) { 467 console.error('Failed to stop mirror screens. Code:' + JSON.stringify(err)); 468 return; 469 } 470 console.info('Succeeded in stopping mirror screens.'); 471 }); 472} catch (exception) { 473 console.error('Failed to stop mirror screens. Code: ' + JSON.stringify(exception)); 474}; 475``` 476 477## screen.stopMirror<sup>10+</sup> 478 479stopMirror(mirrorScreen:Array<number>): Promise<void> 480 481Stops screen mirroring. This API uses a promise to return the result. 482 483**System capability**: SystemCapability.WindowManager.WindowManager.Core 484 485**Parameters** 486 487| Name| Type| Mandatory| Description | 488| ------------ | ------------------- | --- |--------------------| 489| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer.| 490 491**Return value** 492 493| Type| Description| 494| --------------------- | ----------------------- | 495| Promise<void> | Promise that returns no value.| 496 497**Error codes** 498 499For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 500 501| ID| Error Message| 502| ------- | ----------------------- | 503| 1400001 | Invalid display or screen. | 504 505**Example** 506 507```ts 508import { BusinessError } from '@ohos.base'; 509 510try { 511 let mirrorScreenIds: Array<number> = [1, 2, 3]; 512 screen.stopMirror(mirrorScreenIds).then(() => { 513 console.info('Succeeded in stopping mirror screens.'); 514 }).catch((err: BusinessError) => { 515 console.error('Failed to stop mirror screens. Code:' + JSON.stringify(err)); 516 }); 517} catch (exception) { 518 console.error('Failed to stop mirror screens. Code:' + JSON.stringify(exception)); 519}; 520``` 521 522## screen.createVirtualScreen 523 524createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void 525 526Creates a virtual screen. This API uses an asynchronous callback to return the result. 527 528**System capability**: SystemCapability.WindowManager.WindowManager.Core 529 530**Required permissions**: ohos.permission.CAPTURE_SCREEN (mandatory when **VirtualScreenOption.surfaceId** is valid; available only to system applications) 531 532**Parameters** 533 534| Name | Type | Mandatory| Description | 535| -------- | ------------------------------------------- | ---- | ---------------------------------- | 536| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters. | 537| callback | AsyncCallback<[Screen](#screen)> | Yes | Callback used to return the created virtual screen.| 538 539**Error codes** 540 541For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 542 543| ID| Error Message| 544| ------- | ----------------------- | 545| 1400001 | Invalid display or screen. | 546 547**Example** 548 549```ts 550import { BusinessError } from '@ohos.base'; 551 552let screenClass: screen.Screen | null = null; 553try { 554 class VirtualScreenOption { 555 name : string = ''; 556 width : number = 0; 557 height : number = 0; 558 density : number = 0; 559 surfaceId : string = ''; 560 } 561 562 let option : VirtualScreenOption = { 563 name: 'screen01', 564 width: 1080, 565 height: 2340, 566 density: 2, 567 surfaceId: '' 568 }; 569 screen.createVirtualScreen(option, (err: BusinessError, data: AsyncCallback<Screen>) => { 570 const errCode: number = err.code; 571 if (errCode) { 572 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err)); 573 return; 574 } 575 screenClass = data; 576 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 577 }); 578} catch (exception) { 579 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception)); 580}; 581``` 582 583## screen.createVirtualScreen 584 585createVirtualScreen(options:VirtualScreenOption): Promise<Screen> 586 587Creates a virtual screen. This API uses a promise to return the result. 588 589**System capability**: SystemCapability.WindowManager.WindowManager.Core 590 591**Required permissions**: ohos.permission.CAPTURE_SCREEN (mandatory when **VirtualScreenOption.surfaceId** is valid; available only to system applications) 592 593**Parameters** 594 595| Name | Type | Mandatory| Description | 596| ------- | ------------------------------------------- | ---- | ------------------------ | 597| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters.| 598 599**Return value** 600 601| Type | Description | 602| -------------------------------- | ------------------------------------- | 603| Promise<[Screen](#screen)> | Promise used to return the created virtual screen.| 604 605**Error codes** 606 607For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 608 609| ID| Error Message| 610| ------- | ----------------------- | 611| 1400001 | Invalid display or screen. | 612 613**Example** 614 615```ts 616import { BusinessError } from '@ohos.base'; 617 618let screenClass: screen.Screen | null = null; 619try { 620 class VirtualScreenOption { 621 name : string = ''; 622 width : number = 0; 623 height : number = 0; 624 density : number = 0; 625 surfaceId : string = ''; 626 } 627 628 let option : VirtualScreenOption = { 629 name: 'screen01', 630 width: 1080, 631 height: 2340, 632 density: 2, 633 surfaceId: '' 634 }; 635 636 screen.createVirtualScreen(option).then((data: Promise<Screen>) => { 637 screenClass = data; 638 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 639 }).catch((err: BusinessError) => { 640 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err)); 641 }); 642} catch (exception) { 643 console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception)); 644}; 645``` 646 647## screen.destroyVirtualScreen 648 649destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void 650 651Destroys a virtual screen. This API uses an asynchronous callback to return the result. 652 653**System capability**: SystemCapability.WindowManager.WindowManager.Core 654 655**Parameters** 656 657| Name | Type | Mandatory| Description | 658| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 659| screenId | number | Yes | Screen ID. The value must be an integer. | 660| 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.| 661 662**Error codes** 663 664For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 665 666| ID| Error Message| 667| ------- | ----------------------------- | 668| 1400002 | Unauthorized operation. | 669 670**Example** 671 672```ts 673import { BusinessError } from '@ohos.base'; 674 675let screenId: number = 1; 676try { 677 screen.destroyVirtualScreen(screenId, (err: BusinessError) => { 678 const errCode: number = err.code; 679 if (errCode) { 680 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err)); 681 return; 682 } 683 console.info('Succeeded in destroying the virtual screen.'); 684 }); 685} catch (exception) { 686 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception)); 687}; 688``` 689 690## screen.destroyVirtualScreen 691 692destroyVirtualScreen(screenId:number): Promise<void> 693 694Destroys a virtual screen. This API uses a promise to return the result. 695 696**System capability**: SystemCapability.WindowManager.WindowManager.Core 697 698**Parameters** 699 700| Name | Type | Mandatory| Description | 701| -------- | ------ | ---- | ---------- | 702| screenId | number | Yes | Screen ID. The value must be an integer.| 703 704**Return value** 705 706| Type | Description | 707| ------------------- | ------------------------- | 708| Promise<void> | Promise that returns no value.| 709 710**Error codes** 711 712For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 713 714| ID| Error Message| 715| ------- | ----------------------------- | 716| 1400002 | Unauthorized operation. | 717 718**Example** 719 720```ts 721import { BusinessError } from '@ohos.base'; 722 723let screenId: number = 1; 724try { 725 screen.destroyVirtualScreen(screenId).then(() => { 726 console.info('Succeeded in destroying the virtual screen.'); 727 }).catch((err: BusinessError) => { 728 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err)); 729 }); 730} catch (exception) { 731 console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception)); 732}; 733``` 734 735## screen.setVirtualScreenSurface 736 737setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void 738 739Sets the surface for a virtual screen. This API uses an asynchronous callback to return the result. 740 741**System capability**: SystemCapability.WindowManager.WindowManager.Core 742 743**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 744 745**Parameters** 746 747| Name | Type | Mandatory| Description | 748| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 749| screenId | number | Yes | Screen ID. The value must be an integer. | 750| surfaceId | string | Yes | Surface ID. | 751| 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.| 752 753**Error codes** 754 755For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 756 757| ID| Error Message| 758| ------- | ----------------------- | 759| 1400001 | Invalid display or screen. | 760 761**Example** 762 763```ts 764import { BusinessError } from '@ohos.base'; 765 766let screenId: number = 1; 767let surfaceId: string = '2048'; 768try { 769 screen.setVirtualScreenSurface(screenId, surfaceId, (err: BusinessError) => { 770 const errCode: number = err.code; 771 if (errCode) { 772 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err)); 773 return; 774 } 775 console.info('Succeeded in setting the surface for the virtual screen.'); 776 }); 777} catch (exception) { 778 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception)); 779}; 780``` 781 782## screen.setVirtualScreenSurface 783 784setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 785 786Sets the surface for a virtual screen. This API uses a promise to return the result. 787 788**System capability**: SystemCapability.WindowManager.WindowManager.Core 789 790**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 791 792**Parameters** 793 794| Name | Type | Mandatory| Description | 795| --------- | ------ | ---- | ------------- | 796| screenId | number | Yes | Screen ID. The value must be an integer. | 797| surfaceId | string | Yes | Surface ID.| 798 799**Return value** 800 801| Type | Description | 802| ------------------- | ------------------------- | 803| Promise<void> | Promise that returns no value.| 804 805**Error codes** 806 807For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 808 809| ID| Error Message| 810| ------- | ----------------------- | 811| 1400001 | Invalid display or screen. | 812 813**Example** 814 815```ts 816import { BusinessError } from '@ohos.base'; 817 818let screenId: number = 1; 819let surfaceId: string = '2048'; 820try { 821 screen.setVirtualScreenSurface(screenId, surfaceId).then(() => { 822 console.info('Succeeded in setting the surface for the virtual screen.'); 823 }).catch((err: BusinessError) => { 824 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err)); 825 }); 826} catch (exception) { 827 console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception)); 828}; 829``` 830 831## screen.isScreenRotationLocked 832 833isScreenRotationLocked(): Promise<boolean> 834 835Checks whether auto rotate is locked. This API uses a promise to return the result. 836 837**System capability**: SystemCapability.WindowManager.WindowManager.Core 838 839**Return value** 840 841| Type | Description | 842| ---------------------- | ------------------------------------- | 843| Promise<boolean> | Promise used to return the result. If **true** is returned, auto rotate is locked. If **false** is returned, auto rotate is unlocked.| 844 845**Example** 846 847```ts 848import { BusinessError } from '@ohos.base'; 849 850screen.isScreenRotationLocked().then((isLocked: Promise<boolean>) => { 851 console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 852}).catch((err: BusinessError) => { 853 console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err)); 854}); 855``` 856 857## screen.isScreenRotationLocked 858 859isScreenRotationLocked(callback: AsyncCallback<boolean>): void 860 861Checks whether auto rotate is locked. This API uses an asynchronous callback to return the result. 862 863**System capability**: SystemCapability.WindowManager.WindowManager.Core 864 865**Parameters** 866 867| Name | Type | Mandatory| Description | 868| --------- | ---------------------------- | ---- | ------------------------------------------------------------ | 869| 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.| 870 871**Example** 872 873```ts 874import { BusinessError } from '@ohos.base'; 875 876screen.isScreenRotationLocked((err: BusinessError, isLocked: AsyncCallback<boolean>) => { 877 const errCode: number = err.code; 878 if (errCode) { 879 console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err)); 880 return; 881 } 882 console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 883}); 884``` 885 886## screen.setScreenRotationLocked 887 888setScreenRotationLocked(isLocked: boolean): Promise<void> 889 890Sets whether to lock auto rotate. This API uses a promise to return the result. 891 892**System capability**: SystemCapability.WindowManager.WindowManager.Core 893 894**Parameters** 895 896| Name | Type | Mandatory| Description | 897| --------- | ------ | ---- | ------------- | 898| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite.| 899 900**Return value** 901 902| Type | Description | 903| ------------------- | ------------------------- | 904| Promise<void> | Promise that returns no value.| 905 906**Example** 907 908```ts 909import { BusinessError } from '@ohos.base'; 910 911let isLocked: boolean = false; 912try { 913 screen.setScreenRotationLocked(isLocked).then(() => { 914 console.info('Succeeded in unlocking auto rotate'); 915 }).catch((err: BusinessError) => { 916 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(err)); 917 }); 918} catch (exception) { 919 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception)); 920}; 921``` 922 923## screen.setScreenRotationLocked 924 925setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void 926 927Sets whether to lock auto rotate. This API uses an asynchronous callback to return the result. 928 929**System capability**: SystemCapability.WindowManager.WindowManager.Core 930 931**Parameters** 932 933| Name | Type | Mandatory| Description | 934| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 935| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite. | 936| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 937 938**Example** 939 940```ts 941import { BusinessError } from '@ohos.base'; 942 943let isLocked: boolean = false; 944try { 945 screen.setScreenRotationLocked(isLocked, (err: BusinessError) => { 946 const errCode: number = err.code; 947 if (errCode) { 948 console.error('Failed to unlock auto rotate. Cause:' + JSON.stringify(err)); 949 return; 950 } 951 console.info('Succeeded in unlocking auto rotate.'); 952 }); 953} catch (exception) { 954 console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception)); 955}; 956``` 957 958## ExpandOption 959 960Defines the parameters for expanding a screen. 961 962**System capability**: SystemCapability.WindowManager.WindowManager.Core 963 964| Name | Type| Readable| Writable| Description | 965| -------- | -------- | ---- | ---- | ------------------- | 966| screenId | number | Yes | Yes | Screen ID. The value must be an integer. | 967| startX | number | Yes | Yes | Start X coordinate of the screen. The value must be an integer.| 968| startY | number | Yes | Yes | Start Y coordinate of the screen. The value must be an integer.| 969 970## VirtualScreenOption 971 972Defines virtual screen parameters. 973 974**System capability**: SystemCapability.WindowManager.WindowManager.Core 975 976| Name | Type| Readable| Writable| Description | 977| --------- | -------- | ---- | ---- |--------------------------| 978| name | string | Yes | Yes | Name of a virtual screen. | 979| width | number | Yes | Yes | Width of the virtual screen, in pixels. The value must be an integer.| 980| height | number | Yes | Yes | Height of the virtual screen, in pixels. The value must be an integer.| 981| density | number | Yes | Yes | Density of the virtual screen. The value must be a floating point number. | 982| surfaceId | string | Yes | Yes | Surface ID of the virtual screen. | 983 984## Screen 985 986Implements a **Screen** instance. 987 988Before calling any API in **Screen**, you must use **[getAllScreens()](#screengetallscreens)** or **[createVirtualScreen()](#screencreatevirtualscreen)** to obtain a **Screen** instance. 989 990### Attributes 991 992**System capability**: SystemCapability.WindowManager.WindowManager.Core 993 994| Name | Type | Readable| Writable| Description | 995| ----------------- | ---------------------------------------------- | ---- | ---- |-------------------------------------------------------------| 996| id | number | Yes | No | Screen ID. The value must be an integer. | 997| parent | number | Yes | No | ID of the group to which a screen belongs. The value must be an integer. | 998| supportedModeInfo | Array<[ScreenModeInfo](#screenmodeinfo)> | Yes | No | Mode set supported by the screen. | 999| activeModeIndex | number | Yes | No | Index of the active screen mode. The current value and value range of this parameter vary according to the screen resolution, refresh rate, and device hardware. The value must be an integer.| 1000| orientation | [Orientation](#orientation) | Yes | No | Screen orientation. | 1001| sourceMode<sup>10+</sup> | [ScreenSourceMode](#screensourcemode10) | Yes | No | Source mode of the screen. | 1002 1003### setOrientation 1004 1005setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 1006 1007Sets the screen orientation. This API uses an asynchronous callback to return the result. 1008 1009**System capability**: SystemCapability.WindowManager.WindowManager.Core 1010 1011| Name | Type | Mandatory| Description | 1012| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1013| orientation | [Orientation](#orientation) | Yes | Screen orientation. | 1014| 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.| 1015 1016**Error codes** 1017 1018For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 1019 1020| ID| Error Message| 1021| ------- | -------------------------------------------- | 1022| 1400003 | This display manager service works abnormally. | 1023 1024**Example** 1025 1026```ts 1027import { BusinessError } from '@ohos.base'; 1028 1029try { 1030 screenClass.setOrientation(screen.Orientation.VERTICAL, (err: BusinessError) => { 1031 const errCode: number = err.code; 1032 if (errCode) { 1033 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(err)); 1034 return; 1035 } 1036 console.info('Succeeded in setting the vertical orientation.'); 1037 }); 1038} catch (exception) { 1039 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception)); 1040}; 1041``` 1042 1043### setOrientation 1044 1045setOrientation(orientation: Orientation): Promise<void> 1046 1047Sets the screen orientation. This API uses a promise to return the result. 1048 1049**System capability**: SystemCapability.WindowManager.WindowManager.Core 1050 1051| Name | Type | Mandatory| Description | 1052| ----------- | --------------------------- | ---- | ---------- | 1053| orientation | [Orientation](#orientation) | Yes | Screen orientation.| 1054 1055**Return value** 1056 1057| Type | Description | 1058| ------------------- | ------------------------- | 1059| Promise<void> | Promise that returns no value.| 1060 1061**Error codes** 1062 1063For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 1064 1065| ID| Error Message| 1066| ------- | -------------------------------------------- | 1067| 1400003 | This display manager service works abnormally. | 1068 1069**Example** 1070 1071```ts 1072import { BusinessError } from '@ohos.base'; 1073 1074try { 1075 let promise: Promise<void> = screenClass.setOrientation(screen.Orientation.VERTICAL); 1076 promise.then(() => { 1077 console.info('Succeeded in setting the vertical orientation.'); 1078 }).catch((err: BusinessError) => { 1079 console.error('Failed to set the vertical orientation. Cause: ' + JSON.stringify(err)); 1080 }); 1081} catch (exception) { 1082 console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception)); 1083}; 1084``` 1085 1086### setScreenActiveMode 1087 1088setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void 1089 1090Sets the active mode of the screen. This API uses an asynchronous callback to return the result. 1091 1092**System capability**: SystemCapability.WindowManager.WindowManager.Core 1093 1094| Name | Type | Mandatory| Description | 1095| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 1096| modeIndex | number | Yes | Index of the mode to set. The current value and value range of this parameter vary according to the screen resolution, refresh rate, and device hardware. The value must be an integer.| 1097| 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.| 1098 1099**Error codes** 1100 1101For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 1102 1103| ID| Error Message| 1104| ------- | -------------------------------------------- | 1105| 1400003 | This display manager service works abnormally. | 1106 1107**Example** 1108 1109```ts 1110import { BusinessError } from '@ohos.base'; 1111 1112let modeIndex: number = 0; 1113try { 1114 screenClass.setScreenActiveMode(modeIndex, (err: BusinessError) => { 1115 const errCode: number = err.code; 1116 if (errCode) { 1117 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err)); 1118 return; 1119 } 1120 console.info('Succeeded in setting the vertical orientation.'); 1121 }); 1122} catch (exception) { 1123 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception)); 1124}; 1125``` 1126 1127### setScreenActiveMode 1128 1129setScreenActiveMode(modeIndex: number): Promise<void> 1130 1131Sets the active mode of the screen. This API uses a promise to return the result. 1132 1133**System capability**: SystemCapability.WindowManager.WindowManager.Core 1134 1135| Name | Type | Mandatory| Description | 1136| --------- | ------ | ---- | ---------- | 1137| modeIndex | number | Yes | Index of the mode to set. The current value and value range of this parameter vary according to the screen resolution, refresh rate, and device hardware. The value must be an integer.| 1138 1139**Return value** 1140 1141| Type | Description | 1142| ------------------- | ------------------------- | 1143| Promise<void> | Promise that returns no value.| 1144 1145**Error codes** 1146 1147For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 1148 1149| ID| Error Message| 1150| ------- | -------------------------------------------- | 1151| 1400003 | This display manager service works abnormally. | 1152 1153**Example** 1154 1155```ts 1156import { BusinessError } from '@ohos.base'; 1157 1158let modeIndex: number = 0; 1159try { 1160 let promise: Promise<void> = screenClass.setScreenActiveMode(modeIndex); 1161 promise.then(() => { 1162 console.info('Succeeded in setting screen active mode 0.'); 1163 }).catch((err: BusinessError) => { 1164 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err)); 1165 }); 1166} catch (exception) { 1167 console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception)); 1168}; 1169``` 1170 1171### setDensityDpi 1172 1173setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; 1174 1175Sets the pixel density of the screen. This API uses an asynchronous callback to return the result. 1176 1177**System capability**: SystemCapability.WindowManager.WindowManager.Core 1178 1179| Name | Type | Mandatory| Description | 1180| ---------- | ------------------------- | ---- |------------------------------------------| 1181| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640]. | 1182| 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.| 1183 1184**Error codes** 1185 1186For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 1187 1188| ID| Error Message| 1189| ------- | -------------------------------------------- | 1190| 1400003 | This display manager service works abnormally. | 1191 1192**Example** 1193 1194```ts 1195import { BusinessError } from '@ohos.base'; 1196 1197let densityDpi: number = 320; 1198try { 1199 screenClass.setDensityDpi(densityDpi, (err: BusinessError) => { 1200 const errCode: number = err.code; 1201 if (errCode) { 1202 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err)); 1203 return; 1204 } 1205 console.info('Succeeded in setting the vertical orientation.'); 1206 }); 1207} catch (exception) { 1208 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception)); 1209}; 1210``` 1211 1212### setDensityDpi 1213 1214setDensityDpi(densityDpi: number): Promise<void> 1215 1216Sets the pixel density of the screen. This API uses a promise to return the result. 1217 1218**System capability**: SystemCapability.WindowManager.WindowManager.Core 1219 1220| Name | Type | Mandatory| Description | 1221| ---------- | ------ | ---- |------------------------------------| 1222| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640].| 1223 1224**Return value** 1225 1226| Type | Description | 1227| ------------------- | ------------------------- | 1228| Promise<void> | Promise that returns no value.| 1229 1230**Error codes** 1231 1232For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md). 1233 1234| ID| Error Message| 1235| ------- | -------------------------------------------- | 1236| 1400003 | This display manager service works abnormally. | 1237 1238**Example** 1239 1240```ts 1241import { BusinessError } from '@ohos.base'; 1242 1243let densityDpi: number = 320; 1244try { 1245 let promise: Promise<void> = screenClass.setDensityDpi(densityDpi); 1246 promise.then(() => { 1247 console.info('Succeeded in setting the pixel density of the screen to 320.'); 1248 }).catch((err: BusinessError) => { 1249 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err)); 1250 }); 1251} catch (exception) { 1252 console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception)); 1253}; 1254``` 1255 1256## Orientation 1257 1258Enumerates the screen orientations. 1259 1260**System capability**: SystemCapability.WindowManager.WindowManager.Core 1261 1262| Name | Value | Description | 1263| ------------------ | ---- | -------------------------------- | 1264| UNSPECIFIED | 0 | Unspecified. The screen orientation is determined by the system.| 1265| VERTICAL | 1 | Vertical. | 1266| HORIZONTAL | 2 | Horizontal. | 1267| REVERSE_VERTICAL | 3 | Reverse vertical. | 1268| REVERSE_HORIZONTAL | 4 | Reverse horizontal. | 1269 1270## ScreenSourceMode<sup>10+</sup> 1271 1272Enumerates the display content source modes of the screen. 1273 1274**System capability**: SystemCapability.WindowManager.WindowManager.Core 1275 1276| Name | Value | Description | 1277| ------------------ | ---- | -------------------------------- | 1278| SCREEN_MAIN | 0 | The primary screen is displayed (default).| 1279| SCREEN_MIRROR | 1 | The mirror is displayed. | 1280| SCREEN_EXTEND | 2 | The extended screen is displayed. | 1281| SCREEN_ALONE | 3 | The source is unspecified. | 1282 1283## ScreenModeInfo 1284 1285Defines the screen mode information. 1286 1287**System capability**: SystemCapability.WindowManager.WindowManager.Core 1288 1289| Name | Type| Readable| Writable| Description | 1290| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1291| id | number | Yes | Yes | Mode ID. The supported mode is determined by the device resolution and refresh rate. The value must be an integer.| 1292| width | number | Yes | Yes | Width of the screen, in pixels. The value must be an integer. | 1293| height | number | Yes | Yes | Height of the screen, in pixels. The value must be an integer. | 1294| refreshRate | number | Yes | Yes | Refresh rate of the screen. The value must be an integer. | 1295