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.

Setting the Main Window of an Application

In the stage model, the main window of an application is created and maintained by a UIAbility instance. In the onWindowStageCreate callback of the UIAbility instance, 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.

How to Develop

1. Obtain the main window.

Call getMainWindow to obtain the main window of the application.

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

1. Load content for the main window.

Call loadContent to load the page 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 touchable property of the main window.
      let isTouchable: boolean = true;
      windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => {
        let errCode: number = err.code;
        if (errCode) {
          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.');
      })
    })
    // 3. Load the page 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.');
    });
  }
};

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

Call createSubWindow to create a subwindow.

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

1. Load content for the subwindow and show it.

Call setUIContent and showWindow to load and display the content in the subwindow.

1. Destroy 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 click 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 clicked. Calling onWindowStageDestroy is not always necessary. The code here is for reference only.
    this.destroySubWindow();
  }
};

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. This feature is available only for the main window of an application. Since API version 10, the immersive window has the same size as the full screen by default; its layout is controlled by the component module; the background color of its status bar and navigation bar is transparent, and the text color is black. When an application window calls setWindowLayoutFullScreen, with true passed in, the component module controls the immersive full-screen layout of the status bar and navigation bar. If false is passed in, the component module controls the non-immersive full-screen layout of the status bar and navigation bar.

How to Develop

1. Obtain the main window.

Call getMainWindow to obtain the main window of the application.

1. Implement the immersive effect. You can use either of the following methods:

   • Method 1: When the main window of the application is a full-screen window, call setWindowSystemBarEnable to hide the status bar and navigation bar.

   • Method 2: Call setWindowLayoutFullScreen to enable the full-screen mode for the main window layout. Call setWindowSystemBarProperties to set the opacity, background color, text color, and highlighted icon of the status bar and navigation bar to ensure that their display effect is consistent with that of the main window.

2. Load content for the immersive window and show it.

Call loadContent to load the content to the immersive 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. Use method 1 to implement the immersive effect.
      let names: Array<'status'|'navigation'> = [];
      windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => {
        let errCode: number = err.code;
        if (errCode) {
          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.');
      });
      // 2. Use method 2 to implement the immersive effect.
      let isLayoutFullScreen = true;
      windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => {
        let errCode: number = err.code;
        if (errCode) {
          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.');
      });
      let sysBarProps: window.SystemBarProperties = {
        statusBarColor: '#ff00ff',
        navigationBarColor: '#00ff00',
        // The following properties are supported since API version 8.
        statusBarContentColor: '#ffffff',
        navigationBarContentColor: '#ffffff'
      };
      windowClass.setWindowSystemBarProperties(sysBarProps, (err: BusinessError) => {
        let errCode: number = err.code;
        if (errCode) {
          console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err));
          return;
        }
        console.info('Succeeded in setting the system bar properties.');
      });
    })
    // 3. Load the page content to the immersive 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.');
    });
  }
};

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. Generally, the floating window is above all application windows. You can create a floating window and set its properties.

How to Develop

Prerequisites: To create a floating window (a window of the type WindowType.TYPE_FLOAT), you must request the ohos.permission.SYSTEM_FLOAT_WINDOW permission. For details, see Declaring Permissions in the Configuration File.

1. Create a floating window.

Call window.createWindow to create a floating window.

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

1. Load content for the floating window and show it.

Call setUIContent and showWindow to load and display the content in the floating window.

1. Destroy the floating window.

When the floating window 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';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // 1. Create a floating window.
    let windowClass: window.Window|null = null;
    let config: window.Configuration = {
      name: "floatWindow", windowType: window.WindowType.TYPE_FLOAT, ctx: this.context
    };
    window.createWindow(config, (err: BusinessError, data) => {
      let errCode: number = err.code;
      if (errCode) {
        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;
      // 2. Set the position, size, and properties of the floating window.
      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.');
      });
      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 floating window.
      windowClass.setUIContent("pages/page4", (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 floating window.
        (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.');
        });
      });
      // 4. Destroy the floating window when it is no longer needed (depending on the service logic).
      windowClass.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.');
      });
    });
  }
};

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Window Manager

harmony 鸿蒙Application Window Development (FA Model)

harmony 鸿蒙System Window Development (Stage Model Only)

harmony 鸿蒙Window Overview