diff --git a/en/application-dev/ability/stage-ability.md b/en/application-dev/ability/stage-ability.md index 5b61bcec4b25312f994ed94362339e601df5cd55..eaf3f57626dee65535db1fdb4976d83ff547d013 100644 --- a/en/application-dev/ability/stage-ability.md +++ b/en/application-dev/ability/stage-ability.md @@ -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.| @@ -72,35 +73,35 @@ To create Page abilities for an application in the stage model, you must impleme ``` 4. Implement the lifecycle callbacks of the `Ability` class. - 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 export default class MainAbility extends Ability { onCreate(want, launchParam) { console.log("MainAbility onCreate") } - + onDestroy() { console.log("MainAbility onDestroy") } - + onWindowStageCreate(windowStage) { console.log("MainAbility onWindowStageCreate") - + windowStage.loadContent("pages/index").then((data) => { - 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)) }) } - + onWindowStageDestroy() { console.log("MainAbility onWindowStageDestroy") } - + onForeground() { console.log("MainAbility onForeground") } - + onBackground() { console.log("MainAbility onBackground") } @@ -108,6 +109,7 @@ 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: + ```ts import AbilityStage from "@ohos.application.AbilityStage" export default class MyAbilityStage extends AbilityStage { @@ -300,7 +302,7 @@ export default class MainAbility extends Ability { Obtain the `want` parameter that contains the page information from the custom component and process the route based on the URI. ```ts -import router from '@system.router' +import router from '@ohos.router' @Entry @Component diff --git a/en/application-dev/windowmanager/Readme-EN.md b/en/application-dev/windowmanager/Readme-EN.md index 188b3d734af30592e6a886093e8193636cae6357..7007e701afe32675c029f5a4734e50b88f82849f 100644 --- a/en/application-dev/windowmanager/Readme-EN.md +++ b/en/application-dev/windowmanager/Readme-EN.md @@ -2,7 +2,9 @@ * Window * [Window Overview](window-overview.md) - * [Window Development](window-guidelines.md) + * [System Window Development (Stage Model Only)](application-window-stage.md) + * [Application Window Development (FA Model)](application-window-fa.md) + * [Application Window Development (Stage Mode)](system-window-stage.md) * Display * [Display Overview](display-overview.md) * [Display Development](display-guidelines.md) diff --git a/en/application-dev/windowmanager/application-window-fa.md b/en/application-dev/windowmanager/application-window-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..8908173be47d0c3a8bcdb91c1fab623b4d153c9f --- /dev/null +++ b/en/application-dev/windowmanager/application-window-fa.md @@ -0,0 +1,256 @@ +# Application Window Development (FA Model) + +## Basic Concepts + +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.
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.
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 | moveTo(x: number, y: number, callback: AsyncCallback<void>): void | Moves this window.| +| Window | setBackgroundColor(color: string, callback: AsyncCallback<void>): void | Sets the background color for this window.| +| Window | setBrightness(brightness: number, callback: AsyncCallback<void>): void | Sets the brightness for this window.| +| Window | resetSize(width: number, height: number, callback: AsyncCallback<void>): void | Changes the window size.| +| 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.
`systemBarProperties`: properties of the status bar and navigation bar.| +| Window | show(callback: AsyncCallback\): 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. + + ```js + import window from '@ohos.window'; + + var windowClass = null; + // 1. Method 1: Create a subwindow. + window.create("subWindow", window.WindowType.TYPE_APP, (err, data) => { + if (err.code) { + console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in creating subWindow. Data: ' + JSON.stringify(data)); + windowClass = data; + }); + // 1. Method 2: Obtain a subwindow. + 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)); + windowClass = data; + }); + // 1. Method 3: Find a subwindow. + window.find("subWindow", (err, data) => { + if (err.code) { + console.error('Failed to find the subWindow. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in finding subWindow. Data: ' + JSON.stringify(data)); + windowClass = data; + }); + ``` + +2. 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. + + + ```js + // 2. Move the subwindow. + windowClass.moveTo(300, 300, (err, data) => { + if (err.code) { + console.error('Failed to move the window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in moving the window. Data: ' + JSON.stringify(data)); + }); + // 2. Change the size of the subwindow. + windowClass.resetSize(500, 1000, (err, data) => { + if (err.code) { + console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in changing the window size. Data: ' + JSON.stringify(data)); + }); + ``` + +3. Load content for the subwindow and show it. + + Call `loadContent` and `show` to load and display the content in the subwindow. + + + ```js + // 3. Load the page content to the subwindow. + windowClass.loadContent("pages/page2", (err, data) => { + if (err.code) { + 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 + import window from '@ohos.window'; + + var mainWindowClass = 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. + var isFullScreen = true; + mainWindowClass.setFullScreen(isFullScreen, (err, data) => { + if (err.code) { + console.error('Failed to enable the full-screen mode. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in enabling the full-screen mode. Data: ' + JSON.stringify(data)); + }); + // 2. Use method 2 to implement the immersive effect. + var names = []; + mainWindowClass.setSystemBarEnable(names, (err, data) => { + if (err.code) { + console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the system bar to be visible. Data: ' + JSON.stringify(data)); + }); + // 2. Use method 3 to implement the immersive effect. + var isLayoutFullScreen = true; + mainWindowClass.setLayoutFullScreen(isLayoutFullScreen, (err, data) => { + if (err.code) { + console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the window layout to full-screen mode. Data: ' + JSON.stringify(data)); + }); + var SystemBarProperties = { + statusBarColor: '#ff00ff', + navigationBarColor: '#00ff00', + // The following properties are supported since API version 7. + isStatusBarLightIcon: false, + isNavigationBarLightIcon: false, + // The following properties are supported since API version 8. + statusBarContentColor: '#ffffff', + navigationBarContentColor: '#ffffff' + }; + mainWindowClass.setSystemBarProperties(SystemBarProperties, (err, data) => { + if (err.code) { + console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the system bar properties. Data: ' + JSON.stringify(data)); + }); + ``` + +3. Load content for the immersive window and show it. + + Call `loadContent` and `show` to load and display the content in the immersive window. + + + ```js + // 3. Load the page content to the immersive window. + mainWindowClass.loadContent("pages/page3", (err, data) => { + if (err.code) { + 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. + mainWindowClass.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)); + }); + }); + ``` diff --git a/en/application-dev/windowmanager/application-window-stage.md b/en/application-dev/windowmanager/application-window-stage.md new file mode 100644 index 0000000000000000000000000000000000000000..5eca077ff34d4a5cfbe2a76120830bd58db355e7 --- /dev/null +++ b/en/application-dev/windowmanager/application-window-stage.md @@ -0,0 +1,418 @@ +# Application Window Development (Stage Mode) + + +## Basic Concepts + +- 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.
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.
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.| +| Window static method| create(ctx: Context, id: string, type: WindowType, callback: AsyncCallback<Window>): void | Creates a subwindow.
-`ctx`: application context.
-`type`: window type.| +| Window | loadContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to this window.| +| Window | setBackgroundColor(color: string, callback: AsyncCallback<void>): void | Sets the background color for this window.| +| Window | setBrightness(brightness: number, callback: AsyncCallback<void>): void | Sets the brightness for this window.| +| Window | setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void | Sets whether this window is touchable.| +| Window | moveTo(x: number, y: number, callback: AsyncCallback<void>): void | Moves this window.| +| Window | resetSize(width: number, height: number, callback: AsyncCallback<void>): void | Changes the window size.| +| 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.
`systemBarProperties`: properties of the status bar and navigation bar.| +| Window | show(callback: AsyncCallback\): 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 +import Ability from '@ohos.application.Ability' + +class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + // 1. Obtain the main window of the application. + var windowClass = 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. + var isTouchable = true; + windowClass.setTouchable(isTouchable, (err, data) => { + if (err.code) { + console.error('Failed to set the window to be touchable. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the window to be touchable. Data:' + JSON.stringify(data)); + }) + }) + // 3. Load the page content to the main window. + windowStage.loadContent("pages/page2", (err, data) => { + if (err.code) { + console.error('Failed to load the content. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in loading the content. Data: ' + JSON.stringify(data)); + }); + } +}; +``` + + +## Setting a Subwindow of an Application + +You can create an application subwindow, such as a dialog box, and set its properties. + + +### How to Develop + +1. Create or obtain a subwindow. + + Call `createSubWindow` to create a subwindow. + + Call `getSubWindow` to obtain a subwindow. + +2. 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. + +3. Load content for the subwindow and show it. + + Call `loadContent` and `show` to load and display the content in the subwindow. + +4. Destroy the subwindow. + + When the subwindow is no longer needed, you can call `destroy` to destroy it. + + + ```ts + import Ability from '@ohos.application.Ability' + + class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + // 1. Create a subwindow. + var sub_windowClass = null; + windowStage.createSubWindow("mySubWindow", (err, data) => { + if (err.code) { + 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)); + // 1. Obtain an available subwindow. + windowStage.getSubWindow((err, data) => { + if (err.code) { + console.error('Failed to obtain the subWindow. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in obtaining the subWindow. Data: ' + JSON.stringify(data)); + sub_windowClass = data; + }); + // 2. Set the position, size, and other properties of the subwindow. + sub_windowClass.moveTo(300, 300, (err, data) => { + if (err.code) { + console.error('Failed to move the window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in moving the window. Data: ' + JSON.stringify(data)); + }); + sub_windowClass.resetSize(500, 1000, (err, data) => { + if (err.code) { + console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in changing the window size. Data: ' + JSON.stringify(data)); + }); + // 3. Load the page content to the subwindow. + sub_windowClass.loadContent("pages/page3", (err, data) => { + if (err.code) { + 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 + import Ability from '@ohos.application.Ability' + + class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + // 1. Obtain the main window of the application. + var windowClass = 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. + var isFullScreen = true; + windowClass.setFullScreen(isFullScreen, (err, data) => { + if (err.code) { + console.error('Failed to enable the full-screen mode. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in enabling the full-screen mode. Data: ' + JSON.stringify(data)); + }); + // 2. Use method 2 to implement the immersive effect. + var names = null; + windowClass.setSystemBarEnable(names, (err, data) => { + if (err.code) { + console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the system bar to be visible. Data: ' + JSON.stringify(data)); + }); + // 2. Use method 3 to implement the immersive effect. + var isLayoutFullScreen = true; + windowClass.setLayoutFullScreen(isLayoutFullScreen, (err, data) => { + if (err.code) { + console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the window layout to full-screen mode. Data: ' + JSON.stringify(data)); + }); + var SystemBarProperties = { + statusBarColor: '#ff00ff', + navigationBarColor: '#00ff00', + // The following properties are supported since API version 7. + isStatusBarLightIcon: false, + isNavigationBarLightIcon: false, + // The following properties are supported since API version 8. + statusBarContentColor: '#ffffff', + navigationBarContentColor: '#ffffff' + }; + windowClass.setSystemBarProperties(SystemBarProperties, (err, data) => { + if (err.code) { + console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting the system bar properties. Data: ' + JSON.stringify(data)); + }); + }) + // 3. Load the page content to the immersive window. + windowStage.loadContent("pages/page2", (err, data) => { + if (err.code) { + 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. + + ```ts + import Ability from '@ohos.application.Ability' + import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; + import window from '@ohos.window'; + + class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + // 2. Create a floating window. + var windowClass = []; + window.create(this.context, "floatWindow", window.WindowType.TYPE_FlOAT, (err, data) => { + if (err.code) { + console.error('Failed to create the floatWindow. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in creating the floatWindow. Data: ' + JSON.stringify(data)); + windowClass = data; + // 3. Set the position, size, and properties of the floating window. + windowClass.moveTo(300, 300, (err, data) => { + if (err.code) { + console.error('Failed to move the window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in moving the window. Data: ' + JSON.stringify(data)); + }); + windowClass.resetSize(500, 1000, (err, data) => { + if (err.code) { + console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in changing the window size. Data: ' + JSON.stringify(data)); + }); + // 4. Load the page content to the floating window. + windowClass.loadContent("pages/page4", (err, data) => { + if (err.code) { + console.error('Failed to load the content. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in loading the content. Data: ' + JSON.stringify(data)); + // 4. Show the floating window. + 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)); + }); + }); + // 5. Destroy the floating window 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 window. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in destroying the window. Data: ' + JSON.stringify(data)); + }); + }); + }); + } + }; + ``` \ No newline at end of file diff --git a/en/application-dev/windowmanager/figures/windowMode.png b/en/application-dev/windowmanager/figures/windowMode.png new file mode 100644 index 0000000000000000000000000000000000000000..ae9433f9d69e6a4272d45ae2a5302f893cfd5ea9 Binary files /dev/null and b/en/application-dev/windowmanager/figures/windowMode.png differ diff --git a/en/application-dev/windowmanager/system-window-stage.md b/en/application-dev/windowmanager/system-window-stage.md new file mode 100644 index 0000000000000000000000000000000000000000..2bc119ddc5d8c63337b95ef72b25af2c93d7b281 --- /dev/null +++ b/en/application-dev/windowmanager/system-window-stage.md @@ -0,0 +1,111 @@ +# System Window Development (Stage Model Only) + +## Overview + +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).
-`ctx`: application context.
-`type`: window type. | +| Window | resetSize(width: number, height: number, callback: AsyncCallback<void>): void | Changes the window size.| +| Window | moveTo(x: number, y: number, callback: AsyncCallback<void>): void | Moves this window.| +| Window | loadContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to this window.| +| Window | show(callback: AsyncCallback\): 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 | 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. + +```ts +import ExtensionContext from '@ohos.application.ServiceExtensionAbility'; +import window from '@ohos.window'; + +var windowClass = null; + +export default class ServiceExtensionAbility1 extends ExtensionContext { + onCreate(want) { + console.log("[Demo] MainAbility onCreate") + globalThis.abilityWant = want; + // 1. Create a volume bar window. + var windowClass = null; + window.create(this.context, "volume", window.WindowType.TYPE_VOLUME_OVERLAY, (err, data) => { + if (err.code) { + console.error('Failed to create the volume window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in creating the volume window.') + windowClass = data; + // 2. Change the size and position of the volume bar window, or set its properties such as the background color and brightness. + windowClass.moveTo(300, 300, (err, data) => { + if (err.code) { + console.error('Failed to move the window. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in moving the window. Data: ' + JSON.stringify(data)); + }); + windowClass.resetSize(500, 1000, (err, data) => { + if (err.code) { + console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); + return; + } + console.info('Succeeded in changing the window size. Data: ' + JSON.stringify(data)); + }); + // 3. Load the page content to the volume bar window. + windowClass.loadContent("pages/page_volume", (err, data) => { + if (err.code) { + 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 volume bar window. + 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. Hide or destroy the volume bar window. + // Hide the volume bar window when a click event outside the window is detected. + windowClass.on('touchOutside', () => { + console.info('touch outside'); + windowClass.hide((err, data) => { + if (err.code) { + console.error('Failed to hide the window. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in hidinging the window. Data: ' + JSON.stringify(data)); + }); + }); + }); + } +}; +``` diff --git a/en/application-dev/windowmanager/window-guidelines.md b/en/application-dev/windowmanager/window-guidelines.md deleted file mode 100644 index a12fab0a3f5ed773904e86f6024e062239198f24..0000000000000000000000000000000000000000 --- a/en/application-dev/windowmanager/window-guidelines.md +++ /dev/null @@ -1,102 +0,0 @@ -# Window Development - -## When to Use -The interface layer of the window runs in the application process. It loads the page layout and provides APIs. -By calling these APIs, you can create and destroy a window, set the position and size of a window, and enter the immersive mode (full-screen mode). - -## Available APIs -For details about the APIs, see [Window](../reference/apis/js-apis-window.md). - -**Table 1** Main window APIs - -| API | Description | -| :----------------------------------------------------------- | :--------------------------------------------- | -| create(id: string, type: WindowType, callback: AsyncCallback\): void | Creates a subwindow. | -| moveTo(x: number, y: number): Promise\ | 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.| -| resetSize(width: number, height: number): Promise\ | Changes the window size. | -| hide(): Promise\ | Hides the window. | -| destroy(): Promise\ | 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: - -```js - import window from '@ohos.window'; - var windowClass = null; - let promise = window.create("subWindow", window.WindowType.TYPE_APP); - promise.then((data)=> { - windowClass = data; - console.info('SubWindow created. Data: ' + JSON.stringify(data)) - }).catch((err)=>{ - console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err)); - }); -``` - -### Obtaining a Window Object - -- Call **getTopWindow** to obtain the top window of the application. The sample code is as follows: - -```js - var windowClass = null; - let promise = window.getTopWindow(); - promise.then((data)=> { - windowClass = data; - console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)) - }).catch((err)=>{ - console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(err)); - }) -``` - -- You can also call **find** to obtain created subwindows in the application. The sample code is as follows: - -```js - var windowClass = null; - let promise = window.find("subWindow"); - promise.then((data)=> { - windowClass = data; - console.info('window found. Data: ' + JSON.stringify(data)) - }).catch((err)=>{ - 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: - -```js - let promise = windowClass.hide(); - promise.then((data)=> { - console.info('window hidden. Data: ' + JSON.stringify(data)) - 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)) - }) - }).catch((err)=>{ - console.error('Failed to hide the window. Cause: ' + JSON.stringify(err)); - }) -``` - -### Enabling the Full-Screen Mode - -After a window object is obtained, you can call **setFullScreen** to enable the full-screen mode for the window. - -The sample code is as follows: - -```js -import window from '@ohos.window'; -try { - const win = await window.getTopWindow() - await win.setFullScreen(true) -} catch (err) { - console.log(`setFullScreen fail, code = ${err.code}`) -} -``` diff --git a/en/application-dev/windowmanager/window-overview.md b/en/application-dev/windowmanager/window-overview.md index 2cc594c16b9163337d9ce23f25c3cfa36f3914ba..e27a032e7215ca6cea9158c25e9d75a79f2d0c01 100644 --- a/en/application-dev/windowmanager/window-overview.md +++ b/en/application-dev/windowmanager/window-overview.md @@ -1,13 +1,66 @@ -# Window Manager Overview +# Window Overview + + +## Introduction + +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. + + +![windowMode](figures/windowMode.png) + ## 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.