The **Window** module provides basic capabilities for managing windows, including creating and destroying windows and setting serial port attributes.
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.
> **NOTE**<br/>
This module provides the following common window-related functions:
-[Window](#window): the current 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.
| statusBarColor | string | Yes | Yes | Background color of the status bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **\#00FF00** or **\#FF00FF00**.|
| statusBarColor | string | Yes | Yes | Background color of the status bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.|
| isStatusBarLightIcon<sup>7+</sup> | boolean | No | Yes | Whether any icon on the status bar is highlighted. |
| statusBarContentColor<sup>8+</sup> | string | No | Yes | Color of the text on the status bar. |
| navigationBarColor | string | Yes | Yes | Background color of the navigation bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **\#00FF00** or **\#FF00FF00**.|
| navigationBarColor | string | Yes | Yes | Background color of the navigation bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.|
| isNavigationBarLightIcon<sup>7+</sup> | boolean | No | No | Whether any icon on the navigation bar is highlighted. |
| navigationBarContentColor<sup>8+</sup> | string | No | Yes | Color of the text on the navigation bar. |
...
...
@@ -80,7 +86,7 @@ This is a system API and cannot be called by third-party applications.
| type | [WindowType](#windowtype) | Yes | Yes | Type of the system bar whose properties are changed. Only the status bar and navigation bar are supported.|
| isEnable | boolean | Yes | Yes | Whether the system bar is displayed. |
| region | [Rect](#rect) | Yes | Yes | Current position and size of the system bar. |
| backgroundColor | string | Yes | Yes | Background color of the system bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **\#00FF00** or **\#FF00FF00**.|
| backgroundColor | string | Yes | Yes | Background color of the system bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.|
| contentColor | string | Yes | Yes | Color of the text on the system bar. |
## SystemBarTintState<sup>8+</sup>
...
...
@@ -91,14 +97,14 @@ This is a system API and cannot be called by third-party applications.
| isFullScreen | boolean | Yes | Yes | Whether the window is displayed in full screen mode. The default value is **false**. |
| isLayoutFullScreen<sup>7+</sup> | boolean | Yes | Yes | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is **false**. |
| focusable<sup>7+</sup> | boolean | Yes | No | Whether the window can gain focus. The default value is **true**. |
| touchable<sup>7+</sup> | boolean | Yes | No | Whether the window is touchable. The default value is **true**. |
| brightness | number | Yes | Yes | Screen brightness. The value ranges from 0 to 1. The value **1** indicates the maximum brightness. |
| dimBehindValue<sup>(deprecated)</sup> | number | Yes | Yes | Dimness of the window that is not on top. The value ranges from 0 to 1. The value **1** indicates the maximum dimness.<br>This attribute is supported since API version 7 and deprecated since API version 9.<br> |
| isKeepScreenOn | boolean | Yes | Yes | Whether the screen is always on. The default value is **false**. |
| isPrivacyMode<sup>7+</sup> | boolean | Yes | Yes | Whether the window is in privacy mode. The default value is **false**. |
| isRoundCorner<sup>7+</sup> | boolean | Yes | Yes | Whether the window has rounded corners. The default value is **false**. |
| isTransparent<sup>7+</sup> | boolean | Yes | Yes | Whether the window is transparent. The default value is **false**. |
| isFullScreen | boolean | Yes | Yes | Whether the window is displayed in full screen mode. The default value is `false`. |
| isLayoutFullScreen<sup>7+</sup> | boolean | Yes | Yes | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is `false`. |
| focusable<sup>7+</sup> | boolean | Yes | No | Whether the window can gain focus. The default value is `true`. |
| touchable<sup>7+</sup> | boolean | Yes | No | Whether the window is touchable. The default value is `true`. |
| brightness | number | Yes | Yes | Screen brightness. The value ranges from 0 to 1. The value `1` indicates the maximum brightness. |
| dimBehindValue<sup>(deprecated)</sup> | number | Yes | Yes | Dimness of the window that is not on top. The value ranges from 0 to 1. The value `1` indicates the maximum dimness.<br>This attribute is supported since API version 7 and deprecated since API version 9.<br> |
| isKeepScreenOn | boolean | Yes | Yes | Whether the screen is always on. The default value is `false`. |
| isPrivacyMode<sup>7+</sup> | boolean | Yes | Yes | Whether the window is in privacy mode. The default value is `false`. |
| isRoundCorner<sup>7+</sup> | boolean | Yes | Yes | Whether the window has rounded corners. The default value is `false`. |
| isTransparent<sup>7+</sup> | boolean | Yes | Yes | Whether the window is transparent. The default value is `false`. |
| ctx | Context | Yes | Current application context.<br>For the definition of **Context** of API version 8, see [Context](js-apis-Context.md).<br>For the definition of **Context** of API version 9, see [ServiceExtensionContext](js-apis-service-extension-context.md). |
| ctx | Context | Yes | Current application context.<br>For the definition of `Context` of API version 8, see [Context](js-apis-Context.md).<br>For the definition of `Context` of API version 9, see [ServiceExtensionContext](js-apis-service-extension-context.md).|
| id | string | Yes | Window ID. |
| type | [WindowType](#windowtype) | Yes | Window type. |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window created. |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window created. |
| ctx | Context | Yes | Current application context.<br>For the definition of **Context** of API version 8, see [Context](js-apis-Context.md).<br>For the definition of **Context** of API version 9, see [ServiceExtensionContext](js-apis-service-extension-context.md). |
| ctx | Context | Yes | Current application context.<br>For the definition of `Context` of API version 8, see [Context](js-apis-Context.md).<br>For the definition of `Context` of API version 9, see [ServiceExtensionContext](js-apis-service-extension-context.md).|
| id | string | Yes | Window ID. |
| type | [WindowType](#windowtype) | Yes | Window type. |
| ctx | Context | Yes | Current application context.<br>For the definition of **Context** of API version 8, see [Context](js-apis-Context.md).<br>For the definition of **Context** of API version 9, see [AbilityContext](js-apis-ability-context.md). |
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. |
| ctx | Context | Yes | Current application context.<br>For the definition of `Context` of API version 8, see [Context](js-apis-Context.md).<br>For the definition of `Context` of API version 9, see [AbilityContext](js-apis-ability-context.md).|
| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. |
**Example**
```js
varwindowClass=null;
window.getTopWindow(this.context,(err,data)=>{
if(err.code){
console.error('Failed to obtain the top window. Cause: '+JSON.stringify(err));
return;
}
windowClass=data;
console.info('Succeeded in obtaining the top window. Data: '+JSON.stringify(data));
});
```
```js
varwindowClass=null;
window.getTopWindow(this.context,(err,data)=>{
if(err.code){
console.error('Failed to obtain the top window. Cause: '+JSON.stringify(err));
return;
}
windowClass=data;
console.info('Succeeded in obtaining the top window. Data: '+JSON.stringify(data));
});
```
## window.getTopWindow<sup>8+</sup>
...
...
@@ -463,26 +459,26 @@ Obtains the top window of the current application. This API uses a promise to re
| ctx | Context | Yes | Current application context.<br>For the definition of **Context** of API version 8, see [Context](js-apis-Context.md).<br>For the definition of **Context** of API version 9, see [AbilityContext](js-apis-ability-context.md). |
| ctx | Context | Yes | Current application context.<br>For the definition of `Context` of API version 8, see [Context](js-apis-Context.md).<br>For the definition of `Context` of API version 9, see [AbilityContext](js-apis-ability-context.md).|
| type | string | Yes | Type of event to listen for. The value is fixed at **systemBarTintChange**, indicating the property change event of the status bar and navigation bar.|
| callback | Callback<[SystemBarTintState](#systembartintstate)> | Yes | Callback used to return the information. |
| type | string | Yes | Type of event to listen for. The value is fixed at `systemBarTintChange`, indicating the property change event of the status bar and navigation bar.|
| callback | Callback<[SystemBarTintState](#systembartintstate)> | Yes | Callback used to return the properties of the status bar and navigation bar. |
**Example**
```js
vartype='systemBarTintChange';
windowClass.on(type,(data)=>{
console.info('Succeeded in enabling the listener for systemBarTint changes. Data: '+JSON.stringify(data));
});
```
```js
window.on('systemBarTintChange',(data)=>{
console.info('Succeeded in enabling the listener for systemBarTint changes. Data: '+JSON.stringify(data));
});
```
## off('systemBarTintChange')<sup>8+</sup>
...
...
@@ -524,19 +519,20 @@ This is a system API and cannot be called by third-party applications.
| type | string | Yes | Type of event to listen for. The value is fixed at **systemBarTintChange**, indicating the property change event of the status bar and navigation bar.|
| callback | Callback<[SystemBarTintState](#systembartintstate)> | No | Callback used to return the information. |
| type | string | Yes | Type of event to listen for. The value is fixed at `systemBarTintChange`, indicating the property change event of the status bar and navigation bar.|
| callback | Callback<[SystemBarTintState](#systembartintstate)> | No | Callback used to return the properties of the status bar and navigation bar. |
**Example**
```js
vartype='systemBarTintChange';
windowClass.off(type);
```
```js
window.off('systemBarTintChange');
```
## Window
In the following API examples, you must use [getTopWindow()](#windowgettopwindow), [create()](#windowcreate7), or [find()](#windowfind7) to obtain a **Window** instance and then call a method in this instance.
Represents the current window instance, which is the basic unit managed by the window manager.
In the following API examples, you must use [getTopWindow()](#windowgettopwindow), [create()](#windowcreate7), or [find()](#windowfind7) to obtain a `Window` instance and then call a method in this instance.
### hide<sup>7+</sup>
...
...
@@ -552,19 +548,19 @@ This is a system API and cannot be called by third-party applications.
| type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. **TYPE_SYSTEM** indicates the default area of the system. **TYPE_CUTOUT** indicates the notch.|
| callback | AsyncCallback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the area. |
| type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch.|
| callback | AsyncCallback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the area. |
**Example**
```js
vartype=window.AvoidAreaType.TYPE_SYSTEM;
windowClass.getAvoidArea(type,(err,data)=>{
if(err.code){
console.error('Failed to obtain the area. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in obtaining the area. Data:'+JSON.stringify(data));
});
```
```js
vartype=window.AvoidAreaType.TYPE_SYSTEM;
windowClass.getAvoidArea(type,(err,data)=>{
if(err.code){
console.error('Failed to obtain the area. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in obtaining the area. Data:'+JSON.stringify(data));
});
```
### getAvoidArea<sup>7+</sup>
...
...
@@ -971,24 +967,24 @@ Obtains the area where this window cannot be displayed, for example, the system
| type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. **TYPE_SYSTEM** indicates the default area of the system. **TYPE_CUTOUT** indicates the notch.|
| type | [AvoidAreaType](#avoidareatype) | Yes | Type of the area. `TYPE_SYSTEM` indicates the default area of the system. `TYPE_CUTOUT` indicates the notch.|
| isLayoutFullScreen | boolean | Yes | Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed.|
| callback | AsyncCallback<void> | Yes | Callback used to return the execution result. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| names | Array | Yes | Whether to display the status bar and navigation bar. For example, to display the status bar and navigation bar, set this parameter to **["status", "navigation"]**. By default, they are not displayed.|
| callback | AsyncCallback<void> | Yes | Callback used to return the execution result. |
| names | Array | Yes | Whether to display the status bar and navigation bar.<br>For example, to display the status bar and navigation bar, set this parameter to `["status", "navigation"]`. By default, they are not displayed.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| names | Array | Yes | Whether to display the status bar and navigation bar. For example, to display the status bar and navigation bar, set this parameter to **["status", "navigation"]**. By default, they are not displayed.|
| names | Array | Yes | Whether to display the status bar and navigation bar.<br>For example, to display the status bar and navigation bar, set this parameter to `["status", "navigation"]`. By default, they are not displayed.|
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value `true` means that this window is displayed, and `false` means the opposite.|
**Example**
```js
windowClass.isShowing((err,data)=>{
if(err.code){
console.error('Failed to check whether the window is showing. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in checking whether the window is showing. Data: '+JSON.stringify(data))
});
```
```js
windowClass.isShowing((err,data)=>{
if(err.code){
console.error('Failed to check whether the window is showing. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in checking whether the window is showing. Data: '+JSON.stringify(data));
});
```
### isShowing<sup>7+</sup>
...
...
@@ -1342,20 +1337,20 @@ Checks whether this window is displayed. This API uses a promise to return the r
| type | string | Yes | Type of event to listen for. The value is fixed at **systemAvoidAreaChange**, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the information. |
| type | string | Yes | Type of event to listen for. The value is fixed at `systemAvoidAreaChange`, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidArea](#avoidarea)> | Yes | Callback used to return the area. |
**Example**
```js
vartype='systemAvoidAreaChange';
windowClass.on(type,(data)=>{
console.info('Succeeded in enabling the listener for system avoid area changes. Data: '+JSON.stringify(data));
});
```
```js
windowClass.on('systemAvoidAreaChange',(data)=>{
console.info('Succeeded in enabling the listener for system avoid area changes. Data: '+JSON.stringify(data));
});
```
### off('systemAvoidAreaChange')<sup>7+</sup>
...
...
@@ -1439,15 +1431,14 @@ Disables listening for changes to the area where the window cannot be displayed.
| type | string | Yes | Type of event to listen for. The value is fixed at **systemAvoidAreaChange**, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidArea](#avoidarea)> | No | Callback used to return the information. |
| type | string | Yes | Type of event to listen for. The value is fixed at `systemAvoidAreaChange`, indicating the event of changes to the area where the window cannot be displayed.|
| callback | Callback<[AvoidArea](#avoidarea)> | No | Callback used to return the area. |
**Example**
```js
vartype='systemAvoidAreaChange';
windowClass.off(type);
```
```js
windowClass.off('systemAvoidAreaChange');
```
### on('keyboardHeightChange')<sup>7+</sup>
...
...
@@ -1459,19 +1450,18 @@ Enables listening for keyboard height changes.
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value `true` means that the wide color gamut mode is supported, and `false` means the opposite.|
**Example**
```js
windowClass.isSupportWideGamut((err,data)=>{
if(err.code){
console.error('Failed to check whether the window support WideGamut. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in checking whether the window support WideGamut Data: '+JSON.stringify(data))
})
```
```js
windowClass.isSupportWideGamut((err,data)=>{
if(err.code){
console.error('Failed to check whether the window support WideGamut. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in checking whether the window support WideGamut Data: '+JSON.stringify(data));
})
```
### isSupportWideGamut<sup>8+</sup>
...
...
@@ -1533,18 +1522,18 @@ Checks whether this window supports the wide color gamut mode. This API uses a p
| Promise<boolean> | Promise used to return whether the wide color gamut mode is supported.|
| Promise<boolean> | Promise used to return the result. The value `true` means that the wide color gamut mode is supported, and `false` means the opposite.|
**Example**
```js
letpromise=windowClass.isSupportWideGamut();
promise.then((data)=>{
console.info('Succeeded in checking whether the window support WideGamut. Data: '+JSON.stringify(data))
}).catch((err)=>{
console.error('Failed to check whether the window support WideGamut. Cause: '+JSON.stringify(err));
});
```
```js
letpromise=windowClass.isSupportWideGamut();
promise.then((data)=>{
console.info('Succeeded in checking whether the window support WideGamut. Data: '+JSON.stringify(data));
}).catch((err)=>{
console.error('Failed to check whether the window support WideGamut. Cause: '+JSON.stringify(err));
});
```
### setColorSpace<sup>8+</sup>
...
...
@@ -1559,19 +1548,19 @@ Sets this window to the wide or default color gamut mode. This API uses an async
| callback | AsyncCallback<[ColorSpace](#colorspace)> | Yes | Callback used to return the result. When the color gamut mode is obtained successfully, `err` is `undefined`, and `data` is the current color gamut mode.|
**Example**
```js
windowClass.getColorSpace((err,data)=>{
if(err.code){
console.error('Failed to get window colorspace. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in getting window colorspace. Cause:'+JSON.stringify(data))
})
```
```js
windowClass.getColorSpace((err,data)=>{
if(err.code){
console.error('Failed to get window colorspace. Cause:'+JSON.stringify(err));
return;
}
console.info('Succeeded in getting window colorspace. Cause:'+JSON.stringify(data));
})
```
### getColorSpace<sup>8+</sup>
...
...
@@ -1640,20 +1629,20 @@ Obtains the color gamut mode of this window. This API uses a promise to return t
| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**.|
| callback | AsyncCallback<void> | Yes | Callback used to return the execution result. |
| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**.|
| color | string | Yes | Background color to set. The value is a hexadecimal color value and is case insensitive, for example, `#00FF00` or `#FF00FF00`.|
| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means that such an area is touchable, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the execution result. |
| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value `true` means that such an area is touchable, and `false` means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
@@ -1976,56 +1999,24 @@ Sets whether the area outside the subwindow is touchable. This API uses a promis
| Name | Type | Mandatory| Description |
| --------- | ------- | ---- | ---------------- |
| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means that such an area is touchable, and **false** means the opposite.|
| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value `true` means that such an area is touchable, and `false` means the opposite.|
| FOREGROUND | 1 | The window stage is running in the foreground.|
| ACTIVE | 2 | The window stage gains focus.|
| INACTIVE | 3 | The window stage loses focus.|
...
...
@@ -2164,8 +2155,43 @@ Describes the lifecycle of a window stage.
## WindowStage<sup>9+</sup>
Before calling any of the following APIs, you must use `[onWindowStageCreate()](js-apis-application-ability.md#abilityonwindowstagecreate)` to create a **WindowStage** instance.
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()](js-apis-application-ability.md#abilityonwindowstagecreate)` to create a `WindowStage` instance.
