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