# @ohos.screen (Screen)
The **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.
> **NOTE**
>
> 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.
>
> The APIs provided by this module are system APIs.
## Modules to Import
```js
import screen from '@ohos.screen';
```
## screen.getAllScreens
getAllScreens(callback: AsyncCallback<Array<Screen>>): void
Obtains all screens. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | -------------------------------------- |
| callback | AsyncCallback<Array<[Screen](#screen)>> | Yes | Callback used to return all the **Screen** objects obtained.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let screenClass = null;
screen.getAllScreens((err, data) => {
if (err.code) {
console.error('Failed to get all screens. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in getting all screens. Data:' + JSON.stringify(data));
screenClass = data[0];
});
```
## screen.getAllScreens
getAllScreens(): Promise<Array<Screen>>
Obtains all screens. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| --------------------------------------------- | ----------------------------------------- |
| Promise<Array<[Screen](#screen)>> | Promise used to return all the **Screen** objects obtained.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let screenClass = null;
let promise = screen.getAllScreens();
promise.then((data) => {
screenClass = data[0];
console.log('Succeeded in getting all screens. Data:'+ JSON.stringify(data));
}).catch((err) => {
console.log('Failed to get all screens. Cause: ' + JSON.stringify(err));
});
```
## screen.on('connect' | 'disconnect' | 'change')
on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void
Subscribes to events related to the screen state.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ---------------------- | ---- | ----------------------------------------------------------- |
| eventType | string | Yes | Event type.
- **connect**: an event indicating that the screen is connected.
- **disconnect**: an event indicating that the screen is disconnected.
- **change**: an event indicating that the screen state changes.|
| callback | Callback<number> | Yes | Callback used to return the screen ID, which is an integer. |
**Example**
```js
try {
let callback = (data) => {
console.info('Succeeded in registering the callback for screen changes. Data: ' + JSON.stringify(data))
};
screen.on('connect', callback);
} catch (exception) {
console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception));
};
```
## screen.off('connect' | 'disconnect' | 'change')
off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void
Unsubscribes from events related to the screen state.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ---------------------- | ---- | ------------------------------------------------------------ |
| eventType | string | Yes | Event type.
- **connect**: an event indicating that the screen is connected.
- **disconnect**: an event indicating that the screen is disconnected.
- **change**: an event indicating that the screen state changes.|
| callback | Callback<number> | No | Callback used to return the screen ID, which is an integer. |
**Example**
```js
try {
let callback = (data) => {
console.info('Succeeded in unregistering the callback for screen changes. Data: ' + JSON.stringify(data))
};
screen.off('connect', callback);
} catch (exception) {
console.error('Failed to register the callback for screen changes. Code: ' + JSON.stringify(exception));
};
```
## screen.makeExpand
makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void
Sets the screen to the expanded mode. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------ | ---- |----------------------------|
| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen. |
| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the expanded screens, which is an integer.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
try {
let groupId = null;
screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 1080, startY: 0}], (err, data) => {
if (err.code) {
console.error('Failed to expand the screen. Code:' + JSON.stringify(err));
return;
}
groupId = data;
console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception));
};
```
## screen.makeExpand
makeExpand(options:Array<ExpandOption>): Promise<number>
Sets the screen to the expanded mode. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------------ | ---- | ------------------------ |
| options | Array<[ExpandOption](#expandoption)> | Yes | Parameters for expanding the screen.|
**Return value**
| Type | Description |
| --------------------- |---------------------------------|
| Promise<number> | Promise used to return the group ID of the expanded screens, which is an integer.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
try {
screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 1080, startY: 0}]).then((data) => {
console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to expand the screen. Code:' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to expand the screen. Code: ' + JSON.stringify(exception));
};
```
## screen.stopExpand10+
stopExpand(expandScreen:Array<number>, callback: AsyncCallback<void>): void
Stops the expanded mode. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description |
| ------------ | --------------------------- | --- |-----------------------------------------|
| expandScreen | Array<number> | Yes | IDs of the expanded screens. Each ID must be an integer. |
| 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.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
try {
let expandScreenIds = [1, 2, 3];
screen.stopExpand(expandScreenIds, (err) => {
if (err.code) {
console.error('Failed to stop expand screens. Code:' + JSON.stringify(err));
return;
}
console.info('Succeeded in stopping expand screens.');
});
} catch (exception) {
console.error('Failed to stop expand screens. Code: ' + JSON.stringify(exception));
};
```
## screen.stopExpand10+
stopExpand(expandScreen:Array<number>): Promise<void>
Stops the expanded mode. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description |
| ------------ | ------------------- | --- |--------------------|
| expandScreen | Array<number> | Yes | IDs of the expanded screens. Each ID must be an integer.|
**Return value**
| Type| Description|
| --------------------- | ----------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
try {
let expandScreenIds = [1, 2, 3];
screen.stopExpand(expandScreenIds).then(() => {
console.info('Succeeded in stopping expand screens.');
}).catch((err) => {
console.error('Failed to stop expand screens. Code:' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to stop expand screens. Code:' + JSON.stringify(exception));
};
```
## screen.makeMirror
makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void
Sets screen mirroring. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | --------------------------- | ---- |--------------------|
| mainScreen | number | Yes | ID of the primary screen. The value must be an integer. |
| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer.|
| callback | AsyncCallback<number> | Yes | Callback used to return the group ID of the secondary screens, which is an integer. |
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let mainScreenId = 0;
let mirrorScreenIds = [1, 2, 3];
try {
screen.makeMirror(mainScreenId, mirrorScreenIds, (err, data) => {
if (err.code) {
console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception));
};
```
## screen.makeMirror
makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number>
Sets screen mirroring. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------------------- | ---- |--------------------|
| mainScreen | number | Yes | ID of the primary screen. The value must be an integer. |
| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer.|
**Return value**
| Type | Description |
| --------------------- |---------------------------------|
| Promise<number> | Promise used to return the group ID of the secondary screens, which is an integer.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let mainScreenId = 0;
let mirrorScreenIds = [1, 2, 3];
try {
screen.makeMirror(mainScreenId, mirrorScreenIds).then((data) => {
console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to set screen mirroring. Code: ' + JSON.stringify(exception));
};
```
## screen.stopMirror10+
stopMirror(mirrorScreen:Array<number>, callback: AsyncCallback<void>): void
Stops screen mirroring. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description |
| ------------ | --------------------------- | --- |-----------------------------------------|
| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If screen mirroring is stopped, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
try {
let mirrorScreenIds = [1, 2, 3];
screen.stopMirror(mirrorScreenIds, (err) => {
if (err.code) {
console.error('Failed to stop mirror screens. Code:' + JSON.stringify(err));
return;
}
console.info('Succeeded in stopping mirror screens.');
});
} catch (exception) {
console.error('Failed to stop mirror screens. Code: ' + JSON.stringify(exception));
};
```
## screen.stopMirror10+
stopMirror(mirrorScreen:Array<number>): Promise<void>
Stops screen mirroring. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description |
| ------------ | ------------------- | --- |--------------------|
| mirrorScreen | Array<number> | Yes | IDs of secondary screens. Each ID must be an integer.|
**Return value**
| Type| Description|
| --------------------- | ----------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
try {
let mirrorScreenIds = [1, 2, 3];
screen.stopMirror(mirrorScreenIds).then(() => {
console.info('Succeeded in stopping mirror screens.');
}).catch((err) => {
console.error('Failed to stop mirror screens. Code:' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to stop mirror screens. Code:' + JSON.stringify(exception));
};
```
## screen.createVirtualScreen
createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void
Creates a virtual screen. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Required permissions**: ohos.permission.CAPTURE_SCREEN (mandatory when **VirtualScreenOption.surfaceId** is valid; available only to system applications)
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------- | ---- | ---------------------------------- |
| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters. |
| callback | AsyncCallback<[Screen](#screen)> | Yes | Callback used to return the created virtual screen.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let screenClass = null;
try {
screen.createVirtualScreen({
name: 'screen01',
width: 1080,
height: 2340,
density: 2,
surfaceId: ''
}, (err, data) => {
if (err.code) {
console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err));
return;
}
screenClass = data;
console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception));
};
```
## screen.createVirtualScreen
createVirtualScreen(options:VirtualScreenOption): Promise<Screen>
Creates a virtual screen. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Required permissions**: ohos.permission.CAPTURE_SCREEN (mandatory when **VirtualScreenOption.surfaceId** is valid; available only to system applications)
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------------- | ---- | ------------------------ |
| options | [VirtualScreenOption](#virtualscreenoption) | Yes | Virtual screen parameters.|
**Return value**
| Type | Description |
| -------------------------------- | ------------------------------------- |
| Promise<[Screen](#screen)> | Promise used to return the created virtual screen.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let screenClass = null;
try {
screen.createVirtualScreen({
name: 'screen01',
width: 1080,
height: 2340,
density: 2,
surfaceId: ''
}).then((data) => {
screenClass = data;
console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(exception));
};
```
## screen.destroyVirtualScreen
destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void
Destroys a virtual screen. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| screenId | number | Yes | Screen ID. The value must be an integer. |
| 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.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------------- |
| 1400002 | Unauthorized operation. |
**Example**
```js
let screenId = 1;
try {
screen.destroyVirtualScreen(screenId, (err,data) => {
if (err.code) {
console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in destroying the virtual screen.');
});
} catch (exception) {
console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception));
};
```
## screen.destroyVirtualScreen
destroyVirtualScreen(screenId:number): Promise<void>
Destroys a virtual screen. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ---------- |
| screenId | number | Yes | Screen ID. The value must be an integer.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------------- |
| 1400002 | Unauthorized operation. |
**Example**
```js
let screenId = 1;
try {
screen.destroyVirtualScreen(screenId).then((data) => {
console.info('Succeeded in destroying the virtual screen.');
}).catch((err) => {
console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to destroy the virtual screen. Code: ' + JSON.stringify(exception));
};
```
## screen.setVirtualScreenSurface
setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void
Sets the surface for a virtual screen. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | ------------------------------------------------------------ |
| screenId | number | Yes | Screen ID. The value must be an integer. |
| surfaceId | string | Yes | Surface ID. |
| 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.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let screenId = 1;
let surfaceId = '2048';
try {
screen.setVirtualScreenSurface(screenId, surfaceId, (err,data) => {
if (err.code) {
console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting the surface for the virtual screen.');
});
} catch (exception) {
console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception));
};
```
## screen.setVirtualScreenSurface
setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void>
Sets the surface for a virtual screen. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Required permissions**: ohos.permission.CAPTURE_SCREEN (available only to system applications)
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | ------------- |
| screenId | number | Yes | Screen ID. The value must be an integer. |
| surfaceId | string | Yes | Surface ID.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | ----------------------- |
| 1400001 | Invalid display or screen. |
**Example**
```js
let screenId = 1;
let surfaceId = '2048';
try {
screen.setVirtualScreenSurface(screenId, surfaceId).then((data) => {
console.info('Succeeded in setting the surface for the virtual screen.');
}).catch((err) => {
console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to set the surface for the virtual screen. Code: ' + JSON.stringify(exception));
};
```
## screen.isScreenRotationLocked
isScreenRotationLocked(): Promise<boolean>
Checks whether auto rotate is locked. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------- |
| Promise<boolean> | Promise used to return the result. If **true** is returned, auto rotate is locked. If **false** is returned, auto rotate is unlocked.|
**Example**
```js
screen.isScreenRotationLocked().then((isLocked) => {
console.info('Succeeded in getting the screen rotation lock status. isLocked:'+ JSON.stringify(isLocked));
}).catch((err) => {
console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err));
});
```
## screen.isScreenRotationLocked
isScreenRotationLocked(callback: AsyncCallback<boolean>): void
Checks whether auto rotate is locked. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| 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.|
**Example**
```js
screen.isScreenRotationLocked((err, isLocked) => {
if (err.code) {
console.error('Failed to get the screen rotation lock status. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked));
});
```
## screen.setScreenRotationLocked
setScreenRotationLocked(isLocked: boolean): Promise<void>
Sets whether to lock auto rotate. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | ------------- |
| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```js
let isLocked = false;
try {
screen.setScreenRotationLocked(isLocked).then((data) => {
console.info('Succeeded in unlocking auto rotate');
}).catch((err) => {
console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception));
};
```
## screen.setScreenRotationLocked
setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void
Sets whether to lock auto rotate. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | ------------------------------------------------------------ |
| isLocked | boolean | Yes | Whether to lock auto rotate. The value **true** means to lock auto rotate, and **false** means the opposite. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```js
let isLocked = false;
try {
screen.setScreenRotationLocked(isLocked, (err, data) => {
if (err.code) {
console.error('Failed to unlock auto rotate. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in unlocking auto rotate.');
});
} catch (exception) {
console.error('Failed to unlock auto rotate. Code: ' + JSON.stringify(exception));
};
```
## ExpandOption
Defines the parameters for expanding a screen.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type| Readable| Writable| Description |
| -------- | -------- | ---- | ---- | ------------------- |
| screenId | number | Yes | Yes | Screen ID. The value must be an integer. |
| startX | number | Yes | Yes | Start X coordinate of the screen. The value must be an integer.|
| startY | number | Yes | Yes | Start Y coordinate of the screen. The value must be an integer.|
## VirtualScreenOption
Defines virtual screen parameters.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type| Readable| Writable| Description |
| --------- | -------- | ---- | ---- |--------------------------|
| name | string | Yes | Yes | Name of a virtual screen. |
| width | number | Yes | Yes | Width of the virtual screen, in pixels. The value must be an integer.|
| height | number | Yes | Yes | Height of the virtual screen, in pixels. The value must be an integer.|
| density | number | Yes | Yes | Density of the virtual screen. The value must be a floating point number. |
| surfaceId | string | Yes | Yes | Surface ID of the virtual screen. |
## Screen
Implements a **Screen** instance.
Before calling any API in **Screen**, you must use **[getAllScreens()](#screengetallscreens)** or **[createVirtualScreen()](#screencreatevirtualscreen)** to obtain a **Screen** instance.
### Attributes
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Readable| Writable| Description |
| ----------------- | ---------------------------------------------- | ---- | ---- |-------------------------------------------------------------|
| id | number | Yes | No | Screen ID. The value must be an integer. |
| parent | number | Yes | No | ID of the group to which a screen belongs. The value must be an integer. |
| supportedModeInfo | Array<[ScreenModeInfo](#screenmodeinfo)> | Yes | No | Mode set supported by the screen. |
| 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.|
| orientation | [Orientation](#orientation) | Yes | No | Screen orientation. |
| sourceMode10+ | [ScreenSourceMode](#screensourcemode10) | Yes | No | Source mode of the screen. |
### setOrientation
setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void
Sets the screen orientation. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Mandatory| Description |
| ----------- | --------------------------- | ---- | ------------------------------------------------------------ |
| orientation | [Orientation](#orientation) | Yes | Screen orientation. |
| 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.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1400003 | This display manager service works abnormally. |
**Example**
```js
try {
screenClass.setOrientation(screen.Orientation.VERTICAL, (err, data) => {
if (err.code) {
console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting the vertical orientation. data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception));
};
```
### setOrientation
setOrientation(orientation: Orientation): Promise<void>
Sets the screen orientation. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Mandatory| Description |
| ----------- | --------------------------- | ---- | ---------- |
| orientation | [Orientation](#orientation) | Yes | Screen orientation.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1400003 | This display manager service works abnormally. |
**Example**
```js
try {
let promise = screenClass.setOrientation(screen.Orientation.VERTICAL);
promise.then((data) => {
console.info('Succeeded in setting the vertical orientation. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to set the vertical orientation. Cause: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(exception));
};
```
### setScreenActiveMode
setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void
Sets the active mode of the screen. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | ------------------------------------------------------------ |
| 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.|
| 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.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1400003 | This display manager service works abnormally. |
**Example**
```js
let modeIndex = 0;
try {
screenClass.setScreenActiveMode(modeIndex, (err, data) => {
if (err.code) {
console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in setting screen active mode 0. data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception));
};
```
### setScreenActiveMode
setScreenActiveMode(modeIndex: number): Promise<void>
Sets the active mode of the screen. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | ---------- |
| 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.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1400003 | This display manager service works abnormally. |
**Example**
```js
let modeIndex = 0;
try {
let promise = screenClass.setScreenActiveMode(modeIndex);
promise.then((data) => {
console.info('Succeeded in setting screen active mode 0. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(exception));
};
```
### setDensityDpi
setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void;
Sets the pixel density of the screen. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Mandatory| Description |
| ---------- | ------------------------- | ---- |------------------------------------------|
| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640]. |
| 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.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1400003 | This display manager service works abnormally. |
**Example**
```js
let densityDpi = 320;
try {
screenClass.setDensityDpi(densityDpi, (err, data) => {
if (err.code) {
console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeed in setting the pixel density of the screen to 320. data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception));
};
```
### setDensityDpi
setDensityDpi(densityDpi: number): Promise<void>
Sets the pixel density of the screen. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- |------------------------------------|
| densityDpi | number | Yes | Pixel density. The value must be an integer in the range [80, 640].|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Display Error Codes](../errorcodes/errorcode-display.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1400003 | This display manager service works abnormally. |
**Example**
```js
let densityDpi = 320;
try {
let promise = screenClass.setDensityDpi(densityDpi);
promise.then((data) => {
console.info('Succeeded in setting the pixel density of the screen to 320. Data: ' + JSON.stringify(data));
}).catch((err) => {
console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err));
});
} catch (exception) {
console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(exception));
};
```
## Orientation
Enumerates the screen orientations.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Value | Description |
| ------------------ | ---- | -------------------------------- |
| UNSPECIFIED | 0 | Unspecified. The screen orientation is determined by the system.|
| VERTICAL | 1 | Vertical. |
| HORIZONTAL | 2 | Horizontal. |
| REVERSE_VERTICAL | 3 | Reverse vertical. |
| REVERSE_HORIZONTAL | 4 | Reverse horizontal. |
## ScreenSourceMode10+
Enumerates the display content source modes of the screen.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Value | Description |
| ------------------ | ---- | -------------------------------- |
| SCREEN_MAIN | 0 | The primary screen is displayed (default).|
| SCREEN_MIRROR | 1 | The mirror is displayed. |
| SCREEN_EXTEND | 2 | The extended screen is displayed. |
| SCREEN_ALONE | 3 | The source is unspecified. |
## ScreenModeInfo
Defines the screen mode information.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type| Readable| Writable| Description |
| ----------- | -------- | ---- | ---- | -------------------------------------------------- |
| id | number | Yes | Yes | Mode ID. The supported mode is determined by the device resolution and refresh rate. The value must be an integer.|
| width | number | Yes | Yes | Width of the screen, in pixels. The value must be an integer. |
| height | number | Yes | Yes | Height of the screen, in pixels. The value must be an integer. |
| refreshRate | number | Yes | Yes | Refresh rate of the screen. The value must be an integer. |