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 the expanded 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 expanded screens, which 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 the expanded 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 expanded screens, which 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 the expanded 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 expanded 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 the expanded 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 the expanded 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 expanded 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 screen mirroring. 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 value must be an integer. | 360| mirrorScreen | Array<number> | Yes | 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, which 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 screen mirroring. 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 value must be an integer. | 403| mirrorScreen | Array<number> | Yes | 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, which 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 screen mirroring. 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 | 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 screen mirroring 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 screen mirroring. 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 | 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.createVirtualScreen 520 521createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void 522 523Creates a virtual screen. This API uses an asynchronous callback to return the result. 524 525**System capability**: SystemCapability.WindowManager.WindowManager.Core 526 527**Required permissions**: ohos.permission.CAPTURE_SCREEN 528 529**Parameters** 530 531| Name | Type | Mandatory| Description | 532| -------- | ------------------------------------------- | ---- | ---------------------------------- | 533| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters. | 534| callback | AsyncCallback<[Screen](#screen)> | Yes | Callback used to return the created virtual screen.| 535 536**Error codes** 537 538For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 539 540| ID| Error Message| 541| ------- | ----------------------- | 542| 201 | Permission verification failed. | 543| 202 | Permission verification failed. A non-system application calls a system API.| 544| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 545| 1400001 | Invalid display or screen. | 546 547**Example** 548 549```ts 550import { BusinessError } from '@kit.BasicServicesKit'; 551 552let screenClass: screen.Screen | null = null; 553class VirtualScreenOption { 554 name : string = ''; 555 width : number = 0; 556 height : number = 0; 557 density : number = 0; 558 surfaceId : string = ''; 559} 560 561let option : VirtualScreenOption = { 562 name: 'screen01', 563 width: 1080, 564 height: 2340, 565 density: 2, 566 surfaceId: '' 567}; 568screen.createVirtualScreen(option, (err: BusinessError, data: screen.Screen) => { 569 const errCode: number = err.code; 570 if (errCode) { 571 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 572 return; 573 } 574 screenClass = data; 575 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 576}); 577``` 578 579## screen.createVirtualScreen 580 581createVirtualScreen(options:VirtualScreenOption): Promise<Screen> 582 583Creates a virtual screen. This API uses a promise to return the result. 584 585**System capability**: SystemCapability.WindowManager.WindowManager.Core 586 587**Required permissions**: ohos.permission.CAPTURE_SCREEN 588 589**Parameters** 590 591| Name | Type | Mandatory| Description | 592| ------- | ------------------------------------------- | ---- | ------------------------ | 593| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters.| 594 595**Return value** 596 597| Type | Description | 598| -------------------------------- | ------------------------------------- | 599| Promise<[Screen](#screen)> | Promise used to return the created virtual screen.| 600 601**Error codes** 602 603For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 604 605| ID| Error Message| 606| ------- | ----------------------- | 607| 201 | Permission verification failed. | 608| 202 | Permission verification failed. A non-system application calls a system API.| 609| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 610| 1400001 | Invalid display or screen. | 611 612**Example** 613 614```ts 615import { BusinessError } from '@kit.BasicServicesKit'; 616 617let screenClass: screen.Screen | null = null; 618class VirtualScreenOption { 619 name : string = ''; 620 width : number = 0; 621 height : number = 0; 622 density : number = 0; 623 surfaceId : string = ''; 624} 625 626let option : VirtualScreenOption = { 627 name: 'screen01', 628 width: 1080, 629 height: 2340, 630 density: 2, 631 surfaceId: '' 632}; 633 634screen.createVirtualScreen(option).then((data: screen.Screen) => { 635 screenClass = data; 636 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 637}).catch((err: BusinessError) => { 638 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 639}); 640``` 641 642## screen.destroyVirtualScreen 643 644destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void 645 646Destroys a virtual screen. This API uses an asynchronous callback to return the result. 647 648**System capability**: SystemCapability.WindowManager.WindowManager.Core 649 650**Parameters** 651 652| Name | Type | Mandatory| Description | 653| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 654| screenId | number | Yes | Screen ID. The value must be an integer. | 655| 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.| 656 657**Error codes** 658 659For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 660 661| ID| Error Message| 662| ------- | ----------------------------- | 663| 202 | Permission verification failed. A non-system application calls a system API.| 664| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 665| 1400002 | Unauthorized operation. | 666 667**Example** 668 669```ts 670import { BusinessError } from '@kit.BasicServicesKit'; 671 672let screenId: number = 1; 673screen.destroyVirtualScreen(screenId, (err: BusinessError) => { 674 const errCode: number = err.code; 675 if (errCode) { 676 console.error(`Failed to destroy the virtual screen. Code:${err.code},message is ${err.message}`); 677 return; 678 } 679 console.info('Succeeded in destroying the virtual screen.'); 680}); 681``` 682 683## screen.destroyVirtualScreen 684 685destroyVirtualScreen(screenId:number): Promise<void> 686 687Destroys a virtual screen. This API uses a promise to return the result. 688 689**System capability**: SystemCapability.WindowManager.WindowManager.Core 690 691**Parameters** 692 693| Name | Type | Mandatory| Description | 694| -------- | ------ | ---- | ---------- | 695| screenId | number | Yes | Screen ID. The value must be an integer.| 696 697**Return value** 698 699| Type | Description | 700| ------------------- | ------------------------- | 701| Promise<void> | Promise that returns no value.| 702 703**Error codes** 704 705For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 706 707| ID| Error Message| 708| ------- | ----------------------------- | 709| 202 | Permission verification failed. A non-system application calls a system API.| 710| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 711| 1400002 | Unauthorized operation. | 712 713**Example** 714 715```ts 716import { BusinessError } from '@kit.BasicServicesKit'; 717 718let screenId: number = 1; 719screen.destroyVirtualScreen(screenId).then(() => { 720 console.info('Succeeded in destroying the virtual screen.'); 721}).catch((err: BusinessError) => { 722 console.error(`Failed to destroy the virtual screen.Code:${err.code},message is ${err.message}`); 723}); 724``` 725 726## screen.setVirtualScreenSurface 727 728setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void 729 730Sets the surface for a virtual screen. This API uses an asynchronous callback to return the result. 731 732**System capability**: SystemCapability.WindowManager.WindowManager.Core 733 734**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 735 736**Parameters** 737 738| Name | Type | Mandatory| Description | 739| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 740| screenId | number | Yes | Screen ID. The value must be an integer. | 741| surfaceId | string | Yes | Surface ID of the virtual screen. The value can be customized. | 742| 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.| 743 744**Error codes** 745 746For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 747 748| ID| Error Message| 749| ------- | ----------------------- | 750| 201 | Permission verification failed. | 751| 202 | Permission verification failed. A non-system application calls a system API.| 752| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 753| 1400001 | Invalid display or screen. | 754 755**Example** 756 757```ts 758import { BusinessError } from '@kit.BasicServicesKit'; 759 760let screenId: number = 1; 761let surfaceId: string = '2048'; 762screen.setVirtualScreenSurface(screenId, surfaceId, (err: BusinessError) => { 763 const errCode: number = err.code; 764 if (errCode) { 765 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 766 return; 767 } 768 console.info('Succeeded in setting the surface for the virtual screen.'); 769}); 770``` 771 772## screen.setVirtualScreenSurface 773 774setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 775 776Sets the surface for a virtual screen. This API uses a promise to return the result. 777 778**System capability**: SystemCapability.WindowManager.WindowManager.Core 779 780**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications) 781 782**Parameters** 783 784| Name | Type | Mandatory| Description | 785| --------- | ------ | ---- | ------------- | 786| screenId | number | Yes | Screen ID. The value must be an integer. | 787| surfaceId | string | Yes | Surface ID of the virtual screen. The value can be customized.| 788 789**Return value** 790 791| Type | Description | 792| ------------------- | ------------------------- | 793| Promise<void> | Promise that returns no value.| 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).then(() => { 814 console.info('Succeeded in setting the surface for the virtual screen.'); 815}).catch((err: BusinessError) => { 816 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 817}); 818``` 819 820## screen.isScreenRotationLocked 821 822isScreenRotationLocked(): Promise<boolean> 823 824Checks whether auto rotate is locked. This API uses a promise to return the result. 825 826**System capability**: SystemCapability.WindowManager.WindowManager.Core 827 828**Return value** 829 830| Type | Description | 831| ---------------------- | ------------------------------------- | 832| Promise<boolean> | Promise used to return the result. If **true** is returned, auto rotate is locked. If **false** is returned, auto rotate is unlocked.| 833 834**Error codes** 835 836For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 837 838| ID| Error Message| 839| ------- | ----------------------- | 840| 202 | Permission verification failed. A non-system application calls a system API.| 841 842**Example** 843 844```ts 845import { BusinessError } from '@kit.BasicServicesKit'; 846 847screen.isScreenRotationLocked().then((isLocked: boolean) => { 848 console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 849}).catch((err: BusinessError) => { 850 console.error(`Failed to get the screen rotation lock status. Code:${err.code},message is ${err.message}`); 851}); 852``` 853 854## screen.isScreenRotationLocked 855 856isScreenRotationLocked(callback: AsyncCallback<boolean>): void 857 858Checks whether auto rotate is locked. This API uses an asynchronous callback to return the result. 859 860**System capability**: SystemCapability.WindowManager.WindowManager.Core 861 862**Parameters** 863 864| Name | Type | Mandatory| Description | 865| --------- | ---------------------------- | ---- | ------------------------------------------------------------ | 866| 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.| 867 868**Error codes** 869 870For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 871 872| ID| Error Message| 873| ------- | ----------------------- | 874| 202 | Permission verification failed. A non-system application calls a system API.| 875 876**Example** 877 878```ts 879import { BusinessError } from '@kit.BasicServicesKit'; 880 881screen.isScreenRotationLocked((err: BusinessError, isLocked: boolean) => { 882const errCode: number = err.code; 883if (errCode) { 884 console.error(`Failed to get the screen rotation lock status. Code:${err.code},message is ${err.message}`); 885 return; 886} 887console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked)); 888}); 889``` 890 891## screen.setScreenRotationLocked 892 893setScreenRotationLocked(isLocked: boolean): Promise<void> 894 895Sets whether to lock auto rotate. This API uses a promise to return the result. 896 897**System capability**: SystemCapability.WindowManager.WindowManager.Core 898 899**Parameters** 900 901| Name | Type | Mandatory| Description | 902| --------- | ------ | ---- | ------------- | 903| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite.| 904 905**Return value** 906 907| Type | Description | 908| ------------------- | ------------------------- | 909| Promise<void> | Promise that returns no value.| 910 911**Error codes** 912 913For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 914 915| ID| Error Message| 916| ------- | ----------------------- | 917| 202 | Permission verification failed. A non-system application calls a system API.| 918| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 919 920**Example** 921 922```ts 923import { BusinessError } from '@kit.BasicServicesKit'; 924 925let isLocked: boolean = false; 926screen.setScreenRotationLocked(isLocked).then(() => { 927 console.info('Succeeded in unlocking auto rotate'); 928}).catch((err: BusinessError) => { 929 console.error(`Failed to unlock auto rotate. Code:${err.code},message is ${err.message}`); 930}); 931``` 932 933## screen.setScreenRotationLocked 934 935setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void 936 937Sets whether to lock auto rotate. This API uses an asynchronous callback to return the result. 938 939**System capability**: SystemCapability.WindowManager.WindowManager.Core 940 941**Parameters** 942 943| Name | Type | Mandatory| Description | 944| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 945| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite. | 946| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 947 948**Error codes** 949 950For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 951 952| ID| Error Message| 953| ------- | ----------------------- | 954| 202 | Permission verification failed. A non-system application calls a system API.| 955| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 956 957**Example** 958 959```ts 960import { BusinessError } from '@kit.BasicServicesKit'; 961 962let isLocked: boolean = false; 963screen.setScreenRotationLocked(isLocked, (err: BusinessError) => { 964 const errCode: number = err.code; 965 if (errCode) { 966 console.error(`Failed to unlock auto rotate. Code:${err.code},message is ${err.message}`); 967 return; 968 } 969 console.info('Succeeded in unlocking auto rotate.'); 970}); 971``` 972 973## screen.setMultiScreenMode<sup>13+</sup> 974 975setMultiScreenMode(primaryScreenId: number, secondaryScreenId: number, secondaryScreenMode: MultiScreenMode): Promise<void> 976 977Sets the display mode (mirror or extend) of the secondary screen. This API uses a promise to return the result. 978 979**System capability**: SystemCapability.WindowManager.WindowManager.Core 980 981**Parameters** 982 983| Name | Type | Mandatory| Description | 984| ------------ | ------------------- | ---- |--------------------| 985| primaryScreenId | number | Yes | ID of the primary screen. The value must be an integer.| 986| secondaryScreenId | number | Yes | ID of the secondary screen. The value must be an integer.| 987| secondaryScreenMode | [MultiScreenMode](#multiscreenmode13) | Yes | Display mode of the secondary screen.| 988 989**Return value** 990 991| Type | Description | 992| ------------------- | ------------------------- | 993| Promise<void> | Promise that returns no value.| 994 995**Error codes** 996 997For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 998 999| ID| Error Message| 1000| ------- | -------------------------------------------- | 1001| 202 | Permission verification failed, non-system application uses system API. | 1002| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1003| 1400003 | This display manager service works abnormally. | 1004 1005**Example** 1006 1007```ts 1008import { BusinessError } from '@kit.BasicServicesKit'; 1009 1010let primaryScreenId: number = 0; 1011let secondaryScreenId: number = 12; 1012let screenMode: screen.MultiScreenMode = screen.MultiScreenMode.SCREEN_MIRROR; 1013screen.setMultiScreenMode(primaryScreenId, secondaryScreenId, screenMode).then(() => { 1014 console.info('Succeeded in setting multi screen mode. Data: '); 1015}).catch((err: BusinessError) => { 1016 console.error(`Failed to set multi screen mode. Code:${err.code},message is ${err.message}`); 1017}); 1018``` 1019 1020## screen.setMultiScreenRelativePosition<sup>13+</sup> 1021 1022setMultiScreenRelativePosition(mainScreenOptions: MultiScreenPositionOptions, secondaryScreenOptions: MultiScreenPositionOptions): Promise<void> 1023 1024Sets the positions of the primary and secondary screens in extend mode. This API uses a promise to return the result. 1025 1026**System capability**: SystemCapability.WindowManager.WindowManager.Core 1027 1028**Parameters** 1029 1030| Name | Type | Mandatory| Description | 1031| ------------ | ------------------- | ---- |--------------------| 1032| mainScreenOptions | [MultiScreenPositionOptions](#multiscreenpositionoptions13) | Yes | Position of the primary screen.| 1033| secondaryScreenOptions | [MultiScreenPositionOptions](#multiscreenpositionoptions13) | Yes | Position of the secondary screen.| 1034 1035**Return value** 1036 1037| Type | Description | 1038| ------------------- | ------------------------- | 1039| Promise<void> | Promise that returns no value. | 1040 1041**Error codes** 1042 1043For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1044 1045| ID| Error Message| 1046| ------- | -------------------------------------------- | 1047| 202 | Permission verification failed, non-system application uses system API. | 1048| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1049| 1400003 | This display manager service works abnormally. | 1050 1051**Example** 1052 1053```ts 1054import { BusinessError } from '@kit.BasicServicesKit'; 1055 1056let mainScreenOptions: screen.MultiScreenPositionOptions = { 1057 id : 0, 1058 startX : 0, 1059 startY : 0 1060}; 1061 1062let secondaryScreenOptions: screen.MultiScreenPositionOptions = { 1063 id : 12, 1064 startX : 1000, 1065 startY : 1000 1066}; 1067 1068screen.setMultiScreenRelativePosition(mainScreenOptions, secondaryScreenOptions).then(() => { 1069 console.info('Succeeded in setting multi screen relative position. Data: '); 1070}).catch((err: BusinessError) => { 1071 console.error(`Failed to set multi screen relative position. Code:${err.code},message is ${err.message}`); 1072}); 1073``` 1074 1075## ExpandOption 1076 1077Defines the parameters for expanding a screen. 1078 1079**System capability**: SystemCapability.WindowManager.WindowManager.Core 1080 1081| Name | Type| Readable| Writable| Description | 1082| -------- | -------- | ---- | ---- | ------------------- | 1083| screenId | number | Yes | Yes | Screen ID. The value must be an integer. | 1084| startX | number | Yes | Yes | Start X coordinate of the screen. The value must be an integer.| 1085| startY | number | Yes | Yes | Start Y coordinate of the screen. The value must be an integer.| 1086 1087## MultiScreenMode<sup>13+</sup> 1088 1089Enumerates the display modes of secondary screens. 1090 1091**System capability**: SystemCapability.WindowManager.WindowManager.Core 1092 1093| Name | Value | Description | 1094| ------------------ | ---- | -------------------------------- | 1095| SCREEN_MIRROR | 0 | Mirror mode.| 1096| SCREEN_EXTAND | 1 | Extend mode.| 1097 1098## MultiScreenPositionOptions<sup>13+</sup> 1099 1100Describes the screen position information. 1101 1102**System capability**: SystemCapability.WindowManager.WindowManager.Core 1103 1104| Name | Type | Readable| Writable | Description | 1105| -------- | -------- | ---- | ---- | ------------------- | 1106| 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.| 1107| 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.| 1108| 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.| 1109 1110## VirtualScreenOption 1111 1112Defines virtual screen parameters. 1113 1114**System capability**: SystemCapability.WindowManager.WindowManager.Core 1115 1116| Name | Type| Readable| Writable| Description | 1117| --------- | -------- | ---- | ---- |--------------------------| 1118| name | string | Yes | Yes | Name of a virtual screen. | 1119| width | number | Yes | Yes | Width of the virtual screen, in px. The value must be an integer.| 1120| height | number | Yes | Yes | Height of the virtual screen, in px. The value must be an integer.| 1121| density | number | Yes | Yes | Density of the virtual screen, in px. The value must be a floating point number.| 1122| surfaceId | string | Yes | Yes | Surface ID of the virtual screen. | 1123 1124## Screen 1125 1126Implements a **Screen** instance. 1127 1128Before calling any API in **Screen**, you must use **[getAllScreens()](#screengetallscreens)** or **[createVirtualScreen()](#screencreatevirtualscreen)** to obtain a **Screen** instance. 1129 1130### Attributes 1131 1132**System capability**: SystemCapability.WindowManager.WindowManager.Core 1133 1134| Name | Type | Readable| Writable| Description | 1135| ----------------- | ---------------------------------------------- | ---- | ---- |-------------------------------------------------------------| 1136| id | number | Yes | No | Screen ID. The value must be an integer. | 1137| parent | number | Yes | No | ID of the group to which a screen belongs. The value must be an integer. | 1138| supportedModeInfo | Array<[ScreenModeInfo](#screenmodeinfo)> | Yes | No | Mode set supported by the screen. | 1139| 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.| 1140| orientation | [Orientation](#orientation) | Yes | No | Screen orientation. | 1141| sourceMode<sup>10+</sup> | [ScreenSourceMode](#screensourcemode10) | Yes | No | Source mode of the screen. | 1142 1143### setOrientation 1144 1145setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 1146 1147Sets the screen orientation. This API uses an asynchronous callback to return the result. 1148 1149**System capability**: SystemCapability.WindowManager.WindowManager.Core 1150 1151| Name | Type | Mandatory| Description | 1152| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1153| orientation | [Orientation](#orientation) | Yes | Screen orientation. The value must be an enumerated value of **Orientation**. | 1154| 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.| 1155 1156**Error codes** 1157 1158For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1159 1160| ID| Error Message| 1161| ------- | -------------------------------------------- | 1162| 202 | Permission verification failed. A non-system application calls a system API.| 1163| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1164| 1400003 | This display manager service works abnormally. | 1165 1166**Example** 1167 1168```ts 1169import { BusinessError } from '@kit.BasicServicesKit'; 1170 1171class VirtualScreenOption { 1172 name : string = ''; 1173 width : number = 0; 1174 height : number = 0; 1175 density : number = 0; 1176 surfaceId : string = ''; 1177} 1178 1179let option : VirtualScreenOption = { 1180 name: 'screen01', 1181 width: 1080, 1182 height: 2340, 1183 density: 2, 1184 surfaceId: '' 1185}; 1186 1187screen.createVirtualScreen(option).then((data: screen.Screen) => { 1188 let screenClass: screen.Screen = data; 1189 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1190 screenClass.setOrientation(screen.Orientation.VERTICAL, (err: BusinessError) => { 1191 const errCode: number = err.code; 1192 if (errCode) { 1193 console.error(`Failed to set the vertical orientation. Code:${err.code},message is ${err.message}`); 1194 return; 1195 } 1196 console.info('Succeeded in setting the vertical orientation.'); 1197 }); 1198}).catch((err: BusinessError) => { 1199 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1200}); 1201``` 1202 1203### setOrientation 1204 1205setOrientation(orientation: Orientation): Promise<void> 1206 1207Sets the screen orientation. This API uses a promise to return the result. 1208 1209**System capability**: SystemCapability.WindowManager.WindowManager.Core 1210 1211| Name | Type | Mandatory| Description | 1212| ----------- | --------------------------- | ---- | ---------- | 1213| orientation | [Orientation](#orientation) | Yes | Screen orientation. The value must be an enumerated value of **Orientation**.| 1214 1215**Return value** 1216 1217| Type | Description | 1218| ------------------- | ------------------------- | 1219| Promise<void> | Promise that returns no value.| 1220 1221**Error codes** 1222 1223For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1224 1225| ID| Error Message| 1226| ------- | -------------------------------------------- | 1227| 202 | Permission verification failed. A non-system application calls a system API.| 1228| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1229| 1400003 | This display manager service works abnormally. | 1230 1231**Example** 1232 1233```ts 1234import { BusinessError } from '@kit.BasicServicesKit'; 1235 1236class VirtualScreenOption { 1237 name : string = ''; 1238 width : number = 0; 1239 height : number = 0; 1240 density : number = 0; 1241 surfaceId : string = ''; 1242} 1243 1244let option : VirtualScreenOption = { 1245 name: 'screen01', 1246 width: 1080, 1247 height: 2340, 1248 density: 2, 1249 surfaceId: '' 1250}; 1251 1252screen.createVirtualScreen(option).then((data: screen.Screen) => { 1253 let screenClass: screen.Screen = data; 1254 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1255 let promise: Promise<void> = screenClass.setOrientation(screen.Orientation.VERTICAL); 1256 promise.then(() => { 1257 console.info('Succeeded in setting the vertical orientation.'); 1258 }).catch((err: BusinessError) => { 1259 console.error(`Failed to set the vertical orientation. Code:${err.code},message is ${err.message}`); 1260 }); 1261}).catch((err: BusinessError) => { 1262 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1263}); 1264``` 1265 1266### setScreenActiveMode 1267 1268setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void 1269 1270Sets the active mode of the screen. This API uses an asynchronous callback to return the result. 1271 1272**System capability**: SystemCapability.WindowManager.WindowManager.Core 1273 1274| Name | Type | Mandatory| Description | 1275| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 1276| 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.| 1277| 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.| 1278 1279**Error codes** 1280 1281For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1282 1283| ID| Error Message| 1284| ------- | -------------------------------------------- | 1285| 202 | Permission verification failed. A non-system application calls a system API.| 1286| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1287| 1400003 | This display manager service works abnormally. | 1288 1289**Example** 1290 1291```ts 1292import { BusinessError } from '@kit.BasicServicesKit'; 1293 1294class VirtualScreenOption { 1295 name : string = ''; 1296 width : number = 0; 1297 height : number = 0; 1298 density : number = 0; 1299 surfaceId : string = ''; 1300} 1301 1302let option : VirtualScreenOption = { 1303 name: 'screen01', 1304 width: 1080, 1305 height: 2340, 1306 density: 2, 1307 surfaceId: '' 1308}; 1309 1310screen.createVirtualScreen(option).then((data: screen.Screen) => { 1311 let screenClass: screen.Screen = data; 1312 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1313 let modeIndex: number = 0; 1314 screenClass.setScreenActiveMode(modeIndex, (err: BusinessError) => { 1315 const errCode: number = err.code; 1316 if (errCode) { 1317 console.error(`Failed to set screen active mode 0. Code:${err.code},message is ${err.message}`); 1318 return; 1319 } 1320 console.info('Succeeded in setting the vertical orientation.'); 1321 }); 1322}).catch((err: BusinessError) => { 1323 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1324}); 1325``` 1326 1327### setScreenActiveMode 1328 1329setScreenActiveMode(modeIndex: number): Promise<void> 1330 1331Sets the active mode of the screen. This API uses a promise to return the result. 1332 1333**System capability**: SystemCapability.WindowManager.WindowManager.Core 1334 1335| Name | Type | Mandatory| Description | 1336| --------- | ------ | ---- | ---------- | 1337| 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.| 1338 1339**Return value** 1340 1341| Type | Description | 1342| ------------------- | ------------------------- | 1343| Promise<void> | Promise that returns no value.| 1344 1345**Error codes** 1346 1347For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1348 1349| ID| Error Message| 1350| ------- | -------------------------------------------- | 1351| 202 | Permission verification failed. A non-system application calls a system API.| 1352| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1353| 1400003 | This display manager service works abnormally. | 1354 1355**Example** 1356 1357```ts 1358import { BusinessError } from '@kit.BasicServicesKit'; 1359 1360class VirtualScreenOption { 1361 name : string = ''; 1362 width : number = 0; 1363 height : number = 0; 1364 density : number = 0; 1365 surfaceId : string = ''; 1366} 1367 1368let option : VirtualScreenOption = { 1369 name: 'screen01', 1370 width: 1080, 1371 height: 2340, 1372 density: 2, 1373 surfaceId: '' 1374}; 1375 1376screen.createVirtualScreen(option).then((data: screen.Screen) => { 1377 let screenClass: screen.Screen = data; 1378 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1379 let modeIndex: number = 0; 1380 let promise: Promise<void> = screenClass.setScreenActiveMode(modeIndex); 1381 promise.then(() => { 1382 console.info('Succeeded in setting screen active mode 0.'); 1383 }).catch((err: BusinessError) => { 1384 console.error(`Failed to set screen active mode 0.Code:${err.code},message is ${err.message}`); 1385 }); 1386}).catch((err: BusinessError) => { 1387 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1388}); 1389``` 1390 1391### setDensityDpi 1392 1393setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; 1394 1395Sets the pixel density of the screen. This API uses an asynchronous callback to return the result. 1396 1397**System capability**: SystemCapability.WindowManager.WindowManager.Core 1398 1399| Name | Type | Mandatory| Description | 1400| ---------- | ------------------------- | ---- |------------------------------------------| 1401| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640]. | 1402| 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.| 1403 1404**Error codes** 1405 1406For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1407 1408| ID| Error Message| 1409| ------- | -------------------------------------------- | 1410| 202 | Permission verification failed. A non-system application calls a system API.| 1411| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1412| 1400003 | This display manager service works abnormally. | 1413 1414**Example** 1415 1416```ts 1417import { BusinessError } from '@kit.BasicServicesKit'; 1418 1419let densityDpi: number = 320; 1420class VirtualScreenOption { 1421 name : string = ''; 1422 width : number = 0; 1423 height : number = 0; 1424 density : number = 0; 1425 surfaceId : string = ''; 1426} 1427 1428let option : VirtualScreenOption = { 1429 name: 'screen01', 1430 width: 1080, 1431 height: 2340, 1432 density: 2, 1433 surfaceId: '' 1434}; 1435 1436screen.createVirtualScreen(option).then((data: screen.Screen) => { 1437 let screenClass: screen.Screen = data; 1438 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data)); 1439 screenClass.setDensityDpi(densityDpi, (err: BusinessError) => { 1440 const errCode: number = err.code; 1441 if (errCode) { 1442 console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code},message is ${err.message}`); 1443 return; 1444 } 1445 console.info('Succeeded in setting the vertical orientation.'); 1446 }); 1447}).catch((err: BusinessError) => { 1448 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1449}); 1450``` 1451 1452### setDensityDpi 1453 1454setDensityDpi(densityDpi: number): Promise<void> 1455 1456Sets the pixel density of the screen. This API uses a promise to return the result. 1457 1458**System capability**: SystemCapability.WindowManager.WindowManager.Core 1459 1460| Name | Type | Mandatory| Description | 1461| ---------- | ------ | ---- |------------------------------------| 1462| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640].| 1463 1464**Return value** 1465 1466| Type | Description | 1467| ------------------- | ------------------------- | 1468| Promise<void> | Promise that returns no value.| 1469 1470**Error codes** 1471 1472For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md). 1473 1474| ID| Error Message| 1475| ------- | -------------------------------------------- | 1476| 202 | Permission verification failed. A non-system application calls a system API.| 1477| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1478| 1400003 | This display manager service works abnormally. | 1479 1480**Example** 1481 1482```ts 1483import { BusinessError } from '@kit.BasicServicesKit'; 1484 1485let densityDpi: number = 320; 1486class VirtualScreenOption { 1487 name : string = ''; 1488 width : number = 0; 1489 height : number = 0; 1490 density : number = 0; 1491 surfaceId : string = ''; 1492} 1493 1494let option : VirtualScreenOption = { 1495 name: 'screen01', 1496 width: 1080, 1497 height: 2340, 1498 density: 2, 1499 surfaceId: '' 1500}; 1501 1502screen.createVirtualScreen(option).then((data: screen.Screen) => { 1503 let screenClass: screen.Screen = data; 1504 let promise: Promise<void> = screenClass.setDensityDpi(densityDpi); 1505 promise.then(() => { 1506 console.info('Succeeded in setting the pixel density of the screen to 320.'); 1507 }).catch((err: BusinessError) => { 1508 console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code},message is ${err.message}`); 1509 }); 1510}).catch((err: BusinessError) => { 1511 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1512}); 1513``` 1514 1515## Orientation 1516 1517Enumerates the screen orientations. 1518 1519**System capability**: SystemCapability.WindowManager.WindowManager.Core 1520 1521| Name | Value | Description | 1522| ------------------ | ---- | -------------------------------- | 1523| UNSPECIFIED | 0 | Unspecified. The screen orientation is determined by the system.| 1524| VERTICAL | 1 | Vertical. | 1525| HORIZONTAL | 2 | Horizontal. | 1526| REVERSE_VERTICAL | 3 | Reverse vertical. | 1527| REVERSE_HORIZONTAL | 4 | Reverse horizontal. | 1528 1529## ScreenSourceMode<sup>10+</sup> 1530 1531Enumerates the sources of the content displayed on the screen. 1532 1533**System capability**: SystemCapability.WindowManager.WindowManager.Core 1534 1535| Name | Value | Description | 1536| ------------------ | ---- | -------------------------------- | 1537| SCREEN_MAIN | 0 | Content from the primary screen (default).| 1538| SCREEN_MIRROR | 1 | Content from a mirror screen. | 1539| SCREEN_EXTEND | 2 | Content from an extend screen. | 1540| SCREEN_ALONE | 3 | The source is unspecified. | 1541 1542## ScreenModeInfo 1543 1544Defines the screen mode information. 1545 1546**System capability**: SystemCapability.WindowManager.WindowManager.Core 1547 1548| Name | Type| Readable| Writable| Description | 1549| ----------- | -------- | ---- | ---- | -------------------------------------------------- | 1550| id | number | Yes | Yes | Mode ID. The supported mode is determined by the device resolution and refresh rate. The value must be an integer.| 1551| width | number | Yes | Yes | Width of the screen, in px. The value must be an integer. | 1552| height | number | Yes | Yes | Height of the screen, in px. The value must be an integer. | 1553| refreshRate | number | Yes | Yes | Refresh rate of the screen, in hz. The value must be an integer. | 1554