1# @ohos.screen (Screen) (System API) 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 '@kit.ArkUI'; 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 [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 34 35| ID| Error Message| 36| ------- | ----------------------- | 37| 202 | Permission verification failed. A non-system application calls a system API.| 38| 1400001 | Invalid display or screen. | 39 40**Example** 41 42```ts 43import { BusinessError } from '@kit.BasicServicesKit'; 44 45let screenClass: screen.Screen | null = null; 46screen.getAllScreens((err: BusinessError, data: Array<screen.Screen>) => { 47 const errCode: number = err.code; 48 if (errCode) { 49 console.error(`Failed to get all screens. Code:${err.code},message is ${err.message}`); 50 return; 51 } 52 console.info('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 53 screenClass = data[0]; 54}); 55``` 56 57## screen.getAllScreens 58 59getAllScreens(): Promise<Array<Screen>> 60 61Obtains all screens. This API uses a promise to return the result. 62 63**System capability**: SystemCapability.WindowManager.WindowManager.Core 64 65**Return value** 66 67| Type | Description | 68| --------------------------------------------- | ----------------------------------------- | 69| Promise<Array<[Screen](#screen)>> | Promise used to return all the **Screen** objects obtained.| 70 71**Error codes** 72 73For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 74 75| ID| Error Message| 76| ------- | ----------------------- | 77| 202 | Permission verification failed. A non-system application calls a system API.| 78| 1400001 | Invalid display or screen. | 79 80**Example** 81 82```ts 83import { BusinessError } from '@kit.BasicServicesKit'; 84 85let screenClass: screen.Screen | null = null; 86let promise: Promise<Array<screen.Screen>> = screen.getAllScreens(); 87promise.then((data: Array<screen.Screen>) => { 88 screenClass = data[0]; 89 console.log('Succeeded in getting all screens. Data:' + JSON.stringify(data)); 90}).catch((err: BusinessError) => { 91 console.log('Failed to get all screens. Cause: ' + JSON.stringify(err)); 92}); 93``` 94 95## screen.on('connect' | 'disconnect' | 'change') 96 97on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void 98 99Subscribes to events related to the screen state. 100 101**System capability**: SystemCapability.WindowManager.WindowManager.Core 102 103**Parameters** 104 105| Name | Type | Mandatory| Description | 106| --------- | ---------------------- | ---- | ----------------------------------------------------------- | 107| 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.| 108| callback | Callback<number> | Yes | Callback used to return the screen ID, which is an integer. | 109 110**Error codes** 111 112For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 113 114| ID| Error Message| 115| ------- | ----------------------- | 116| 202 | Permission verification failed. A non-system application calls a system API.| 117| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 118 119**Example** 120 121```ts 122let callback: Callback<number> = (data: number) => { 123 console.info('Succeeded in registering the callback for screen changes. Data: ' + JSON.stringify(data)) 124}; 125screen.on('connect', callback); 126``` 127 128## screen.off('connect' | 'disconnect' | 'change') 129 130off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void 131 132Unsubscribes from events related to the screen state. 133 134**System capability**: SystemCapability.WindowManager.WindowManager.Core 135 136**Parameters** 137 138| Name | Type | Mandatory| Description | 139| --------- | ---------------------- | ---- | ------------------------------------------------------------ | 140| 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.| 141| callback | Callback<number> | No | Callback used to return the screen ID, which is an integer. | 142 143**Error codes** 144 145For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 146 147| ID| Error Message| 148| ------- | ----------------------- | 149| 202 | Permission verification failed. A non-system application calls a system API.| 150| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 151 152**Example** 153 154```ts 155let callback: Callback<number> = (data: number) => { 156 console.info('Succeeded in unregistering the callback for screen changes. Data: ' + JSON.stringify(data)) 157}; 158screen.off('connect', callback); 159screen.off('connect'); 160``` 161 162## screen.makeExpand 163 164makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void 165 166Sets the screen to extended mode. This API uses an asynchronous callback to return the result. 167 168**System capability**: SystemCapability.WindowManager.WindowManager.Core 169 170**Parameters** 171 172| Name | Type | Mandatory| Description | 173| -------- | ------------------------------------------ | ---- |----------------------------| 174| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen. | 175| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the extended screens, where the ID is an integer.| 176 177**Error codes** 178 179For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 180 181| ID| Error Message| 182| ------- | ----------------------- | 183| 202 | Permission verification failed. A non-system application calls a system API.| 184| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 185| 1400001 | Invalid display or screen. | 186 187**Example** 188 189```ts 190import { BusinessError } from '@kit.BasicServicesKit'; 191 192let groupId: number | null = null; 193class ExpandOption { 194 screenId: number = 0; 195 startX: number = 0; 196 startY: number = 0; 197} 198let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 }; 199let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 }; 200let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ]; 201screen.makeExpand(expandOptionArray, (err: BusinessError, data: number) => { 202 const errCode: number = err.code; 203 if (errCode) { 204 console.error(`Failed to expand the screen. Code:${err.code},message is ${err.message}`); 205 return; 206 } 207 groupId = data; 208 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 209}); 210``` 211 212## screen.makeExpand 213 214makeExpand(options:Array<ExpandOption>): Promise<number> 215 216Sets the screen to extended mode. This API uses a promise to return the result. 217 218**System capability**: SystemCapability.WindowManager.WindowManager.Core 219 220**Parameters** 221 222| Name | Type | Mandatory| Description | 223| ------- | ------------------------------------------ | ---- | ------------------------ | 224| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen.| 225 226**Return value** 227 228| Type | Description | 229| --------------------- |---------------------------------| 230| Promise<number> | Promise used to return the group ID of the extended screens, where the ID is an integer.| 231 232**Error codes** 233 234For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 235 236| ID| Error Message| 237| ------- | ----------------------- | 238| 202 | Permission verification failed. A non-system application calls a system API.| 239| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 240| 1400001 | Invalid display or screen. | 241 242**Example** 243 244```ts 245import { BusinessError } from '@kit.BasicServicesKit'; 246 247class ExpandOption { 248 screenId: number = 0; 249 startX: number = 0; 250 startY: number = 0; 251} 252let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 }; 253let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 }; 254let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ]; 255screen.makeExpand(expandOptionArray).then(( 256 data: number) => { 257 console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data)); 258}).catch((err: BusinessError) => { 259 console.error(`Failed to expand the screen. Code:${err.code},message is ${err.message}`); 260}); 261``` 262 263## screen.stopExpand<sup>10+</sup> 264 265stopExpand(expandScreen:Array<number>, callback: AsyncCallback<void>): void 266 267Stops extended mode. This API uses an asynchronous callback to return the result. 268 269**System capability**: SystemCapability.WindowManager.WindowManager.Core 270 271**Parameters** 272 273| Name| Type| Mandatory| Description | 274| ------------ | --------------------------- | --- |-----------------------------------------| 275| expandScreen | Array<number> | Yes | IDs of the extended screens. Each ID must be an integer. The size of the **expandScreen** array cannot exceed 1000. | 276| callback | AsyncCallback<void> | Yes | Callback used to return the result. If extended mode is stopped, **err** is **undefined**; otherwise, **err** is an error object.| 277 278**Error codes** 279 280For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 281 282| ID| Error Message| 283| ------- | ----------------------- | 284| 202 | Permission verification failed. A non-system application calls a system API.| 285| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 286| 1400001 | Invalid display or screen. | 287 288**Example** 289 290```ts 291import { BusinessError } from '@kit.BasicServicesKit'; 292 293let expandScreenIds: Array<number> = [1, 2, 3]; 294screen.stopExpand(expandScreenIds, (err: BusinessError) => { 295 const errCode: number = err.code; 296 if (errCode) { 297 console.error(`Failed to stop expand screens. Code:${err.code},message is ${err.message}`); 298 return; 299 } 300 console.info('Succeeded in stopping expand screens.'); 301}); 302``` 303 304## screen.stopExpand<sup>10+</sup> 305 306stopExpand(expandScreen:Array<number>): Promise<void> 307 308Stops extended mode. This API uses a promise to return the result. 309 310**System capability**: SystemCapability.WindowManager.WindowManager.Core 311 312**Parameters** 313 314| Name| Type| Mandatory| Description | 315| ------------ | ------------------- | --- |--------------------| 316| expandScreen | Array<number> | Yes | IDs of the extended screens. Each ID must be an integer. The size of the expandScreen array cannot exceed 1000.| 317 318**Return value** 319 320| Type| Description| 321| --------------------- | ----------------------- | 322| Promise<void> | Promise that returns no value.| 323 324**Error codes** 325 326For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 327 328| ID| Error Message| 329| ------- | ----------------------- | 330| 202 | Permission verification failed. A non-system application calls a system API.| 331| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 332| 1400001 | Invalid display or screen. | 333 334**Example** 335 336```ts 337import { BusinessError } from '@kit.BasicServicesKit'; 338 339let expandScreenIds: Array<number> = [1, 2, 3]; 340screen.stopExpand(expandScreenIds).then(() => { 341 console.info('Succeeded in stopping expand screens.'); 342}).catch((err: BusinessError) => { 343 console.error(`Failed to stop expand screens. Code:${err.code},message is ${err.message}`); 344}); 345``` 346 347## screen.makeMirror 348 349makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void 350 351Sets the screen to mirror mode. This API uses an asynchronous callback to return the result. 352 353**System capability**: SystemCapability.WindowManager.WindowManager.Core 354 355**Parameters** 356 357| Name | Type | Mandatory| Description | 358| ------------ | --------------------------- | ---- |--------------------| 359| mainScreen | number | Yes | ID of the primary screen. The ID must be an integer. | 360| mirrorScreen | Array<number> | Yes | Array of IDs of secondary screens. Each ID must be an integer.| 361| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the secondary screens, where the ID is an integer. | 362 363**Error codes** 364 365For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 366 367| ID| Error Message| 368| ------- | ----------------------- | 369| 202 | Permission verification failed. A non-system application calls a system API.| 370| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 371| 1400001 | Invalid display or screen. | 372 373**Example** 374 375```ts 376import { BusinessError } from '@kit.BasicServicesKit'; 377 378let mainScreenId: number = 0; 379let mirrorScreenIds: Array<number> = [1, 2, 3]; 380screen.makeMirror(mainScreenId, mirrorScreenIds, (err: BusinessError, data: number) => { 381 const errCode: number = err.code; 382 if (errCode) { 383 console.error(`Failed to set screen mirroring. Code:${err.code},message is ${err.message}`); 384 return; 385 } 386 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 387}); 388``` 389 390## screen.makeMirror 391 392makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number> 393 394Sets the screen to mirror mode. This API uses a promise to return the result. 395 396**System capability**: SystemCapability.WindowManager.WindowManager.Core 397 398**Parameters** 399 400| Name | Type | Mandatory| Description | 401| ------------ | ------------------- | ---- |--------------------| 402| mainScreen | number | Yes | ID of the primary screen. The ID must be an integer. | 403| mirrorScreen | Array<number> | Yes | Array of IDs of secondary screens. Each ID must be an integer.| 404 405**Return value** 406 407| Type | Description | 408| --------------------- |---------------------------------| 409| Promise<number> | Promise used to return the group ID of the secondary screens, where the ID is an integer.| 410 411**Error codes** 412 413For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 414 415| ID| Error Message| 416| ------- | ----------------------- | 417| 202 | Permission verification failed. A non-system application calls a system API.| 418| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 419| 1400001 | Invalid display or screen. | 420 421**Example** 422 423```ts 424import { BusinessError } from '@kit.BasicServicesKit'; 425 426let mainScreenId: number = 0; 427let mirrorScreenIds: Array<number> = [1, 2, 3]; 428screen.makeMirror(mainScreenId, mirrorScreenIds).then((data: number) => { 429 console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data)); 430}).catch((err: BusinessError) => { 431 console.error(`Failed to set screen mirroring. Code:${err.code},message is ${err.message}`); 432}); 433``` 434 435## screen.stopMirror<sup>10+</sup> 436 437stopMirror(mirrorScreen:Array<number>, callback: AsyncCallback<void>): void 438 439Stops mirror mode. This API uses an asynchronous callback to return the result. 440 441**System capability**: SystemCapability.WindowManager.WindowManager.Core 442 443**Parameters** 444 445| Name| Type| Mandatory| Description | 446| ------------ | --------------------------- | --- |-----------------------------------------| 447| mirrorScreen | Array<number> | Yes | Array of IDs of secondary screens. Each ID must be an integer. The size of the mirrorScreen array cannot exceed 1000.| 448| callback | AsyncCallback<void> | Yes | Callback used to return the result. If mirror mode is stopped, **err** is **undefined**; otherwise, **err** is an error object.| 449 450**Error codes** 451 452For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 453 454| ID| Error Message| 455| ------- | ----------------------- | 456| 202 | Permission verification failed. A non-system application calls a system API.| 457| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 458| 1400001 | Invalid display or screen. | 459 460**Example** 461 462```ts 463import { BusinessError } from '@kit.BasicServicesKit'; 464 465let mirrorScreenIds: Array<number> = [1, 2, 3]; 466screen.stopMirror(mirrorScreenIds, (err: BusinessError) => { 467 const errCode: number = err.code; 468 if (errCode) { 469 console.error(`Failed to stop mirror screens. Code:${err.code},message is ${err.message}`); 470 return; 471 } 472 console.info('Succeeded in stopping mirror screens.'); 473}); 474``` 475 476## screen.stopMirror<sup>10+</sup> 477 478stopMirror(mirrorScreen:Array<number>): Promise<void> 479 480Stops mirror mode. This API uses a promise to return the result. 481 482**System capability**: SystemCapability.WindowManager.WindowManager.Core 483 484**Parameters** 485 486| Name| Type| Mandatory| Description | 487| ------------ | ------------------- | --- |--------------------| 488| mirrorScreen | Array<number> | Yes | Array of IDs of secondary screens. Each ID must be an integer. The size of the **mirrorScreen** array cannot exceed 1000.| 489 490**Return value** 491 492| Type| Description| 493| --------------------- | ----------------------- | 494| Promise<void> | Promise that returns no value.| 495 496**Error codes** 497 498For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 499 500| ID| Error Message| 501| ------- | ----------------------- | 502| 202 | Permission verification failed. A non-system application calls a system API.| 503| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 504| 1400001 | Invalid display or screen. | 505 506**Example** 507 508```ts 509import { BusinessError } from '@kit.BasicServicesKit'; 510 511let mirrorScreenIds: Array<number> = [1, 2, 3]; 512screen.stopMirror(mirrorScreenIds).then(() => { 513 console.info('Succeeded in stopping mirror screens.'); 514}).catch((err: BusinessError) => { 515 console.error(`Failed to stop mirror screens.Code:${err.code},message is ${err.message}`); 516}); 517``` 518 519## screen.makeUnique<sup>16+</sup> 520 521makeUnique(uniqueScreen: Array<number>): Promise<Array<number>> 522 523Sets the screen to independent display mode. This API uses a promise to return the result. 524 525**System capability**: SystemCapability.Window.SessionManager 526 527**Parameters** 528 529| Name | Type | Mandatory| Description | 530| --------- | ------ | ---- | ------------- | 531| uniqueScreen | Array<number> | Yes | Arry of independent screen IDs. Each ID must be an integer greater than or equal to 0; otherwise, error code 401 is returned.| 532 533**Return value** 534 535| Type | Description | 536| ------------------- | ------------------------- | 537| Promise<Array<number>> | Promise used to returns the independent screen IDs, where each ID is an integer greater than or equal to 0.| 538 539**Error codes** 540 541For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 542 543| ID| Error Message| 544| ------- | ----------------------- | 545| 202 | Permission verification failed. A non-system application calls a system API. | 546| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 547| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 548| 1400001 | Invalid display or screen. | 549| 1400003 | This display manager service works abnormally. | 550 551**Example** 552 553```ts 554import { BusinessError } from '@kit.BasicServicesKit'; 555 556let uniqueScreenIds: Array<number> = [1001, 1002, 1003]; 557screen.makeUnique(uniqueScreenIds).then((data: Array<number>) => { 558 console.info('Succeeded in making unique screens.'); 559}).catch((err: BusinessError) => { 560 console.error(`Failed to make unique screens. Code:${err.code},message is ${err.message}`); 561}); 562``` 563 564## screen.createVirtualScreen 565 566createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void 567 568Creates a virtual screen. This API uses an asynchronous callback to return the result. 569 570**System capability**: SystemCapability.WindowManager.WindowManager.Core 571 572**Required permissions**: ohos.permission.CAPTURE_SCREEN 573 574**Parameters** 575 576| Name | Type | Mandatory| Description | 577| -------- | ------------------------------------------- | ---- | ---------------------------------- | 578| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters. | 579| callback | AsyncCallback<[Screen](#screen)> | Yes | Callback used to return the created virtual screen.| 580 581**Error codes** 582 583For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 584 585| ID| Error Message| 586| ------- | ----------------------- | 587| 201 | Permission verification failed. | 588| 202 | Permission verification failed. A non-system application calls a system API.| 589| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 590| 1400001 | Invalid display or screen. | 591 592**Example** 593 594```ts 595import { BusinessError } from '@kit.BasicServicesKit'; 596 597let screenClass: screen.Screen | null = null; 598class VirtualScreenOption { 599 name : string = ''; 600 width : number = 0; 601 height : number = 0; 602 density : number = 0; 603 surfaceId : string = ''; 604} 605 606let option : VirtualScreenOption = { 607 name: 'screen01', 608 width: 1080, 609 height: 2340, 610 density: 2, 611 surfaceId: '' 612}; 613screen.createVirtualScreen(option, (err: BusinessError, data: screen.Screen) => { 614 const errCode: number = err.code; 615 if (errCode) { 616 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 617 return; 618 } 619 screenClass = data; 620 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 621}); 622``` 623 624## screen.createVirtualScreen 625 626createVirtualScreen(options:VirtualScreenOption): Promise<Screen> 627 628Creates a virtual screen. This API uses a promise to return the result. 629 630**System capability**: SystemCapability.WindowManager.WindowManager.Core 631 632**Required permissions**: ohos.permission.CAPTURE_SCREEN 633 634**Parameters** 635 636| Name | Type | Mandatory| Description | 637| ------- | ------------------------------------------- | ---- | ------------------------ | 638| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters.| 639 640**Return value** 641 642| Type | Description | 643| -------------------------------- | ------------------------------------- | 644| Promise<[Screen](#screen)> | Promise used to return the created virtual screen.| 645 646**Error codes** 647 648For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 649 650| ID| Error Message| 651| ------- | ----------------------- | 652| 201 | Permission verification failed. | 653| 202 | Permission verification failed. A non-system application calls a system API.| 654| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 655| 1400001 | Invalid display or screen. | 656 657**Example** 658 659```ts 660import { BusinessError } from '@kit.BasicServicesKit'; 661 662let screenClass: screen.Screen | null = null; 663class VirtualScreenOption { 664 name : string = ''; 665 width : number = 0; 666 height : number = 0; 667 density : number = 0; 668 surfaceId : string = ''; 669} 670 671let option : VirtualScreenOption = { 672 name: 'screen01', 673 width: 1080, 674 height: 2340, 675 density: 2, 676 surfaceId: '' 677}; 678 679screen.createVirtualScreen(option).then((data: screen.Screen) => { 680 screenClass = data; 681 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 682}).catch((err: BusinessError) => { 683 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 684}); 685``` 686 687## screen.destroyVirtualScreen 688 689destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void 690 691Destroys a virtual screen. This API uses an asynchronous callback to return the result. 692 693**System capability**: SystemCapability.WindowManager.WindowManager.Core 694 695**Parameters** 696 697| Name | Type | Mandatory| Description | 698| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 699| screenId | number | Yes | Screen ID. The value must be an integer. | 700| 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.| 701 702**Error codes** 703 704For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 705 706| ID| Error Message| 707| ------- | ----------------------------- | 708| 202 | Permission verification failed. A non-system application calls a system API.| 709| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 710| 1400002 | Unauthorized operation. | 711 712**Example** 713 714```ts 715import { BusinessError } from '@kit.BasicServicesKit'; 716 717let screenId: number = 1; 718screen.destroyVirtualScreen(screenId, (err: BusinessError) => { 719 const errCode: number = err.code; 720 if (errCode) { 721 console.error(`Failed to destroy the virtual screen. Code:${err.code},message is ${err.message}`); 722 return; 723 } 724 console.info('Succeeded in destroying the virtual screen.'); 725}); 726``` 727 728## screen.destroyVirtualScreen 729 730destroyVirtualScreen(screenId:number): Promise<void> 731 732Destroys a virtual screen. This API uses a promise to return the result. 733 734**System capability**: SystemCapability.WindowManager.WindowManager.Core 735 736**Parameters** 737 738| Name | Type | Mandatory| Description | 739| -------- | ------ | ---- | ---------- | 740| screenId | number | Yes | Screen ID. The value must be an integer.| 741 742**Return value** 743 744| Type | Description | 745| ------------------- | ------------------------- | 746| Promise<void> | Promise that returns no value.| 747 748**Error codes** 749 750For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 751 752| ID| Error Message| 753| ------- | ----------------------------- | 754| 202 | Permission verification failed. A non-system application calls a system API.| 755| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 756| 1400002 | Unauthorized operation. | 757 758**Example** 759 760```ts 761import { BusinessError } from '@kit.BasicServicesKit'; 762 763let screenId: number = 1; 764screen.destroyVirtualScreen(screenId).then(() => { 765 console.info('Succeeded in destroying the virtual screen.'); 766}).catch((err: BusinessError) => { 767 console.error(`Failed to destroy the virtual screen.Code:${err.code},message is ${err.message}`); 768}); 769``` 770 771## screen.setVirtualScreenSurface 772 773setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void 774 775Sets the surface for a virtual screen. This API uses an asynchronous callback to return the result. 776 777**System capability**: SystemCapability.WindowManager.WindowManager.Core 778 779**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 780 781**Parameters** 782 783| Name | Type | Mandatory| Description | 784| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 785| screenId | number | Yes | Screen ID. The value must be an integer. | 786| surfaceId | string | Yes | Surface ID of the virtual screen. The value can be customized. | 787| 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.| 788 789**Error codes** 790 791For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 792 793| ID| Error Message| 794| ------- | ----------------------- | 795| 201 | Permission verification failed. | 796| 202 | Permission verification failed. A non-system application calls a system API.| 797| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 798| 1400001 | Invalid display or screen. | 799 800**Example** 801 802```ts 803import { BusinessError } from '@kit.BasicServicesKit'; 804 805let screenId: number = 1; 806let surfaceId: string = '2048'; 807screen.setVirtualScreenSurface(screenId, surfaceId, (err: BusinessError) => { 808 const errCode: number = err.code; 809 if (errCode) { 810 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 811 return; 812 } 813 console.info('Succeeded in setting the surface for the virtual screen.'); 814}); 815``` 816## screen.setScreenPrivacyMaskImage<sup>18+</sup> 817 818setScreenPrivacyMaskImage(screenId:number, image?: image.PixelMap): Promise<void> 819 820Sets a privacy mask image for the screen. This API uses a promise to return the result. 821 822**System capability**: SystemCapability.Window.SessionManager 823 824**Parameters** 825 826| Name | Type | Mandatory| Description | 827| --------- | ------ | ---- | ------------- | 828| screenId | number | Yes | Screen ID. The value must be a positive integer. | 829| image | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | No | Privacy mask image. If no value is passed, the privacy mask image is cleared, reverting to the default style.| 830 831**Return value** 832 833| Type | Description | 834| ------------------- | ------------------------- | 835| Promise<void> | Promise that returns no value.| 836 837**Error codes** 838 839For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 840 841| ID| Error Message| 842| ------- | ----------------------- | 843| 202 | Permission verification failed. A non-system application calls a system API.| 844| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 845| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 846| 1400001 | Invalid display or screen. | 847| 1400003 | This display manager service works abnormally. | 848 849**Example** 850 851```ts 852import { BusinessError } from '@kit.BasicServicesKit'; 853import { image } from '@kit.ImageKit'; 854 855const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 856let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } } 857image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 858 console.info('Succeeded in creating pixelmap.'); 859 let screenId: number = 1; 860 screen.setScreenPrivacyMaskImage(screenId, pixelMap).then(() => { 861 console.info('Succeeded in setting the privacy mask image for the screen.'); 862 }).catch((err: BusinessError) => { 863 console.error(`Failed to set the privacy mask image for the screen. Code:${err.code},message is ${err.message}`); 864 }); 865}).catch((error: BusinessError) => { 866 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 867}) 868``` 869## screen.setVirtualScreenSurface 870 871setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 872 873Sets the surface for a virtual screen. This API uses a promise to return the result. 874 875**System capability**: SystemCapability.WindowManager.WindowManager.Core 876 877**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 878 879**Parameters** 880 881| Name | Type | Mandatory| Description | 882| --------- | ------ | ---- | ------------- | 883| screenId | number | Yes | Screen ID. The value must be an integer. | 884| surfaceId | string | Yes | Surface ID of the virtual screen. The value can be customized.| 885 886**Return value** 887 888| Type | Description | 889| ------------------- | ------------------------- | 890| Promise<void> | Promise that returns no value.| 891 892**Error codes** 893 894For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 895 896| ID| Error Message| 897| ------- | ----------------------- | 898| 201 | Permission verification failed. | 899| 202 | Permission verification failed. A non-system application calls a system API.| 900| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 901| 1400001 | Invalid display or screen. | 902 903**Example** 904 905```ts 906import { BusinessError } from '@kit.BasicServicesKit'; 907 908let screenId: number = 1; 909let surfaceId: string = '2048'; 910screen.setVirtualScreenSurface(screenId, surfaceId).then(() => { 911 console.info('Succeeded in setting the surface for the virtual screen.'); 912}).catch((err: BusinessError) => { 913 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 914}); 915``` 916 917## screen.isScreenRotationLocked 918 919isScreenRotationLocked(): Promise<boolean> 920 921Checks whether auto rotate is locked. This API uses a promise to return the result. 922 923**System capability**: SystemCapability.WindowManager.WindowManager.Core 924 925**Return value** 926 927| Type | Description | 928| ---------------------- | ------------------------------------- | 929| Promise<boolean> | Promise used to return the result. If **true** is returned, auto rotate is locked. If **false** is returned, auto rotate is unlocked.| 930 931**Error codes** 932 933For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 934 935| ID| Error Message| 936| ------- | ----------------------- | 937| 202 | Permission verification failed. A non-system application calls a system API.| 938 939**Example** 940 941```ts 942import { BusinessError } from '@kit.BasicServicesKit'; 943 944screen.isScreenRotationLocked().then((isLocked: boolean) => { 945 console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 946}).catch((err: BusinessError) => { 947 console.error(`Failed to get the screen rotation lock status. Code:${err.code},message is ${err.message}`); 948}); 949``` 950 951## screen.isScreenRotationLocked 952 953isScreenRotationLocked(callback: AsyncCallback<boolean>): void 954 955Checks whether auto rotate is locked. This API uses an asynchronous callback to return the result. 956 957**System capability**: SystemCapability.WindowManager.WindowManager.Core 958 959**Parameters** 960 961| Name | Type | Mandatory| Description | 962| --------- | ---------------------------- | ---- | ------------------------------------------------------------ | 963| 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.| 964 965**Error codes** 966 967For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 968 969| ID| Error Message| 970| ------- | ----------------------- | 971| 202 | Permission verification failed. A non-system application calls a system API.| 972 973**Example** 974 975```ts 976import { BusinessError } from '@kit.BasicServicesKit'; 977 978screen.isScreenRotationLocked((err: BusinessError, isLocked: boolean) => { 979const errCode: number = err.code; 980if (errCode) { 981 console.error(`Failed to get the screen rotation lock status. Code:${err.code},message is ${err.message}`); 982 return; 983} 984console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 985}); 986``` 987 988## screen.setScreenRotationLocked 989 990setScreenRotationLocked(isLocked: boolean): Promise<void> 991 992Sets whether to lock auto rotate. This API uses a promise to return the result. 993 994**System capability**: SystemCapability.WindowManager.WindowManager.Core 995 996**Parameters** 997 998| Name | Type | Mandatory| Description | 999| --------- | ------ | ---- | ------------- | 1000| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite.| 1001 1002**Return value** 1003 1004| Type | Description | 1005| ------------------- | ------------------------- | 1006| Promise<void> | Promise that returns no value.| 1007 1008**Error codes** 1009 1010For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1011 1012| ID| Error Message| 1013| ------- | ----------------------- | 1014| 202 | Permission verification failed. A non-system application calls a system API.| 1015| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1016 1017**Example** 1018 1019```ts 1020import { BusinessError } from '@kit.BasicServicesKit'; 1021 1022let isLocked: boolean = false; 1023screen.setScreenRotationLocked(isLocked).then(() => { 1024 console.info('Succeeded in unlocking auto rotate'); 1025}).catch((err: BusinessError) => { 1026 console.error(`Failed to unlock auto rotate. Code:${err.code},message is ${err.message}`); 1027}); 1028``` 1029 1030## screen.setScreenRotationLocked 1031 1032setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void 1033 1034Sets whether to lock auto rotate. This API uses an asynchronous callback to return the result. 1035 1036**System capability**: SystemCapability.WindowManager.WindowManager.Core 1037 1038**Parameters** 1039 1040| Name | Type | Mandatory| Description | 1041| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 1042| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite. | 1043| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1044 1045**Error codes** 1046 1047For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1048 1049| ID| Error Message| 1050| ------- | ----------------------- | 1051| 202 | Permission verification failed. A non-system application calls a system API.| 1052| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1053 1054**Example** 1055 1056```ts 1057import { BusinessError } from '@kit.BasicServicesKit'; 1058 1059let isLocked: boolean = false; 1060screen.setScreenRotationLocked(isLocked, (err: BusinessError) => { 1061 const errCode: number = err.code; 1062 if (errCode) { 1063 console.error(`Failed to unlock auto rotate. Code:${err.code},message is ${err.message}`); 1064 return; 1065 } 1066 console.info('Succeeded in unlocking auto rotate.'); 1067}); 1068``` 1069 1070## screen.setMultiScreenMode<sup>13+</sup> 1071 1072setMultiScreenMode(primaryScreenId: number, secondaryScreenId: number, secondaryScreenMode: MultiScreenMode): Promise<void> 1073 1074Sets the display mode (mirror or extend) of the secondary screen. This API uses a promise to return the result. 1075 1076**System capability**: SystemCapability.WindowManager.WindowManager.Core 1077 1078**Parameters** 1079 1080| Name | Type | Mandatory| Description | 1081| ------------ | ------------------- | ---- |--------------------| 1082| primaryScreenId | number | Yes | ID of the primary screen. The value must be an integer.| 1083| secondaryScreenId | number | Yes | ID of the secondary screen. The value must be an integer.| 1084| secondaryScreenMode | [MultiScreenMode](#multiscreenmode13) | Yes | Display mode of the secondary screen.| 1085 1086**Return value** 1087 1088| Type | Description | 1089| ------------------- | ------------------------- | 1090| Promise<void> | Promise that returns no value.| 1091 1092**Error codes** 1093 1094For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1095 1096| ID| Error Message| 1097| ------- | -------------------------------------------- | 1098| 202 | Permission verification failed, non-system application uses system API. | 1099| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1100| 1400003 | This display manager service works abnormally. | 1101 1102**Example** 1103 1104```ts 1105import { BusinessError } from '@kit.BasicServicesKit'; 1106 1107let primaryScreenId: number = 0; 1108let secondaryScreenId: number = 12; 1109let screenMode: screen.MultiScreenMode = screen.MultiScreenMode.SCREEN_MIRROR; 1110screen.setMultiScreenMode(primaryScreenId, secondaryScreenId, screenMode).then(() => { 1111 console.info('Succeeded in setting multi screen mode. Data: '); 1112}).catch((err: BusinessError) => { 1113 console.error(`Failed to set multi screen mode. Code:${err.code},message is ${err.message}`); 1114}); 1115``` 1116 1117## screen.setMultiScreenRelativePosition<sup>13+</sup> 1118 1119setMultiScreenRelativePosition(mainScreenOptions: MultiScreenPositionOptions, secondaryScreenOptions: MultiScreenPositionOptions): Promise<void> 1120 1121Sets the positions of the primary and secondary screens in extend mode. This API uses a promise to return the result. 1122 1123**System capability**: SystemCapability.WindowManager.WindowManager.Core 1124 1125**Parameters** 1126 1127| Name | Type | Mandatory| Description | 1128| ------------ | ------------------- | ---- |--------------------| 1129| mainScreenOptions | [MultiScreenPositionOptions](#multiscreenpositionoptions13) | Yes | Position of the primary screen.| 1130| secondaryScreenOptions | [MultiScreenPositionOptions](#multiscreenpositionoptions13) | Yes | Position of the secondary screen.| 1131 1132**Return value** 1133 1134| Type | Description | 1135| ------------------- | ------------------------- | 1136| Promise<void> | Promise that returns no value. | 1137 1138**Error codes** 1139 1140For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1141 1142| ID| Error Message| 1143| ------- | -------------------------------------------- | 1144| 202 | Permission verification failed, non-system application uses system API. | 1145| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1146| 1400003 | This display manager service works abnormally. | 1147 1148**Example** 1149 1150```ts 1151import { BusinessError } from '@kit.BasicServicesKit'; 1152 1153let mainScreenOptions: screen.MultiScreenPositionOptions = { 1154 id : 0, 1155 startX : 0, 1156 startY : 0 1157}; 1158 1159let secondaryScreenOptions: screen.MultiScreenPositionOptions = { 1160 id : 12, 1161 startX : 1000, 1162 startY : 1000 1163}; 1164 1165screen.setMultiScreenRelativePosition(mainScreenOptions, secondaryScreenOptions).then(() => { 1166 console.info('Succeeded in setting multi screen relative position. Data: '); 1167}).catch((err: BusinessError) => { 1168 console.error(`Failed to set multi screen relative position. Code:${err.code},message is ${err.message}`); 1169}); 1170``` 1171 1172## ExpandOption 1173 1174Defines the parameters for expanding a screen. 1175 1176**System capability**: SystemCapability.WindowManager.WindowManager.Core 1177 1178| Name | Type| Readable| Writable| Description | 1179| -------- | -------- | ---- | ---- | ------------------- | 1180| screenId | number | Yes | Yes | Screen ID. The value must be an integer. | 1181| startX | number | Yes | Yes | Start X coordinate of the screen. The value must be an integer.| 1182| startY | number | Yes | Yes | Start Y coordinate of the screen. The value must be an integer.| 1183 1184## MultiScreenMode<sup>13+</sup> 1185 1186Enumerates the display modes of secondary screens. 1187 1188**System capability**: SystemCapability.WindowManager.WindowManager.Core 1189 1190| Name | Value | Description | 1191| ------------------ | ---- | -------------------------------- | 1192| SCREEN_MIRROR | 0 | Mirror mode.| 1193| SCREEN_EXTAND | 1 | Extend mode.| 1194 1195## MultiScreenPositionOptions<sup>13+</sup> 1196 1197Describes the screen position information. 1198 1199**System capability**: SystemCapability.WindowManager.WindowManager.Core 1200 1201| Name | Type | Readable| Writable | Description | 1202| -------- | -------- | ---- | ---- | ------------------- | 1203| id | number | Yes | Yes | Screen ID. The value must be a positive integer. Any non-positive integer values will be considered invalid and result in an error.| 1204| startX | number | Yes | Yes | Start X coordinate of the screen. The upper left vertex of the bounding rectangle formed by the two screens is used as the origin, with the positive direction being rightwards. The value must be a positive integer. Any non-positive integer values will be considered invalid and result in an error.| 1205| startY | number | Yes | Yes | Start Y coordinate of the screen. The upper left vertex of the bounding rectangle formed by the two screens is used as the origin, with the positive direction being downwards. The value must be a positive integer. Any non-positive integer values will be considered invalid and result in an error.| 1206 1207## VirtualScreenOption 1208 1209Defines virtual screen parameters. 1210 1211**System capability**: SystemCapability.WindowManager.WindowManager.Core 1212 1213| Name | Type| Readable| Writable| Description | 1214| --------- | -------- | ---- | ---- |--------------------------| 1215| name | string | Yes | Yes | Name of a virtual screen. | 1216| width | number | Yes | Yes | Width of the virtual screen, in px. The value must be an integer.| 1217| height | number | Yes | Yes | Height of the virtual screen, in px. The value must be an integer.| 1218| density | number | Yes | Yes | Density of the virtual screen, in px. The value must be a floating point number.| 1219| surfaceId | string | Yes | Yes | Surface ID of the virtual screen. | 1220 1221## screen.makeMirrorWithRegion<sup>15+</sup> 1222 1223makeMirrorWithRegion(mainScreen:number, mirrorScreen:Array<number>, mainScreenRegion:Rect): Promise<number> 1224 1225Sets a rectangle on the screen to mirror mode. This API uses a promise to return the result. 1226 1227**System capability**: SystemCapability.WindowManager.WindowManager.Core 1228 1229**Atomic service API**: This API can be used in atomic services since API version 15. 1230 1231**Parameters** 1232 1233| Name | Type | Mandatory| Description | 1234| ------------ | ------------------- | ---- |--------------------| 1235| mainScreen | number | Yes | ID of the primary screen. The ID must be a positive integer. | 1236| mirrorScreen | Array<number> | Yes | Array of IDs of secondary screens. Each ID must be a positive integer. | 1237| mainScreenRegion | [Rect](#rect15) | Yes | Rectangle on the primary screen to be mirrored. | 1238 1239**Return value** 1240 1241| Type | Description | 1242| --------------------- |---------------------------------| 1243| Promise<number> | Promise used to return the group ID of the secondary screens, where the ID is a positive integer.| 1244 1245**Error codes** 1246 1247For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1248 1249| ID| Error Message| 1250| ------- | ----------------------- | 1251| 202 | Permission verification failed. A non-system application calls a system API.| 1252| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1253| 1400001 | Invalid display or screen. | 1254 1255**Example** 1256 1257```ts 1258import { BusinessError } from '@kit.BasicServicesKit'; 1259 1260let mainScreenId: number = 0; 1261let mirrorScreenIds: Array<number> = [1, 2, 3]; 1262let mainScreenRegion: screen.Rect = { 1263 left : 0, 1264 top : 0, 1265 width : 1920, 1266 height : 1080 1267}; 1268screen.makeMirrorWithRegion(mainScreenId, mirrorScreenIds, mainScreenRegion).then((data: number) => { 1269 console.info(`Succeeded in setting screen mirroring. Data: ${JSON.stringify(data)}`); 1270}).catch((err: BusinessError) => { 1271 console.error(`Failed to set screen area mirroring. Code:${err.code},message is ${err.message}`); 1272}); 1273``` 1274 1275## Screen 1276 1277Implements a **Screen** instance. 1278 1279Before calling any API in **Screen**, you must use **[getAllScreens()](#screengetallscreens)** or **[createVirtualScreen()](#screencreatevirtualscreen)** to obtain a **Screen** instance. 1280 1281### Attributes 1282 1283 1284| Name | Type | Read-Only| Optional| Description | 1285| ----------------- | ---------------------------------------------- | ---- | ---- |-------------------------------------------------------------| 1286| id | number | Yes | No | Screen ID. The value must be an integer.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core | 1287| parent | number | Yes | No | ID of the group to which a screen belongs. The value must be an integer.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core | 1288| supportedModeInfo | Array<[ScreenModeInfo](#screenmodeinfo)> | Yes | No | Mode set supported by the screen.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core | 1289| 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.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 1290| orientation | [Orientation](#orientation) | Yes | No | Screen orientation.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core | 1291| sourceMode<sup>10+</sup> | [ScreenSourceMode](#screensourcemode10) | Yes | No | Source mode of the screen.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core | 1292| serialNumber<sup>15+</sup> | string | Yes | Yes | Serial number of the extended screen. Currently, this property is available only for 2-in-1 devices. <br>**System capability**: SystemCapability.WindowManager.WindowManager | 1293 1294### setOrientation 1295 1296setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 1297 1298Sets the screen orientation. This API uses an asynchronous callback to return the result. 1299 1300**System capability**: SystemCapability.WindowManager.WindowManager.Core 1301 1302| Name | Type | Mandatory| Description | 1303| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1304| orientation | [Orientation](#orientation) | Yes | Screen orientation. The value must be an enumerated value of **Orientation**. | 1305| 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.| 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| 202 | Permission verification failed. A non-system application calls a system API.| 1314| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1315| 1400003 | This display manager service works abnormally. | 1316 1317**Example** 1318 1319```ts 1320import { BusinessError } from '@kit.BasicServicesKit'; 1321 1322class VirtualScreenOption { 1323 name : string = ''; 1324 width : number = 0; 1325 height : number = 0; 1326 density : number = 0; 1327 surfaceId : string = ''; 1328} 1329 1330let option : VirtualScreenOption = { 1331 name: 'screen01', 1332 width: 1080, 1333 height: 2340, 1334 density: 2, 1335 surfaceId: '' 1336}; 1337 1338screen.createVirtualScreen(option).then((data: screen.Screen) => { 1339 let screenClass: screen.Screen = data; 1340 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1341 screenClass.setOrientation(screen.Orientation.VERTICAL, (err: BusinessError) => { 1342 const errCode: number = err.code; 1343 if (errCode) { 1344 console.error(`Failed to set the vertical orientation. Code:${err.code},message is ${err.message}`); 1345 return; 1346 } 1347 console.info('Succeeded in setting the vertical orientation.'); 1348 }); 1349}).catch((err: BusinessError) => { 1350 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1351}); 1352``` 1353 1354### setOrientation 1355 1356setOrientation(orientation: Orientation): Promise<void> 1357 1358Sets the screen orientation. This API uses a promise to return the result. 1359 1360**System capability**: SystemCapability.WindowManager.WindowManager.Core 1361 1362| Name | Type | Mandatory| Description | 1363| ----------- | --------------------------- | ---- | ---------- | 1364| orientation | [Orientation](#orientation) | Yes | Screen orientation. The value must be an enumerated value of **Orientation**.| 1365 1366**Return value** 1367 1368| Type | Description | 1369| ------------------- | ------------------------- | 1370| Promise<void> | Promise that returns no value.| 1371 1372**Error codes** 1373 1374For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1375 1376| ID| Error Message| 1377| ------- | -------------------------------------------- | 1378| 202 | Permission verification failed. A non-system application calls a system API.| 1379| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1380| 1400003 | This display manager service works abnormally. | 1381 1382**Example** 1383 1384```ts 1385import { BusinessError } from '@kit.BasicServicesKit'; 1386 1387class VirtualScreenOption { 1388 name : string = ''; 1389 width : number = 0; 1390 height : number = 0; 1391 density : number = 0; 1392 surfaceId : string = ''; 1393} 1394 1395let option : VirtualScreenOption = { 1396 name: 'screen01', 1397 width: 1080, 1398 height: 2340, 1399 density: 2, 1400 surfaceId: '' 1401}; 1402 1403screen.createVirtualScreen(option).then((data: screen.Screen) => { 1404 let screenClass: screen.Screen = data; 1405 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1406 let promise: Promise<void> = screenClass.setOrientation(screen.Orientation.VERTICAL); 1407 promise.then(() => { 1408 console.info('Succeeded in setting the vertical orientation.'); 1409 }).catch((err: BusinessError) => { 1410 console.error(`Failed to set the vertical orientation. Code:${err.code},message is ${err.message}`); 1411 }); 1412}).catch((err: BusinessError) => { 1413 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1414}); 1415``` 1416 1417### setScreenActiveMode 1418 1419setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void 1420 1421Sets the active mode of the screen. This API uses an asynchronous callback to return the result. 1422 1423**System capability**: SystemCapability.WindowManager.WindowManager.Core 1424 1425| Name | Type | Mandatory| Description | 1426| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 1427| 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.| 1428| 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.| 1429 1430**Error codes** 1431 1432For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1433 1434| ID| Error Message| 1435| ------- | -------------------------------------------- | 1436| 202 | Permission verification failed. A non-system application calls a system API.| 1437| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1438| 1400003 | This display manager service works abnormally. | 1439 1440**Example** 1441 1442```ts 1443import { BusinessError } from '@kit.BasicServicesKit'; 1444 1445class VirtualScreenOption { 1446 name : string = ''; 1447 width : number = 0; 1448 height : number = 0; 1449 density : number = 0; 1450 surfaceId : string = ''; 1451} 1452 1453let option : VirtualScreenOption = { 1454 name: 'screen01', 1455 width: 1080, 1456 height: 2340, 1457 density: 2, 1458 surfaceId: '' 1459}; 1460 1461screen.createVirtualScreen(option).then((data: screen.Screen) => { 1462 let screenClass: screen.Screen = data; 1463 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1464 let modeIndex: number = 0; 1465 screenClass.setScreenActiveMode(modeIndex, (err: BusinessError) => { 1466 const errCode: number = err.code; 1467 if (errCode) { 1468 console.error(`Failed to set screen active mode 0. Code:${err.code},message is ${err.message}`); 1469 return; 1470 } 1471 console.info('Succeeded in setting the vertical orientation.'); 1472 }); 1473}).catch((err: BusinessError) => { 1474 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1475}); 1476``` 1477 1478### setScreenActiveMode 1479 1480setScreenActiveMode(modeIndex: number): Promise<void> 1481 1482Sets the active mode of the screen. This API uses a promise to return the result. 1483 1484**System capability**: SystemCapability.WindowManager.WindowManager.Core 1485 1486| Name | Type | Mandatory| Description | 1487| --------- | ------ | ---- | ---------- | 1488| 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.| 1489 1490**Return value** 1491 1492| Type | Description | 1493| ------------------- | ------------------------- | 1494| Promise<void> | Promise that returns no value.| 1495 1496**Error codes** 1497 1498For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1499 1500| ID| Error Message| 1501| ------- | -------------------------------------------- | 1502| 202 | Permission verification failed. A non-system application calls a system API.| 1503| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1504| 1400003 | This display manager service works abnormally. | 1505 1506**Example** 1507 1508```ts 1509import { BusinessError } from '@kit.BasicServicesKit'; 1510 1511class VirtualScreenOption { 1512 name : string = ''; 1513 width : number = 0; 1514 height : number = 0; 1515 density : number = 0; 1516 surfaceId : string = ''; 1517} 1518 1519let option : VirtualScreenOption = { 1520 name: 'screen01', 1521 width: 1080, 1522 height: 2340, 1523 density: 2, 1524 surfaceId: '' 1525}; 1526 1527screen.createVirtualScreen(option).then((data: screen.Screen) => { 1528 let screenClass: screen.Screen = data; 1529 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1530 let modeIndex: number = 0; 1531 let promise: Promise<void> = screenClass.setScreenActiveMode(modeIndex); 1532 promise.then(() => { 1533 console.info('Succeeded in setting screen active mode 0.'); 1534 }).catch((err: BusinessError) => { 1535 console.error(`Failed to set screen active mode 0.Code:${err.code},message is ${err.message}`); 1536 }); 1537}).catch((err: BusinessError) => { 1538 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1539}); 1540``` 1541 1542### setDensityDpi 1543 1544setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; 1545 1546Sets the pixel density of the screen. This API uses an asynchronous callback to return the result. 1547 1548**System capability**: SystemCapability.WindowManager.WindowManager.Core 1549 1550| Name | Type | Mandatory| Description | 1551| ---------- | ------------------------- | ---- |------------------------------------------| 1552| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640]. | 1553| 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.| 1554 1555**Error codes** 1556 1557For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1558 1559| ID| Error Message| 1560| ------- | -------------------------------------------- | 1561| 202 | Permission verification failed. A non-system application calls a system API.| 1562| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1563| 1400003 | This display manager service works abnormally. | 1564 1565**Example** 1566 1567```ts 1568import { BusinessError } from '@kit.BasicServicesKit'; 1569 1570let densityDpi: number = 320; 1571class VirtualScreenOption { 1572 name : string = ''; 1573 width : number = 0; 1574 height : number = 0; 1575 density : number = 0; 1576 surfaceId : string = ''; 1577} 1578 1579let option : VirtualScreenOption = { 1580 name: 'screen01', 1581 width: 1080, 1582 height: 2340, 1583 density: 2, 1584 surfaceId: '' 1585}; 1586 1587screen.createVirtualScreen(option).then((data: screen.Screen) => { 1588 let screenClass: screen.Screen = data; 1589 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1590 screenClass.setDensityDpi(densityDpi, (err: BusinessError) => { 1591 const errCode: number = err.code; 1592 if (errCode) { 1593 console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code},message is ${err.message}`); 1594 return; 1595 } 1596 console.info('Succeeded in setting the vertical orientation.'); 1597 }); 1598}).catch((err: BusinessError) => { 1599 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1600}); 1601``` 1602 1603### setDensityDpi 1604 1605setDensityDpi(densityDpi: number): Promise<void> 1606 1607Sets the pixel density of the screen. This API uses a promise to return the result. 1608 1609**System capability**: SystemCapability.WindowManager.WindowManager.Core 1610 1611| Name | Type | Mandatory| Description | 1612| ---------- | ------ | ---- |------------------------------------| 1613| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640].| 1614 1615**Return value** 1616 1617| Type | Description | 1618| ------------------- | ------------------------- | 1619| Promise<void> | Promise that returns no value.| 1620 1621**Error codes** 1622 1623For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1624 1625| ID| Error Message| 1626| ------- | -------------------------------------------- | 1627| 202 | Permission verification failed. A non-system application calls a system API.| 1628| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1629| 1400003 | This display manager service works abnormally. | 1630 1631**Example** 1632 1633```ts 1634import { BusinessError } from '@kit.BasicServicesKit'; 1635 1636let densityDpi: number = 320; 1637class VirtualScreenOption { 1638 name : string = ''; 1639 width : number = 0; 1640 height : number = 0; 1641 density : number = 0; 1642 surfaceId : string = ''; 1643} 1644 1645let option : VirtualScreenOption = { 1646 name: 'screen01', 1647 width: 1080, 1648 height: 2340, 1649 density: 2, 1650 surfaceId: '' 1651}; 1652 1653screen.createVirtualScreen(option).then((data: screen.Screen) => { 1654 let screenClass: screen.Screen = data; 1655 let promise: Promise<void> = screenClass.setDensityDpi(densityDpi); 1656 promise.then(() => { 1657 console.info('Succeeded in setting the pixel density of the screen to 320.'); 1658 }).catch((err: BusinessError) => { 1659 console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code},message is ${err.message}`); 1660 }); 1661}).catch((err: BusinessError) => { 1662 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1663}); 1664``` 1665 1666## Orientation 1667 1668Enumerates the screen orientations. 1669 1670**System capability**: SystemCapability.WindowManager.WindowManager.Core 1671 1672| Name | Value | Description | 1673| ------------------ | ---- | -------------------------------- | 1674| UNSPECIFIED | 0 | Unspecified. The screen orientation is determined by the system.| 1675| VERTICAL | 1 | Vertical. | 1676| HORIZONTAL | 2 | Horizontal. | 1677| REVERSE_VERTICAL | 3 | Reverse vertical. | 1678| REVERSE_HORIZONTAL | 4 | Reverse horizontal. | 1679 1680## ScreenSourceMode<sup>10+</sup> 1681 1682Enumerates the sources of the content displayed on the screen. 1683 1684**System capability**: SystemCapability.WindowManager.WindowManager.Core 1685 1686| Name | Value | Description | 1687| ------------------ | ---- | -------------------------------- | 1688| SCREEN_MAIN | 0 | Content from the primary screen (default).| 1689| SCREEN_MIRROR | 1 | Content from a mirror screen. | 1690| SCREEN_EXTEND | 2 | Content from an extend screen. | 1691| SCREEN_ALONE | 3 | The source is unspecified. | 1692 1693## ScreenModeInfo 1694 1695Defines the screen mode information. 1696 1697**System capability**: SystemCapability.WindowManager.WindowManager.Core 1698 1699| Name | Type| Readable| Writable| Description | 1700| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1701| id | number | Yes | Yes | Mode ID. The supported mode is determined by the device resolution and refresh rate. The value must be an integer.| 1702| width | number | Yes | Yes | Width of the screen, in px. The value must be an integer. | 1703| height | number | Yes | Yes | Height of the screen, in px. The value must be an integer. | 1704| refreshRate | number | Yes | Yes | Refresh rate of the screen, in hz. The value must be an integer. | 1705 1706## Rect<sup>15+</sup> 1707 1708Describes the rectangle information. 1709 1710**System capability**: SystemCapability.WindowManager.WindowManager.Core 1711 1712**Atomic service API**: This API can be used in atomic services since API version 15. 1713 1714| Name | Type| Readable| Writable| Description | 1715| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1716| left | number | Yes | Yes | X coordinate of the vertex in the upper left corner of the rectangle, in px. The value must be an integer.| 1717| top | number | Yes | Yes | Y coordinate of the vertex in the upper left corner of the rectangle, in px. The value must be an integer.| 1718| width | number | Yes | Yes | Width of the rectangle, in px. The value must be an integer. | 1719| height | number | Yes | Yes | Height of the rectangle, in px. The value must be an integer. | 1720