@@ -42,6 +42,7 @@ The table below describes the APIs provided by the `AbilityStage` class, which h
The table below describes the APIs provided by the `Ability` class. For details about the APIs, see [Ability](../reference/apis/js-apis-application-ability.md).
**Table 2** Ability APIs
|API|Description|
|:------|:------|
|onCreate(want: Want, param: AbilityConstant.LaunchParam): void|Called when an ability is created.|
...
...
@@ -58,7 +59,7 @@ To create Page abilities for an application in the stage model, you must impleme
```
import AbilityStage from "@ohos.application.AbilityStage"
```
2. Implement the `AbilityStage` class.
2. Implement the `AbilityStage` class. The default relative path generated by the APIs is **entry\src\main\ets\Application\AbilityStage.ts**.
@@ -70,9 +71,9 @@ To create Page abilities for an application in the stage model, you must impleme
```js
importAbilityfrom'@ohos.application.Ability'
```
4. Implement the lifecycle callbacks of the `Ability` class.
4. Implement the lifecycle callbacks of the `Ability` class. The default relative path generated by the APIs is **entry\src\main\ets\MainAbility\MainAbility.ts**.
In the `onWindowStageCreate(windowStage)` API, use `loadContent` to set the application page to be loaded. For details about how to use the `Window` APIs, see [Window Development](../windowmanager/window-guidelines.md).
In the `onWindowStageCreate(windowStage)` API, use `loadContent` to set the application page to be loaded. For details about how to use the `Window` APIs, see [Window Development](../windowmanager/application-window-stage.md).
```ts
exportdefaultclassMainAbilityextendsAbility{
onCreate(want,launchParam){
...
...
@@ -87,7 +88,7 @@ To create Page abilities for an application in the stage model, you must impleme
console.log("MainAbility load content succeed with data: "+JSON.stringify(data))
console.log("MainAbility load content succeed")
}).catch((error)=>{
console.error("MainAbility load content failed with error: "+JSON.stringify(error))
})
...
...
@@ -107,7 +108,10 @@ To create Page abilities for an application in the stage model, you must impleme
}
```
### Obtaining AbilityStage and Ability Configurations
Both the `AbilityStage` and `Ability` classes have the `context` attribute. An application can obtain the context of an `Ability` instance through `this.context` to obtain the configuration details. The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the `context` attribute in the `AbilityStage` class. The sample code is as follows:
Both the `AbilityStage` and `Ability` classes have the `context` attribute. An application can obtain the context of an `Ability` instance through `this.context` to obtain the configuration details.
The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the `context` attribute in the `AbilityStage` class. The sample code is as follows:
Immersive window: System windows such as the status bar and navigation bar are controlled in such a way that they are unobtrusive and natural looking in the entire screen, thereby engaging users more deeply with the content displayed.
The immersive window feature is valid only when the main window of an application is displayed in full-screen mode. It does not apply to a main window in free window mode or a subwindow (for example, a dialog box or a floating window).
## When to Use
In the FA model, you can perform the following operations during application window development:
- Setting the properties and content of the subwindow of an application
- Experiencing the immersive window feature
## Available APIs
The table below lists the common APIs used for application window development. For details about more APIs, see [Window](../reference/apis/js-apis-window.md).
| Instance| API| Description|
| -------- | -------- | -------- |
| Window static method| create(id: string, type: WindowType, callback: AsyncCallback<Window>): void | Creates a subwindow.<br>This API can be used only in the FA model.|
| Window static method| getTopWindow(callback: AsyncCallback<Window>): void | Obtains the top window of the current application.<br>This API can be used only in the FA model.|
| Window static method| find(id: string, callback: AsyncCallback<Window>): void | Finds a window based on the ID.|
| Window | loadContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to this window.|
| Window | setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void | Sets whether to enable the full-screen mode for this window.|
| Window | setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void | Sets whether to enable the full-screen mode for the window layout. |
| Window | setSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | Sets whether to display the status bar and navigation bar in this window.|
| Window | setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void | Sets the properties of the status bar and navigation bar in this window.<br>`systemBarProperties`: properties of the status bar and navigation bar.|
| Window | show(callback: AsyncCallback\<void>): void | Shows this window.|
| Window | on(type: 'touchOutside', callback: Callback<void>): void | Enables listening for click events outside this window.|
| Window | destroy(callback: AsyncCallback<void>): void | Destroys this window.|
## Setting the Subwindow of an Application
You can create a subwindow, such as a dialog box, and set its properties.
### How to Develop
1. Create or obtain a subwindow.
- Call `window.create` to create a subwindow.
- Call `window.getTopWindow` to obtain the top window – subwindow.
- Call `window.find` to find an available subwindow.
console.error('Failed to load the content. Cause: '+JSON.stringify(err));
return;
}
console.info('Succeeded in loading the content. Data: '+JSON.stringify(data));
// 3. Show the subwindow.
windowClass.show((err,data)=>{
if(err.code){
console.error('Failed to show the window. Cause: '+JSON.stringify(err));
return;
}
console.info('Succeeded in showing the window. Data: '+JSON.stringify(data));
});
});
```
4. Destroy the subwindow.
When the subwindow is no longer needed, you can call `destroy` to destroy it.
```js
// 4. Destroy the subwindow when a click event outside the window is detected.
windowClass.on('touchOutside',()=>{
console.info('touch outside');
windowClass.destroy((err,data)=>{
if(err.code){
console.error('Failed to destroy the subwindow. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in destroying the subwindow. Data: '+JSON.stringify(data));
});
});
```
## Experiencing the Immersive Window Feature
To create a better video watching and gaming experience, you can use the immersive window feature to hide the system windows, including the status bar and navigation bar. To achieve this effect, you can use the immersive window feature, which is available only for the main window of an application.
### How to Develop
1. Obtain the main window.
The immersive window feature can be implemented only after the main window is obtained. You can call `window.getTopWindow` to obtain the main window.
```js
importwindowfrom'@ohos.window';
varmainWindowClass=null;
// 1. Obtain the main window.
window.getTopWindow((err,data)=>{
if(err.code){
console.error('Failed to get the subWindow. Cause: '+JSON.stringify(err));
return;
}
console.info('Succeeded in getting subWindow. Data: '+JSON.stringify(data));
mainWindowClass=data;
});
```
2. Implement the immersive effect. You can use any of the following methods:
- Method 1: Call `setFullScreen` to set the main window to be displayed in full screen. In this case, the navigation bar and status bar are hidden.
- Method 2: Call `setSystemBarEnable` to hide the navigation bar and status bar.
- Method 3: Call `setLayoutFullScreen` to enable the full-screen mode for the main window layout. Call `setSystemPropertites` to set the opacity, background color, text color, and highlighted icon of the navigation bar and status bar to ensure that their display effect is consistent with that of the main window.
```js
// 2. Use method 1 to implement the immersive effect.
- Immersive window: System windows such as the status bar and navigation bar are controlled in such a way that they are unobtrusive on the entire screen, thereby engaging users more deeply with the content displayed.
The immersive window feature is valid only when the main window of an application is displayed in full-screen mode. It does not apply to a main window in free window mode or a subwindow (for example, a dialog box or a floating window).
- Floating window: a special application window that can still be displayed in the foreground when the main window and corresponding ability are running the background.
The floating window can be used to continue playing a video in a small window after the application returns to the background, or offer a quick entry (for example, bubbles) to a specific application. Before creating a floating window, an application must apply for the required permission.
## When to Use
In the stage model, 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
- Experiencing the immersive window feature
- Setting a floating window
## Available APIs
The table below lists the common APIs used for application window development. For details about more APIs, see [Window](../reference/apis/js-apis-window.md).
| Instance| API| Description|
| -------- | -------- | -------- |
| WindowStage | getMainWindow(callback: AsyncCallback<Window>): void | Obtains the main window of this window stage.<br>This API can be used only in the stage model.|
| WindowStage | loadContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to the main window in this window stage.<br>This API can be used only in the stage model.|
| WindowStage | createSubWindow(name: string, callback: AsyncCallback<Window>): void | Creates a subwindow.<br>This API can be used only in the stage model.|
| Window | setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void | Sets whether to enable the full-screen mode for this window.|
| Window | setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void | Sets whether to enable the full-screen mode for the window layout. |
| Window | setSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | Sets whether to display the status bar and navigation bar in this window.|
| Window | setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void | Sets the properties of the status bar and navigation bar in this window.<br>`systemBarProperties`: properties of the status bar and navigation bar.|
| Window | show(callback: AsyncCallback\<void>): void | Shows this window.|
| Window | on(type: 'touchOutside', callback: Callback<void>): void | Enables listening for click events outside this window.|
| Window | destroy(callback: AsyncCallback<void>): void | Destroys this window.|
## Setting the Main Window of an Application
In the stage model, the main window of an application is created and maintained by an `Ability` instance. In the `onWindowStageCreate` callback of the `Ability` instance, use `WindowStage` to obtain the main window of the application and set its properties.
### How to Develop
1. Obtain the main window.
Call `getMainWindow` to obtain the main window of the application.
2. Set the properties of the main window.
You can set multiple properties of the main window, such as the background color, brightness, and whether the main window is touchable. The code snippet below uses the `touchable` property as an example.
3. Load content for the main window.
Call `loadContent` to load the page content to the main window.
```ts
importAbilityfrom'@ohos.application.Ability'
classMainAbilityextendsAbility{
onWindowStageCreate(windowStage){
// 1. Obtain the main window of the application.
varwindowClass=null;
windowStage.getMainWindow((err,data)=>{
if(err.code){
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 touchable property of the main window.
console.error('Failed to load the content. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in loading the content. Data: '+JSON.stringify(data));
// 3. Show the subwindow.
sub_windowClass.show((err,data)=>{
if(err.code){
console.error('Failed to show the window. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in showing the window. Data: '+JSON.stringify(data));
});
});
// 4. Destroy the subwindow when a click event outside the window is detected.
sub_windowClass.on('touchOutside',()=>{
console.info('touch outside');
sub_windowClass.destroy((err,data)=>{
if(err.code){
console.error('Failed to destroy the window. Cause: '+JSON.stringify(err));
return;
}
console.info('Succeeded in destroying the window. Data: '+JSON.stringify(data));
});
});
})
}
};
```
## Experiencing the Immersive Window Feature
To create a better video watching and gaming experience, you can use the immersive window feature to hide the system windows, including the status bar and navigation bar. To achieve this effect, you can use the immersive window feature, which is available only for the main window of an application.
### How to Develop
1. Obtain the main window.
Call `getMainWindow` to obtain the main window of the application.
2. Implement the immersive effect. You can use any of the following methods:
- Method 1: Call `setFullScreen` to set the main window to be displayed in full screen. In this case, the navigation bar and status bar are hidden.
- Method 2: Call `setSystemBarEnable` to hide the navigation bar and status bar.
- Method 3: Call `setLayoutFullScreen` to enable the full-screen mode for the main window layout. Call `setSystemPropertites` to set the opacity, background color, text color, and highlighted icon of the navigation bar and status bar to ensure that their display effect is consistent with that of the main window.
3. Load content for the immersive window and show it.
Call `loadContent` and `show` to load and display the content in the immersive window.
```ts
importAbilityfrom'@ohos.application.Ability'
classMainAbilityextendsAbility{
onWindowStageCreate(windowStage){
// 1. Obtain the main window of the application.
varwindowClass=null;
windowStage.getMainWindow((err,data)=>{
if(err.code){
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. Use method 1 to implement the immersive effect.
console.error('Failed to load the content. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in loading the content. Data: '+JSON.stringify(data));
// 3. Show the immersive window.
windowStage.show((err,data)=>{
if(err.code){
console.error('Failed to show the window. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in showing the window. Data: '+JSON.stringify(data));
});
});
}
};
```
## Setting a Floating Window
A floating window is created based on an existing task. It is always displayed in the foreground, even if the task used for creating the floating window is switched to the background. You can create a floating window and set its properties.
### How to Develop
1. Apply for permissions.
To create a floating window (of the `WindowType.TYPE_FLOAT` type), you must configure the `ohos.permission.SYSTEM_FLOAT_WINDOW` permission in the `requestPermissions` field of the `module.json5` file. For details about the file, see [Application Package Structure Configuration File](../quick-start/stage-structure.md).
> **NOTE**
>
> If the task for creating the floating window is reclaimed by the system, the floating window will no longer be displayed. If you want the floating window to be displayed in such a case, apply for a [continuous task](../task-management/background-task-overview.md).
```json
{
"module":{
"requestPermissions":[
{
"name":"ohos.permission.SYSTEM_FLOAT_WINDOW",
"usedScene":{
"abilities":[
"MainAbility"
],
"when":"inuse"
}
}
]
}
}
```
2. Create a floating window.
Call `window.create` to create a floating window.
3. Set properties for the floating window.
After the floating window is created, you can set its properties, such as the size, position, background color, and brightness.
4. Load content for the floating window and show it.
Call `loadContent` and `show` to load and display the content in the floating window.
5. Destroy the floating window.
When the floating window is no longer needed, you can call `destroy` to destroy it.
In the stage model, system applications are allowed to create and manage system windows, including the volume bar, wallpaper, notification panel, status bar, and navigation bar. For details about the supported system window types, see "WindowType" in [Window](../reference/apis/js-apis-window.md).
## Available APIs
For details, see [Window](../reference/apis/js-apis-window.md).
| Instance| API| Description|
| -------- | -------- | -------- |
| Window static method| create(ctx: Context, id: string, type: WindowType, callback: AsyncCallback<Window>): void | Creates a system window when `ctx` is [ServiceExtensionContext](../reference/apis/js-apis-service-extension-context.md).<br>-`ctx`: application context.<br>-`type`: window type. |
| Window | loadContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to this window.|
| Window | show(callback: AsyncCallback\<void>): void | Shows this window.|
| Window | on(type: 'touchOutside', callback: Callback<void>): void | Enables listening for click events outside this window.|
| Window | hide (callback: AsyncCallback\<void>): void | Hides this window. This is a system API.|
| Window | destroy(callback: AsyncCallback<void>): void | Destroys this window.|
## How to Develop
This section uses the volume bar as an example to describe the steps for system window development.
1. Create a system window.
In the case of [ServiceExtensionContext](../reference/apis/js-apis-service-extension-context.md), call `window.create` to create a system window of the volume bar type.
2. Set the properties of the system window.
After the volume bar window is created, you can change its size and position, and set its properties such as the background color and brightness.
3. Load content for the system window and show it.
You can call `loadContent` and `show` to load and display the content in the volume bar window.
4. Hide or destroy the system window.
When the volume bar window is no longer needed, you can call `hide` or `destroy` to hide or destroy it.
| moveTo(x: number, y: number): Promise\<void> | Moves the window. A positive value of **x** indicates that the window moves to the right, and a positive value of **y** indicates that the window moves downwards.|
| destroy(): Promise\<void> | Destroys the window. |
## How to Develop
### Creating a Main Window
Currently, the main window is automatically created when the application is started. The declaration period, hiding, and destruction of the main window are managed by the application.
### Creating a Subwindow
You can call **create** to create a subwindow. The sample code is as follows:
console.error('Failed to find the Window. Cause: '+JSON.stringify(err));
});
```
### Hiding and Destroying a Window
After a window object is obtained, you can call **hide** and **destroy** to hide and destroy the window object, respectively. The sample code is as follows:
The **Window** module provides a mechanism for displaying multiple application UIs and interacting with end users on the same physical screen.
- For application developers, the **Window** module provides APIs for UI display and user interaction.
- For end users, the **Window** module provides a way to control application UIs.
- For the entire operating system, the **Window** module provides logic for application UI management.
## Features
In OpenHarmony, the **Window** module has the following features:
-**Provides a `Window` object to hold application and system UIs.** You can load the UIs through the window to implement UI display.
-**Maintains the window relationship (overlay layers and positions).** Different types of application and system windows have different default positions and overlay layers (z-index). End user can adjust the position and overlay layer of a window within a certain range.
-**Provides window decoration.** Window decoration refers to the title bar and border of a window. The title bar usually provides the Maximize, Minimize, and Close buttons and has the default click behavior. The border enables users to make the window larger or smaller by dragging. Window decoration is the default behavior of OpenHarmony. You can enable or disable window decoration without paying attention to the implementation at the UI code layer.
-**Provides window animations.** When a window is displayed, hidden, or switched, an animation is usually used to smooth the interaction process. In OpenHarmony, the animation is the default behavior for application windows. You do not need to set or modify the code.
-**Provides guidance for input event distribution.** Events are distributed based on the window status and focus. Touch and mouse events are distributed based on the window position and size, and keyboard events are distributed to the focused window. You can call APIs provided by the **Window** module to set whether a window is touchable and can gain focus.
The Window Manager subsystem provides basic capabilities of window management. It is the basis for UI display.
The Window Manager subsystem enables multiple applications to simultaneously display on the same screen and interact with users. For each application, you need to design the interaction interface in the fixed window area. A window acts as a display container of the application UI, and the Window Manager subsystem organizes the interaction UIs into a form visible to end users.
## Basic Concepts
**Immersive**: The colors of the application UI, status bar, and navigation bar are the same to achieve the visual integrity.
### Window Type
In OpenHarmony, the **Window** module provides system windows and application windows.
- A **system window** implements specific functionalities of the system, such as the volume bar, wallpaper, notification panel, status bar, and navigation bar.
- An **application window** is related to the application display. Based on the displayed content, application windows are further classified into main windows and subwindows.
- A main window shows the application UI and appears on the **Recent tasks** page.
- A subwindow shows auxiliary windows such as dialog boxes and floating windows of an application. It is not displayed on the **Task Management** page.
### Application Window Mode
The application window mode refers to the display mode of the main window when it is started. Currently, OpenHarmony supports three application window modes: full-screen, split-screen, and free window. This is the multi-window capability.
- In **full-screen** mode, the main window is displayed on the entire screen when it is started.
- In **split-screen** mode, the main window occupies part of the screen when it is started, and the other part of the screen is occupied by another window. You can resize the two windows by dragging the split line between them.
- In **free window** mode, the size and position of the main window can be changed as needed. Multiple free windows can be simultaneously displayed on the screen. These free windows are arranged on the z-axis in the sequence that they are opened or gain the focus. When a free window is clicked or touched, its z-index is incremented and it gains the focus.
## Working Principles
To display a UI on a screen, the application and system need to request a window object from the Window Manager subsystem. This object generally represents a rectangular area on the screen and has attributes such as the position, width, height, and overlay layer. The object also loads the root node of the UI framework, through which the application UI is loaded and displayed in the window.
The window implementation and development vary according to the application development model, that is, FA model and stage model.
For details about the overall architecture and design ideas of the two models, see [FA Model Overview](../ability/fa-brief.md) and [Stage Model Overview](../ability/stage-brief.md).
You are advised to use the stage model for window development.
## Constraints
You cannot develop system windows in the FA model.
