@ohos.display (Display) (System API)
The Display module provides APIs for managing displays, such as obtaining information about the default display, obtaining information about all displays, and listening for the addition and removal of displays.
NOTE
The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
This topic describes only system APIs provided by the module. For details about its public APIs, see @ohso.display (Display).
Modules to Import
import display from '@ohos.display';
display.hasPrivateWindow9+
hasPrivateWindow(displayId: number): boolean
Checks whether there is a visible privacy window on a display. The privacy window can be set by calling setWindowPrivacyMode(). The content in the privacy window cannot be captured or recorded.
System API: This is a system API.
System capability: SystemCapability.WindowManager.WindowManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | number | Yes | ID of the display. The value must be an integer. |
Return value
Type | Description |
---|---|
boolean | Whether there is a visible privacy window on the display. The value true means that there is a visible privacy window on the display, and false means the opposite. |
Error codes
For details about the error codes, see Display Error Codes.
ID | Error Message |
---|---|
1400003 | This display manager service works abnormally. |
Example
import display from '@ohos.display';
let displayClass: display.Display | null = null;
try {
displayClass = display.getDefaultDisplaySync();
let ret: boolean = true;
try {
ret = display.hasPrivateWindow(displayClass.id);
} catch (exception) {
console.error('Failed to check has privateWindow or not. Code: ' + JSON.stringify(exception));
}
if (ret == undefined) {
console.log("Failed to check has privateWindow or not.");
}
if (ret) {
console.log("There has privateWindow.");
} else if (!ret) {
console.log("There has no privateWindow.");
}
} catch (exception) {
console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}
display.on('privateModeChange')10+
on(type: 'privateModeChange', callback: Callback<boolean>): void
Subscribes to privacy mode changes of this display. When there is a privacy window in the foreground of the display, the display is in privacy mode, and the content in the privacy window cannot be captured or recorded.
System API: This is a system API.
System capability: SystemCapability.WindowManager.WindowManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed at 'privateModeChange', indicating the event of display privacy mode changes. |
callback | Callback<boolean> | Yes | Callback used to return whether the privacy mode of the display is changed. The value true means that the display changes to the privacy mode, and false means the opposite. |
Example
import { Callback } from '@ohos.base';
let callback: Callback<boolean> = (data: boolean) => {
console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
try {
display.on("privateModeChange", callback);
} catch (exception) {
console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
}
display.off('privateModeChange')10+
off(type: 'privateModeChange', callback?: Callback<boolean>): void
Unsubscribes from privacy mode changes of this display. When there is a privacy window in the foreground of the display, the display is in privacy mode, and the content in the privacy window cannot be captured or recorded.
System API: This is a system API.
System capability: SystemCapability.WindowManager.WindowManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed at 'privateModeChange', indicating the event of display privacy mode changes. |
callback | Callback<boolean> | No | Callback used to return whether the privacy mode of the display is changed. The value true means that the display changes to the privacy mode, and false means the opposite. |
Example
try {
display.off("privateModeChange");
} catch (exception) {
console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
}
display.setFoldDisplayMode10+
setFoldDisplayMode(mode: FoldDisplayMode): void
Sets the display mode of the foldable device.
System API: This is a system API.
System capability: SystemCapability.Window.SessionManager
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
mode | FoldDisplayMode | Yes | Display mode. |
Error codes
For details about the error codes, see Display Error Codes.
ID | Error Message |
---|---|
1400003 | This display manager service works abnormally. |
Example
import display from '@ohos.display';
try {
let mode: display.FoldDisplayMode = display.FoldDisplayMode.FOLD_DISPLAY_MODE_FULL;
display.setFoldDisplayMode(mode);
} catch (exception) {
console.error('Failed to change the fold display mode. Code: ' + JSON.stringify(exception));
}
display.setFoldStatusLocked11+
setFoldStatusLocked(locked: boolean): void
Sets whether to lock the current fold status of the foldable device.
System API: This is a system API.
System capability: SystemCapability.Window.SessionManager
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
locked | boolean | Yes | Whether to lock the current fold status of the foldable device. The value true means to lock the current fold status, and false means the opposite. |
Error codes
For details about the error codes, see Display Error Codes.
ID | Error Message |
---|---|
1400003 | This display manager service works abnormally. |
Example
import display from '@ohos.display';
try {
let locked: boolean = false;
display.setFoldStatusLocked(locked);
} catch (exception) {
console.error('Failed to change the fold status locked mode. Code: ' + JSON.stringify(exception));
}
Display
Implements a Display instance, with properties and APIs defined.
Before calling any API in Display, you must use getAllDisplays() or getDefaultDisplaySync() to obtain a Display instance.
hasImmersiveWindow11+
hasImmersiveWindow(callback: AsyncCallback<boolean>): void
Checks whether this screen contains an immersive window. This API uses an asynchronous callback to return the result.
System API: This is a system API.
System capability: SystemCapability.Window.SessionManager
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value true means that the screen contains immersive windows, and false means the opposite. |
Error codes
For details about the error codes, see Display Error Codes.
ID | Error Message |
---|---|
1400001 | Invalid display or screen. |
1400003 | This display manager service works abnormally. |
Example
import { BusinessError } from '@ohos.base';
import display from '@ohos.display'
let displayClass: display.Display | null = null;
try {
displayClass = display.getDefaultDisplaySync();
} catch (exception) {
console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}
try {
displayClass.hasImmersiveWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(exception));
}
hasImmersiveWindow11+
hasImmersiveWindow(): Promise<boolean>
Checks whether this screen contains an immersive window. This API uses a promise to return the result.
System API: This is a system API.
System capability: SystemCapability.Window.SessionManager
Return value
Type | Description |
---|---|
Promise<boolean> | Promise used to return the result. The value true means that the screen contains immersive windows, and false means the opposite. |
Error codes
For details about the error codes, see Display Error Codes.
ID | Error Message |
---|---|
1400001 | Invalid display or screen. |
1400003 | This display manager service works abnormally. |
Example
import { BusinessError } from '@ohos.base';
import display from '@ohos.display'
let displayClass: display.Display | null = null;
try {
displayClass = display.getDefaultDisplaySync();
} catch (exception) {
console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}
let promise = displayClass.hasImmersiveWindow();
promise.then((data) => {
console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err));
})
getAvailableArea11+
getAvailableArea(): Promise<Rect>
Obtains the available area of the current screen. This API uses a promise to return the result.
System API: This is a system API.
System capability: SystemCapability.Window.SessionManager
Return value
Type | Description |
---|---|
Promise<Rect> | Promise used to return the available area, which is a rectangle. |
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';
import display from '@ohos.display'
let displayClass: display.Display | null = null;
try {
displayClass = display.getDefaultDisplaySync();
let promise = displayClass.getAvailableArea();
promise.then((data) => {
console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error('Failed to get the available area in this display. Code: ' + JSON.stringify(err));
})
} catch (exception) {
console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}
on('availableAreaChange')11+
on(type: 'availableAreaChange', callback: Callback<Rect>): void
Subscribes to changes of the available area on the current screen. This API uses an asynchronous callback to return the result.
System API: This is a system API.
System capability: SystemCapability.Window.SessionManager
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The event 'availableAreaChange' is triggered when the available area of the screen changes. |
callback | Callback<Rect> | Yes | Callback used to return the new available area. |
Error codes
For details about the error codes, see Display Error Codes.
ID | Error Message |
---|---|
1400003 | This display manager service works abnormally. |
Example
import { Callback } from '@ohos.base';
import display from '@ohos.display'
let callback: Callback<display.Rect> = (data: display.Rect) => {
console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
let displayClass: display.Display | null = null;
try {
displayClass = display.getDefaultDisplaySync();
displayClass.on("availableAreaChange", callback);
} catch (exception) {
console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
}
off('availableAreaChange')11+
off(type: 'availableAreaChange', callback?: Callback<Rect>): void
Unsubscribes from changes of the available area on the current screen.
System API: This is a system API.
System capability: SystemCapability.Window.SessionManager
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The event 'availableAreaChange' is triggered when the available area of the screen changes. |
callback | Callback<Rect> | No | Callback used for unsubscription. If no value is passed in, all subscriptions to the specified event are canceled. |
Error codes
For details about the error codes, see Display Error Codes.
ID | Error Message |
---|---|
1400003 | This display manager service works abnormally. |
Example
import { Callback } from '@ohos.base';
import display from '@ohos.display'
let callback: Callback<display.Rect> = (data: display.Rect) => {
console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
let displayClass: display.Display | null = null;
try {
displayClass = display.getDefaultDisplaySync();
displayClass.off("availableAreaChange", callback);
} catch (exception) {
console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
}