# @ohos.window (Window)
The Window module provides basic window management capabilities, such as creating and destroying the current window, setting properties for the current window, and managing and scheduling windows.
This module provides the following common window-related functionalities:
- [Window](#window): window instance, which is the basic unit managed by the window manager.
- [WindowStage](#windowstage9): window manager that manages windows.
> **NOTE**
>
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
```ts
import { window } from '@kit.ArkUI';
```
## WindowType7+
Enumerates the window types.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Value| Description |
|-------------------------------------| ------ |----------------------------------------------------------------------------------------|
| TYPE_APP | 0 | Application subwindow.
**Model restriction**: This API can be used only in the FA model. |
| TYPE_SYSTEM_ALERT | 1 | System alert window.
**NOTE**
This property is supported since API version 7 and deprecated since API version 11. |
| TYPE_FLOAT9+ | 8 | Floating window.
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 12.|
| TYPE_DIALOG10+ | 16 | Modal window.
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 12.|
## Configuration9+
Defines the parameters for creating a subwindow or system window.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name| Type| Mandatory| Description |
| ---------- | -------------------------- | -- |-----------------------------------------------------------------------------|
| name | string | Yes| Name of the window. |
| windowType | [WindowType](#windowtype7) | Yes| Window type. |
| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | No| Current application context. If no value is passed, no context is used.
In the FA model, do not pass in this parameter when creating a subwindow. Otherwise, an error is reported.
In the stage model, you must pass in this parameter when creating a floating window, modal window, or system window.|
| displayId | number | No| ID of the current physical screen. If no value is passed, the default value **-1** is used. The value must be an integer. |
| parentId | number | No| ID of the parent window. If no value is passed, the default value **-1** is used. The value must be an integer. |
| decorEnabled12+ | boolean | No| Whether the window decoration is enabled. This parameter is valid only when **windowType** is set to **TYPE_DIALOG**. The value **true** means that the window decoration is enabled, and **false** means the opposite. The default value is **false**.
**System capability**: SystemCapability.Window.SessionManager|
| title12+ | string| No| Title of the window when **decorEnabled** is set to **true**. If this parameter is not set, an empty string is used by default.
**System capability**: SystemCapability.Window.SessionManager|
## AvoidAreaType7+
Enumerates the types of the area where the window cannot be displayed.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
| Name | Value | Description |
| -------------------------------- | ---- | ------------------------------------------------------------ |
| TYPE_SYSTEM | 0 | Default area of the system. Generally, the status bar and navigation bar are included. The default area may vary according to the device in use.|
| TYPE_CUTOUT | 1 | Notch. |
| TYPE_SYSTEM_GESTURE9+ | 2 | Gesture area. |
| TYPE_KEYBOARD9+ | 3 | Soft keyboard area. |
| TYPE_NAVIGATION_INDICATOR11+ | 4 | Navigation bar area. |
## SystemBarProperties
Describes the properties of the status bar and navigation bar. These properties are valid for the window-level status bar and navigation bar.
**Atomic service API**: This API can be used in atomic services since API version 12.
| Name | Type| Mandatory| Description |
| -------------------------------------- | -------- | ---- | ------------------------------------------------------------ |
| statusBarColor | string | No | Background color of the status bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**. The default value is **'#0x66000000'**.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| isStatusBarLightIcon7+ | boolean | No | Whether any icon on the status bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| statusBarContentColor8+ | string | No | Color of the text on the status bar. After this property is set, the setting of **isStatusBarLightIcon** is invalid. The default value is **'#0xE5FFFFFF'**.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| navigationBarColor | string | No | Background color of the navigation bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**. The default value is **'#0x66000000'**.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| isNavigationBarLightIcon7+ | boolean | No | Whether any icon on the navigation bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| navigationBarContentColor8+ | string | No | Color of the text on the navigation bar. After this property is set, the setting of **isNavigationBarLightIcon** is invalid. The default value is **'#0xE5FFFFFF'**.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| enableStatusBarAnimation12+ | boolean | No | Whether to enable animation for a status bar property change. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.
**System capability**: SystemCapability.Window.SessionManager|
| enableNavigationBarAnimation12+ | boolean | No | Whether to enable animation for a navigation bar property change. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.
**System capability**: SystemCapability.Window.SessionManager|
## SystemBarStyle12+
Describes the properties of the status bar. These properties are valid for the page-level status bar.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type| Read-Only| Optional| Description |
| ------ | -------- | ---- | ---- | ------------------ |
| statusBarContentColor | string | Yes | Yes | Color of the text on the status bar. The default value is **'#0xE5FFFFFF'**.|
## Orientation9+
Enumerates the window orientations.
| Name | Value | Description |
| ------------------------------------- | ---- | ----------------------------- |
| UNSPECIFIED | 0 | Unspecified. The orientation is determined by the system.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| PORTRAIT | 1 | Portrait.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.|
| LANDSCAPE | 2 | Landscape.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| PORTRAIT_INVERTED | 3 | Reverse portrait.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.|
| LANDSCAPE_INVERTED | 4 | Reverse landscape.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.|
| AUTO_ROTATION | 5 | Automatically rotates with the sensor. The orientation can be portrait, landscape, reverse portrait, or reverse landscape.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.|
| AUTO_ROTATION_PORTRAIT | 6 | Automatically rotates with the sensor in the vertical direction. The orientation can be portrait or reverse portrait.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| AUTO_ROTATION_LANDSCAPE | 7 | Automatically rotates with the sensor in the horizontal direction. The orientation can be landscape or reverse landscape.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.|
| AUTO_ROTATION_RESTRICTED | 8 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation can be portrait, landscape, reverse portrait, or reverse landscape.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.|
| AUTO_ROTATION_PORTRAIT_RESTRICTED | 9 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation can be portrait or reverse portrait.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| AUTO_ROTATION_LANDSCAPE_RESTRICTED | 10 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation can be landscape or reverse landscape.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| LOCKED | 11 | Locked.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| AUTO_ROTATION_UNSPECIFIED12+ | 12 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system. For example, the window can rotate to portrait, landscape, or reverse landscape, but not reverse portrait, on a certain device.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager|
| USER_ROTATION_PORTRAIT12+ | 13 | Temporarily rotates to portrait mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager|
| USER_ROTATION_LANDSCAPE12+ | 14 | Temporarily rotates to landscape mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager|
| USER_ROTATION_PORTRAIT_INVERTED12+ | 15 | Temporarily rotates to reverse portrait mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager|
| USER_ROTATION_LANDSCAPE_INVERTED12+ | 16 | Temporarily rotates to reverse landscape mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager|
| FOLLOW_DESKTOP12+ | 17 | Follows the orientation of the home screen.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager|
## Rect7+
Describes the rectangular area of the window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
| Name | Type| Readable| Writable| Description |
| ------ | -------- | ---- | ---- | ------------------ |
| left | number | Yes | Yes | Left boundary of the rectangle, in px. The value must be an integer.|
| top | number | Yes | Yes | Top boundary of the rectangle, in px. The value must be an integer.|
| width | number | Yes | Yes | Width of the rectangle, in px. The value must be an integer.|
| height | number | Yes | Yes | Height of the rectangle, in px. The value must be an integer.|
## AvoidArea7+
Describes the area where the window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. Touch events will not be responded in this area.
Pay attention to the following restrictions on this area:
- The non-navigation bar area in the gesture area at the bottom supports transparent transmission of touch events, touch and hold events, but not drag events.
- The gesture area on the left and right sides supports transparent transmission of touch events, touch and hold events, and swipe up and down events, but not drag events.
- The navigation bar area supports responding to touch events, touch and hold events, and drag events. However, it does not support transparent transmission of events.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
| Name | Type | Readable| Writable| Description |
| ---------- | ------------- | ---- | ---- | ------------------ |
| visible9+ | boolean | Yes | Yes | Whether the window can be displayed in the area. The value **true** means that the window can be displayed in the area, and **false** means the opposite.|
| leftRect | [Rect](#rect7) | Yes | Yes | Rectangle on the left of the screen.|
| topRect | [Rect](#rect7) | Yes | Yes | Rectangle at the top of the screen.|
| rightRect | [Rect](#rect7) | Yes | Yes | Rectangle on the right of the screen.|
| bottomRect | [Rect](#rect7) | Yes | Yes | Rectangle at the bottom of the screen.|
## Size7+
Describes the window size.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
| Name | Type| Readable| Writable| Description |
| ------ | -------- | ---- | ---- | ---------- |
| width | number | Yes | Yes | Window width, in px. The value must be an integer.|
| height | number | Yes | Yes | Window height, in px. The value must be an integer.|
## RectChangeReason12+
Enumerates the reasons for window rectangle (position and size) changes.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
| Name | Value | Description |
| --------------------- | ---- | ------------------------------------------------------------ |
| UNDEFINED | 0 | Default value. |
| MAXIMIZE | 1 | The window is maximized. |
| RECOVER | 2 | The window is restored to the previous state. |
| MOVE | 3 | The window is moved.|
| DRAG | 4 | The window is zoomed in or out by dragging.|
| DRAG_START | 5 | The window starts zooming in or out.|
| DRAG_END | 6 | The window finishes zooming in or out.|
## RectChangeOptions12+
Describes the value and reason returned upon a window rectangle (position and size) change.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
| Name | Type | Readable| Writable| Description |
| ---------- | ------------- | ---- | ---- | ------------------ |
| rect | [Rect](#rect7) | Yes | Yes | New value of the window rectangle.|
| reason | [RectChangeReason](#rectchangereason12) | Yes | Yes | Reason for the window rectangle change.|
## AvoidAreaOptions12+
Describes the new area where the window cannot be displayed. The new area is returned when the corresponding event is triggered.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
| Name | Type | Readable| Writable| Description |
| ---------- | ------------- | ---- | ---- | ------------------ |
| type | [AvoidAreaType](#avoidareatype7) | Yes | Yes | Type of the new area returned.|
| area | [AvoidArea](#avoidarea7) | Yes | Yes | New area returned.|
## WindowProperties
Describes the window properties.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Type | Read-Only| Optional| Description |
| ------------------------------------- | ------------------------- | ---- | ---- |--------------------------------------------------------------------------------------------------------|
| windowRect7+ | [Rect](#rect7) | No | No | Window size, which can be obtained from the page lifecycle [onPageShow](./arkui-ts/ts-custom-component-lifecycle.md#onpageshow) or the application lifecycle [onForeground](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonforeground).
**Atomic service API**: This API can be used in atomic services since API version 11. |
| drawableRect11+ | [Rect](#rect7) | No | No | Size of the rectangle that can be drawn in the window. The upper boundary and left boundary are calculated relative to the window.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| type7+ | [WindowType](#windowtype7) | No | No | Window type.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| isFullScreen | boolean | No | No | Whether the window is displayed in full-screen mode. The default value is **false**. The value **true** means that the window is displayed in full-screen mode, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| isLayoutFullScreen7+ | boolean | No | No | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is **false**. The value **true** means that the window is immersive, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| focusable7+ | boolean | Yes | No | Whether the window can gain focus. The default value is **true**. The value **true** means that the window can gain focus, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| touchable7+ | boolean | Yes | No | Whether the window is touchable. The default value is **true**. The value **true** means that the window is touchable, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| brightness | number | No | No | Screen brightness. The value is a floating point number in the range [0.0, 1.0], and the value **1.0** means the brightest. If no value is passed, the brightness follows the system. In this case, the obtained brightness value is **-1**.
**Atomic service API**: This API can be used in atomic services since API version 11. |
| dimBehindValue(deprecated) | number | No | No | Dimness of the window that is not on top. The value is a floating point number in the range [0.0, 1.0], and the value **1.0** means the dimmest.
**NOTE**
This property is supported since API version 7 and deprecated since API version 9. |
| isKeepScreenOn | boolean | No | No | Whether the screen is always on. The default value is **false**. The value **true** means that the screen is always on, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 11. |
| isPrivacyMode7+ | boolean | No | No | Whether the window is in privacy mode. The default value is **false**. The value **true** means that the window is in privacy mode, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| isRoundCorner(deprecated) | boolean | No | No | Whether the window has rounded corners. The default value is **false**. The value **true** means that the window has rounded corners, and **false** means the opposite.
**NOTE**
This property is supported since API version 7 and deprecated since API version 9. |
| isTransparent7+ | boolean | No | No | Whether the window is transparent. The default value is **false**. The value **true** means that the window is transparent, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| id9+ | number | Yes | No | Window ID. The default value is **0**. The value must be an integer.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| displayId12+ | number | Yes | Yes | ID of the screen where the window is located. By default, the ID of the main screen is returned. The value must be an integer.
**Atomic service API**: This API can be used in atomic services since API version 12.|
## DecorButtonStyle14+
Describes the button style of the system decoration bar.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 14.
| Name | Type | Readable| Writable| Description |
| ---------- | ------------- | ---- | ---- | ------------------ |
| colorMode | [ConfigurationConstant.ColorMode](../apis-ability-kit/js-apis-app-ability-configurationConstant.md#colormode) | Yes | Yes | Color mode. Buttons automatically adapt to light colors in dark mode and to dark colors in light mode. If this parameter is not set, they will automatically match the system color mode.|
| buttonBackgroundSize | number | Yes | Yes | Size of the button when it is highlighted. The value ranges from 20 vp to 40 vp. The default value is 28 vp.|
| spacingBetweenButtons | number | Yes | Yes | Spacing between buttons. The value ranges from 12 vp to 24 vp. The default value is 12 vp.|
| closeButtonRightMargin | number | Yes | Yes | Margin between the rightmost edge of the close button and the window. The value ranges from 8 vp to 22 vp. The default value is 20 vp.|
## ColorSpace8+
Enumerates the color spaces.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
| Name | Value| Description |
| ---------- | ------ | -------------- |
| DEFAULT | 0 | Default SRGB gamut.|
| WIDE_GAMUT | 1 | Wide-gamut. |
## WindowEventType10+
Enumerates the window lifecycle states.
**Atomic service API**: This API can be used in atomic services since API version 11.
| Name | Value| Description |
| ---------- | ------ | ---------- |
| WINDOW_SHOWN | 1 | The window is running in the foreground.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| WINDOW_ACTIVE | 2 | The window gains focus.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| WINDOW_INACTIVE | 3 | The window loses focus.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| WINDOW_HIDDEN | 4 | The window is running in the background.
**System capability**: SystemCapability.WindowManager.WindowManager.Core|
| WINDOW_DESTROYED11+ | 7 | The window is destroyed.
**System capability**: SystemCapability.Window.SessionManager|
## WindowLimits11+
Defines the window size limits. You can call [setWindowLimits](#setwindowlimits11) to set the window size limits and call [getWindowLimits](#getwindowlimits11) to obtain the current window size limits.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
| Name | Type | Readable| Writable| Description |
| :-------- | :----- | :--- | :--- | :----------------------------------------------------------- |
| maxWidth | number | Yes | Yes | Maximum window width, in px. The value must be an integer. The default value is **0**, indicating that the property does not change. The lower limit is **0**, and the upper limit is the maximum width specified by the system. |
| maxHeight | number | Yes | Yes | Maximum window height, in px. The value must be an integer. The default value is **0**, indicating that the property does not change. The lower limit is **0**, and the upper limit is the maximum height specified by the system. |
| minWidth | number | Yes | Yes | Minimum window width, in px. The value must be an integer. The default value is **0**, indicating that the property does not change. The lower limit is **0**, and the upper limit is the minimum width specified by the system. |
| minHeight | number | Yes | Yes | Minimum window height, in px. The value must be an integer. The default value is **0**, indicating that the property does not change. The lower limit is **0**, and the upper limit is the minimum height specified by the system. |
## WindowStatusType11+
Enumerates the window modes.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
| Name | Value | Description |
| ---------- | ---- | ----------------------------- |
| UNDEFINED | 0 | The window mode is not defined by the application. |
| FULL_SCREEN | 1 | The application is displayed in full screen. |
| MAXIMIZE | 2 | The application window is maximized. |
| MINIMIZE | 3 | The application window is minimized. |
| FLOATING | 4 | The application is displayed in a floating window. |
| SPLIT_SCREEN | 5 | The application is displayed in split-screen mode. |
## TitleButtonRect11+
Defines the rectangle used to hold the minimize, maximize, and close buttons on the title bar. This rectangle is located in the upper right corner of the window.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
| Name | Type | Readable| Writable| Description |
| ------ | ------ | ---- | ---- | ------------------------------------------ |
| right | number | Yes | Yes | Right boundary of the rectangle, in vp. The value must be an integer.|
| top | number | Yes | Yes | Top boundary of the rectangle, in vp. The value must be an integer.|
| width | number | Yes | Yes | Width of the rectangle, in vp. The value must be an integer. |
| height | number | Yes | Yes | Height of the rectangle, in vp. The value must be an integer. |
## MaximizePresentation12+
Enumerates the layout when the window is maximized.
**System capability**: SystemCapability.Window.SessionManager
| Name | Value | Description |
| ---------- | ---- | ----------------------------- |
| FOLLOW_APP_IMMERSIVE_SETTING | 0 | The window, when maximized, follows the immersive layout of the application.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| EXIT_IMMERSIVE | 1 | The window, when maximized, exits the immersive layout.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| ENTER_IMMERSIVE | 2 | The window, when maximized, transitions into the immersive layout, and the window title bar and dock bar are displayed when the cursor hovers over the hot zone.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| ENTER_IMMERSIVE_DISABLE_TITLE_AND_DOCK_HOVER14+ | 3 | The window, when maximized, transitions into the immersive layout, and the window title bar and dock bar are not displayed when you hover the cursor over the hot zone.
**Atomic service API**: This API can be used in atomic services since API version 14. |
## window.createWindow9+
createWindow(config: Configuration, callback: AsyncCallback<Window>): void
Creates a subwindow or system window. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**)
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------------------------------------- | -- | --------------------------------- |
| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window. |
| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the window created.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | Permission verification failed. The application does not have the permission required to call the API. |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300001 | Repeated operation. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
| 1300006 | This window context is abnormal. |
| 1300008 | The display device is abnormal. |
| 1300009 | The parent window is invalid. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
let config: window.Configuration = {
name: "test",
windowType: window.WindowType.TYPE_DIALOG,
ctx: this.context
};
try {
window.createWindow(config, (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data));
windowClass.resize(500, 1000);
});
} catch (exception) {
console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
## window.createWindow9+
createWindow(config: Configuration): Promise<Window>
Creates a subwindow or system window. This API uses a promise to return the result.
**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**)
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | -------------------------------- | -- | ------------------ |
| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window.|
**Return value**
| Type| Description|
| -------------------------------- | ------------------------------------ |
| Promise<[Window](#window)> | Promise used to return the window created.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------- |
| 201 | Permission verification failed. The application does not have the permission required to call the API. |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300001 | Repeated operation. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
| 1300006 | This window context is abnormal. |
| 1300008 | The display device is abnormal. |
| 1300009 | The parent window is invalid. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
let config: window.Configuration = {
name: "test",
windowType: window.WindowType.TYPE_DIALOG,
ctx: this.context
};
try {
let promise = window.createWindow(config);
promise.then((data) => {
windowClass = data;
console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
## window.findWindow9+
findWindow(name: string): Window
Finds a window based on the name.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------- |
| name | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).|
**Return value**
| Type| Description|
| ----------------- | ------------------- |
| [Window](#window) | Window found.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
let windowClass: window.Window | undefined = undefined;
try {
windowClass = window.findWindow('test');
} catch (exception) {
console.error(`Failed to find the Window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
## window.getLastWindow9+
getLastWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void
Obtains the top window of the current application. This API uses an asynchronous callback to return the result. If no subwindow is available, the main window of the application is returned.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------------------------------------- | -- | ---------------------------------------- |
| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Current application context.|
| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the top window obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300006 | This window context is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
try {
window.getLastWindow(this.context, (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
## window.getLastWindow9+
getLastWindow(ctx: BaseContext): Promise<Window>
Obtains the top window of the current application. This API uses a promise to return the result. If no subwindow is available, the main window of the application is returned.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ----------- | ---- | ------------------------------------------------------------ |
| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.|
**Return value**
| Type| Description|
| -------------------------------- | ------------------------------------------- |
| Promise<[Window](#window)> | Promise used to return the top window obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300006 | This window context is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
try {
let promise = window.getLastWindow(this.context);
promise.then((data) => {
windowClass = data;
console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
## window.shiftAppWindowFocus11+
shiftAppWindowFocus(sourceWindowId: number, targetWindowId: number): Promise<void>
Shifts the window focus from the source window to the target window in the same application. The window focus can be shifted between the main window and a subwindow.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory | Description |
| -------------- | ------ | ----- | ----------------------- |
| sourceWindowId | number | Yes | ID of the source window, which is having the focus.|
| targetWindowId | number | Yes | ID of the target window. |
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| ------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
// ...
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
let subWindowClass: window.Window | undefined = undefined;
let windowClassId: number = -1;
let subWindowClassId: number = -1;
try {
// Obtain the main window and ID of the application.
let promise = windowStage.getMainWindow();
promise.then((data) => {
if (data == null) {
console.error("Failed to obtaining the window. Cause: The data is empty");
return;
}
windowClass = data;
windowClass.setUIContent("pages/Index");
windowClassId = windowClass.getWindowProperties().id;
console.info('Succeeded in obtaining the window')
}).catch((err: BusinessError) => {
console.error(`Failed to obtaining the window. Cause code: ${err.code}, message: ${err.message}`);
});
// Create or obtain a subwindow and its ID. In this case, the subwindow has focus.
let promiseSub = windowStage.createSubWindow("testSubWindow");
promiseSub.then((data) => {
if (data == null) {
console.error("Failed to obtaining the window. Cause: The data is empty");
return;
}
subWindowClass = data;
subWindowClassId = subWindowClass.getWindowProperties().id;
subWindowClass.resize(500, 500);
subWindowClass.setUIContent("pages/Index2");
subWindowClass.showWindow();
// Listen for the window status and ensure that the window is ready.
subWindowClass.on("windowEvent", (windowEvent) => {
if (windowEvent == window.WindowEventType.WINDOW_ACTIVE) {
// Switch the focus.
let promise = window.shiftAppWindowFocus(subWindowClassId, windowClassId);
promise.then(() => {
console.info('Succeeded in shifting app window focus');
}).catch((err: BusinessError) => {
console.error(`Failed to shift app window focus. Cause code: ${err.code}, message: ${err.message}`);
});
}
});
});
} catch (exception) {
console.error(`Failed to shift app focus. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
## window.getWindowsByCoordinate14+
getWindowsByCoordinate(displayId: number, windowNumber?: number, x?: number, y?: number): Promise<Array<Window>>
Obtains visible windows at the specified coordinates of the application. This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------- |----|---------------------------------------------------------------------------|
| displayId | number| Yes | ID of the display where the windows are located. The value must be an integer and can be obtained from [WindowProperties](#windowproperties).|
| windowNumber | number| No | Number of windows to obtain. The value must be an integer greater than 0. If this parameter is not set or is less than or equal to 0, all windows that meet the conditions are returned. |
| x | number | No | X coordinate. The value must be a non-negative integer. If this parameter is not set or is less than 0, all visible windows are returned. |
| y | number| No | Y coordinate. The value must be a non-negative integer. If this parameter is not set or is less than 0, all visible windows are returned. |
**Return value**
| Type | Description |
| -------------------------------- |-------------------------|
| Promise<Array<[Window](#window)>> | Promise used to return an array of window objects.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID | Error Message|
|----------| ------------------------------ |
| 401 | Parameter error. Possible cause: Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300003 | This window manager service works abnormally. |
```ts
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
try {
let properties = windowClass.getWindowProperties();
window.getWindowsByCoordinate(properties.displayId).then((data) => {
console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
for (let window of data) {
// do something with window
}
}).catch((err: BusinessError) => {
console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`);
});
window.getWindowsByCoordinate(properties.displayId, 2, 500, 500).then((data) => {
console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
for (let window of data) {
// do something with window
}
}).catch((err: BusinessError) => {
console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to get window from point. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
## window.create(deprecated)
create(id: string, type: WindowType, callback: AsyncCallback<Window>): void
Creates a subwindow. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead.
**Model restriction**: This API can be used only in the FA model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | ------------------------------------ |
| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).|
| type | [WindowType](#windowtype7) | Yes | Window type. |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
window.create('test', window.WindowType.TYPE_APP, (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data));
});
```
## window.create(deprecated)
create(id: string, type: WindowType): Promise<Window>
Creates a subwindow. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead.
**Model restriction**: This API can be used only in the FA model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------- | ---- | ---------- |
| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). |
| type | [WindowType](#windowtype7) | Yes | Window type.|
**Return value**
| Type | Description |
| -------------------------------- | --------------------------------------- |
| Promise<[Window](#window)> | Promise used to return the subwindow created.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
let promise = window.create('test', window.WindowType.TYPE_APP);
promise.then((data) => {
windowClass = data;
console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`);
});
```
## window.create(deprecated)
create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void
Creates a system window. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------ |
| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context. |
| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). |
| type | [WindowType](#windowtype7) | Yes | Window type. |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
window.create('test', window.WindowType.TYPE_SYSTEM_ALERT, (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data));
windowClass.resetSize(500, 1000);
});
```
## window.create(deprecated)
create(ctx: BaseContext, id: string, type: WindowType): Promise<Window>
Creates a system window. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------- | ---- | ------------------------------------------------------------ |
| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.|
| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).|
| type | [WindowType](#windowtype7) | Yes | Window type. |
**Return value**
| Type | Description |
| -------------------------------- | --------------------------------------- |
| Promise<[Window](#window)> | Promise used to return the subwindow created.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
let promise = window.create('test', window.WindowType.TYPE_SYSTEM_ALERT);
promise.then((data) => {
windowClass = data;
console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`);
});
```
## window.find(deprecated)
find(id: string, callback: AsyncCallback<Window>): void
Finds a window based on the ID. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | ------------------------------------ |
| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).|
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window found.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
window.find('test', (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data));
});
```
## window.find(deprecated)
find(id: string): Promise<Window>
Finds a window based on the ID. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------- |
| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).|
**Return value**
| Type | Description |
| -------------------------------- | ------------------------------------- |
| Promise<[Window](#window)> | Promise used to return the window found.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
let promise = window.find('test');
promise.then((data) => {
windowClass = data;
console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`);
});
```
## window.getTopWindow(deprecated)
getTopWindow(callback: AsyncCallback<Window>): void
Obtains the top window of the current application. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead.
**Model restriction**: This API can be used only in the FA model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | -------------------------------------------- |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
window.getTopWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
});
```
## window.getTopWindow(deprecated)
getTopWindow(): Promise<Window>
Obtains the top window of the current application. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead.
**Model restriction**: This API can be used only in the FA model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| -------------------------------- | ----------------------------------------------- |
| Promise<[Window](#window)> | Promise used to return the top window obtained.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let windowClass: window.Window | undefined = undefined;
let promise = window.getTopWindow();
promise.then((data)=> {
windowClass = data;
console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError)=>{
console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
});
```
## window.getTopWindow(deprecated)
getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void
Obtains the top window of the current application. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.|
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage:window.WindowStage){
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
try {
window.getTopWindow(this.context, (err: BusinessError, data) => {
const errCode: number = err.code;
if(errCode){
console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
return ;
}
windowClass = data;
console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
});
} catch(error){
console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`);
}
}
}
```
## window.getTopWindow(deprecated)
getTopWindow(ctx: BaseContext): Promise<Window>
Obtains the top window of the current application. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------- | ---- | ------------------------------------------------------------ |
| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.|
**Return value**
| Type | Description |
| -------------------------------- | ----------------------------------------------- |
| Promise<[Window](#window)> | Promise used to return the top window obtained.|
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage:window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
let promise = window.getTopWindow(this.context);
promise.then((data) => {
windowClass = data;
console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
}).catch((error: BusinessError) => {
console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`);
});
}
}
```
## SpecificSystemBar11+
type SpecificSystemBar = 'status' \| 'navigation' \| 'navigationIndicator'
Enumerates the types of system bars that can be displayed or hidden.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 11.
| Type | Description |
|------------|--------|
| 'status' | Status bar. |
| 'navigation' | Three-button navigation bar. |
| 'navigationIndicator' | Bottom navigation bar.|
## Window
Represents a window instance, which is the basic unit managed by the window manager.
In the following API examples, you must use [getLastWindow()](#windowgetlastwindow9), [createWindow()](#windowcreatewindow9), or [findWindow()](#windowfindwindow9) to obtain a **Window** instance (named windowClass in this example) and then call a method in this instance.
### showWindow9+
showWindow(callback: AsyncCallback<void>): void
Shows this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application subwindow. For the main window of an application, this API moves it at the top when the main window is already displayed.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------- | -- | --------- |
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.showWindow((err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in showing the window.');
});
```
### showWindow9+
showWindow(): Promise<void>
Shows this window. This API uses a promise to return the result. This API takes effect only for a system window or an application subwindow. For the main window of an application, this API moves it at the top when the main window is already displayed.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type| Description|
| ------------------- | ----------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.showWindow();
promise.then(() => {
console.info('Succeeded in showing the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### destroyWindow9+
destroyWindow(callback: AsyncCallback<void>): void
Destroys this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application subwindow.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------- | -- | --------- |
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.destroyWindow((err) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in destroying the window.');
});
```
### destroyWindow9+
destroyWindow(): Promise<void>
Destroys this window. This API uses a promise to return the result. This API takes effect only for a system window or an application subwindow.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.destroyWindow();
promise.then(() => {
console.info('Succeeded in destroying the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### moveWindowTo9+
moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void
Moves this window. This API uses an asynchronous callback to return the result.
In full-screen mode, this API takes effect only on 2-in-1 devices.
On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------- | -- | --------------------------------------------- |
| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
windowClass.moveWindowTo(300, 300, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in moving the window.');
});
} catch (exception) {
console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### moveWindowTo9+
moveWindowTo(x: number, y: number): Promise<void>
Moves this window. This API uses a promise to return the result. A value is returned once the API is called successfully. However, the final effect cannot be obtained immediately from the return value. To obtain the final effect immediately, call [moveWindowToAsync()](#movewindowtoasync12).
In full-screen mode, this API takes effect only on 2-in-1 devices.
On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -- | ----- | -- | --------------------------------------------- |
| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let promise = windowClass.moveWindowTo(300, 300);
promise.then(() => {
console.info('Succeeded in moving the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### moveWindowToAsync12+
moveWindowToAsync(x: number, y: number): Promise<void>
Moves this window. This API uses a promise to return the result.
A value is returned once the call takes effect. You can use **getWindowProperties** in the callback (see the code snippet below) to obtain the final effect immediately.
This API takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode).
On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name| Type| Mandatory| Description|
| -- | ----- | -- | --------------------------------------------- |
| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300010 | The operation in the current window status is invalid. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let promise = windowClass.moveWindowToAsync(300, 300);
promise.then(() => {
console.info('Succeeded in moving the window.');
let rect = windowClass?.getWindowProperties().windowRect;
console.info(`Get window rect: ` + JSON.stringify(rect));
}).catch((err: BusinessError) => {
console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### moveWindowToGlobal13+
moveWindowToGlobal(x: number, y: number): Promise<void>
Moves this window based on the coordinates. This API uses a promise to return the result. A value is returned once the call takes effect.
This operation is not supported in a window in full-screen mode.
On non-2-in-1 devices, the subwindow moves along with the main window.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 13.
**Parameters**
| Name| Type| Mandatory| Description|
| -- | ----- | -- | --------------------------------------------- |
| x | number | Yes| Distance that the window moves along the x-axis, in px, with the upper left corner of the display used as the origin. A positive value indicates that the window moves to the right, and a negative value indicates that the window moves to the left. The value must be an integer. If a non-integer is passed in, the value is rounded down.|
| y | number | Yes| Distance that the window moves along the y-axis, in px, with the upper left corner of the display used as the origin. A positive value indicates that the window moves downwards, and a negative value indicates that the window moves upwards. The value must be an integer. If a non-integer is passed in, the value is rounded down.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300010 | The operation in the current window status is invalid. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let promise = windowClass.moveWindowToGlobal(300, 300);
promise.then(() => {
console.info('Succeeded in moving the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### resize9+
resize(width: number, height: number, callback: AsyncCallback<void>): void
Changes the size of this window. This API uses an asynchronous callback to return the result.
The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp.
The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits.
The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp.
The window width and height you set must meet the limits. The rules are as follows:
- If the window width or height you set is less than the minimum width or height limit, then the minimum width or height limit takes effect.
- If the window width or height you set is greater than the maximum width or height limit, then the maximum width or height limit takes effect.
This operation is not supported in a window in full-screen mode.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------- | -- | ------------------------ |
| width | number | Yes| New width of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
| height | number | Yes| New height of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
windowClass.resize(500, 1000, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in changing the window size.');
});
} catch (exception) {
console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### resize9+
resize(width: number, height: number): Promise<void>
Changes the size of this window. This API uses a promise to return the result.
A value is returned once the API is called successfully. However, the final effect cannot be obtained immediately from the return value. To obtain the final effect immediately, call [resizeAsync()](#resizeasync12).
The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp.
The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits.
The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp.
The window width and height you set must meet the limits. The rules are as follows:
- If the window width or height you set is less than the minimum width or height limit, then the minimum width or height limit takes effect.
- If the window width or height you set is greater than the maximum width or height limit, then the maximum width or height limit takes effect.
This operation is not supported in a window in full-screen mode.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ------ | -- | ------------------------ |
| width | number | Yes| New width of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
| height | number | Yes| New height of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let promise = windowClass.resize(500, 1000);
promise.then(() => {
console.info('Succeeded in changing the window size.');
}).catch((err: BusinessError) => {
console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### resizeAsync12+
resizeAsync(width: number, height: number): Promise<void>
Changes the size of this window. This API uses a promise to return the result.
A value is returned once the call takes effect. You can use **getWindowProperties** in the callback (see the code snippet below) to obtain the final effect immediately.
The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp.
The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits.
The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp.
The window width and height you set must meet the limits. The rules are as follows:
- If the window width or height you set is less than the minimum width or height limit, then the minimum width or height limit takes effect.
- If the window width or height you set is greater than the maximum width or height limit, then the maximum width or height limit takes effect.
This operation is not supported in a window in full-screen mode.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ------ | -- | ------------------------ |
| width | number | Yes| New width of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
| height | number | Yes| New height of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300010 | The operation in the current window status is invalid. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let promise = windowClass.resizeAsync(500, 1000);
promise.then(() => {
console.info('Succeeded in changing the window size.');
let rect = windowClass?.getWindowProperties().windowRect;
console.info(`Get window rect: ` + JSON.stringify(rect));
}).catch((err: BusinessError) => {
console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### getWindowProperties9+
getWindowProperties(): WindowProperties
Obtains the properties of this window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type| Description|
| ------------------------------------- | ------------- |
| [WindowProperties](#windowproperties) | Window properties obtained.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
try {
let properties = windowClass.getWindowProperties();
} catch (exception) {
console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### getGlobalRect13+
getGlobalRect(): Rect
Obtains the actual display area of this window on the screen. This API returns the result synchronously.
This API can determine the actual on-screen location and size of a window that has been resized on certain devices.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 13.
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| [Rect](#rect7) | A set of four values, which indicates the horizontal distance from the screen's top-left corner to the window's left edge, the vertical distance from the screen's top-left corner to the window's top edge, the width of the window after scaling, and the height of the window after scaling.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
try {
let rect = windowClass.getGlobalRect();
console.info(`Succeeded in getting window rect: ` + JSON.stringify(rect));
} catch (exception) {
console.error(`Failed to get window rect. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### getWindowAvoidArea9+
getWindowAvoidArea(type: AvoidAreaType): AvoidArea
Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area.
This API can be used in the **onWindowStageCreate** callback to obtain the avoid area in the initial layout during application startup. It can also be used when a subwindow requires temporary display, necessitating the avoidance of the layout for the existing content.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| ---- |----------------------------------| -- | ------------------------------------------------------------ |
| type | [AvoidAreaType](#avoidareatype7) | Yes| Type of the area.|
**Return value**
| Type| Description|
|--------------------------| ----------------- |
| [AvoidArea](#avoidarea7) | Area where the window cannot be displayed.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
let type = window.AvoidAreaType.TYPE_SYSTEM;
try {
let avoidArea = windowClass.getWindowAvoidArea(type);
} catch (exception) {
console.error(`Failed to obtain the area. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setTitleAndDockHoverShown14+
setTitleAndDockHoverShown(isTitleHoverShown?: boolean, isDockHoverShown?: boolean): Promise<void>
Sets whether to show the window title bar and dock bar when the cursor hovers over the hot zone while the main window is in full-screen mode. This API uses a promise to return the result. It can be used only on 2-in-1 devices.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 14.
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------- | ---- | ------------------------------------------------------------ |
| isTitleHoverShown | boolean | No | Whether to show the window title bar.
The value **true** means to show the window title bar, and **false** means the opposite. The default value is **true**.|
| isDockHoverShown | boolean | No | Whether to show the dock bar.
The value **true** means to show the dock bar, and **false** means the opposite. The default value is **true**.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
// Load the page corresponding to the main window.
windowStage.loadContent('pages/Index', (err) => {
let mainWindow: window.Window | undefined = undefined;
// Obtain the main window.
windowStage.getMainWindow().then(
data => {
mainWindow = data;
console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
// Call maximize to enable the full-screen mode for the window.
mainWindow.maximize(window.MaximizePresentation.ENTER_IMMERSIVE);
// Call setTitleAndDockHoverShown to hide the window title bar and dock bar.
mainWindow.setTitleAndDockHoverShown(false, false);
}
).catch((err: BusinessError) => {
if(err.code){
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
}
});
});
}
}
```
### setWindowLayoutFullScreen9+
setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>
Sets whether the main window layout or the subwindow layout is immersive. This API uses a promise to return the result. From API version 14, this API does not take effect on 2-in-1 devices.
- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them.
- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name| Type| Mandatory| Description|
| ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ |
| isLayoutFullScreen | boolean | Yes| Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window layout is immersive, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let isLayoutFullScreen = true;
try {
let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen);
promise.then(() => {
console.info('Succeeded in setting the window layout to full-screen mode.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setImmersiveModeEnabledState12+
setImmersiveModeEnabledState(enabled: boolean): void
Sets whether to enable the immersive layout for the main window. This API does not change the window mode or size. From API version 14, this API does not take effect on 2-in-1 devices.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------- | ---- | ------------------------------------------------------------ |
| enabled | boolean | Yes | Whether to enable the immersive layout.
The value **true** means to enable the immersive layout, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
try {
let enabled = false;
windowClass.setImmersiveModeEnabledState(enabled);
} catch (exception) {
console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### getImmersiveModeEnabledState12+
getImmersiveModeEnabledState(): boolean
Checks whether the immersive layout is enabled for this window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Return value**
| Type | Description |
| ------- | ------------------------------------------------------------------------------------ |
| boolean | Result indicating whether the immersive layout is enabled.
The value **true** means that the immersive layout is enabled, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| -------- | -------------------------------------------- |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
try {
let isEnabled = windowClass.getImmersiveModeEnabledState();
} catch (exception) {
console.error(`Failed to get the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowSystemBarEnable9+
setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void>
Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses a promise to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, this API does not take effect on 2-in-1 devices.
The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description|
| ----- | ---------------------------- | -- | --------------------------------- |
| names | Array<'status'\|'navigation'> | Yes| Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.
For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed.
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let names: Array<'status' | 'navigation'> = [];
try {
let promise = windowClass.setWindowSystemBarEnable(names);
promise.then(() => {
console.info('Succeeded in setting the system bar to be invisible.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setSpecificSystemBarEnabled11+
setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void>
Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses a promise to return the result. From API version 12, this API does not take effect on 2-in-1 devices.
The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type | Mandatory| Description|
| ----- | ---------------------------- | -- | --------------------------------- |
| name | [SpecificSystemBar](#specificsystembar11) | Yes| Type of the system bar to be shown or hidden.|
| enable | boolean | Yes| Whether to show the three-button navigation bar, status bar, and bottom navigation bar. The value **true** means to show them, and **false** means to hide them.|
| enableAnimation12+ | boolean | No| Whether to enable animation when the three-button navigation bar, status bar, and bottom navigation bar status changes. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// Hide the bottom navigation bar.
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
try {
let promise = windowClass.setSpecificSystemBarEnabled('navigationIndicator', false);
promise.then(() => {
console.info('Succeeded in setting the system bar to be invisible.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setWindowSystemBarProperties9+
setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void>
Sets the properties of the three-button navigation bar and status bar of the main window. This API uses a promise to return the result. This API does not take effect on 2-in-1 devices.
This API does not take effect when it is called by a subwindow.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------- | ------------------------------------------- | ---- | ---------------------- |
| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let SystemBarProperties: window.SystemBarProperties = {
statusBarColor: '#ff00ff',
navigationBarColor: '#00ff00',
// The following properties are supported since API version 8.
statusBarContentColor: '#ffffff',
navigationBarContentColor: '#00ffff'
};
try {
let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties);
promise.then(() => {
console.info('Succeeded in setting the system bar properties.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### getWindowSystemBarProperties12+
getWindowSystemBarProperties(): SystemBarProperties
Obtains the properties of the three-button navigation bar and status bar of the main window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Return value**
| Type| Description|
| ------------------------------------- | ------------- |
| [SystemBarProperties](#systembarproperties) | Properties of the three-button navigation bar and status bar.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
try {
let systemBarProperty = windowClass.getWindowSystemBarProperties();
console.info('Success in obtaining system bar properties. Property: ' + JSON.stringify(systemBarProperty));
} catch (err) {
console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`);
}
});
}
};
```
### setPreferredOrientation9+
setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void
Sets the preferred orientation for the main window. This API uses an asynchronous callback to return the result. This API takes effect only on devices that support rotation with the sensor. It does not take effect on 2-in-1 devices or in the subwindow mode.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------- | ------------------------------------------- | ---- | ---------------------- |
| orientation | [Orientation](#orientation9) | Yes | Orientation to set. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. The callback indicates the API call result. It does not mean that the application rotation animation ends.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let orientation = window.Orientation.AUTO_ROTATION;
try {
windowClass.setPreferredOrientation(orientation, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set window orientation. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting window orientation.');
});
} catch (exception) {
console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setPreferredOrientation9+
setPreferredOrientation(orientation: Orientation): Promise<void>
Sets the preferred orientation for the main window. This API uses a promise to return the result. This API takes effect only on devices that support rotation with the sensor. It does not take effect on 2-in-1 devices or in the subwindow mode.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------- | ------------------------------------------- | ---- | ---------------------- |
| orientation | [Orientation](#orientation9) | Yes | Orientation to set. |
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let orientation = window.Orientation.AUTO_ROTATION;
try {
let promise = windowClass.setPreferredOrientation(orientation);
promise.then(() => {
console.info('Succeeded in setting the window orientation.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window orientation. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### getPreferredOrientation12+
getPreferredOrientation(): Orientation
Obtains the orientation of the main window. This API can be called only by the main window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Return value**
| Type| Description|
|------------------------------| ------------------ |
| [Orientation](#orientation9) | Orientation.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
try {
let orientation = windowClass.getPreferredOrientation();
} catch (exception) {
console.error(`Failed to get window orientation. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
};
```
### getUIContext10+
getUIContext(): UIContext
Obtain a **UIContext** instance.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type | Description |
| ---------- | ---------------------- |
| [UIContext](js-apis-arkui-UIContext.md#uicontext) | **UIContext** instance obtained.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { window, UIContext } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
// Load content for the main window.
windowStage.loadContent("pages/page2", (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
// Obtain the main window.
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
let errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
// Obtain a UIContext instance.
let uiContext: UIContext | null = null;
uiContext = windowClass.getUIContext();
});
});
}
};
```
### setUIContent9+
setUIContent(path: string, callback: AsyncCallback<void>): void
Loads the content of a page, with its path in the current project specified, to this window. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ------------------------- | -- | -------------------- |
| path | string | Yes| Path of the page from which the content will be loaded. In the stage model, the path is configured in the **main_pages.json** file of the project. In the FA model, the path is configured in the **config.json** file of the project.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
windowClass.setUIContent('pages/page2/page3', (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setUIContent9+
setUIContent(path: string): Promise<void>
Loads the content of a page, with its path in the current project specified, to this window. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| ---- | ------ | -- | ------------------ |
| path | string | Yes| Path of the page from which the content will be loaded. In the stage model, the path is configured in the **main_pages.json** file of the project. In the FA model, the path is configured in the **config.json** file of the project.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let promise = windowClass.setUIContent('pages/page2/page3');
promise.then(() => {
console.info('Succeeded in loading the content.');
}).catch((err: BusinessError) => {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### loadContent9+
loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void
Loads the content of a page, with its path in the current project specified, to this window, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the page from which the content will be loaded. The path is configured in the **main_pages.json** file of the project.|
| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
windowClass.loadContent('pages/page2', storage, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
```
### loadContent9+
loadContent(path: string, storage: LocalStorage): Promise<void>
Loads the content of a page, with its path in the current project specified, to this window, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the page from which the content will be loaded. The path is configured in the **main_pages.json** file of the project.|
| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
let promise = windowClass.loadContent('pages/page2', storage);
promise.then(() => {
console.info('Succeeded in loading the content.');
}).catch((err: BusinessError) => {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
});
```
### loadContentByName11+
loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void
Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| name | string | Yes | Name of the named route page. |
| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // Import the named route page.
console.info('onWindowStageCreate');
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
try {
(windowClass as window.Window).loadContentByName(Index.entryName, storage, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
```ts
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
### loadContentByName11+
loadContentByName(name: string, callback: AsyncCallback<void>): void
Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------------- |
| name | string | Yes | Name of the named route page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // Import the named route page.
try {
(windowClass as window.Window).loadContentByName(Index.entryName, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
```ts
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName})
@Component
export struct Index {
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
### loadContentByName11+
loadContentByName(name: string, storage?: LocalStorage): Promise<void>
Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| name | string | Yes | Name of the named route page. |
| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // Import the named route page.
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
try {
let promise = (windowClass as window.Window).loadContentByName(Index.entryName, storage);
promise.then(() => {
console.info('Succeeded in loading the content.');
}).catch((err: BusinessError) => {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
```ts
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
### isWindowShowing9+
isWindowShowing(): boolean
Checks whether this window is displayed.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type| Description|
| ------- | ------------------------------------------------------------------ |
| boolean | Whether the window is displayed. The value **true** means that the window is displayed, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
try {
let data = windowClass.isWindowShowing();
console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data));
} catch (exception) {
console.error(`Failed to check whether the window is showing. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('windowSizeChange')7+
on(type: 'windowSizeChange', callback: Callback<Size>): void
Subscribes to the window size change event.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.|
| callback | Callback<[Size](#size7)> | Yes | Callback used to return the window size. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
**Example**
```ts
try {
windowClass.on('windowSizeChange', (data) => {
console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error(`Failed to enable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('windowSizeChange')7+
off(type: 'windowSizeChange', callback?: Callback<Size>): void
Unsubscribes from the window size change event.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------- | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.|
| callback | Callback<[Size](#size7)> | No | Callback used to return the window size. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
**Example**
```ts
const callback = (size: window.Size) => {
// ...
}
try {
// Enable listening through the on API.
windowClass.on('windowSizeChange', callback);
// Disable the listening of a specified callback.
windowClass.off('windowSizeChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('windowSizeChange');
} catch (exception) {
console.error(`Failed to disable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('avoidAreaChange')9+
on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void
Subscribes to the event indicating changes to the area where this window cannot be displayed.
Common scenarios for triggering this event are as follows: transitions between full-screen mode, floating mode, and split-screen mode of the application window; rotation of the application window; transitions between folded and unfolded states of a foldable device; transfer of the application window between multiple devices.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |----------------------------------| ---- |--------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'avoidAreaChange'**, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidAreaOptions](#avoidareaoptions12)> | Yes | Callback used to return the area and area type.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
**Example**
```ts
try {
windowClass.on('avoidAreaChange', (data) => {
console.info('Succeeded in enabling the listener for system avoid area changes. type:' +
JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area));
});
} catch (exception) {
console.error(`Failed to enable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('avoidAreaChange')9+
off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaOptions>): void
Unsubscribes from the event indicating changes to the area where this window cannot be displayed.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |----------------------------------|------|------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'avoidAreaChange'**, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidAreaOptions](#avoidareaoptions12)> | No | Callback used to return the area and area type. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. |
**Example**
```ts
interface Param {
type: window.AvoidAreaType,
area: window.AvoidArea
}
const callback = (data: Param) => {
// ...
}
try {
windowClass.on('avoidAreaChange', callback);
windowClass.off('avoidAreaChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('avoidAreaChange');
} catch (exception) {
console.error(`Failed to enable or disable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('keyboardHeightChange')7+
on(type: 'keyboardHeightChange', callback: Callback<number>): void
Subscribes to the event indicating soft keyboard height changes in fixed state.
The system notifies the keyboard height change when the soft keyboard is invoked by the window and overlaps with the window.
Since API version 10, the soft keyboard can be set to the fixed or floating state. For details, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10).
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------- | ---- |-------------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.|
| callback | Callback<number> | Yes | Callback used to return the current keyboard height, which is an integer, in px. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
windowClass.on('keyboardHeightChange', (data) => {
console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data));
});
} catch (exception) {
console.error(`Failed to enable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('keyboardHeightChange')7+
off(type: 'keyboardHeightChange', callback?: Callback<number>): void
Unsubscribes from the event indicating soft keyboard height changes in fixed state.
Since API version 10, the soft keyboard can be set to the fixed or floating state. For details, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10).
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.|
| callback | Callback<number> | No | Callback used to return the current keyboard height, which is an integer, in px. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
const callback = (height: number) => {
// ...
}
try {
windowClass.on('keyboardHeightChange', callback);
windowClass.off('keyboardHeightChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('keyboardHeightChange');
} catch (exception) {
console.error(`Failed to disable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('touchOutside')11+
on(type: 'touchOutside', callback: Callback<void>): void
Subscribes to the touch event outside this window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.|
| callback | Callback<void> | Yes | Callback used to return the touch event outside this window. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
**Example**
```ts
try {
windowClass.on('touchOutside', () => {
console.info('touch outside');
});
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('touchOutside')11+
off(type: 'touchOutside', callback?: Callback<void>): void
Unsubscribes from the touch event outside this window.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |----------------------| ---- |--------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.|
| callback | Callback<void> | No | Callback used to return the touch event outside this window. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
**Example**
```ts
const callback = () => {
// ...
}
try {
windowClass.on('touchOutside', callback);
windowClass.off('touchOutside', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('touchOutside');
} catch (exception) {
console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('screenshot')9+
on(type: 'screenshot', callback: Callback<void>): void
Subscribes to the screenshot event.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event, which can be initiated from the Control Panel, by running hdc commands, or by calling the screenshot interfaces.|
| callback | Callback<void> | Yes | Callback invoked when a screenshot event occurs. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
**Example**
```ts
try {
windowClass.on('screenshot', () => {
console.info('screenshot happened');
});
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('screenshot')9+
off(type: 'screenshot', callback?: Callback<void>): void
Unsubscribes from the screenshot event.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event.|
| callback | Callback<void> | No | Callback invoked when a screenshot event occurs. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
**Example**
```ts
let callback = () => {
console.info('screenshot happened');
};
try {
windowClass.on('screenshot', callback);
windowClass.off('screenshot', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('screenshot');
} catch (exception) {
console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('dialogTargetTouch')10+
on(type: 'dialogTargetTouch', callback: Callback<void>): void
Subscribes to click or touch events in a window covered by a modal window. This API takes effect only when it is called by a modal window.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the click or touch event in a window covered by a modal window.|
| callback | Callback<void>| Yes | Callback invoked when a click or touch event occurs in the window covered by the modal window.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
**Example**
```ts
try {
windowClass.on('dialogTargetTouch', () => {
console.info('touch dialog target');
});
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('dialogTargetTouch')10+
off(type: 'dialogTargetTouch', callback?: Callback<void>): void
Unsubscribes from the touch event of the target window in the modal window mode.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the touch event of the target window in the modal window mode.|
| callback | Callback<void> | No | Callback invoked when the touch event occurs in the target window of the modal window mode. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
**Example**
```ts
const callback = () => {
// ...
}
try {
windowClass.on('dialogTargetTouch', callback);
windowClass.off('dialogTargetTouch', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('dialogTargetTouch');
} catch (exception) {
console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('windowEvent')10+
on(type: 'windowEvent', callback: Callback<WindowEventType>): void
Subscribes to the window lifecycle change event.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.|
| callback | Callback<[WindowEventType](#windoweventtype10)> | Yes | Callback used to return the window lifecycle state. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
**Example**
```ts
try {
windowClass.on('windowEvent', (data) => {
console.info('Window event happened. Event:' + JSON.stringify(data));
});
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('windowEvent')10+
off(type: 'windowEvent', callback?: Callback<WindowEventType>): void
Unsubscribes from the window lifecycle change event.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.|
| callback | Callback<[WindowEventType](#windoweventtype10)> | No | Callback used to return the window lifecycle state. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
**Example**
```ts
const callback = (windowEventType: window.WindowEventType) => {
// ...
}
try {
// Enable listening through the on API.
windowClass.on('windowEvent', callback);
// Disable the listening of a specified callback.
windowClass.off('windowEvent', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('windowEvent');
} catch (exception) {
console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('displayIdChange')14+
on(type: 'displayIdChange', callback: Callback<number>): void
Subscribes to the display change event of this window. For example, this event is triggered when the window is moved to a different display.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------| ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.|
| callback | Callback<number> | Yes | Callback invoked when the display where the window is located changes. The callback contains a parameter of the number type, indicating the new display ID. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
try {
windowClass.on('displayIdChange', (data) => {
console.info('Window displayId changed, displayId=' + JSON.stringify(data));
});
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('displayIdChange')14+
off(type: 'displayIdChange', callback?: Callback<number>): void
Unsubscribes from the display change event of this window.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |----------------------------| ---- |--------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.|
| callback | Callback<number> | No | Callback invoked when the display where the window is located changes. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
const callback = (displayId: number) => {
// ...
}
try {
// Enable listening through the on API.
windowClass.on('displayIdChange', callback);
// Disable the listening of a specified callback.
windowClass.off('displayIdChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('displayIdChange');
} catch (exception) {
console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('windowVisibilityChange')11+
on(type: 'windowVisibilityChange', callback: Callback<boolean>): void
Subscribes to the visibility status change event of this window.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------| ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.|
| callback | Callback<boolean> | Yes | Callback used to return the visibility status of the window, which is a Boolean value. The value **true** means that the window is visible, and **false** means the opposite. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
try {
windowClass.on('windowVisibilityChange', (boolean) => {
console.info('Window visibility changed, isVisible=' + boolean);
});
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('windowVisibilityChange')11+
off(type: 'windowVisibilityChange', callback?: Callback<boolean>): void
Unsubscribes from the visibility status change event of this window.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |----------------------------| ---- |--------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.|
| callback | Callback<boolean> | No | Callback used to return the visibility status of the window. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
const callback = (bool: boolean) => {
// ...
}
try {
// Enable listening through the on API.
windowClass.on('windowVisibilityChange', callback);
// Disable the listening of a specified callback.
windowClass.off('windowVisibilityChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('windowVisibilityChange');
} catch (exception) {
console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('noInteractionDetected')12+
on(type: 'noInteractionDetected', timeout: number, callback: Callback<void>): void
Subscribes to non-interaction events in a window within the specified period.
Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------| ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'noInteractionDetected'**, indicating that there is no interaction event in the window within the specified period.|
| timeout | number | Yes | Period during which no interaction is performed, in seconds. The value must be an integer. Negative numbers and decimals are invalid.|
| callback | Callback<void> | Yes | Callback invoked when there is no interaction event in the current window within the specified period. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
try {
windowClass.on('noInteractionDetected', 60, () => {
console.info('no interaction in 60s');
});
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('noInteractionDetected')12+
off(type: 'noInteractionDetected', callback?: Callback<void>): void
Unsubscribes from non-interaction events in a window within the specified period.
Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |----------------------------| ---- |--------------------------------------|
| type | string | Yes | Event type. The value is fixed at **'noInteractionDetected'**, indicating that there is no interaction event in the window within the specified period.|
| callback | Callback<void> | No | Callback invoked when there is no interaction event in the current window within the specified period. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
const callback = () => {
// ...
}
try {
windowClass.on('noInteractionDetected', 60, callback);
windowClass.off('noInteractionDetected', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('noInteractionDetected');
} catch (exception) {
console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### on('windowStatusChange')11+
on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void
Subscribes to the window status change event. A notification is sent when the window status changes (the window properties may not be updated).
> **NOTE**
>
> When this API is called on 2-in-1 devices, the return value is **WindowStatusType::FULL_SCREEN** when the window is maximized.
>
> Upon the return value **WindowStatusType::FULL_SCREEN**, you can call [getImmersiveModeEnabledState()](#getimmersivemodeenabledstate12) to determine whether the window is in full-screen or maximized mode on 2-in-1 devices. The return value **true** means that the window is in full-screen mode, and **false** means that the window is maximized.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.|
| callback | Callback<[WindowStatusType](#windowstatustype11)> | Yes | Callback used to return the window status. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
**Example**
```ts
try {
windowClass.on('windowStatusChange', (WindowStatusType) => {
console.info('Succeeded in enabling the listener for window status changes. Data: ' + JSON.stringify(WindowStatusType));
});
} catch (exception) {
console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('windowStatusChange')11+
off(type: 'windowStatusChange', callback?: Callback<WindowStatusType>): void
Unsubscribes from the window status change event.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------- | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.|
| callback | Callback<[WindowStatusType](#windowstatustype11)> | No | Callback used to return the window status. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
**Example**
```ts
const callback = (windowStatusType: window.WindowStatusType) => {
// ...
}
try {
windowClass.on('windowStatusChange', callback);
windowClass.off('windowStatusChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('windowStatusChange');
} catch (exception) {
console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowGrayScale12+
setWindowGrayScale(grayScale: number): Promise<void>
Sets the grayscale effect for this window. This API uses a promise to return the result. This API can be called only after [loadContent()](#loadcontent9) or [setUIContent()](#setuicontent9) is called.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name| Type| Mandatory| Description |
| --------- | ------ | -- | ---------------------------------------- |
| grayScale | number | Yes| Grayscale of the window. The value is a floating point number in the range [0.0, 1.0]. The value **0.0** means that the window image does not change, and **1.0** means that the window image is completely turned into grayscale. The effect changes linearly between 0.0 and 1.0.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass?.setUIContent('pages/Index', (error: BusinessError) => {
if (error.code) {
console.error(`Failed to set the content. Cause code: ${error.code}`);
return;
}
console.info('Succeeded in setting the content.');
let grayScale: number = 0.5;
try {
if (canIUse("SystemCapability.Window.SessionManager")) {
let promise = windowClass?.setWindowGrayScale(grayScale);
promise?.then(() => {
console.info('Succeeded in setting the grayScale.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the grayScale. Cause code: ${err.code}, message: ${err.message}`);
});
}
} catch (exception) {
console.error(`Failed to set the grayScale. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
```
### on('windowTitleButtonRectChange')11+
on(type: 'windowTitleButtonRectChange', callback: Callback<TitleButtonRect>): void
Subscribes to the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'windowTitleButtonRectChange'**, indicating that the change event of the rectangle that holds the minimize, maximize, and close buttons.|
| callback | Callback<[TitleButtonRect](#titlebuttonrect11)> | Yes | Callback used to return the new rectangle.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
windowClass.setUIContent('pages/WindowPage').then(() => {
try {
windowClass?.on('windowTitleButtonRectChange', (titleButtonRect) => {
console.info('Succeeded in enabling the listener for window title buttons area changes. Data: ' + JSON.stringify(titleButtonRect));
});
} catch (exception) {
console.error(`Failed to enable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
})
```
### off('windowTitleButtonRectChange')11+
off(type: 'windowTitleButtonRectChange', callback?: Callback<TitleButtonRect>): void
Unsubscribes from the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'windowTitleButtonRectChange'**, indicating that the change event of the rectangle that holds the minimize, maximize, and close buttons.|
| callback | Callback<[TitleButtonRect](#titlebuttonrect11)> | No | Callback used to return the new rectangle. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
windowClass.setUIContent('pages/WindowPage').then(() => {
const callback = (titleButtonRect: window.TitleButtonRect) => {
// ...
}
try {
// Enable listening through the on API.
windowClass?.on('windowTitleButtonRectChange', callback);
// Disable the listening of a specified callback.
windowClass?.off('windowTitleButtonRectChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass?.off('windowTitleButtonRectChange');
} catch (exception) {
console.error(`Failed to disable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
})
```
### on('windowRectChange')12+
on(type: 'windowRectChange', callback: Callback<RectChangeOptions>): void
Subscribes to window rectangle (position and size) change events.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event.|
| callback | Callback<[RectChangeOptions](#rectchangeoptions12)> | Yes | Callback used to return the value and reason of the window rectangle change. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
windowClass.on('windowRectChange', (data: window.RectChangeOptions) => {
console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data));
});
```
### off('windowRectChange')12+
off(type: 'windowRectChange', callback?: Callback<RectChangeOptions>): void
Unsubscribes from window rectangle (position and size) change events.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event. |
| callback | Callback<[RectChangeOptions](#rectchangeoptions12)> | No | Callback used to return the value and reason of the window rectangle change. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
const callback = (rectChangeOptions: window.RectChangeOptions) => {
// ...
}
windowClass.on('windowRectChange', callback);
windowClass.off('windowRectChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('windowRectChange');
```
### on('subWindowClose')12+
on(type: 'subWindowClose', callback: Callback<void>): void
Subscribes to the event indicating that the subwindow is closed. This event is triggered only when the user clicks the close button in the upper right corner provided by the system to close the subwindow. It is not triggered when the subwindow is closed in other ways.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the subwindow close event.|
| callback | Callback<void> | Yes | Callback invoked when the close button in the upper right corner of the subwindow is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the subwindow. The value **true** means not to close the subwindow, and **false** means to continue to close the subwindow. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
const callback = () => {
// ...
return true;
}
try {
windowClass.on('subWindowClose', callback);
} catch (exception) {
console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### off('subWindowClose')12+
off(type: 'subWindowClose', callback?: Callback<void>): void
Unsubscribes from the event indicating that the subwindow is closed.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the subwindow close event. |
| callback | Callback<void> | No | Callback invoked when the close button in the upper right corner of the subwindow is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the subwindow. The value **true** means not to close the subwindow, and **false** means to continue to close the subwindow. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
const callback = () => {
// ...
return true;
}
try {
windowClass.on('subWindowClose', callback);
windowClass.off('subWindowClose', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('subWindowClose');
} catch (exception) {
console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### isWindowSupportWideGamut9+
isWindowSupportWideGamut(callback: AsyncCallback<boolean>): void
Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | ---------------------------- | -- | -------------------------------------------------------------------------------- |
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. The value **true** means that the wide-gamut color space is supported, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.isWindowSupportWideGamut((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data));
});
```
### isWindowSupportWideGamut9+
isWindowSupportWideGamut(): Promise<boolean>
Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type| Description|
| ---------------------- | ------------------------------------------------------------------------------------ |
| Promise<boolean> | Promise used to return the result. The value **true** means that the wide-gamut color space is supported, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.isWindowSupportWideGamut();
promise.then((data) => {
console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setWindowColorSpace9+
setWindowColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void
Sets a color space for this window. This API uses an asynchronous callback to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ---------- | ------------------------- | -- | ----------- |
| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting window colorspace.');
});
} catch (exception) {
console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowColorSpace9+
setWindowColorSpace(colorSpace:ColorSpace): Promise<void>
Sets a color space for this window. This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ---------- | ------------------------- | -- | ------------- |
| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let promise = windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT);
promise.then(() => {
console.info('Succeeded in setting window colorspace.');
}).catch((err: BusinessError) => {
console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### getWindowColorSpace9+
getWindowColorSpace(): ColorSpace
Obtains the color space of this window.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type| Description|
| ------------------------- | ------------- |
| [ColorSpace](#colorspace8) | Color space obtained.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
let colorSpace = windowClass.getWindowColorSpace();
```
### setWindowBackgroundColor9+
setWindowBackgroundColor(color: string): void
Sets the background color for this window. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| ----- | ------ | -- | ----------------------------------------------------------------------- |
| color | string | Yes| Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
windowClass.loadContent("pages/page2", storage, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
let color: string = '#00ff33';
try {
windowClass?.setWindowBackgroundColor(color);
} catch (exception) {
console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`);
};
});
```
### setWindowBrightness9+
setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void
Sets the screen brightness for the main window. This API uses an asynchronous callback to return the result.
When the screen brightness setting for the window by this API takes effect, Control Panel cannot adjust the overall system screen brightness. It can do so only after the window-specific screen brightness is restored to the default value.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description |
| ---------- | ------------------------- | -- |-------------------------------------------|
| brightness | number | Yes| Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let brightness: number = 1;
try {
windowClass.setWindowBrightness(brightness, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the brightness.');
});
} catch (exception) {
console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setWindowBrightness9+
setWindowBrightness(brightness: number): Promise<void>
Sets the screen brightness for the main window. This API uses a promise to return the result.
When the screen brightness setting for the window by this API takes effect, Control Panel cannot adjust the overall system screen brightness. It can do so only after the window-specific screen brightness is restored to the default value.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description |
| ---------- | ------ | -- |----------------------------------------|
| brightness | number | Yes| Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let brightness: number = 1;
try {
let promise = windowClass.setWindowBrightness(brightness);
promise.then(() => {
console.info('Succeeded in setting the brightness.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setWindowFocusable9+
setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void
Sets whether this window is focusable, that is, whether the window can gain focus after it is being clicked or using other methods. This API uses an asynchronous callback to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ----------- | ------------------------- | -- | ------------------------------------------------------- |
| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isFocusable: boolean = true;
try {
windowClass.setWindowFocusable(isFocusable, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window to be focusable.');
});
} catch (exception) {
console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowFocusable9+
setWindowFocusable(isFocusable: boolean): Promise<void>
Sets whether this window is focusable, that is, whether the window can gain focus after it is being clicked or using other methods. This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ----------- | ------- | -- | -------------------------------------------------------- |
| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. |
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isFocusable: boolean = true;
try {
let promise = windowClass.setWindowFocusable(isFocusable);
promise.then(() => {
console.info('Succeeded in setting the window to be focusable.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowKeepScreenOn9+
setWindowKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void
Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result.
Set **isKeepScreenOn** to **true** only in necessary scenarios (such as navigation, video playback, drawing, and gaming scenarios). After exiting these scenarios, set the parameter to **false**. Do not use this API in other scenarios (such as no screen interaction or audio playback). When the system detects that the API is used in a non-standard manner, automatic screen-off may be invoked.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -------------- | ------------------------- | -- | ---------------------------------------------------- |
| isKeepScreenOn | boolean | Yes| Whether to keep the screen always on. The value **true** means to keep the screen always on, and **false** means the opposite. |
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isKeepScreenOn: boolean = true;
try {
windowClass.setWindowKeepScreenOn(isKeepScreenOn, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the screen to be always on.');
});
} catch (exception) {
console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowKeepScreenOn9+
setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void>
Sets whether to keep the screen always on. This API uses a promise to return the result.
Set **isKeepScreenOn** to **true** only in necessary scenarios (such as navigation, video playback, drawing, and gaming scenarios). After exiting these scenarios, set the parameter to **false**. Do not use this API in other scenarios (such as no screen interaction or audio playback). When the system detects that the API is used in a non-standard manner, automatic screen-off may be invoked.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type| Mandatory| Description|
| -------------- | ------- | -- | --------------------------------------------------- |
| isKeepScreenOn | boolean | Yes| Whether to keep the screen always on. The value **true** means to keep the screen always on, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isKeepScreenOn: boolean = true;
try {
let promise = windowClass.setWindowKeepScreenOn(isKeepScreenOn);
promise.then(() => {
console.info('Succeeded in setting the screen to be always on.');
}).catch((err: BusinessError) => {
console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowPrivacyMode9+
setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void
Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result.
A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Required permissions**: ohos.permission.PRIVACY_WINDOW
**Parameters**
| Name| Type| Mandatory| Description|
| ------------- | ------------------------- | -- | ------------------------------------------------------ |
| isPrivacyMode | boolean | Yes| Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite. |
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 201 | Permission verification failed. The application does not have the permission required to call the API. |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
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 code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window to privacy mode.');
});
} catch (exception) {
console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowPrivacyMode9+
setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void>
Sets whether this window is in privacy mode. This API uses a promise to return the result.
A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Required permissions**: ohos.permission.PRIVACY_WINDOW
**Parameters**
| Name| Type| Mandatory| Description|
| ------------- | ------- | -- | ----------------------------------------------------- |
| isPrivacyMode | boolean | Yes| Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 201 | Permission verification failed. The application does not have the permission required to call the API. |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isPrivacyMode: boolean = true;
try {
let promise = windowClass.setWindowPrivacyMode(isPrivacyMode);
promise.then(() => {
console.info('Succeeded in setting the window to privacy mode.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowTouchable9+
setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void
Sets whether this window is touchable. This API uses an asynchronous callback to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ----------- | ------------------------- | -- | ----------------------------------------------- |
| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isTouchable = true;
try {
windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window to be touchable.');
});
} catch (exception) {
console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowTouchable9+
setWindowTouchable(isTouchable: boolean): Promise<void>
Sets whether this window is touchable. This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| ----------- | ------- | -- | ----------------------------------------------- |
| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isTouchable: boolean = true;
try {
let promise = windowClass.setWindowTouchable(isTouchable);
promise.then(() => {
console.info('Succeeded in setting the window to be touchable.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### snapshot9+
snapshot(callback: AsyncCallback<image.PixelMap>): void
Captures this window. This API uses an asynchronous callback to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ------------------------- | ---- | -------------------- |
| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
windowClass.snapshot((err: BusinessError, pixelMap: image.PixelMap) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
pixelMap.release(); // Release the memory in time after the PixelMap is used.
});
```
### snapshot9+
snapshot(): Promise<image.PixelMap>
Captures this window. This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
let promise = windowClass.snapshot();
promise.then((pixelMap: image.PixelMap) => {
console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
pixelMap.release(); // Release the memory in time after the PixelMap is used.
}).catch((err: BusinessError) => {
console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setAspectRatio10+
setAspectRatio(ratio: number): Promise<void>
Sets the aspect ratio of the window content layout. This API uses a promise to return the result.
When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**.
This API can be called only for the main window and the setting takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). The aspect ratio is saved persistently, which means that the setting is valid even after the application is closed or the device is restarted.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------ | ------- | ---- |-------------------------------------------|
| ratio | number | Yes | Aspect ratio of the window content layout except border decoration. The value is a floating point number and is restricted by the maximum and minimum sizes of the window. The minimum ratio is the value of minimum width divided by the maximum height, and the maximum ratio is the maximum width divided by the minimum height. The maximum and minimum sizes of the window are determined by the intersection of the setting of [WindowLimits](#windowlimits11) and the system limit. The system limit takes precedence over [WindowLimits](#windowlimits11). The valid range of **ratio** varies with [WindowLimits](#windowlimits11). If [WindowLimits](#windowlimits11) is set prior to **ratio**, any conflict will result in an error code when setting **ratio**. Conversely, if **ratio** is set before and then conflicts arise with the subsequently configured [WindowLimits](#windowlimits11), the window's aspect ratio may not adhere to the initially configured value of **ratio**.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application.
if (!windowClass) {
console.info('windowClass is null');
}
try {
let ratio = 1.0;
let promise = windowClass.setAspectRatio(ratio);
promise.then(() => {
console.info('Succeeded in setting aspect ratio of window.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### setAspectRatio10+
setAspectRatio(ratio: number, callback: AsyncCallback<void>): void
Sets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result.
When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**.
This API can be called only for the main window and the setting takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). The aspect ratio is saved persistently, which means that the setting is valid even after the application is closed or the device is restarted.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------ | ------- | ---- |--------------------------------------------|
| ratio | number | Yes | Aspect ratio of the window content layout except border decoration. The value is a floating point number and is restricted by the maximum and minimum sizes of the window. The minimum ratio is the value of minimum width divided by the maximum height, and the maximum ratio is the maximum width divided by the minimum height. The maximum and minimum sizes of the window are determined by the intersection of the setting of [WindowLimits](#windowlimits11) and the system limit. The system limit takes precedence over [WindowLimits](#windowlimits11). The valid range of **ratio** varies with [WindowLimits](#windowlimits11). If [WindowLimits](#windowlimits11) is set prior to **ratio**, any conflict will result in an error code when setting **ratio**. Conversely, if **ratio** is set before and then conflicts arise with the subsequently configured [WindowLimits](#windowlimits11), the window's aspect ratio may not adhere to the initially configured value of **ratio**.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application.
if (!windowClass) {
console.info('Failed to load the content. Cause: windowClass is null');
}
try {
let ratio = 1.0;
windowClass.setAspectRatio(ratio, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the aspect ratio of window.');
});
} catch (exception) {
console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### resetAspectRatio10+
resetAspectRatio(): Promise<void>
Resets the aspect ratio of the window content layout. This API uses a promise to return the result.
This API can be called only for the main window and the setting takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). After this API is called, the persistently stored aspect ratio is cleared.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application.
if (!windowClass) {
console.info('Failed to load the content. Cause: windowClass is null');
}
try {
let promise = windowClass.resetAspectRatio();
promise.then(() => {
console.info('Succeeded in resetting aspect ratio of window.');
}).catch((err: BusinessError) => {
console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### resetAspectRatio10+
resetAspectRatio(callback: AsyncCallback<void>): void
Resets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result.
This API can be called only for the main window and the setting takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). After this API is called, the persistently stored aspect ratio is cleared.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application.
if (!windowClass) {
console.info('Failed to load the content. Cause: windowClass is null');
}
try {
windowClass.resetAspectRatio((err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in resetting aspect ratio of window.');
});
} catch (exception) {
console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### minimize11+
minimize(callback: AsyncCallback<void>): void
The behavior of this API varies based on the caller:
- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar.
- Hides the subwindow if the caller is a subwindow. The subwindow cannot be restored in the dock bar.
This API uses an asynchronous callback to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.minimize((err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in minimizing the window.');
});
```
### minimize11+
minimize(): Promise<void>
The behavior of this API varies based on the caller:
- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar.
- Hides the subwindow if the caller is a subwindow. The subwindow cannot be restored in the dock bar.
This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.minimize();
promise.then(() => {
console.info('Succeeded in minimizing the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### maximize12+
maximize(presentation?: MaximizePresentation): Promise<void>
Maximizes the main window. This API uses a promise to return the result.
This API can be used only on 2-in-1 devices.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name| Type | Mandatory| Description|
| ----- | ---------------------------- | -- | --------------------------------- |
| presentation | [MaximizePresentation](#maximizepresentation12) | No| Layout when the window is maximized. The default value is **window.MaximizePresentation.ENTER_IMMERSIVE**, indicating that the window enters the immersive layout when maximized.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let promise = windowClass.maximize();
// let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE);
promise.then(() => {
console.info('Succeeded in maximizing the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
};
```
### setResizeByDragEnabled14+
setResizeByDragEnabled(enable: boolean, callback: AsyncCallback<void>): void
Sets whether to enable the main window or subwindow with decorations to resize itself by dragging. This API uses an asynchronous callback to return the result.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name| Type | Mandatory| Description|
| ----- | ---------------------------- | -- | --------------------------------- |
| enable | boolean | Yes| Whether to enable the window to resize itself by dragging. The value **true** means to enable the window to resize itself by dragging, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let enabled = false;
windowClass.setResizeByDragEnabled(enabled, (err) => {
if (err.code) {
console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the function of disabling the resize by drag window.');
});
```
### setResizeByDragEnabled14+
setResizeByDragEnabled(enable: boolean): Promise<void>
Sets whether to enable the main window or subwindow with decorations to resize itself by dragging. This API uses a promise to return the result.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name| Type | Mandatory| Description|
| ----- | ---------------------------- | -- | --------------------------------- |
| enable | boolean | Yes| Whether to enable the window to resize itself by dragging. The value **true** means to enable the window to resize itself by dragging, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let enabled = false;
let promise = windowClass.setResizeByDragEnabled(enabled);
promise.then(() => {
console.info('Succeeded in setting the function of disabling the resize by drag window.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### recover11+
recover(): Promise<void>
Restores the main window from the full-screen, maximized, or split-screen mode to a floating window, and restores the window size and position to those before the full-screen, maximized, or split-screen mode is entered. If the main window is already in the floating window mode, nothing will happen. This API uses a promise to return the result. It takes effect only in the multi-window stack layout on 2-in-1 devices.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300001 | Repeated operation. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let promise = windowClass.recover();
promise.then(() => {
console.info('Succeeded in recovering the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to recover the window. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
}
```
### restore14+
restore(): Promise<void>
Restores the main window from minimization to the foreground, returning it to its size and position before it is minimized. This API uses a promise to return the result.
This API takes effect only in the multi-window stack layout when the main window is minimized and the UIAbility is in the **onForeground** state. It can be used only on 2-in-1 devices.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| **ID**| **Error Message** |
| ------------ | ------------------------------------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage): void {
// Load the page corresponding to the main window.
windowStage.loadContent('pages/Index', (err) => {
let mainWindow: window.Window | undefined = undefined;
// Obtain the main window.
windowStage.getMainWindow().then(
data => {
mainWindow = data;
console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
// Call minimize() to minimize the main window.
mainWindow.minimize();
// Set the delay function to restore the main window after a delay of 5 seconds.
setTimeout(()=>{
// Call restore() to restore the main window.
let promise = mainWindow.restore();
promise.then(() => {
console.info('Succeeded in restoring the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to restore the window. Cause code: ${err.code},
message: ${err.message}`);
});
},5000);
}
).catch((err: BusinessError) => {
if(err.code){
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
}
});
});
}
}
```
### getWindowLimits11+
getWindowLimits(): WindowLimits
Obtains the size limits of this application window.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ----------------------------- | ------------------ |
| [WindowLimits](#windowlimits11) | Window size limits.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| :------- | :----------------------------- |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
try {
let windowLimits = windowClass.getWindowLimits();
} catch (exception) {
console.error(`Failed to obtain the window limits of window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowLimits11+
setWindowLimits(windowLimits: WindowLimits): Promise<WindowLimits>
Sets the size limits for this application window. This API uses a promise to return the result.
By default, system size limits are provided. They are determined by the product configuration and cannot be modified. If **setWindowLimits** has not been called, you can call [getWindowLimits](#getwindowlimits11) to obtain the system size limits.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| :----------- | :---------------------------- | :--- | :----------------------------- |
| windowLimits | [WindowLimits](#windowlimits11) | Yes | Target size limits, in px.|
**Return value**
| Type | Description |
| :------------------------------------------- | :---------------------------------- |
| Promise<[WindowLimits](#windowlimits11)> | Promise used to return the final size limits, which are the intersection between the passed-in size limits and the system size limits.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| :------- | :-------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let windowLimits: window.WindowLimits = {
maxWidth: 1500,
maxHeight: 1000,
minWidth: 500,
minHeight: 400
};
let promise = windowClass.setWindowLimits(windowLimits);
promise.then((data) => {
console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowMask12+
setWindowMask(windowMask: Array<Array<number>>): Promise<void>;
Sets a mask for this window to get an irregularly shaped window. This API uses a promise to return the result.
The mask is used to describe the shape of the irregularly shaped window.
This API is available only for subwindows and global floating windows on 2-in-1 devices.
When the size of an irregularly shaped window changes, the actual display content is the intersection of the mask size and the window size.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| :----------- | :---------------------------- | :--- | :----------------------------- |
| windowMask | Array<Array<number>> | Yes | Mask. The value can only be a two-dimensional array containing the window size in pixels, with each element in the array set to either **0** or **1**. The value **0** indicates that the pixel is transparent, and **1** indicates that the pixel is opaque. If the passed-in pixel array does not match the window size or the value of any element in the array is not **0** or **1**, the value is invalid.|
**Return value**
| Type | Description |
| :------------------------------------------- | :---------------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| :------- | :-------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let windowMask: Array> = [
[0, 0, 0, 1, 0, 0, 0],
[0, 0, 1, 1, 1, 0, 0],
[0, 1, 1, 0, 1, 1, 0],
[1, 1, 0, 0, 0, 1, 1]
];
let promise = windowClass.setWindowMask(windowMask);
promise.then(() => {
console.info('Succeeded in setting the window mask.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window mask. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set the window mask. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### keepKeyboardOnFocus11+
keepKeyboardOnFocus(keepKeyboardFlag: boolean): void
Sets whether to keep the soft keyboard created by others when a window has focus. This API can be called only by a system window or an application subwindow.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| ---------------- | ------- | ---- | ------------------------------------------------------------ |
| keepKeyboardFlag | boolean | Yes | Whether to keep the soft keyboard created by others. The value **true** means to keep the soft keyboard, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ---------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
try {
windowClass.keepKeyboardOnFocus(true);
} catch (exception) {
console.error(`Failed to keep keyboard onFocus. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowDecorVisible11+
setWindowDecorVisible(isVisible: boolean): void
Sets whether the title bar is visible in the window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
When the window title bar is hidden and the main window transitions into full-screen mode, hovering the cursor over the hot zone of the top window's title bar will cause a floating title bar to appear. To prevent the floating title bar from appearing, call [setTitleAndDockHoverShown()](#settitleanddockhovershown14).
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| isVisible | boolean | Yes | Whether the title bar is visible. The value **true** means that the title bar is visible and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
windowClass.loadContent("pages/page2", storage, (err: BusinessError) => {
let errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
let isVisible = false;
// Call setWindowDecorVisible.
try {
windowClass?.setWindowDecorVisible(isVisible);
} catch (exception) {
console.error(`Failed to set the visibility of window decor. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
```
### setWindowTitleMoveEnabled14+
setWindowTitleMoveEnabled(enabled: boolean): void
Enables or disables the capability to move the window (either main window or subwindow) by dragging its title bar and to maximize the window with a double-click. This API can be used only on 2-in-1 devices. When this capability is disabled, you can use [startMoving()](#startmoving14) to move the window by dragging in the application's hot zone and use [maximize()](#maximize12) to maximize the window.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| enabled | boolean | Yes | Whether to enable the capability to move the window by dragging the title bar and to maximize the window with a double-click. The value **true** means to enable the capability, and **false** means to disable it.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
try {
let enabled = false;
windowClass.setWindowTitleMoveEnabled(enabled);
} catch (exception) {
console.error(`Failed to set the window title move enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setSubWindowModal12+
setSubWindowModal(isModal: boolean): Promise<void>
Enables the modal property of the subwindow. This API uses a promise to return the result.
This API must be called by a subwindow and the setting takes effect for the subwindow.
After the modal property is enabled, the parent window does not respond to user interactions until the subwindow is closed or the subwindow's modal property is disabled.
If this API is called by a main window, an error is reported.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| isModal | boolean | Yes | Whether to enable the modal property of the subwindow. The value **true** means to enable the modal property, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
// Create a subwindow.
try {
let subWindow = windowStage.createSubWindow("testSubWindow");
subWindow.then((data) => {
if (data == null) {
console.error("Failed to create the subWindow. Cause: The data is empty");
return;
}
windowClass = data;
let promise = windowClass.setSubWindowModal(true);
promise.then(() => {
console.info('Succeeded in setting subwindow modal');
}).catch((err: BusinessError) => {
console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`);
});
});
} catch (exception) {
console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### setSubWindowModal14+
setSubWindowModal(isModal: boolean, modalityType: ModalityType): Promise<void>
Sets the modality type of the subwindow. This API uses a promise to return the result.
When the subwindow is of the window-modal type, its parent window does not respond to user interactions until the subwindow is closed or the subwindow's modal property is disabled.
When the subwindow is of the application-modal type, its parent window and the windows from other instances of the application do not respond to user interactions until the subwindow is closed or the subwindow's modal property is disabled.
This API is used to set the modality type. To disable the modal property, you are advised to use [setSubWindowModal12+](#setsubwindowmodal12).
If this API is called by a main window, an error is reported.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| isModal | boolean | Yes | Whether to enable the modal property of the subwindow. The value **true** means to enable the modal property, and **false** means the opposite. Currently, this parameter can only be set to **true**.|
| modalityType | [ModalityType](#modalitytype14) | Yes | Modality type of the subwindow.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
// Create a subwindow.
try {
let subWindow = windowStage.createSubWindow("testSubWindow");
subWindow.then((data) => {
if (data == null) {
console.error("Failed to create the subWindow. Cause: The data is empty");
return;
}
windowClass = data;
let promise = windowClass.setSubWindowModal(true, window.ModalityType.WINDOW_MODALITY);
promise.then(() => {
console.info('Succeeded in setting subwindow modal');
}).catch((err: BusinessError) => {
console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`);
});
});
} catch (exception) {
console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### setWindowDecorHeight11+
setWindowDecorHeight(height: number): void
Sets the height of the title bar of this window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
When the main window transitions into full-screen mode, hovering the mouse over the hot zone of the window's title bar region will cause a floating title bar to appear, with a fixed height of 37 vp.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| height | number | Yes |Height of the title bar. It takes effect only for the window with the title bar. The value is an integer in the range [37,112]. The unit is vp. If a floating point number is passed in, the value is rounded down. A value outside the range is invalid.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
windowClass.setUIContent('pages/WindowPage').then(() => {
let height: number = 50;
try {
windowClass?.setWindowDecorHeight(height);
console.info(`Succeeded in setting the height of window decor: ${height}`);
} catch (exception) {
console.error(`Failed to set the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`);
}
})
```
### setDecorButtonStyle14+
setDecorButtonStyle(dectorStyle: DecorButtonStyle): void
Sets the button style of the decoration bar. The setting takes effect only for the main window on 2-in-1 devices and the subwindow with the window title enabled.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| dectorStyle | [DecorButtonStyle](#decorbuttonstyle14) | Yes | Button style of the decoration bar.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
import { ConfigurationConstant } from '@kit.AbilityKit';
try {
let colorMode : ConfigurationConstant.ColorMode = ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT;
let style: window.DecorButtonStyle = {
colorMode: colorMode,
buttonBackgroundSize: 24,
spacingBetweenButtons: 12,
closeButtonRightMargin: 20
};
windowClass.setDecorButtonStyle(style);
console.info('Succeeded in setting the style of button. Data: ' + JSON.stringify(style));
} catch (exception) {
console.error(`Failed to set the style of button. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### getDecorButtonStyle14+
getDecorButtonStyle(): DecorButtonStyle
Obtains the button style of the decoration bar. The setting takes effect only for the main window on 2-in-1 devices and the subwindow with the window title enabled.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------------------------- | ------------------------------------------------------------ |
| [DecorButtonStyle](#decorbuttonstyle14) | Button style on the decoration bar of the current window. The decoration button area is located in the upper right corner of the window.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
try {
let decorButtonStyle = windowClass.getDecorButtonStyle();
console.info('Succeeded in getting the style of button. Data: ' + JSON.stringify(decorButtonStyle));
} catch (exception) {
console.error(`Failed to get the style of button. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### getWindowDecorHeight11+
getWindowDecorHeight(): number
Obtains the height of the title bar of this window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------ | ------------------------------------------------------------ |
| number | Height of the title bar. The value is an integer in the range [37,112]. The unit is vp.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
windowClass.setUIContent('pages/WindowPage').then(() => {
try {
let height = windowClass?.getWindowDecorHeight();
console.info(`Succeeded in getting the height of window decor: ${height}`);
} catch (exception) {
console.error(`Failed to get the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`);
}
})
```
### getTitleButtonRect11+
getTitleButtonRect(): TitleButtonRect
Obtains the rectangle that holds the minimize, maximize, and close buttons on the title bar of the main window or the decorated subwindow.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------------------------- | ------------------------------------------------------------ |
| [TitleButtonRect](#titlebuttonrect11) | Rectangle obtained, which is located in the upper right corner of the window.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
try {
let titleButtonArea = windowClass.getTitleButtonRect();
console.info('Succeeded in obtaining the area of title buttons. Data: ' + JSON.stringify(titleButtonArea));
} catch (exception) {
console.error(`Failed to get the area of title buttons. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### getWindowStatus12+
getWindowStatus(): WindowStatusType
Obtains the mode of this window.
> **NOTE**
>
> When this API is called on 2-in-1 devices, the return value is **WindowStatusType::FULL_SCREEN** when the window is maximized.
>
> Upon the return value **WindowStatusType::FULL_SCREEN**, you can call [getImmersiveModeEnabledState()](#getimmersivemodeenabledstate12) to determine whether the window is in full-screen or maximized mode on 2-in-1 devices. The return value **true** means that the window is in full-screen mode, and **false** means that the window is maximized.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Type | Description |
| ------------------------------ | ----------------------------------------|
| [WindowStatusType](#windowstatustype11) | Window mode. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
try {
let windowStatusType = windowClass.getWindowStatus();
} catch (exception) {
console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### isFocused12+
isFocused(): boolean
Checks whether this window is focused.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Return value**
| Type| Description|
| ------- | ------------------------------------------------------------------ |
| boolean | Result indicating whether the window is focused. The value **true** means that the window is focused, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
**Example**
```ts
try {
let focus = windowClass.isFocused();
console.info('Succeeded in checking whether the window is focused. Data: ' + JSON.stringify(focus));
} catch (exception) {
console.error(`Failed to check whether the window is focused. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### createSubWindowWithOptions12+
createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window>
Creates a subwindow under the main window or another subwindow. This API uses a promise to return the result. It takes effect only on 2-in-1 devices.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------- |
| name | string | Yes | Name of the subwindow.|
| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the subwindow. |
**Return value**
| Type | Description |
| -------------------------------- | ------------------------------------------------ |
| Promise<[Window](#window)> | Promise used to used to return the subwindow created.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let options : window.SubWindowOptions = {
title: 'title',
decorEnabled: true,
isModal: true
};
let promise = windowClass.createSubWindowWithOptions('mySubWindow', options);
promise.then((data) => {
console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
}
```
### setWindowTitleButtonVisible14+
setWindowTitleButtonVisible(isMaximizeButtonVisible: boolean, isMinimizeButtonVisible: boolean, isCloseButtonVisible?: boolean): void
Shows or hides the maximize, minimize, and close buttons on the title bar of the main window.
This API can be used only on 2-in-1 devices.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| isMaximizeButtonVisible | boolean | Yes | Whether to show the maximize button. The value **true** means to show the button, and **false** means to hide it. If the maximize button is hidden, the corresponding restore button is also hidden in the maximize scenario.|
| isMinimizeButtonVisible | boolean | Yes | Whether to show the minimize button. The value **true** means to show the button, and **false** means to hide it.|
| isCloseButtonVisible | boolean | No | Whether to show the close button. The value **true** means to show the button, and **false** means to hide it.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage): void {
// Load the page corresponding to the main window.
windowStage.loadContent('pages/Index', (err) => {
let mainWindow: window.Window | undefined = undefined;
// Obtain the main window.
windowStage.getMainWindow().then(
data => {
mainWindow = data;
console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
// Call setWindowTitleButtonVisible to hide the maximize, minimize, and close buttons on the title bar of the main window.
mainWindow.setWindowTitleButtonVisible(false, false, false);
}
).catch((err: BusinessError) => {
if(err.code){
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
}
});
});
}
}
```
### setWindowTopmost14+
setWindowTopmost(isWindowTopmost: boolean): Promise<void>
Places the main window above all the other windows of the application. This API uses a promise to return the result.
Applications use custom shortcut keys to pin or unpin the main window.
This API can be used only on 2-in-1 devices.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Required permissions**: ohos.permission.WINDOW_TOPMOST
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| isWindowTopmost | boolean | Yes | Whether to pin the main window on top. The value **true** means to pin the main window on top, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 201 | Permission verification failed. The application does not have the permission required to call the API. |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// ets/pages/Index.ets
import { window } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
const context = (getContext(this) as common.UIAbilityContext);
let windowClass: window.Window | undefined;
let keyUpEventAry: string[] = [];
@Entry
@Component
struct Index {
build() {
RelativeContainer() {
Button("Pin")
.onClick(() => {
try {
let promiseCtx = window.getLastWindow(context);
promiseCtx.then((data) => {
windowClass = data;
// The value true means to pin the window on top, and false means to unpin the window.
let isWindowTopmost: boolean = true;
let promiseTopmost = windowClass.setWindowTopmost(isWindowTopmost);
promiseTopmost.then(() => {
console.info('Succeeded in setting the main window to be topmost.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the main window to be topmost. Cause code: ${err.code}, message: ${err.message}`);
});
})
} catch (exception) {
console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`)
}
})
}
.height('100%')
.width('100%')
.onKeyEvent((event) => {
if(event) {
if(event.type === KeyType.Down) {
keyUpEventAry = [];
}
if(event.type === KeyType.Up) {
keyUpEventAry.push(event.keyText);
// Press Ctrl+T to pin or unpin the main window.
if(windowClass && keyUpEventAry.includes('KEYCODE_CTRL_LEFT') && keyUpEventAry.includes('KEYCODE_T')) {
let isWindowTopmost: boolean = false;
windowClass.setWindowTopmost(isWindowTopmost);
}
}
}
})
}
}
```
### raiseToAppTop14+
raiseToAppTop(): Promise<void>
Called by a subwindow to elevate the subwindow to the topmost layer. Its effect is limited to subwindows of the same type that share the same parent window of the current application. This API uses a promise to return the result.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
| 1300009 | The parent window is invalid. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.raiseToAppTop();
promise.then(() => {
console.info('Succeeded in raising the window to app top.');
}).catch((err: BusinessError) => {
console.error(`Failed to raise the window to app top. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setRaiseByClickEnabled14+
setRaiseByClickEnabled(enable: boolean): Promise<void>
Sets whether to enable a subwindow to raise itself by click. This API uses a promise to return the result.
Generally, when a subwindow is clicked, it is brought to the forefront among sibling subwindows of the same type that share the same parent window within the application. If the **enable** parameter is set to **false**, when the subwindow is clicked, it still stays in its existing position.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| enable | boolean | Yes | Whether a subwindow can be raised by clicking. The value **true** means that the subwindow can be raised by clicking, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
| 1300009 | The parent window is invalid. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
// Create a subwindow.
try {
let subWindow = windowStage.createSubWindow("testSubWindow");
subWindow.then((data) => {
if (data == null) {
console.error("Failed to create the subWindow. Cause: The data is empty");
return;
}
windowClass = data;
let enabled = false;
let promise = windowClass.setRaiseByClickEnabled(enabled);
promise.then(()=> {
console.info('Succeeded in disabling the raise-by-click function.');
}).catch((err: BusinessError)=>{
console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`);
});
});
} catch (exception) {
console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### enableLandscapeMultiWindow12+
enableLandscapeMultiWindow(): Promise<void>
Enables the landscape multi-window mode for the UI page that supports the horizontal layout. You are not advised to call this API for the UI page that adopts the vertical layout.
This API takes effect only for the main window of the application. In addition, **preferMultiWindowOrientation** must be set to **landscape_auto** in the [abilities](../../quick-start/module-configuration-file.md#abilities) tag in the **module.json5** file.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let promise = windowClass.enableLandscapeMultiWindow();
promise.then(() => {
console.info('Succeeded in making multi-window become landscape.');
}).catch((err: BusinessError) => {
console.error(`Failed to make multi-window become landscape. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
}
```
### disableLandscapeMultiWindow12+
disableLandscapeMultiWindow(): Promise<void>
Disables the landscape multi-window mode for the UI page that supports the horizontal layout.
This API takes effect only for the main window of the application. In addition, **preferMultiWindowOrientation** must be set to **landscape_auto** in the [abilities](../../quick-start/module-configuration-file.md#abilities) tag in the **module.json5** file.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let promise = windowClass.disableLandscapeMultiWindow();
promise.then(() => {
console.info('Succeeded in making multi-window become not landscape.');
}).catch((err: BusinessError) => {
console.error(`Failed to make multi-window become not landscape. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
}
```
### setDialogBackGestureEnabled12+
setDialogBackGestureEnabled(enabled: boolean): Promise<void>
Sets whether the modal window responds to the back gesture event. An error code is returned if this API is called for a non-modal window.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------- | ---- | ------------------------------------------------------------ |
| enabled | boolean | Yes | Whether to respond to the back gesture event.
The value **true** means to respond to the back gesture event and trigger the **onBackPress** callback, and **false** means the opposite.
|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | -------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
let config: window.Configuration = {
name: "test",
windowType: window.WindowType.TYPE_DIALOG,
ctx: this.context
};
try {
window.createWindow(config, (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
windowClass.setUIContent("pages/Index");
let enabled = true;
let promise = windowClass.setDialogBackGestureEnabled(enabled);
promise.then(() => {
console.info('Succeeded in setting dialog window to respond back gesture.');
}).catch((err: BusinessError) => {
console.error(`Failed to set dialog window to respond back gesture. Cause code: ${err.code}, message: ${err.message}`);
});
});
} catch (exception) {
console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
```ts
// ets/pages/Index.ets
@Entry
@Component
struct Index {
@State message: string = 'Hello World'
build() {
RelativeContainer() {
Text(this.message)
.id('HelloWorld')
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.height('100%')
.width('100%')
}
onBackPress(): boolean | void {
console.info('Succeeded in setting dialog window to respond back gesture.');
return true;
}
}
```
### startMoving14+
startMoving(): Promise<void>
Starts moving this window. This API uses a promise to return the result.
The window moves along with the cursor only when this API is called in the callback function of [onTouch](./arkui-ts/ts-universal-events-touch.md#touchevent), where the event type is **TouchType.Down**.
This API takes effect only for the main window, subwindow, and system window on 2-in-1 devices. If it is called for other device types or window types, an error is reported.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 14.
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| -------- | -------------------------------------------- |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300001 | Repeated operation. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// ets/pages/Index.ets
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
build() {
Row() {
Column() {
Blank('160')
.color(Color.Blue)
.onTouch((event: TouchEvent) => {
if (event.type === TouchType.Down) {
try {
windowClass.startMoving().then(() => {
console.info('Succeeded in starting moving window.')
}).catch((err: BusinessError) => {
console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
})
}.width('100%')
}.height('100%').width('100%')
}
}
```
### setGestureBackEnabled13+
setGestureBackEnabled(enabled: boolean): Promise<void>
Sets whether to enable the back gesture feature in this window. This API takes effect only in full-screen mode of the main window and cannot be used on 2-in-1 devices.
When the back gesture feature is disabled, the application does not recognize the gesture hot zone for back redirection, causing the side-swipe gesture non-functional. However, after you switch to another application or return to the home screen, the gesture hot zone functions normally and the side-swipe gesture works properly.
When the back gesture feature is enabled, the application recognizes the gesture hot zone for back redirection, allowing the side-swipe gesture to function as expected.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 13.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | --------- | -------- | --------------------------------------------- |
| enabled | boolean | Yes | Whether to enable the back gesture feature. The value **true** means to enable the feature, and **false** means to disable it.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
// Disable the back gesture feature in the current window.
try {
let gestureBackEnabled: boolean = false;
let promise = windowClass.setGestureBackEnabled(gestureBackEnabled);
promise.then(() => {
console.info(`Succeeded in setting gesture back disabled`);
}).catch((err: BusinessError) => {
console.error(`Failed to set gesture back disabled, Cause code: ${err.code}, message: ${err.message}`);
});
} catch(exception) {
console.error(`Failed to set gesture back disabled, Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### isGestureBackEnabled13+
isGestureBackEnabled(): boolean
Checks whether the back gesture feature is enabled in this window. This API takes effect only in full-screen mode of the main window and cannot be used on 2-in-1 devices.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 13.
**Return value**
| Type | Description |
| ------------------- | --------------------------------------------- |
| boolean | Whether the back gesture feature is enabled. The value **true** means that the back gesture feature is enabled, and **false** means that it is disabled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
| 1300004 | Unauthorized operation. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
// Check whether the back gesture feature is enabled in the current window.
try {
let gestureBackEnabled: boolean = windowClass.isGestureBackEnabled();
console.info(`Succeeded in obtaining gesture back enabled status: ${gestureBackEnabled}`);
} catch (exception) {
console.error(`Failed to get gesture back enabled status. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setWindowSystemBarProperties(deprecated)
setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void
Sets the properties of the three-button navigation bar and status bar of the main window. This API uses an asynchronous callback to return the result. This API does not take effect on 2-in-1 devices.
This API does not take effect when it is called by a subwindow.
> **NOTE**
>
> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [setWindowSystemBarProperties](#setwindowsystembarproperties9) in promise mode instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------- | ------------------------------------------- | ---- | ---------------------- |
| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let SystemBarProperties: window.SystemBarProperties = {
statusBarColor: '#ff00ff',
navigationBarColor: '#00ff00',
// The following properties are supported since API version 8.
statusBarContentColor: '#ffffff',
navigationBarContentColor: '#00ffff'
};
try {
windowClass.setWindowSystemBarProperties(SystemBarProperties, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the system bar properties.');
});
} catch (exception) {
console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setWindowSystemBarEnable(deprecated)
setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void
Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses an asynchronous callback to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, this API does not take effect on 2-in-1 devices.
The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow.
> **NOTE**
>
> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [setWindowSystemBarEnable](#setwindowsystembarenable9) in promise mode instead.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| names | Array<'status'\|'navigation'> | Yes | Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.
For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed.
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let names: Array<'status' | 'navigation'> = [];
try {
windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the system bar to be invisible.');
});
} catch (exception) {
console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### setWindowLayoutFullScreen(deprecated)
setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void
Sets whether the main window layout or the subwindow layout is immersive. This API uses an asynchronous callback to return the result.
- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them.
- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them.
> **NOTE**
>
> This API is supported since API version 9 and deprecated since API version 12. You are advised to use [setWindowLayoutFullScreen](#setwindowlayoutfullscreen9) in promise mode instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 12.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------ | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window layout is immersive, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let isLayoutFullScreen = true;
try {
windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window layout to full-screen mode.');
});
} catch (exception) {
console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`);
}
});
}
}
```
### show(deprecated)
show(callback: AsyncCallback<void>): void
Shows this window. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.show((err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in showing the window.');
});
```
### show(deprecated)
show(): Promise<void>
Shows this window. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.show();
promise.then(() => {
console.info('Succeeded in showing the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### destroy(deprecated)
destroy(callback: AsyncCallback<void>): void
Destroys this window. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback<void> | Yes | Callback used to return the result.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.destroy((err: BusinessError) => {
const errCode: number = err.code;
if (err.code) {
console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in destroying the window.');
});
```
### destroy(deprecated)
destroy(): Promise<void>
Destroys this window. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.destroy();
promise.then(() => {
console.info('Succeeded in destroying the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### moveTo(deprecated)
moveTo(x: number, y: number, callback: AsyncCallback<void>): void
Moves this window. This API uses an asynchronous callback to return the result.
This operation is not supported in a window in full-screen mode.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------------------- |
| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.moveTo(300, 300, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in moving the window.');
});
```
### moveTo(deprecated)
moveTo(x: number, y: number): Promise<void>
Moves this window. This API uses a promise to return the result.
This operation is not supported in a window in full-screen mode.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------- |
| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.moveTo(300, 300);
promise.then(() => {
console.info('Succeeded in moving the window.');
}).catch((err: BusinessError) => {
console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`);
});
```
### resetSize(deprecated)
resetSize(width: number, height: number, callback: AsyncCallback<void>): void
Changes the size of this window. This API uses an asynchronous callback to return the result.
The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp.
The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits.
The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp.
The window width and height you set must meet the limits. The rules are as follows:
- If the window width or height you set is less than the minimum width or height limit, then the minimum width or height limit takes effect.
- If the window width or height you set is greater than the maximum width or height limit, then the maximum width or height limit takes effect.
This operation is not supported in a window in full-screen mode.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------------- |
| width | number | Yes | New width of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
| height | number | Yes | New height of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.resetSize(500, 1000, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in changing the window size.');
});
```
### resetSize(deprecated)
resetSize(width: number, height: number): Promise<void>
Changes the size of this window. This API uses a promise to return the result.
The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp.
The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits.
The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp.
The window width and height you set must meet the limits. The rules are as follows:
- If the window width or height you set is less than the minimum width or height limit, then the minimum width or height limit takes effect.
- If the window width or height you set is greater than the maximum width or height limit, then the maximum width or height limit takes effect.
This operation is not supported in a window in full-screen mode.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------- |
| width | number | Yes | New width of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
| height | number | Yes | New height of the window, in px. The value must be an integer. If a floating point number is passed in, the value is rounded down. A negative value is invalid.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.resetSize(500, 1000);
promise.then(() => {
console.info('Succeeded in changing the window size.');
}).catch((err: BusinessError) => {
console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`);
});
```
### getProperties(deprecated)
getProperties(callback: AsyncCallback<WindowProperties>): void
Obtains the properties of this window. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------------------------- | ---- | ---------------------------- |
| callback | AsyncCallback<[WindowProperties](#windowproperties)> | Yes | Callback used to return the window properties.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.getProperties((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data));
});
```
### getProperties(deprecated)
getProperties(): Promise<WindowProperties>
Obtains the properties of this window. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ---------------------------------------------------- | ------------------------------- |
| Promise<[WindowProperties](#windowproperties)> | Promise used to return the window properties.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.getProperties();
promise.then((data) => {
console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`);
});
```
### getAvoidArea(deprecated)
getAvoidArea(type: [AvoidAreaType](#avoidareatype7), callback: AsyncCallback<[AvoidArea](#avoidarea7)>): void
Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |-----------------------------------------------| ---- | ------------------------------------------------------------ |
| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area.|
| callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let type = window.AvoidAreaType.TYPE_SYSTEM;
windowClass.getAvoidArea(type, (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data));
});
```
### getAvoidArea(deprecated)
getAvoidArea(type: [AvoidAreaType](#avoidareatype7)): Promise<[AvoidArea](#avoidarea7)>
Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ |----------------------------------| ---- | ------------------------------------------------------------ |
| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area.|
**Return value**
| Type | Description |
|-----------------------------------------| ----------------------------------- |
| Promise<[AvoidArea](#avoidarea7)> | Promise used to return the area.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let type = window.AvoidAreaType.TYPE_SYSTEM;
let promise = windowClass.getAvoidArea(type);
promise.then((data) => {
console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setFullScreen(deprecated)
setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void
Sets whether the main window or the subwindow is in full-screen mode. This API uses an asynchronous callback to return the result.
- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them.
- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) and [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9) to implement the full-screen mode.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------------------------- | ---- | ---------------------------------------------- |
| isFullScreen | boolean | Yes | Whether to set full-screen mode. This setting affects the display of the status bar and navigation bar. The value **true** means to set full-screen mode, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let isFullScreen: boolean = true;
windowClass.setFullScreen(isFullScreen, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in enabling the full-screen mode.');
});
});
}
}
```
### setFullScreen(deprecated)
setFullScreen(isFullScreen: boolean): Promise<void>
Sets whether the main window or the subwindow is in full-screen mode. This API uses a promise to return the result.
- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them.
- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9-1) and [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9-1) to implement the full-screen mode.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | ------- | ---- | ---------------------------------------------- |
| isFullScreen | boolean | Yes | Whether to set full-screen mode. This setting affects the display of the status bar and navigation bar. The value **true** means to set full-screen mode, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let isFullScreen: boolean = true;
let promise = windowClass.setFullScreen(isFullScreen);
promise.then(() => {
console.info('Succeeded in enabling the full-screen mode.');
}).catch((err: BusinessError) => {
console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
}
```
### setLayoutFullScreen(deprecated)
setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void
Sets whether the main window layout or the subwindow layout is immersive. This API uses an asynchronous callback to return the result.
- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them.
- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------ | ------------------------- | ---- | ------------------------------------------------------------ |
| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. This setting does not affect the display of the status bar and navigation bar. The value **true** means that the window layout is immersive, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let isLayoutFullScreen: boolean = true;
windowClass.setLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window layout to full-screen mode.');
});
});
}
}
```
### setLayoutFullScreen(deprecated)
setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>
Sets whether the main window layout or the subwindow layout is immersive. This API uses a promise to return the result.
- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them.
- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------ |
| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. This setting does not affect the display of the status bar and navigation bar. The value **true** means that the window layout is immersive, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let isLayoutFullScreen: boolean = true;
let promise = windowClass.setLayoutFullScreen(isLayoutFullScreen);
promise.then(() => {
console.info('Succeeded in setting the window layout to full-screen mode.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
}
```
### setSystemBarEnable(deprecated)
setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void
Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses an asynchronous callback to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, this API does not take effect on 2-in-1 devices.
The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| names | Array<'status'\|'navigation'> | Yes | Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.
For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed.
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let names: Array<'status' | 'navigation'> = [];
windowClass.setSystemBarEnable(names, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the system bar to be invisible.');
});
});
}
}
```
### setSystemBarEnable(deprecated)
setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void>
Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses a promise to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, this API does not take effect on 2-in-1 devices.
The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------------------- | ---- | ------------------------ |
| names | Array<'status'\|'navigation'> | Yes | Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.
For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed.
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let names: Array<'status' | 'navigation'> = [];
let promise = windowClass.setSystemBarEnable(names);
promise.then(() => {
console.info('Succeeded in setting the system bar to be invisible.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
}
```
### setSystemBarProperties(deprecated)
setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void
Sets the properties of the three-button navigation bar and status bar of the main window. This API uses an asynchronous callback to return the result. This API does not take effect on 2-in-1 devices.
This API does not take effect when it is called by a subwindow.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------- | ------------------------------------------- | ---- | ---------------------- |
| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let SystemBarProperties: window.SystemBarProperties = {
statusBarColor: '#ff00ff',
navigationBarColor: '#00ff00',
// The following properties are supported since API version 8.
statusBarContentColor: '#ffffff',
navigationBarContentColor: '#00ffff'
};
windowClass.setSystemBarProperties(SystemBarProperties, (err) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the system bar properties.');
});
});
}
}
```
### setSystemBarProperties(deprecated)
setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void>
Sets the properties of the three-button navigation bar and status bar of the main window. This API uses a promise to return the result. This API does not take effect on 2-in-1 devices.
This API does not take effect when it is called by a subwindow.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------------- | ------------------------------------------- | ---- | ---------------------- |
| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
let SystemBarProperties: window.SystemBarProperties = {
statusBarColor: '#ff00ff',
navigationBarColor: '#00ff00',
// The following properties are supported since API version 8.
statusBarContentColor: '#ffffff',
navigationBarContentColor: '#00ffff'
};
let promise = windowClass.setSystemBarProperties(SystemBarProperties);
promise.then(() => {
console.info('Succeeded in setting the system bar properties.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`);
});
});
}
}
```
### loadContent(deprecated)
loadContent(path: string, callback: AsyncCallback<void>): void
Loads content from a page to this window. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------- |
| path | string | Yes | Path of the page from which the content will be loaded. In the stage model, the path is configured in the **main_pages.json** file of the project. In the FA model, the path is configured in the **config.json** file of the project.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.loadContent('pages/page2/page3', (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
```
### loadContent(deprecated)
loadContent(path: string): Promise<void>
Loads content from a page to this window. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------- |
| path | string | Yes | Path of the page from which the content will be loaded. In the stage model, the path is configured in the **main_pages.json** file of the project. In the FA model, the path is configured in the **config.json** file of the project.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.loadContent('pages/page2/page3');
promise.then(() => {
console.info('Succeeded in loading the content.');
}).catch((err: BusinessError) => {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
});
```
### isShowing(deprecated)
isShowing(callback: AsyncCallback<boolean>): void
Checks whether this window is displayed. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the window is displayed, and **false** means the opposite.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.isShowing((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data));
});
```
### isShowing(deprecated)
isShowing(): Promise<boolean>
Checks whether this window is displayed. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| Promise<boolean> | Promise used to return the result. The value **true** means that the window is displayed, and **false** means the opposite.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.isShowing();
promise.then((data) => {
console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`);
});
```
### on('systemAvoidAreaChange')(deprecated)
on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void
Subscribes to the event indicating changes to the area where this window cannot be displayed.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. Use [on('avoidAreaChange')](#onavoidareachange9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'systemAvoidAreaChange'**, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. |
**Example**
```ts
windowClass.on('systemAvoidAreaChange', (data) => {
console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data));
});
```
### off('systemAvoidAreaChange')(deprecated)
off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void
Unsubscribes from the event indicating changes to the area where this window cannot be displayed.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. Use [off('avoidAreaChange')](#offavoidareachange9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
| type | string | Yes | Event type. The value is fixed at **'systemAvoidAreaChange'**, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidArea](#avoidarea7)> | No | Callback used to return the area. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Example**
```ts
const callback = (avoidArea: window.AvoidArea) => {
// ...
}
windowClass.on('systemAvoidAreaChange', callback);
windowClass.off('systemAvoidAreaChange', callback);
// Unregister all the callbacks that have been registered through on().
windowClass.off('systemAvoidAreaChange');
```
### isSupportWideGamut(deprecated)
isSupportWideGamut(callback: AsyncCallback<boolean>): void
Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the wide-gamut color space is supported, and **false** means the opposite.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.isSupportWideGamut((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data));
});
```
### isSupportWideGamut(deprecated)
isSupportWideGamut(): Promise<boolean>
Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| Promise<boolean> | Promise used to return the result. The value **true** means that the wide-gamut color space is supported, and **false** means the opposite.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.isSupportWideGamut();
promise.then((data) => {
console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setColorSpace(deprecated)
setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void
Sets a color space for this window. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------- | ---- | ------------ |
| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting window colorspace.');
});
```
### setColorSpace(deprecated)
setColorSpace(colorSpace:ColorSpace): Promise<void>
Sets a color space for this window. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------- | ---- | -------------- |
| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT);
promise.then(() => {
console.info('Succeeded in setting window colorspace.');
}).catch((err: BusinessError) => {
console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
});
```
### getColorSpace(deprecated)
getColorSpace(callback: AsyncCallback<ColorSpace>): void
Obtains the color space of this window. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------------- | ---- | ---------------------------------------------------------- |
| callback | AsyncCallback<[ColorSpace](#colorspace8)> | Yes | Callback used to return the result. When the color space is obtained successfully, **err** is **undefined**, and **data** is the current color space.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.getColorSpace((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data));
});
```
### getColorSpace(deprecated)
getColorSpace(): Promise<ColorSpace>
Obtains the color space of this window. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Return value**
| Type | Description |
| ---------------------------------------- | ------------------------------- |
| Promise<[ColorSpace](#colorspace8)> | Promise used to return the current color space.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.getColorSpace();
promise.then((data) => {
console.info('Succeeded in getting window color space. Cause:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setBackgroundColor(deprecated)
setBackgroundColor(color: string, callback: AsyncCallback<void>): void
Sets the background color for this window. This API uses an asynchronous callback to return the result. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| color | string | Yes | Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let color: string = '#00ff33';
windowClass.setBackgroundColor(color, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the background color.');
});
```
### setBackgroundColor(deprecated)
setBackgroundColor(color: string): Promise<void>
Sets the background color for this window. This API uses a promise to return the result. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| color | string | Yes | Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let color: string = '#00ff33';
let promise = windowClass.setBackgroundColor(color);
promise.then(() => {
console.info('Succeeded in setting the background color.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setBrightness(deprecated)
setBrightness(brightness: number, callback: AsyncCallback<void>): void
Sets the screen brightness for this window. This API uses an asynchronous callback to return the result.
When the screen brightness setting for the window takes effect, Control Panel cannot adjust the system screen brightness. It can do so only after the window screen brightness is restored to the default value.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------- | ---- |---------------------------------------|
| brightness | number | Yes | Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let brightness: number = 1;
windowClass.setBrightness(brightness, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the brightness.');
});
```
### setBrightness(deprecated)
setBrightness(brightness: number): Promise<void>
Sets the screen brightness for this window. This API uses a promise to return the result.
When the screen brightness setting for the window takes effect, Control Panel cannot adjust the system screen brightness. It can do so only after the window screen brightness is restored to the default value.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- |------------------------------------------|
| brightness | number | Yes | Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let brightness: number = 1;
let promise = windowClass.setBrightness(brightness);
promise.then(() => {
console.info('Succeeded in setting the brightness.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setDimBehind(deprecated)
setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void
Sets the dimness of the window that is not on top. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ------------------------- | ---- |----------------------------------------|
| dimBehindValue | number | Yes | Dimness of the window to set. The value range is [0.0, 1.0], and the value **1.0** means the dimmest.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.setDimBehind(0.5, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the dimness.');
});
```
### setDimBehind(deprecated)
setDimBehind(dimBehindValue: number): Promise<void>
Sets the dimness of the window that is not on top. This API uses a promise to return the result.
> **NOTE**
>
> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ------ | ---- | -------------------------------------------------- |
| dimBehindValue | number | Yes | Dimness of the window to set. The value ranges from 0 to 1. The value **1** indicates the dimmest.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.setDimBehind(0.5);
promise.then(() => {
console.info('Succeeded in setting the dimness.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setFocusable(deprecated)
setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void
Sets whether this window is focusable, that is, whether the window can gain focus after it is being operated or using other methods. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ------------------------- | ---- | ---------------------------- |
| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isFocusable: boolean = true;
windowClass.setFocusable(isFocusable, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window to be focusable.');
});
```
### setFocusable(deprecated)
setFocusable(isFocusable: boolean): Promise<void>
Sets whether this window is focusable, that is, whether the window can gain focus after it is being clicked or using other methods. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ------- | ---- | ---------------------------- |
| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isFocusable: boolean = true;
let promise = windowClass.setFocusable(isFocusable);
promise.then(() => {
console.info('Succeeded in setting the window to be focusable.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setKeepScreenOn(deprecated)
setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void
Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ------------------------- | ---- | ------------------------ |
| isKeepScreenOn | boolean | Yes | Whether to keep the screen always on. The value **true** means to keep the screen always on, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isKeepScreenOn: boolean = true;
windowClass.setKeepScreenOn(isKeepScreenOn, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the screen to be always on.');
});
```
### setKeepScreenOn(deprecated)
setKeepScreenOn(isKeepScreenOn: boolean): Promise<void>
Sets whether to keep the screen always on. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------------- | ------- | ---- | ------------------------ |
| isKeepScreenOn | boolean | Yes | Whether to keep the screen always on. The value **true** means to keep the screen always on, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isKeepScreenOn: boolean = true;
let promise = windowClass.setKeepScreenOn(isKeepScreenOn);
promise.then(() => {
console.info('Succeeded in setting the screen to be always on.');
}).catch((err: BusinessError) => {
console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setOutsideTouchable(deprecated)
setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): void
Sets whether the area outside the subwindow is touchable. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9.
>
> Since API version 9, the area outside the subwindow is touchable by default. This API is no longer supported and no substitute API is provided.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | ---------------- |
| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means the area outside the subwindow is touchable, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
windowClass.setOutsideTouchable(true, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the area to be touchable.');
});
```
### setOutsideTouchable(deprecated)
setOutsideTouchable(touchable: boolean): Promise<void>
Sets whether the area outside the subwindow is touchable. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9.
>
> Since API version 9, the area outside the subwindow is touchable by default. This API is no longer supported and no substitute API is provided.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | ---------------- |
| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means the area outside the subwindow is touchable, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let promise = windowClass.setOutsideTouchable(true);
promise.then(() => {
console.info('Succeeded in setting the area to be touchable.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setPrivacyMode(deprecated)
setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void
Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result.
A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------- | ------------------------- | ---- | -------------------- |
| isPrivacyMode | boolean | Yes | Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isPrivacyMode: boolean = true;
windowClass.setPrivacyMode(isPrivacyMode, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window to privacy mode.');
});
```
### setPrivacyMode(deprecated)
setPrivacyMode(isPrivacyMode: boolean): Promise<void>
Sets whether this window is in privacy mode. This API uses a promise to return the result.
A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------- | ------- | ---- | -------------------- |
| isPrivacyMode | boolean | Yes | Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isPrivacyMode: boolean = true;
let promise = windowClass.setPrivacyMode(isPrivacyMode);
promise.then(() => {
console.info('Succeeded in setting the window to privacy mode.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`);
});
```
### setTouchable(deprecated)
setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void
Sets whether this window is touchable. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ------------------------- | ---- | -------------------- |
| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isTouchable = true;
windowClass.setTouchable(isTouchable, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in setting the window to be touchable.');
});
```
### setTouchable(deprecated)
setTouchable(isTouchable: boolean): Promise<void>
Sets whether this window is touchable. This API uses a promise to return the result.
> **NOTE**
>
> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9-1) instead.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ------- | ---- | -------------------- |
| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let isTouchable = true;
let promise = windowClass.setTouchable(isTouchable);
promise.then(() => {
console.info('Succeeded in setting the window to be touchable.');
}).catch((err: BusinessError) => {
console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`);
});
```
## WindowStageEventType9+
Describes the lifecycle of a window stage.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
| Name | Value| Description |
| ---------- | ------ | ---------- |
| SHOWN | 1 | The window stage is shown in the foreground, for example, when launching from the application icon, triggered whether it is the first launch or resuming from the background.|
| ACTIVE | 2 | The window stage gains focus, for example, the state of the application window after handling a click event, or the state after the application is launched.|
| INACTIVE | 3 | The window stage loses focus, for example, the state of the window that was in focus when a new application is opened or another window is clicked.|
| HIDDEN | 4 | The window stage is running in the background, for example, when the application exists after swiping up or the application window is closed.|
| RESUMED11+ | 5 | The window stage is interactive in the foreground, for example, when an application is opened and can interact with the user.|
| PAUSED11+ | 6 | The window stage is non-interactive in the foreground, for example, when the application enters the recent tasks screen after swiping up from the bottom of the screen.|
## ModalityType14+
Enumerates the modality types of the subwindow.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 14.
| Name | Value | Description |
| -------------------- | ------ | ---------- |
| WINDOW_MODALITY | 0 | Window-modal. Select this value when you want the parent window not to respond to user interactions.|
| APPLICATION_MODALITY | 1 | Application-modal. Select this value when you want both the parent window and all windows of other instances of the application not to respond to user interactions.
This API can be used only on 2-in-1 devices.|
## SubWindowOptions11+
Describes the parameters used for creating a subwindow.
**System capability**: SystemCapability.Window.SessionManager
| Name | Type | Read-Only| Optional| Description |
| ---------- | ---- | ---- | ---- | ----------- |
| title11+ | string | No| No| Title of the subwindow.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| decorEnabled11+ | boolean | No| No| Whether decorations are displayed in the subwindow. The value **true** means decorations are displayed, and **false** means the opposite.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| isModal12+ | boolean | No| Yes| Whether the modal property is enabled for the subwindow. The value** true** means that the modal property is enabled for the subwindow, and **false** means to disable it. The default value is **false**.
**Atomic service API**: This API can be used in atomic services since API version 12. |
| modalityType14+ | [ModalityType](#modalitytype14) | No| Yes| Modality type of the subwindow. This parameter takes effect only when the modal property is enabled for the subwindow. **WINDOW_MODALITY** means window-modal, and **APPLICATION_MODALITY** means application-modal. The default value is **WINDOW_MODALITY**.
**Atomic service API**: This API can be used in atomic services since API version 14. |
## WindowStage9+
Implements a window manager, which manages each basic window unit, that is, [Window](#window) instance.
Before calling any of the following APIs, you must use [onWindowStageCreate()](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) to create a **WindowStage** instance.
### getMainWindow9+
getMainWindow(callback: AsyncCallback<Window>): void
Obtains the main window of this window stage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | --------------------------------------------- |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
windowStage.getMainWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
});
}
};
```
### getMainWindow9+
getMainWindow(): Promise<Window>
Obtains the main window of this window stage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type | Description |
| -------------------------------- | ------------------------------------------------ |
| Promise<[Window](#window)> | Promise used to return the main window.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
let promise = windowStage.getMainWindow();
promise.then((data) => {
windowClass = data;
console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
});
}
};
```
### getMainWindowSync9+
getMainWindowSync(): Window
Obtains the main window of this window stage.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type| Description|
| ----------------- | --------------------------------- |
| [Window](#window) | Main window.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
try {
let windowClass = windowStage.getMainWindowSync();
} catch (exception) {
console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### createSubWindow9+
createSubWindow(name: string, callback: AsyncCallback<Window>): void
Creates a subwindow for this window stage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------- | ---- | --------------------------------------------- |
| name | string | Yes | Name of the subwindow. |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
try {
windowStage.createSubWindow('mySubWindow', (err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
if (!windowClass) {
console.info('Failed to load the content. Cause: windowClass is null');
}
else {
(windowClass as window.Window).resize(500, 1000);
}
});
} catch (exception) {
console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### createSubWindow9+
createSubWindow(name: string): Promise<Window>
Creates a subwindow for this window stage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------- |
| name | string | Yes | Name of the subwindow.|
**Return value**
| Type | Description |
| -------------------------------- | ------------------------------------------------ |
| Promise<[Window](#window)> | Promise used to return the subwindow.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
try {
let promise = windowStage.createSubWindow('mySubWindow');
promise.then((data) => {
windowClass = data;
console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### createSubWindowWithOptions11+
createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window>
Creates a subwindow for this window stage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------- |
| name | string | Yes | Name of the subwindow.|
| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the subwindow. |
**Return value**
| Type | Description |
| -------------------------------- | ------------------------------------------------ |
| Promise<[Window](#window)> | Promise used to return the subwindow created.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
let windowClass: window.Window | undefined = undefined;
try {
let options : window.SubWindowOptions = {
title: 'title',
decorEnabled: true
};
let promise = windowStage.createSubWindowWithOptions('mySubWindow', options);
promise.then((data) => {
windowClass = data;
console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### getSubWindow9+
getSubWindow(callback: AsyncCallback<Array<Window>>): void
Obtains all the subwindows of this window stage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------------- |
| callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the subwindows.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
let windowClass: window.Window[] = [];
windowStage.getSubWindow((err: BusinessError, data) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`);
return;
}
windowClass = data;
console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data));
});
}
};
```
### getSubWindow9+
getSubWindow(): Promise<Array<Window>>
Obtains all the subwindows of this window stage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Return value**
| Type | Description |
| --------------------------------------------- | ---------------------------------------------------- |
| Promise<Array<[Window](#window)>> | Promise used to return all the subwindows.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
let windowClass: window.Window[] = [];
let promise = windowStage.getSubWindow();
promise.then((data) => {
windowClass = data;
console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`);
});
}
};
```
### loadContent9+
loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void
Loads the content of a page, with its path in the current project specified, to the main window of this window stage, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the page from which the content will be loaded. The path is configured in the **main_pages.json** file of the project. |
| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
storage: LocalStorage = new LocalStorage();
onWindowStageCreate(windowStage: window.WindowStage) {
this.storage.setOrCreate('storageSimpleProp', 121);
console.log('onWindowStageCreate');
try {
windowStage.loadContent('pages/page2', this.storage, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### loadContent9+
loadContent(path: string, storage?: LocalStorage): Promise<void>
Loads the content of a page, with its path in the current project specified, to the main window of this window stage, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| path | string | Yes | Path of the page from which the content will be loaded. The path is configured in the **main_pages.json** file of the project.|
| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
storage: LocalStorage = new LocalStorage();
onWindowStageCreate(windowStage: window.WindowStage) {
this.storage.setOrCreate('storageSimpleProp', 121);
console.log('onWindowStageCreate');
try {
let promise = windowStage.loadContent('pages/page2', this.storage);
promise.then(() => {
console.info('Succeeded in loading the content.');
}).catch((err: BusinessError) => {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
;
}
};
```
### loadContent9+
loadContent(path: string, callback: AsyncCallback<void>): void
Loads content from a page to this window stage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------- |
| path | string | Yes | Path of the page from which the content will be loaded. The path is configured in the **main_pages.json** file of the project.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
try {
windowStage.loadContent('pages/page2', (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### loadContentByName11+
loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void
Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window stage, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| name | string | Yes | Name of the named route page. |
| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // Import the named route page.
export default class EntryAbility extends UIAbility {
// ...
storage: LocalStorage = new LocalStorage();
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
this.storage.setOrCreate('storageSimpleProp', 121);
try {
windowStage.loadContentByName(Index.entryName, this.storage, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
```ts
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
### loadContentByName11+
loadContentByName(name: string, callback: AsyncCallback<void>): void
Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window stage. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------------- |
| name | string | Yes | Name of the named route page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // Import the named route page.
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
try {
windowStage.loadContentByName(Index.entryName, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
```ts
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName})
@Component
export struct Index {
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
### loadContentByName11+
loadContentByName(name: string, storage?: LocalStorage): Promise<void>;
Loads the content a [named route](../../ui/arkts-routing.md#named-route) page to this window stage, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------ | ---- | ------------------------------------------------------------ |
| name | string | Yes | Name of the named route page. |
| storage | LocalStorage | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | --------------------------------------------- |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // Import the named route page.
export default class EntryAbility extends UIAbility {
// ...
storage: LocalStorage = new LocalStorage();
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
this.storage.setOrCreate('storageSimpleProp', 121);
try {
let promise = windowStage.loadContentByName(Index.entryName, this.storage);
promise.then(() => {
console.info('Succeeded in loading the content.');
}).catch((err: BusinessError) => {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
```ts
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
@State message: string = 'Hello World'
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
```
### on('windowStageEvent')9+
on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void
Subscribes to the window stage lifecycle change event.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event.|
| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the window stage lifecycle state. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
try {
windowStage.on('windowStageEvent', (data) => {
console.info('Succeeded in enabling the listener for window stage event changes. Data: ' +
JSON.stringify(data));
});
} catch (exception) {
console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### off('windowStageEvent')9+
off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType>): void
Unsubscribes from the window stage lifecycle change event.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.WindowManager.WindowManager.Core
**Atomic service API**: This API can be used in atomic services since API version 11.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event.|
| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | No | Callback used to return the window stage lifecycle state. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
const callback = (windowStageEventType: window.WindowStageEventType) => {
// ...
}
try {
windowStage.on('windowStageEvent', callback);
} catch (exception) {
console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
try {
windowStage.off('windowStageEvent', callback);
// Unregister all the callbacks that have been registered through on().
windowStage.off('windowStageEvent');
} catch (exception) {
console.error(`Failed to disable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### on('windowStageClose')14+
on(eventType: 'windowStageClose', callback: Callback<void>): void
Subscribes to the click event on the close button in the three-button navigation bar of the main window. This API can be used only on 2-in-1 devices. This event is triggered when the close button in the three-button navigation bar of the main window is clicked. The registered lifecycle callback function [UIAbility.onPrepareToTerminate](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonpreparetoterminate10) is not executed.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 14.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| eventType | string | Yes | Event type. The value is fixed at **'windowStageClose'**, indicating that the close button in the three-button navigation bar of the main window is clicked|
| callback | Callback<void> | Yes | Callback invoked when the close button in the upper right corner of the main window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the main window. The value **true** means not to close the main window, and **false** means to continue to close the main window.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
try {
windowStage.on('windowStageClose', () => {
console.info('Succeeded in enabling the listener for window stage close event.');
return false;
});
} catch (exception) {
console.error(`Failed to enable the listener for window stage close event. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### off('windowStageClose')14+
off(eventType: 'windowStageClose', callback?: Callback<void>): void
Unsubscribes from the click event on the close button in the three-button navigation bar of the main window. This API can be used only on 2-in-1 devices.
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.Window.SessionManager
**Atomic service API**: This API can be used in atomic services since API version 14.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| eventType | string | Yes | Event type. The value is fixed at **'windowStageClose'**, indicating that the close button in the three-button navigation bar of the main window is clicked.|
| callback | Callback<void> | No | Callback invoked when the close button in the upper right corner of the main window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the main window. The value **true** means not to close the main window, and **false** means to continue to close the main window. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
const callback = () => {
// ...
return false;
}
try {
windowStage.on('windowStageClose', callback);
windowStage.off('windowStageClose', callback);
windowStage.off('windowStageClose');
} catch (exception) {
console.error(`Failed to disable the listener for window stage close changes. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### setDefaultDensityEnabled12+
setDefaultDensityEnabled(enabled: boolean): void
Enables the system's default density.
By default, the system's default density is not used, and the window layout changes with the system display size.
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 12.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| ---------------- | ------- | ---- | ---------------------------- |
| enabled | boolean | Yes | Whether to enable the system's default density. The value **true** means to enable the system's default density, and **false** means the opposite. When the system's default density is enabled, the window layout does not change with the system display size.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300005 | This window stage is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.log('onWindowStageCreate');
try {
windowStage.setDefaultDensityEnabled(true);
} catch (exception) {
console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
};
```
### setWindowModal14+
setWindowModal(isModal: boolean): Promise<void>
Enables the modal property of the main window. This API uses a promise to return the result.
This API must be called by the main window and the setting takes effect for the main window. After the modal property of the main window is enabled, other main windows in the same application process and their subwindows do not respond to user interactions until the main window is closed or the main window's modal property is disabled.
This API can be used only on 2-in-1 devices.
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| isModal | boolean | Yes | Whether to enable the modal property of the main window. The value **true** means to enable the modal property, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
try {
let promise = windowStage.setWindowModal(true);
promise.then(() => {
console.info('Succeeded in setting window modal');
}).catch((err: BusinessError) => {
console.error(`Failed to set window modal. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set window modal. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### removeStartingWindow14+
removeStartingWindow(): Promise<void>
Allows the application to control the time when the launch page disappears.
This API takes effect only for the application main window when **enable.remove.starting.window** under **metadata** in [abilities](../../quick-start/module-configuration-file.md#abilities) in the **module.json5** file is set to **true**.
If the tag is set to **true**, the system provides timeout protection for the launch page. If this API is not called within 5 seconds, the system automatically removes the launch page.
If the tag is set to **false** or is not configured, this API does not take effect. The launch page will be automatically removed after the first frame of the application is rendered.
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
console.info('onWindowStageCreate');
windowStage.removeStartingWindow().then(() => {
console.info('Succeeded in removing starting window.');
}).catch((err: BusinessError) => {
console.error(`Failed to remove starting window. Cause code: ${err.code}, message: ${err.message}`);
});
}
};
```
### setWindowRectAutoSave14+
setWindowRectAutoSave(enabled: boolean): Promise<void>
Sets whether to enable the auto-save feature for the size of the main window. This API uses a promise to return the result. It takes effect only on 2-in-1 devices.
This API must be called by the main window and the setting takes effect for the main window. When the auto-save feature is enabled, the application will remember the size and state of the main window upon its closure under the same UIAbility.
Upon relaunch, the window will reopen in accordance with these remembered size and state.
The following rules apply in stacking scenarios:
1. If the current instance is a free-form window, the next opened window will adopt the same size when stacked.
2. If the current instance is maximized or in full-screen mode, the next opened window will maintain the maximized state when stacked.
The following table describes the memory rules:
|Last Window State|Memorizing Rule|
|-------------|-------|
|Free-form window|Retains the size/position of the free-form window, rebound if exceeding the workspace|
|Split-screen window|Retains the size and position of the free-form window before screen splitting.|
|Maximized window|Retains the maximized state.|
|Immersive window|Retains the size and position of the free-form window before immersive mode.|
|Minimized window|Retains the size and position of the free-form window before minimization.|
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | --------------------------------------------- |
| enabled | boolean | Yes | Whether to enable the auto-save feature for the main window's size. The value **true** means to enable the auto-save feature, and **false** means the opposite.|
**Return value**
| Type| Description|
| ------------------- | ------------------------ |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
| 1300003 | This window manager service works abnormally. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
try {
let promise = windowStage.setWindowRectAutoSave(true);
promise.then(() => {
console.info('Succeeded in setting window rect auto-save');
}).catch((err: BusinessError) => {
console.error(`Failed to set window rect auto-save. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to set window rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```
### isWindowRectAutoSave14+
isWindowRectAutoSave(): Promise<boolean>
Checks whether the auto-save feature is enabled for the main window's size. This API uses a promise to return the result. It takes effect only on 2-in-1 devices.
**Model restriction**: This API can be used only in the stage model.
**Atomic service API**: This API can be used in atomic services since API version 14.
**System capability**: SystemCapability.Window.SessionManager
**Return value**
| Type| Description|
| ---------------------- | ------------------------------------------------------------------------------------ |
| Promise<boolean> | Promise used to return the result. The value **true** means that the auto-save feature is enabled, and **false** means the opposite.|
**Error codes**
For details about the error codes, see [Window Error Codes](errorcode-window.md).
| ID| Error Message|
| ------- | ------------------------------ |
| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
| 1300002 | This window state is abnormal. |
**Example**
```ts
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage): void {
console.info('onWindowStageCreate');
try {
let promise = windowStage.isWindowRectAutoSave();
promise.then((data) => {
console.info('Succeeded in checking whether the window support the rect auto-save. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${err.code}, message: ${err.message}`);
});
} catch (exception) {
console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`);
}
}
}
```