@ohos.screen (Screen) (System API)

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

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>>	Yes	Callback used to return all the Screen objects obtained.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let screenClass: screen.Screen | null = null;
screen.getAllScreens((err: BusinessError, data: Array<screen.Screen>) => {
  const errCode: number = err.code;
  if (errCode) {
    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>>	Promise used to return all the Screen objects obtained.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let screenClass: screen.Screen | null = null;
let promise: Promise<Array<screen.Screen>> = screen.getAllScreens();
promise.then((data: Array<screen.Screen>) => {
  screenClass = data[0];
  console.log('Succeeded in getting all screens. Data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  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

try {
  let callback: Callback<number> = (data: number) => {
    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

try {
  let callback: Callback<number> = (data: number) => {
    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>	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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

try {
  let groupId: number | null = null;
  class ExpandOption {
    screenId: number = 0;
    startX: number = 0;
    startY: number = 0;
  }
  let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 };
  let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 };
  let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ];
  screen.makeExpand(expandOptionArray, (err: BusinessError, data: number) => {
    const errCode: number = err.code;
    if (errCode) {
      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>	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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

try {
  class ExpandOption {
    screenId: number = 0;
    startX: number = 0;
    startY: number = 0;
  }
  let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 };
  let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 };
  let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ];
  screen.makeExpand(expandOptionArray).then((
    data: number) => {
    console.info('Succeeded in expanding the screen. Data: ' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    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.stopExpand¹⁰⁺

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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

try {
  let expandScreenIds: Array<number> = [1, 2, 3];
  screen.stopExpand(expandScreenIds, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      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.stopExpand¹⁰⁺

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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

try {
  let expandScreenIds: Array<number> = [1, 2, 3];
  screen.stopExpand(expandScreenIds).then(() => {
    console.info('Succeeded in stopping expand screens.');
  }).catch((err: BusinessError) => {
    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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let mainScreenId: number = 0;
let mirrorScreenIds: Array<number> = [1, 2, 3];
try {
  screen.makeMirror(mainScreenId, mirrorScreenIds, (err: BusinessError, data: number) => {
    const errCode: number = err.code;
    if (errCode) {
      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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let mainScreenId: number = 0;
let mirrorScreenIds: Array<number> = [1, 2, 3];
try {
  screen.makeMirror(mainScreenId, mirrorScreenIds).then((data: number) => {
    console.info('Succeeded in setting screen mirroring. Data: ' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    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.stopMirror¹⁰⁺

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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

try {
  let mirrorScreenIds: Array<number> = [1, 2, 3];
  screen.stopMirror(mirrorScreenIds, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      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.stopMirror¹⁰⁺

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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

try {
  let mirrorScreenIds: Array<number> = [1, 2, 3];
  screen.stopMirror(mirrorScreenIds).then(() => {
    console.info('Succeeded in stopping mirror screens.');
  }).catch((err: BusinessError) => {
    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

Parameters

Name	Type	Mandatory	Description
options	VirtualScreenOption	Yes	Virtual screen parameters.
callback	AsyncCallback<Screen>	Yes	Callback used to return the created virtual screen.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let screenClass: screen.Screen | null = null;
try {
  class VirtualScreenOption {
    name : string = '';
    width : number =  0;
    height : number = 0;
    density : number = 0;
    surfaceId : string = '';
  }

  let option : VirtualScreenOption = { 
    name: 'screen01',
    width: 1080,
    height: 2340,
    density: 2,
    surfaceId: ''
  };
  screen.createVirtualScreen(option, (err: BusinessError, data: screen.Screen) => {
    const errCode: number = err.code;
    if (errCode) {
      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

Parameters

Name	Type	Mandatory	Description
options	VirtualScreenOption	Yes	Virtual screen parameters.

Return value

Type	Description
Promise<Screen>	Promise used to return the created virtual screen.

Error codes

For details about the error codes, see Display Error Codes.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let screenClass: screen.Screen | null = null;
try {
  class VirtualScreenOption {
    name : string = '';
    width : number =  0;
    height : number = 0;
    density : number = 0;
    surfaceId : string = '';
  }

  let option : VirtualScreenOption = { 
    name: 'screen01',
    width: 1080,
    height: 2340,
    density: 2,
    surfaceId: ''
  };

  screen.createVirtualScreen(option).then((data: screen.Screen) => {
    screenClass = data;
    console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    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.

ID	Error Message
1400002	Unauthorized operation.

Example

import { BusinessError } from '@ohos.base';

let screenId: number = 1;
try {
  screen.destroyVirtualScreen(screenId, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      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.

ID	Error Message
1400002	Unauthorized operation.

Example

import { BusinessError } from '@ohos.base';

let screenId: number = 1;
try {
  screen.destroyVirtualScreen(screenId).then(() => {
    console.info('Succeeded in destroying the virtual screen.');
  }).catch((err: BusinessError) => {
    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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let screenId: number = 1;
let surfaceId: string = '2048';
try {
  screen.setVirtualScreenSurface(screenId, surfaceId, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      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.

ID	Error Message
1400001	Invalid display or screen.

Example

import { BusinessError } from '@ohos.base';

let screenId: number = 1;
let surfaceId: string = '2048';
try {
  screen.setVirtualScreenSurface(screenId, surfaceId).then(() => {
    console.info('Succeeded in setting the surface for the virtual screen.');
  }).catch((err: BusinessError) => {
    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

import { BusinessError } from '@ohos.base';

screen.isScreenRotationLocked().then((isLocked: boolean) => {
  console.info('Succeeded in getting the screen rotation lock status. isLocked:' + JSON.stringify(isLocked));
}).catch((err: BusinessError) => {
  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

import { BusinessError } from '@ohos.base';

screen.isScreenRotationLocked((err: BusinessError, isLocked: boolean) => {
  const errCode: number = err.code;
  if (errCode) {
    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

import { BusinessError } from '@ohos.base';

let isLocked: boolean = false;
try {
  screen.setScreenRotationLocked(isLocked).then(() => {
    console.info('Succeeded in unlocking auto rotate');
  }).catch((err: BusinessError) => {
    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

import { BusinessError } from '@ohos.base';

let isLocked: boolean = false;
try {
  screen.setScreenRotationLocked(isLocked, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      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 px. The value must be an integer.
height	number	Yes	Yes	Height of the virtual screen, in px. The value must be an integer.
density	number	Yes	Yes	Density of the virtual screen, in px. 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() or createVirtualScreen() 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>	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	Yes	No	Screen orientation.
sourceMode¹⁰⁺	ScreenSourceMode	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	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.

ID	Error Message
1400003	This display manager service works abnormally.

Example

import { BusinessError } from '@ohos.base';

  try {
    class VirtualScreenOption {
      name : string = '';
      width : number =  0;
      height : number = 0;
      density : number = 0;
      surfaceId : string = '';
    }

    let option : VirtualScreenOption = {
      name: 'screen01',
      width: 1080,
      height: 2340,
      density: 2,
      surfaceId: ''
    };

    screen.createVirtualScreen(option).then((data: screen.Screen) => {
      let screenClass: screen.Screen = data;
      console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
      screenClass.setOrientation(screen.Orientation.VERTICAL, (err: BusinessError) => {
        const errCode: number = err.code;
        if (errCode) {
          console.error('Failed to set the vertical orientation. Code: ' + JSON.stringify(err));
          return;
        }
        console.info('Succeeded in setting the vertical orientation.');
      });
    }).catch((err: BusinessError) => {
      console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err));
    });
  } 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	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.

ID	Error Message
1400003	This display manager service works abnormally.

Example

import { BusinessError } from '@ohos.base';

  try {
    class VirtualScreenOption {
      name : string = '';
      width : number =  0;
      height : number = 0;
      density : number = 0;
      surfaceId : string = '';
    }

    let option : VirtualScreenOption = {
      name: 'screen01',
      width: 1080,
      height: 2340,
      density: 2,
      surfaceId: ''
    };

    screen.createVirtualScreen(option).then((data: screen.Screen) => {
      let screenClass: screen.Screen = data;
      console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
      let promise: Promise<void> = screenClass.setOrientation(screen.Orientation.VERTICAL);
      promise.then(() => {
        console.info('Succeeded in setting the vertical orientation.');
      }).catch((err: BusinessError) => {
        console.error('Failed to set the vertical orientation. Cause: ' + JSON.stringify(err));
      });
    }).catch((err: BusinessError) => {
      console.error('Failed to create the virtual screen. Code: ' + 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.

ID	Error Message
1400003	This display manager service works abnormally.

Example

import { BusinessError } from '@ohos.base';

try {
  class VirtualScreenOption {
    name : string = '';
    width : number =  0;
    height : number = 0;
    density : number = 0;
    surfaceId : string = '';
  }

  let option : VirtualScreenOption = {
    name: 'screen01',
    width: 1080,
    height: 2340,
    density: 2,
    surfaceId: ''
  };

  screen.createVirtualScreen(option).then((data: screen.Screen) => {
    let screenClass: screen.Screen = data;
    console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
    let modeIndex: number = 0;
    screenClass.setScreenActiveMode(modeIndex, (err: BusinessError) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err));
        return;
      }
      console.info('Succeeded in setting the vertical orientation.');
    });
  }).catch((err: BusinessError) => {
    console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err));
  });
} catch (exception) {
  console.error('Failed to set the vertical orientation. 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.

ID	Error Message
1400003	This display manager service works abnormally.

Example

import { BusinessError } from '@ohos.base';

try {
  class VirtualScreenOption {
    name : string = '';
    width : number =  0;
    height : number = 0;
    density : number = 0;
    surfaceId : string = '';
  }

  let option : VirtualScreenOption = {
    name: 'screen01',
    width: 1080,
    height: 2340,
    density: 2,
    surfaceId: ''
  };

  screen.createVirtualScreen(option).then((data: screen.Screen) => {
    let screenClass: screen.Screen = data;
    console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
    let modeIndex: number = 0;
    let promise: Promise<void> = screenClass.setScreenActiveMode(modeIndex);
    promise.then(() => {
      console.info('Succeeded in setting screen active mode 0.');
    }).catch((err: BusinessError) => {
      console.error('Failed to set screen active mode 0. Code: ' + JSON.stringify(err));
    });
  }).catch((err: BusinessError) => {
    console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err));
  });
} catch (exception) {
  console.error('Failed to set the vertical orientation. 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.

ID	Error Message
1400003	This display manager service works abnormally.

Example

import { BusinessError } from '@ohos.base';

let densityDpi: number = 320;
try {
  class VirtualScreenOption {
    name : string = '';
    width : number =  0;
    height : number = 0;
    density : number = 0;
    surfaceId : string = '';
  }

  let option : VirtualScreenOption = {
    name: 'screen01',
    width: 1080,
    height: 2340,
    density: 2,
    surfaceId: ''
  };

  screen.createVirtualScreen(option).then((data: screen.Screen) => {
    let screenClass: screen.Screen = data;
    console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(data));
    screenClass.setDensityDpi(densityDpi, (err: BusinessError) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err));
        return;
      }
      console.info('Succeeded in setting the vertical orientation.');
    });
  }).catch((err: BusinessError) => {
    console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err));
  });
} catch (exception) {
  console.error('Failed to set the vertical orientation. 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.

ID	Error Message
1400003	This display manager service works abnormally.

Example

import { BusinessError } from '@ohos.base';

let densityDpi: number = 320;
try {
  class VirtualScreenOption {
    name : string = '';
    width : number =  0;
    height : number = 0;
    density : number = 0;
    surfaceId : string = '';
  }

  let option : VirtualScreenOption = {
    name: 'screen01',
    width: 1080,
    height: 2340,
    density: 2,
    surfaceId: ''
  };

  screen.createVirtualScreen(option).then((data: screen.Screen) => {
    let screenClass: screen.Screen = data;
    let promise: Promise<void> = screenClass.setDensityDpi(densityDpi);
    promise.then(() => {
      console.info('Succeeded in setting the pixel density of the screen to 320.');
    }).catch((err: BusinessError) => {
      console.error('Failed to set the pixel density of the screen to 320. Code: ' + JSON.stringify(err));
    });
  }).catch((err: BusinessError) => {
    console.error('Failed to create the virtual screen. Code: ' + JSON.stringify(err));
  });
} catch (exception) {
  console.error('Failed to set the vertical orientation. 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.

ScreenSourceMode¹⁰⁺

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 px. The value must be an integer.
height	number	Yes	Yes	Height of the screen, in px. The value must be an integer.
refreshRate	number	Yes	Yes	Refresh rate of the screen, in hz. The value must be an integer.

@ohos.screen (Screen) (System API)

Modules to Import

screen.getAllScreens

screen.getAllScreens

screen.on('connect' | 'disconnect' | 'change')

screen.off('connect' | 'disconnect' | 'change')

screen.makeExpand

screen.makeExpand

screen.stopExpand10+

screen.stopExpand10+

screen.makeMirror

screen.makeMirror

screen.stopMirror10+

screen.stopMirror10+

screen.createVirtualScreen

screen.createVirtualScreen

screen.destroyVirtualScreen

screen.destroyVirtualScreen

screen.setVirtualScreenSurface

screen.setVirtualScreenSurface

screen.isScreenRotationLocked

screen.isScreenRotationLocked

screen.setScreenRotationLocked

screen.setScreenRotationLocked

ExpandOption

VirtualScreenOption

Screen

Attributes

setOrientation

setOrientation

setScreenActiveMode

setScreenActiveMode

setDensityDpi

setDensityDpi

Orientation

ScreenSourceMode10+

ScreenModeInfo

screen.stopExpand¹⁰⁺

screen.stopExpand¹⁰⁺

screen.stopMirror¹⁰⁺

screen.stopMirror¹⁰⁺

ScreenSourceMode¹⁰⁺