You can perform the following operations during application window development:
Setting the properties and content of the main window of an application
Setting the properties and content of the subwindow of an application
The following describes the development procedure specific to each application scenario.
The table below lists the common APIs used for application window development. For details about more APIs, see @ohos.window.
| Instance | API | Description |
|---|---|---|
| WindowStage | getMainWindow(callback: AsyncCallback<Window>): void | Obtains the main window of this window stage. This API can be used only in the stage model. |
| WindowStage | loadContent(path: string, callback: AsyncCallback<void>): void | Loads content to the main window in this window stage. path: path of the page from which the content will be loaded. The path is configured in the main_pages.json file of the project. This API can be used only in the stage model. |
| WindowStage | createSubWindow(name: string, callback: AsyncCallback<Window>): void | Creates a subwindow. This API can be used only in the stage model. |
| WindowStage | on(type: 'windowStageEvent', callback: Callback<WindowStageEventType>): void | Subscribes to the WindowStage lifecycle change event. This API can be used only in the stage model. |
| Window | setUIContent(path: string, callback: AsyncCallback<void>): void | Loads the content of a page, with its path in the current project specified, to this window. path: path of the page from which the content will be loaded. The path is configured in the main_pages.json file of the project in the stage model. |
| Window | setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void | Sets whether the window is in private mode. |
| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | Moves this window. |
| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | Changes the window size. |
| Window | showWindow(callback: AsyncCallback<void>): void | Shows this window. |
| Window | destroyWindow(callback: AsyncCallback<void>): void | Destroys this window. |
UIAbility creates and maintains the lifecycle of the main window of an application. In the onWindowStageCreate callback of UIAbility, use WindowStage to obtain the main window of the application and set its properties. You can also set the properties (for example, maxWindowWidth) in the module.json5 file.
Prerequisites: setWindowPrivacyMode is used to set a window to the privacy mode, which is applicable to scenarios where screen capture or recording is disabled. To use this API, you must request the ohos.permission.PRIVACY_WINDOW permission. For details, see Requesting Application Permissions.
Call getMainWindow to obtain the main window of the application.
Set the privacy mode of the main window.
If the setWindowPrivacyMode API is used to set the main window to the privacy mode, the content in the window cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled.
Load content to the main window.
Call loadContent to load content to the main window.
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
// 1. Obtain the main window of the application.
let windowClass: window.Window | null = null;
windowStage.getMainWindow((err: BusinessError, data) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err));
return;
}
windowClass = data;
console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
// 2. Set the window to the privacy mode.
let isPrivacyMode: boolean = true;
try {
windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => {
const errCode: number = err.code;
if(errCode) {
console.error('Failed to set the window to privacy mode. Cause:' +
JSON.stringify(err));
return;
}
console.info('Succeeded in setting the window to privacy mode.');
});
} catch (exception) {
console.error('Failed to set the window to privacy mode. Cause:' +
JSON.stringify(exception));
}
})
// 3. Load content to the main window.
windowStage.loadContent("pages/page2", (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to load the content. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in loading the content.');
});
}
}; You can create a subwindow, such as a dialog box, and set its properties.
Call createSubWindow to create a subwindow.
Set the properties of the subwindow.
After the subwindow is created, you can set its properties, such as the size, position, background color, and brightness.
Load content to and show the subwindow.
Call setUIContent to load content to the subwindow and showWindow to show the subwindow.
When the subwindow is no longer needed, you can call destroyWindow to destroy it.
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import { BusinessError } from '@ohos.base';
let windowStage_: window.WindowStage | null = null;
let sub_windowClass: window.Window | null = null;
export default class EntryAbility extends UIAbility {
showSubWindow() {
// 1. Create a subwindow.
if (windowStage_ == null) {
console.error('Failed to create the subwindow. Cause: windowStage_ is null');
}
else {
windowStage_.createSubWindow("mySubWindow", (err: BusinessError, data) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err));
return;
}
sub_windowClass = data;
console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
// 2. Set the position, size, and other properties of the subwindow.
sub_windowClass.moveWindowTo(300, 300, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to move the window. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in moving the window.');
});
sub_windowClass.resize(500, 500, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to change the window size. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in changing the window size.');
});
// 3. Load the page content to the subwindow.
sub_windowClass.setUIContent("pages/page3", (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to load the content. Cause:' + JSON.stringify(err));
return;
}
console.info('Succeeded in loading the content.');
// 3. Show the subwindow.
(sub_windowClass as window.Window).showWindow((err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in showing the window.');
});
});
})
}
}
destroySubWindow() {
// 4. Destroy the subwindow when it is no longer needed (depending on the service logic).
(sub_windowClass as window.Window).destroyWindow((err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err));
return;
}
console.info('Succeeded in destroying the window.');
});
}
onWindowStageCreate(windowStage: window.WindowStage) {
windowStage_ = windowStage;
// Create a subwindow when it is needed, for example, when a tap event occurs in the main window. Calling onWindowStageCreate is not always necessary. The code here is for reference only.
this.showSubWindow();
}
onWindowStageDestroy() {
// Destroy the subwindow when it is no longer needed, for example, when the Close button in the subwindow is tapped. Calling onWindowStageDestroy is not always necessary. The code here is for reference only.
this.destroySubWindow();
}
}; When running in the foreground, an application may switch between interactive and non-interactive states and process services depending on the state. For example, when the user opens the multitasking screen, an application becomes non-interactive and pauses the service interaction with the user, such as video playback or camera preview; when the user switched back to the foreground, the application becomes interactive again, and the paused service needs to be resumed.
After a WindowStage object is created, the application can listen for the windowStageEvent event to obtain window stage lifecycle changes, for example, whether the window stage is interactive or non-interactive in the foreground. The application can process services based on the reported event status.
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
try {
windowStage.on('windowStageEvent', (data) => {
console.info('Succeeded in enabling the listener for window stage event changes. Data: ' +
JSON.stringify(data));
// Process services based on the event status.
if (data == window.WindowStageEventType.SHOWN) {
console.info('current window stage event is SHOWN');
// The application enters the foreground and is interactive by default.
// ...
} else if (data == window.WindowStageEventType.HIDDEN) {
console.info('current window stage event is HIDDEN');
// The application enters the background and is non-interactive by default.
// ...
} else if (data == window.WindowStageEventType.PAUSED) {
console.info('current window stage event is PAUSED');
// The user opens the multitasking screen when the application is running in the foreground, and the application becomes non-interactive.
// ...
} else if (data == window.WindowStageEventType.RESUMED) {
console.info('current window stage event is RESUMED');
// The user switches back from the multitasking screen to the application, and the application becomes interactive.
// ...
}
// ...
});
} catch (exception) {
console.error('Failed to enable the listener for window stage event changes. Cause:' +
JSON.stringify(exception));
}
}
}