@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

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

Error codes

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

Example

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

Error codes

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

Example

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

Example

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

Example

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

Error codes

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

Example

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

Return value

Error codes

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

Example

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.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

Error codes

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

Example

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

Return value

Error codes

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

Example

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.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

Error codes

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

Example

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

Return value

Error codes

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

Example

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

Error codes

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

Example

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

Return value

Error codes

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

Example

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

Error codes

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

Example

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

Return value

Error codes

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

Example

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

Example

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

Example

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

Return value

Example

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

Example

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

VirtualScreenOption

Defines virtual screen parameters.

System capability: SystemCapability.WindowManager.WindowManager.Core

Screen

Implements a Screen instance.

Before calling any API in Screen, you must use getAllScreens() or createVirtualScreen() to obtain a Screen instance.

System capability: SystemCapability.WindowManager.WindowManager.Core

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

Error codes

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

Example

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

Return value

Error codes

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

Example

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

Error codes

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

Example

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

Return value

Error codes

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

Example

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

Error codes

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

Example

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

Return value

Error codes

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

Example

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

ScreenModeInfo

Defines the screen mode information.

System capability: SystemCapability.WindowManager.WindowManager.Core