1# @ohos.window (Window) 2 3The 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. 4 5This module provides the following common window-related functionalities: 6 7- [Window](#window): window instance, which is the basic unit managed by the window manager. 8- [WindowStage](#windowstage9): window manager that manages windows. 9 10> **NOTE** 11> 12> 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. 13 14## Modules to Import 15 16```ts 17import { window } from '@kit.ArkUI'; 18``` 19 20## WindowType<sup>7+</sup> 21 22Enumerates the window types. 23 24**System capability**: SystemCapability.WindowManager.WindowManager.Core 25 26| Name | Value| Description | 27|-------------------------------------| ------ |----------------------------------------------------------------------------------------| 28| TYPE_APP | 0 | Child window of an application.<br>**Model restriction**: This API can be used only in the FA model. | 29| TYPE_SYSTEM_ALERT | 1 | System alert window.<br>**NOTE**<br>This property is supported since API version 7 and deprecated since API version 11. | 30| TYPE_FLOAT<sup>9+</sup> | 8 | Floating window.<br>**Model restriction**: This API can be used only in the stage model.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 31| TYPE_DIALOG<sup>10+</sup> | 16 | Modal window.<br>**Model restriction**: This API can be used only in the stage model.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 32| TYPE_MAIN<sup>18+</sup> | 32 | Main window of an application.<br>This window type cannot be used when creating a window. It is only for reading purposes in the return value of the **getWindowProperties** API. | 33 34## Configuration<sup>9+</sup> 35 36Describes the parameters for creating a child window or system window. 37 38**Atomic service API**: This API can be used in atomic services since API version 12. 39 40**System capability**: SystemCapability.WindowManager.WindowManager.Core 41 42| Name| Type| Mandatory| Description | 43| ---------- | -------------------------- | -- |-----------------------------------------------------------------------------| 44| name | string | Yes| Name of the window. | 45| windowType | [WindowType](#windowtype7) | Yes| Window type. | 46| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | No| Current application context. If no value is passed, no context is used.<br>In the FA model, do not pass in this parameter when creating a child window. Otherwise, an error is reported.<br>In the stage model, you must pass in this parameter when creating a floating window, modal window, or system window.| 47| 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. | 48| 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. | 49| decorEnabled<sup>12+</sup> | 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**.<br>**System capability**: SystemCapability.Window.SessionManager| 50| title<sup>12+</sup> | string| No| Title of the window when **decorEnabled** is set to **true**. The title display area should not go past the left side of the three-button area of the system. Any part that goes beyond will show as an ellipsis. If this parameter is not set, an empty string is used.<br>**System capability**: SystemCapability.Window.SessionManager| 51| defaultDensityEnabled<sup>20+</sup> | boolean| No| Whether the window should use the default density of the system. If the default density is used, the window does not change layout when the system display size changes.<br>If this parameter is set to **true** for a system window, the window uses the default density and is not affected by [setDefaultDensityEnabled()](#setdefaultdensityenabled12) or [setCustomDensity()](#setcustomdensity15) settings for the main window.<br>If this parameter is set to **false**, the window does not use the default density and is affected by those settings.<br>The default value is **false**.<br>**System capability**: SystemCapability.Window.SessionManager| 52 53## AvoidAreaType<sup>7+</sup> 54 55Enumerates the types of areas that window content should avoid. 56 57**System capability**: SystemCapability.WindowManager.WindowManager.Core 58 59**Atomic service API**: This API can be used in atomic services since API version 11. 60 61| Name | Value | Description | 62| -------------------------------- | ---- | ------------------------------------------------------------ | 63| TYPE_SYSTEM | 0 | Default area of the system. <!--RP11-->It contains the status bar and three-button navigation bar.<!--RP11End--> | 64| TYPE_CUTOUT | 1 | Notch area. | 65| TYPE_SYSTEM_GESTURE<sup>9+</sup> | 2 | Gesture area. Currently, no device has this type of avoid area. | 66| TYPE_KEYBOARD<sup>9+</sup> | 3 | Soft keyboard area. | 67| TYPE_NAVIGATION_INDICATOR<sup>11+</sup> | 4 | Bottom navigation bar. <!--RP12-->OpenHarmony devices do not support this capability.<!--RP12End--> | 68 69 70## SystemBarProperties 71 72Describes the properties of the status bar<!--Del--> and three-button navigation bar<!--DelEnd-->. It is used to set the window-level status bar<!--Del--> and three-button navigation bar<!--DelEnd--> properties. 73 74**Atomic service API**: This API can be used in atomic services since API version 12. 75 76| Name | Type| Mandatory| Description | 77| -------------------------------------- | -------- | ---- | ------------------------------------------------------------ | 78| 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 **'#66000000'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 79| isStatusBarLightIcon<sup>7+</sup> | 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**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 80| statusBarContentColor<sup>8+</sup> | 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 **'#E5FFFFFF'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 81| navigationBarColor | string | No | Background color of the three-button 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 **'#66000000'**.<br><!--RP13--><!--RP13End--> **System capability**: SystemCapability.WindowManager.WindowManager.Core| 82| isNavigationBarLightIcon<sup>7+</sup> | boolean | No | Whether any icon on the three-button navigation bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.<br><!--RP13--><!--RP13End--> **System capability**: SystemCapability.WindowManager.WindowManager.Core| 83| navigationBarContentColor<sup>8+</sup> | string | No | Color of the text on the three-button navigation bar. After this property is set, the setting of **isNavigationBarLightIcon** is invalid. The default value is **'#E5FFFFFF'**.<br><!--RP13--><!--RP13End--> **System capability**: SystemCapability.WindowManager.WindowManager.Core| 84| enableStatusBarAnimation<sup>12+</sup> | 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**.<br>**System capability**: SystemCapability.Window.SessionManager| 85| enableNavigationBarAnimation<sup>12+</sup> | boolean | No | Whether to enable animation for a three-button navigation bar property change. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.<br><!--RP13--><!--RP13End--> **System capability**: SystemCapability.Window.SessionManager| 86 87## StatusBarProperty<sup>18+</sup> 88 89Describes the properties of the status bar. These properties are returned when you query the status bar's configuration details. 90 91**Atomic service API**: This API can be used in atomic services since API version 18. 92 93| Name | Type| Mandatory| Description| 94| ------------------------------------- | -------- | ---- |------- | 95| contentColor | string | Yes | Color of the text on the status bar. The value is in ARGB format, for example, **#E5FFFFFF**.<br>**System capability**: SystemCapability.Window.SessionManager| 96 97## SystemBarStyle<sup>12+</sup> 98 99Describes the properties of the status bar. These properties are valid for the page-level status bar. 100 101**Atomic service API**: This API can be used in atomic services since API version 12. 102 103**System capability**: SystemCapability.WindowManager.WindowManager.Core 104 105| Name | Type| Read-Only| Optional| Description | 106| ------ | -------- | ---- | ---- | ------------------ | 107| statusBarContentColor | string | Yes | Yes | Color of the text on the status bar. The default value is **'#E5FFFFFF'**.| 108 109## Orientation<sup>9+</sup> 110 111Enumerates the window orientations. 112 113| Name | Value | Description | 114| ------------------------------------- | ---- | ----------------------------- | 115| UNSPECIFIED | 0 | Unspecified. The orientation is determined by the system.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 116| PORTRAIT | 1 | Portrait.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 117| LANDSCAPE | 2 | Landscape.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 118| PORTRAIT_INVERTED | 3 | Reverse portrait.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 119| LANDSCAPE_INVERTED | 4 | Reverse landscape.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 120| AUTO_ROTATION | 5 | Automatically rotates with the sensor. The orientation can be portrait, landscape, reverse portrait, or reverse landscape.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 121| AUTO_ROTATION_PORTRAIT | 6 | Automatically rotates with the sensor in the vertical direction. The orientation can be portrait or reverse portrait.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 122| AUTO_ROTATION_LANDSCAPE | 7 | Automatically rotates with the sensor in the horizontal direction. The orientation can be landscape or reverse landscape.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 123| 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.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 124| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 125| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 126| LOCKED | 11 | Locked.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 127| AUTO_ROTATION_UNSPECIFIED<sup>12+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 128| USER_ROTATION_PORTRAIT<sup>12+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 129| USER_ROTATION_LANDSCAPE<sup>12+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 130| USER_ROTATION_PORTRAIT_INVERTED<sup>12+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 131| USER_ROTATION_LANDSCAPE_INVERTED<sup>12+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 132| FOLLOW_DESKTOP<sup>12+</sup> | 17 | Follows the orientation of the home screen.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 133 134## Rect<sup>7+</sup> 135 136Describes the rectangular area of the window. 137 138**System capability**: SystemCapability.WindowManager.WindowManager.Core 139 140**Atomic service API**: This API can be used in atomic services since API version 11. 141 142| Name | Type| Readable| Writable| Description | 143| ------ | -------- | ---- | ---- | ------------------ | 144| left | number | Yes | Yes | Left boundary of the rectangle, in px. The value must be an integer.| 145| top | number | Yes | Yes | Top boundary of the rectangle, in px. The value must be an integer.| 146| width | number | Yes | Yes | Width of the rectangle, in px. The value must be an integer.| 147| height | number | Yes | Yes | Height of the rectangle, in px. The value must be an integer.| 148 149## AvoidArea<sup>7+</sup> 150 151Describes 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. 152 153Pay attention to the following restrictions on this area: 154 155- The bottom gesture area, apart from the bottom navigation bar area, supports transparent transmission of touch events, and touch and hold events, but not drag events. 156 157- 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. 158 159- The bottom navigation bar area supports responding to touch events, touch and hold events, and drag events. However, it does not support transparent transmission of events. 160 161**System capability**: SystemCapability.WindowManager.WindowManager.Core 162 163**Atomic service API**: This API can be used in atomic services since API version 11. 164 165| Name | Type | Readable| Writable| Description | 166| ---------- | ------------- | ---- | ---- | ------------------ | 167| visible<sup>9+</sup> | 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.| 168| leftRect | [Rect](#rect7) | Yes | Yes | Rectangle on the left of the screen.| 169| topRect | [Rect](#rect7) | Yes | Yes | Rectangle at the top of the screen.| 170| rightRect | [Rect](#rect7) | Yes | Yes | Rectangle on the right of the screen.| 171| bottomRect | [Rect](#rect7) | Yes | Yes | Rectangle at the bottom of the screen.| 172 173## Size<sup>7+</sup> 174 175Describes the window size. 176 177**System capability**: SystemCapability.WindowManager.WindowManager.Core 178 179**Atomic service API**: This API can be used in atomic services since API version 11. 180 181| Name | Type| Readable| Writable| Description | 182| ------ | -------- | ---- | ---- | ---------- | 183| width | number | Yes | Yes | Window width, in px. The value must be an integer.| 184| height | number | Yes | Yes | Window height, in px. The value must be an integer.| 185 186## RectChangeReason<sup>12+</sup> 187 188Enumerates the reasons for window rectangle (position and size) changes. 189 190**System capability**: SystemCapability.Window.SessionManager 191 192**Atomic service API**: This API can be used in atomic services since API version 12. 193 194| Name | Value | Description | 195| --------------------- | ---- | ------------------------------------------------------------ | 196| UNDEFINED | 0 | Default value. | 197| MAXIMIZE | 1 | The window is maximized. | 198| RECOVER | 2 | The window is restored to the previous state. | 199| MOVE | 3 | The window is moved.| 200| DRAG | 4 | The window is zoomed in or out by dragging.| 201| DRAG_START | 5 | The window starts zooming in or out.| 202| DRAG_END | 6 | The window finishes zooming in or out.| 203 204## RectChangeOptions<sup>12+</sup> 205 206Describes the value and reason returned upon a window rectangle (position and size) change. 207 208**System capability**: SystemCapability.Window.SessionManager 209 210**Atomic service API**: This API can be used in atomic services since API version 12. 211 212| Name | Type | Readable| Writable| Description | 213| ---------- | ------------- | ---- | ---- | ------------------ | 214| rect | [Rect](#rect7) | Yes | Yes | New value of the window rectangle.| 215| reason | [RectChangeReason](#rectchangereason12) | Yes | Yes | Reason for the window rectangle change.| 216 217## AvoidAreaOptions<sup>12+</sup> 218 219Describes the new area where the window cannot be displayed. The new area is returned when the corresponding event is triggered. 220 221**System capability**: SystemCapability.WindowManager.WindowManager.Core 222 223**Atomic service API**: This API can be used in atomic services since API version 12. 224 225| Name | Type | Readable| Writable| Description | 226| ---------- | ------------- | ---- | ---- | ------------------ | 227| type | [AvoidAreaType](#avoidareatype7) | Yes | Yes | Type of the new area returned.| 228| area | [AvoidArea](#avoidarea7) | Yes | Yes | New area returned.| 229 230## WindowProperties 231 232Describes the window properties. 233 234**System capability**: SystemCapability.WindowManager.WindowManager.Core 235 236| Name | Type | Read-Only| Optional| Description | 237| ------------------------------------- | ------------------------- | ---- | ---- |--------------------------------------------------------------------------------------------------------| 238| windowRect<sup>7+</sup> | [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#onforeground).<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 239| drawableRect<sup>11+</sup> | [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. In the stage model, this API must be used after [loadContent()](#loadcontent9) or [setUIContent()](#setuicontent9) is called to load the page content.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 240| type<sup>7+</sup> | [WindowType](#windowtype7) | No | No | Window type.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 241| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 242| isLayoutFullScreen<sup>7+</sup> | boolean | No | No | Whether the window is immersive and in full-screen mode (not in floating window or split-screen scenarios). The default value is **false**. The value **true** means that the window is immersive and in full-screen mode, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 243| focusable<sup>7+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 244| touchable<sup>7+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 245| 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**.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 246| dimBehindValue<sup>(deprecated)</sup> | 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.<br>**NOTE**<br>This property is supported since API version 7 and deprecated since API version 9.<br>Currently, no substitute is available.| 247| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 248| isPrivacyMode<sup>7+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 249| isRoundCorner<sup>(deprecated)</sup> | 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.<br>**NOTE**<br>This property is supported since API version 7 and deprecated since API version 9.<br>Currently, no substitute is available.| 250| isTransparent<sup>7+</sup> | boolean | No | No | Whether the window background is transparent. The default value is **false**. The value **true** means that the window is transparent, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 251| id<sup>9+</sup> | number | Yes | No | Window ID. The default value is **0**. The value must be an integer.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 252| displayId<sup>12+</sup> | 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 253| name<sup>18+</sup> | string | Yes | Yes | Window name. The default value is an empty string.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 254 255## DecorButtonStyle<sup>14+</sup> 256 257Describes the button style of the system decoration bar. 258 259**System capability**: SystemCapability.Window.SessionManager 260 261**Atomic service API**: This API can be used in atomic services since API version 14. 262 263| Name | Type | Readable| Writable| Description | 264| ---------- | ------------- | ---- | ---- | ------------------ | 265| 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.| 266| 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.| 267| spacingBetweenButtons | number | Yes | Yes | Spacing between buttons. The value ranges from 8 vp to 24 vp. The default value is 12 vp.| 268| closeButtonRightMargin | number | Yes | Yes | Margin between the rightmost edge of the close button and the window. The value ranges from 6 vp to 22 vp. The default value is 20 vp.| 269| buttonIconSize<sup>20+</sup> | number | Yes | Yes | Size of the button icon. The value ranges from 16 vp to 24 vp. The default value is 20 vp.| 270| buttonBackgroundCornerRadius<sup>20+</sup> | number | Yes | Yes | Radius of the button background rounded corner. The value ranges from 4 vp to 8 vp. The default value is 4 vp.| 271 272## ColorSpace<sup>8+</sup> 273 274Enumerates the color spaces. 275 276**Atomic service API**: This API can be used in atomic services since API version 12. 277 278**System capability**: SystemCapability.WindowManager.WindowManager.Core 279 280| Name | Value| Description | 281| ---------- | ------ | -------------- | 282| DEFAULT | 0 | Default SRGB gamut.| 283| WIDE_GAMUT | 1 | Wide-gamut. | 284 285## WindowEventType<sup>10+</sup> 286 287Enumerates the window lifecycle states. 288 289**Atomic service API**: This API can be used in atomic services since API version 11. 290 291| Name | Value| Description | 292| ---------- | ------ | ---------- | 293| WINDOW_SHOWN | 1 | The window is running in the foreground.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 294| WINDOW_ACTIVE | 2 | The window gains focus.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 295| WINDOW_INACTIVE | 3 | The window loses focus.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 296| WINDOW_HIDDEN | 4 | The window is running in the background.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 297| WINDOW_DESTROYED<sup>11+</sup> | 7 | The window is destroyed.<br>**System capability**: SystemCapability.Window.SessionManager| 298 299## WindowLimits<sup>11+</sup> 300 301Describes 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. 302 303**Atomic service API**: This API can be used in atomic services since API version 12. 304 305**System capability**: SystemCapability.Window.SessionManager 306 307| Name | Type | Readable| Writable| Description | 308| :-------- | :----- | :--- | :--- | :----------------------------------------------------------- | 309| 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. | 310| 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. | 311| 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. | 312| 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. | 313 314## WindowStatusType<sup>11+</sup> 315 316Enumerates the window modes. 317 318**Atomic service API**: This API can be used in atomic services since API version 12. 319 320**System capability**: SystemCapability.Window.SessionManager 321 322| Name | Value | Description | 323| ---------- | ---- | ----------------------------- | 324| UNDEFINED | 0 | The window mode is not defined by the application. | 325| FULL_SCREEN | 1 | The application is displayed in full screen. | 326| MAXIMIZE | 2 | The application window is maximized. | 327| MINIMIZE | 3 | The application window is minimized. | 328| FLOATING | 4 | The application is displayed in a floating window. | 329| SPLIT_SCREEN | 5 | The application is displayed in split-screen mode. | 330 331## TitleButtonRect<sup>11+</sup> 332 333Describes 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. 334 335**Atomic service API**: This API can be used in atomic services since API version 12. 336 337**System capability**: SystemCapability.Window.SessionManager 338 339| Name | Type | Readable| Writable| Description | 340| ------ | ------ | ---- | ---- | ------------------------------------------ | 341| right | number | Yes | Yes | Right boundary of the rectangle, in vp. The value must be an integer.| 342| top | number | Yes | Yes | Top boundary of the rectangle, in vp. The value must be an integer.| 343| width | number | Yes | Yes | Width of the rectangle, in vp. The value must be an integer. | 344| height | number | Yes | Yes | Height of the rectangle, in vp. The value must be an integer. | 345 346## MaximizePresentation<sup>12+</sup> 347 348Enumerates the layout when the window is maximized. 349 350**System capability**: SystemCapability.Window.SessionManager 351 352| Name | Value | Description | 353| ---------- | ---- | ----------------------------- | 354| FOLLOW_APP_IMMERSIVE_SETTING | 0 | The window, when maximized, follows the immersive layout of the application.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 355| EXIT_IMMERSIVE | 1 | The window, when maximized, exits the immersive layout.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 356| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 357| ENTER_IMMERSIVE_DISABLE_TITLE_AND_DOCK_HOVER<sup>14+</sup> | 3 | The window, when maximized, transitions into the immersive layout, and the window title bar and dock bar are not displayed when the cursor hovers over the hot zone.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 358 359## MoveConfiguration<sup>15+</sup> 360 361Describes the window movement configuration. 362 363**Atomic service API**: This API can be used in atomic services since API version 15. 364 365**System capability**: SystemCapability.Window.SessionManager 366 367| Name | Type | Mandatory| Description | 368| ------ | ------ | ---- | ------------------------------------------ | 369| displayId | number | No| Target display ID. The value must be an integer. If a non-integer is passed in, the value is rounded down. If this parameter is passed in, the window is positioned relative to the upper left corner of the target display. If this parameter is left empty or the target display ID does not exist, the window is positioned relative to the upper left corner of the current display.| 370 371## WindowDensityInfo<sup>15+</sup> 372 373Describes the information about the display density of the screen where the window is located and the window's custom display density. It is a scale factor independent of pixel units, that is, a factor for scaling display size. 374 375**Atomic service API**: This API can be used in atomic services since API version 15. 376 377**System capability**: SystemCapability.Window.SessionManager 378 379| Name | Type| Readable| Writable| Description | 380| ------ | -------- | ---- | ---- | ---------- | 381| systemDensity | number | Yes | No | System's display size scale factor for the screen where the window is located. The value ranges from 0.5 to 4.0 and varies according to user settings.| 382| defaultDensity | number | Yes | No | Default display size scale factor for the screen where the window is located. The value ranges from 0.5 to 4.0 and varies with the screen.| 383| customDensity | number | Yes | No | Custom display size scale factor of the window. The value ranges from 0.5 to 4.0. If this parameter is left unspecified, the system's display size scale factor is used.| 384 385## WindowLayoutInfo<sup>15+</sup> 386 387Describes the information about the window layout. 388 389**Atomic service API**: This API can be used in atomic services since API version 15. 390 391**System capability**: SystemCapability.Window.SessionManager 392 393| Name | Type | Mandatory| Description | 394| ------ | ------ | ---- | ------------------------------------------ | 395| windowRect<sup>15+</sup> | [Rect](#rect7) | Yes| Window rectangle, that is, the position and size of the window on the display.| 396 397## KeyboardInfo<sup>18+</sup> 398 399Describes the information about the soft keyboard window. 400 401**Atomic service API**: This API can be used in atomic services since API version 18. 402 403**System capability**: SystemCapability.Window.SessionManager 404 405| Name | Type | Mandatory| Description | 406| ------ | ------ | ---- | ------------------------------------------ | 407| beginRect | [Rect](#rect7) | Yes| Position and size of the soft keyboard before the animation starts.| 408| endRect | [Rect](#rect7) | Yes| Position and size of the soft keyboard before the animation ends.| 409| animated<sup>20+</sup> | boolean | No| Whether there is a show/hide animation. The value **true** means that there is a show/hide animation, and **false** means the opposite.| 410| config<sup>20+</sup> | [WindowAnimationConfig](#windowanimationconfig20) | No| Animation configuration.| 411 412## ShowWindowOptions<sup>20+</sup> 413 414Describes the parameters for displaying a child window or system window. 415 416**System capability**: SystemCapability.Window.SessionManager 417 418**Atomic service API**: This API can be used in atomic services since API version 20. 419 420| Name | Type | Mandatory| Description | 421| ------ | ------ | ---- | ------------------------------------------ | 422| focusOnShow | boolean | No| Whether the window automatically gains focus when [showWindow()](#showwindow20) is called. The default is **true**. This parameter does not take effect for the main window, modal window, and dialog boxes.| 423 424## WindowAnimationCurve<sup>20+</sup> 425 426Enumerates the types of window animation curves. 427 428**Atomic service API**: This API can be used in atomic services since API version 20. 429 430**System capability**: SystemCapability.Window.SessionManager 431 432| Name | Value | Description | 433| ------------------- | ---- | ------------------------------------------------------------ | 434| LINEAR | 0 | The animation speed is constant from start to finish.<br>When this curve type is used, **duration** in [WindowAnimationConfig](#windowanimationconfig20) is mandatory.<br>When this curve type is used, **param** in [WindowAnimationConfig](#windowanimationconfig20) is optional and does not take effect.| 435| INTERPOLATION_SPRING | 1 | Interpolator spring curve, an animation curve from 0 to 1, where the actual animation values are interpolated based on the curve. The animation duration is subject to the curve parameters, rather than the **duration** parameter in [WindowAnimationConfig](#windowanimationconfig20).<br>When this curve type is used, **duration** in [WindowAnimationConfig](#windowanimationconfig20) is optional and does not take effect.<br>When this curve type is used, **param** in [WindowAnimationConfig](#windowanimationconfig20) is mandatory.| 436 437## WindowAnimationConfig<sup>20+</sup> 438 439Describes the configuration for window animation. 440 441**Atomic service API**: This API can be used in atomic services since API version 20. 442 443**System capability**: SystemCapability.Window.SessionManager 444 445| Name | Type | Mandatory| Description | 446| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 447| curve | [WindowAnimationCurve](#windowanimationcurve20) | Yes | Type of animation curve. | 448| duration | number | No | Duration for playing the animation, in milliseconds (ms).<br>The default value is 0, and the maximum value is 3000.<br>Whether it is required depends on the animation curve type.| 449| param | [WindowAnimationCurveParam](#windowanimationcurveparam20) | No | Parameters for the animation curve. Whether it is required depends on the animation curve type. | 450 451## WindowAnimationCurveParam<sup>20+</sup> 452 453type WindowAnimationCurveParam = Array<number> 454 455Defines the parameters for the animation curve. The meaning of **WindowAnimationCurveParam** varies depending on the type of [WindowAnimationCurve](#windowanimationcurve20). 456 457**Atomic service API**: This API can be used in atomic services since API version 20. 458 459**System capability**: SystemCapability.Window.SessionManager 460 461When the curve type is **LINEAR**, **WindowAnimationCurveParam** is optional and have no effect. 462 463When the curve type is **INTERPOLATION_SPRING**, **WindowAnimationCurveParam** must be set as an array of length 4: [velocity,mass,stiffness,damping]. 464 465- **velocity**: initial velocity, which is of the number type. This parameter is mandatory. 466 467 It describes the impact of external factors to the spring animation, designed to help ensure smooth transition from the previous motion state. This is a normalized velocity, and it is calculated as the actual initial velocity divided by the change in the animation property. 468 469- **mass**: mass, which is of the number type. This parameter is mandatory. The value range is (0, +∞). If the value is less than or equal to 0, the value **1** is used. 470 471 It describes the inertia of the object in the elastic system, affecting the amplitude of oscillation and the speed of return to equilibrium. The greater the mass, the greater the amplitude of the oscillation, and the slower the speed of restoring to the equilibrium position. 472 473- **stiffness**: stiffness, which is of the number type. This parameter is mandatory. The value range is (0, +∞). If the value is less than or equal to 0, the value **1** is used. 474 475 It describes the degree to which an object deforms by resisting the force applied. In an elastic system, the greater the stiffness, the stronger the capability to resist deformation, and the faster the speed of restoring to the equilibrium position. 476 477- **damping**: damping, which is of the number type. This parameter is mandatory. The value range is (0, +∞). If the value is less than or equal to 0, the value **1** is used. 478 479 It is used to describe the oscillation and attenuation of the system after being disturbed. The larger the damping, the smaller the number of oscillations of elastic motion, and the smaller the oscillation amplitude. 480 481 482## WindowInfo<sup>18+</sup> 483 484Describes the window information. 485 486**System capability**: SystemCapability.Window.SessionManager 487 488| Name | Type | Read-Only| Optional| Description | 489| ------ | ------ | ---- | ---- | ------------------------------------------ | 490| rect | [Rect](js-apis-window.md#rect7) | Yes | No | Window size.| 491| bundleName | string | Yes | No | Bundle name of the application. | 492| abilityName | string | Yes | No | Ability name. | 493| windowId | number | Yes | No | Window ID. | 494| windowStatusType | [WindowStatusType](js-apis-window.md#windowstatustype11) | Yes | No | Window mode. | 495| isFocused | boolean | Yes | Yes | Whether the window gains focus. The value **true** means that the window gains focus, and **false** means the opposite. | 496 497## WindowTransitionType<sup>20+</sup> 498 499Enumerates the types of window transition animations. 500 501**Atomic service API**: This API can be used in atomic services since API version 20. 502 503**System capability**: SystemCapability.Window.SessionManager 504 505| Name | Value | Description | 506| ------- | ---- | -------------------------- | 507| DESTROY | 0 | Transition animation when the window is destroyed.| 508 509## TransitionAnimation<sup>20+</sup> 510 511Describes the window transition animation. 512 513**Atomic service API**: This API can be used in atomic services since API version 20. 514 515**System capability**: SystemCapability.Window.SessionManager 516 517| Name | Type | Mandatory| Description | 518| ------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 519| config | [WindowAnimationConfig](#windowanimationconfig20) | Yes | Transition animation configuration. | 520| opacity | number | No | Opacity of the window during the transition animation. If this parameter is set to **0**, the window is completely transparent. When the animation type is **WindowTransitionType.DESTROY**, this represents the opacity at the end of the animation. The value ranges from 0 to 1. The value is reset to **1** when the animation ends.| 521 522## WindowAnchor<sup>20+</sup> 523 524Enumerates the window anchor points. 525 526**Atomic service API**: This API can be used in atomic services since API version 20. 527 528**System capability**: SystemCapability.Window.SessionManager 529 530| Name | Value | Description | 531| ---------- | ---- | ----------------------------- | 532| TOP_START | 0 | Top left corner of the window.| 533| TOP | 1 | Horizontal center point along the top edge of the window.| 534| TOP_END | 2 | Top right corner of the window.| 535| START | 3 | Vertical center point along the left edge of the window.| 536| CENTER | 4 | Center point of the window, both horizontally and vertically.| 537| END | 5 | Vertical center point along the right edge of the window.| 538| BOTTOM_START | 6 | Bottom left corner of the window.| 539| BOTTOM | 7 | Horizontal center point along the bottom edge of the window.| 540| BOTTOM_END | 8 | Bottom right corner of the window.| 541 542## Callback<sup>15+</sup> 543 544### (data: T)<sup>15+</sup> 545 546(data: T): V; 547 548Describes a generic callback function. 549 550You can set **data** to customize the parameter type of the information returned by the callback. 551 552**Atomic service API**: This API can be used in atomic services since API version 15. 553 554**System capability**: SystemCapability.Window.SessionManager 555 556**Parameters** 557 558| Name| Type| Mandatory| Description| 559| ---- | ---- | ---- | -------------------------- | 560| data | T | Yes | Parameter of type T that needs to be passed when the callback function is called.| 561 562**Return value** 563 564| Type| Description| 565| -------------------------------- | ------------------------------------ | 566| V | Value of type V.| 567 568## RotationChangeType<sup>19+</sup> 569 570Enumerates the types of window rotation events. 571 572**Atomic service API**: This API can be used in atomic services since API version 19. 573 574**System capability**: SystemCapability.Window.SessionManager 575 576| Name | Value| Description | 577| ------ | ---- | --------------------- | 578| WINDOW_WILL_ROTATE| 0 | The window is about to rotate.| 579| WINDOW_DID_ROTATE | 1 | The window has finished rotating.| 580 581## RectType<sup>19+</sup> 582 583Enumerates the types of window rectangle coordinate systems. 584 585**Atomic service API**: This API can be used in atomic services since API version 19. 586 587**System capability**: SystemCapability.Window.SessionManager 588 589| Name | Value| Description | 590| ------ | ---- | --------------------- | 591| RELATIVE_TO_SCREEN | 0 | The window rectangle is relative to the screen coordinate system.| 592| RELATIVE_TO_PARENT_WINDOW | 1 | The window rectangle is relative to the parent window coordinate system.| 593 594## RotationChangeInfo<sup>19+</sup> 595 596Describes the window information obtained during window rotation changes. 597 598**Atomic service API**: This API can be used in atomic services since API version 19. 599 600**System capability**: SystemCapability.Window.SessionManager 601 602| Name | Type| Read-Only | Optional| Description | 603| ------ | ---- | ----- | ---- | ----------------------- | 604| type | [RotationChangeType](#rotationchangetype19) | Yes| No| Type of window rotation event.| 605| orientation | number | Yes| No| Display orientation of the window.<br>- **0**: portrait.<br>- **1**: reverse landscape.<br>- **2**: reverse portrait.<br>- **3**: landscape.<br>Note that the orientation here is different from the orientation property of the display object.| 606| displayId | number | Yes| No| ID of the screen where the window is located.| 607| displayRect | [Rect](#rect7) | Yes| No| Size of the rectangle after the screen where the window is located is rotated.| 608 609## RotationChangeResult<sup>19+</sup> 610 611Describes the information returned by the application during window rotation changes. 612 613The system uses the information to adjust the size of the current window rectangle. If the returned information is about the rotation change of the main window, the system does not change the size of the main window. 614 615There are limitations on the size of application windows and system windows. For details about specific restrictions and rules, see [resize](#resize9). 616 617**Atomic service API**: This API can be used in atomic services since API version 19. 618 619**System capability**: SystemCapability.Window.SessionManager 620 621| Name | Type| Read-Only | Optional| Description | 622| ------ | ---- | ----- | ---- | ----------------------- | 623| rectType | [RectType](#recttype19) | No| No| Type of window rectangle coordinate system.| 624| windowRect | [Rect](#rect7) | No| No| Information about the window's rectangle relative to the screen or parent window coordinate system.| 625 626## RotationChangeCallback<sup>19+</sup> 627 628### (info: T)<sup>19+</sup> 629 630(info: T): U; 631 632Describes a generic callback function for rotation event notifications. 633 634In this callback function, the parameter type is [RotationChangeInfo](#rotationchangeinfo19), and the return value type is [RotationChangeResult](#rotationchangeresult19)\|void. 635 636**Atomic service API**: This API can be used in atomic services since API version 19. 637 638**System capability**: SystemCapability.Window.SessionManager 639 640**Parameters** 641 642| Name| Type| Mandatory| Description| 643| ---- | ---- | ---- | -------------------------- | 644| info | T | Yes | Parameter of type [RotationChangeInfo](#rotationchangeinfo19) passed by the system when the callback function is called.| 645 646**Return value** 647 648| Type| Description| 649| -------------------------------- | ------------------------------------ | 650| U | Value of type [RotationChangeResult](#rotationchangeresult19)\|void.| | 651 652## GlobalWindowMode<sup>20+</sup> 653 654Enumerates the window modes. 655 656**Atomic service API**: This API can be used in atomic services since API version 20. 657 658**System capability**: SystemCapability.Window.SessionManager 659 660| Name | Value| Type | Description | 661| ------ | --- | --- | ------------------------ | 662| FULLSCREEN | 1 | number | Full-screen window.| 663| SPLIT | 1 << 1 | number | Split-screen window.| 664| FLOAT | 1 << 2 | number | Floating window.| 665| PIP | 1 << 3 | number | PiP.| 666 667## window.createWindow<sup>9+</sup> 668 669createWindow(config: Configuration, callback: AsyncCallback<Window>): void 670 671Creates a child window or system window. This API uses an asynchronous callback to return the result. 672 673**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required only when the window type is **window.WindowType.TYPE_FLOAT**.) 674 675**Atomic service API**: This API can be used in atomic services since API version 12. 676 677**System capability**: SystemCapability.WindowManager.WindowManager.Core 678 679**Parameters** 680 681| Name| Type| Mandatory| Description| 682| -------- | -------------------------------------- | -- | --------------------------------- | 683| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window. | 684| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the window created.| 685 686**Error codes** 687 688For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 689 690| ID| Error Message| 691| ------- | -------------------------------- | 692| 201 | Permission verification failed. The application does not have the permission required to call the API. | 693| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 694| 801 | Capability not supported. createWindow can not work correctly due to limited device capabilities. | 695| 1300001 | Repeated operation. | 696| 1300002 | This window state is abnormal. | 697| 1300004 | Unauthorized operation. | 698| 1300006 | This window context is abnormal. | 699| 1300009 | The parent window is invalid. | 700 701**Example** 702 703```ts 704import { UIAbility } from '@kit.AbilityKit'; 705import { window } from '@kit.ArkUI'; 706import { BusinessError } from '@kit.BasicServicesKit'; 707 708export default class EntryAbility extends UIAbility { 709 onWindowStageCreate(windowStage: window.WindowStage): void { 710 let windowClass: window.Window | undefined = undefined; 711 let config: window.Configuration = { 712 name: "test", 713 windowType: window.WindowType.TYPE_DIALOG, 714 ctx: this.context 715 }; 716 try { 717 window.createWindow(config, (err: BusinessError, data) => { 718 const errCode: number = err.code; 719 if (errCode) { 720 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 721 return; 722 } 723 windowClass = data; 724 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 725 windowClass.resize(500, 1000); 726 }); 727 } catch (exception) { 728 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 729 } 730 } 731} 732``` 733 734## window.createWindow<sup>9+</sup> 735 736createWindow(config: Configuration): Promise<Window> 737 738Creates a child window or system window. This API uses a promise to return the result. 739 740**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required only when the window type is **window.WindowType.TYPE_FLOAT**.) 741 742**Atomic service API**: This API can be used in atomic services since API version 12. 743 744**System capability**: SystemCapability.WindowManager.WindowManager.Core 745 746**Parameters** 747 748| Name| Type| Mandatory| Description| 749| ------ | -------------------------------- | -- | ------------------ | 750| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window.| 751 752**Return value** 753 754| Type| Description| 755| -------------------------------- | ------------------------------------ | 756| Promise<[Window](#window)> | Promise used to return the window created.| 757 758**Error codes** 759 760For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 761 762| ID| Error Message| 763| ------- | -------------------------------- | 764| 201 | Permission verification failed. The application does not have the permission required to call the API. | 765| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 766| 801 | Capability not supported. createWindow can not work correctly due to limited device capabilities. | 767| 1300001 | Repeated operation. | 768| 1300002 | This window state is abnormal. | 769| 1300004 | Unauthorized operation. | 770| 1300006 | This window context is abnormal. | 771| 1300009 | The parent window is invalid. | 772 773**Example** 774 775```ts 776import { UIAbility } from '@kit.AbilityKit'; 777import { window } from '@kit.ArkUI'; 778import { BusinessError } from '@kit.BasicServicesKit'; 779 780export default class EntryAbility extends UIAbility { 781 onWindowStageCreate(windowStage: window.WindowStage): void { 782 let config: window.Configuration = { 783 name: "test", 784 windowType: window.WindowType.TYPE_DIALOG, 785 ctx: this.context, 786 defaultDensityEnabled: true 787 }; 788 try { 789 window.createWindow(config).then((value:window.Window) => { 790 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(value)); 791 value.resize(500, 1000); 792 }).catch((err:BusinessError)=> { 793 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 794 }); 795 } catch (exception) { 796 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 797 } 798 } 799} 800``` 801 802## window.findWindow<sup>9+</sup> 803 804findWindow(name: string): Window 805 806Finds a window based on the name. 807 808**System capability**: SystemCapability.WindowManager.WindowManager.Core 809 810**Atomic service API**: This API can be used in atomic services since API version 11. 811 812**Parameters** 813 814| Name| Type | Mandatory| Description | 815| ------ | ------ | ---- | -------- | 816| name | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 817 818**Return value** 819 820| Type| Description| 821| ----------------- | ------------------- | 822| [Window](#window) | Window found.| 823 824**Error codes** 825 826For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 827 828| ID| Error Message| 829| ------- | -------------------------------- | 830| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 831| 1300002 | This window state is abnormal. | 832 833**Example** 834 835```ts 836let windowClass: window.Window | undefined = undefined; 837try { 838 windowClass = window.findWindow('test'); 839} catch (exception) { 840 console.error(`Failed to find the Window. Cause code: ${exception.code}, message: ${exception.message}`); 841} 842``` 843 844## window.getLastWindow<sup>9+</sup> 845 846getLastWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 847 848Obtains the topmost layer child window of the current application. This API uses an asynchronous callback to return the result. 849 850If no child window exists or the child window is not displayed by calling [showWindow()](#showwindow9), the main window of the application is returned. 851 852**Atomic service API**: This API can be used in atomic services since API version 12. 853 854**System capability**: SystemCapability.WindowManager.WindowManager.Core 855 856**Parameters** 857 858| Name| Type| Mandatory| Description| 859| -------- | -------------------------------------- | -- | ---------------------------------------- | 860| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Current application context.| 861| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the topmost layer window obtained.| 862 863**Error codes** 864 865For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 866 867| ID| Error Message| 868| ------- | -------------------------------- | 869| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 870| 1300002 | This window state is abnormal. Top window or main window is null or destroyed. | 871| 1300006 | This window context is abnormal. | 872 873**Example** 874 875```ts 876import { UIAbility } from '@kit.AbilityKit'; 877import { window } from '@kit.ArkUI'; 878import { BusinessError } from '@kit.BasicServicesKit'; 879 880export default class EntryAbility extends UIAbility { 881 // ... 882 onWindowStageCreate(windowStage: window.WindowStage): void { 883 console.info('onWindowStageCreate'); 884 windowStage.createSubWindow('TestSubWindow').then((subWindow) => { 885 subWindow.showWindow().then(() => { 886 try { 887 window.getLastWindow(this.context, (err: BusinessError, topWindow) => { 888 const errCode: number = err.code; 889 if (errCode) { 890 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 891 return; 892 } 893 console.info(`Succeeded in obtaining the top window. Window id: ${topWindow.getWindowProperties().id}`); 894 }); 895 } catch (exception) { 896 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 897 } 898 }); 899 }); 900 } 901 //... 902} 903``` 904 905## window.getLastWindow<sup>9+</sup> 906 907getLastWindow(ctx: BaseContext): Promise<Window> 908 909Obtains the topmost layer child window of the current application. This API uses a promise to return the result. 910 911If no child window exists or the child window is not displayed by calling [showWindow()](#showwindow9), the main window of the application is returned. 912 913**Atomic service API**: This API can be used in atomic services since API version 12. 914 915**System capability**: SystemCapability.WindowManager.WindowManager.Core 916 917**Parameters** 918 919| Name| Type| Mandatory| Description| 920| ------ | ----------- | ---- | ------------------------------------------------------------ | 921| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 922 923**Return value** 924 925| Type| Description| 926| -------------------------------- | ------------------------------------------- | 927| Promise<[Window](#window)> | Promise used to return the topmost layer window obtained.| 928 929**Error codes** 930 931For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 932 933| ID| Error Message| 934| ------- | -------------------------------- | 935| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 936| 1300002 | This window state is abnormal. Top window or main window is null or destroyed. | 937| 1300006 | This window context is abnormal. | 938 939**Example** 940 941```ts 942// EntryAbility.ets 943import { UIAbility } from '@kit.AbilityKit'; 944import { window } from '@kit.ArkUI'; 945import { BusinessError } from '@kit.BasicServicesKit'; 946 947export default class EntryAbility extends UIAbility { 948 // ... 949 onWindowStageCreate(windowStage: window.WindowStage): void { 950 console.info('onWindowStageCreate'); 951 windowStage.createSubWindow('TestSubWindow').then((subWindow) => { 952 subWindow.showWindow().then(() => { 953 try { 954 window.getLastWindow(this.context).then((topWindow) => { 955 console.info(`Succeeded in obtaining the top window. Window id: ${topWindow.getWindowProperties().id}`); 956 }).catch((err: BusinessError) => { 957 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 958 }); 959 } catch (exception) { 960 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 961 } 962 }); 963 }); 964 } 965 //... 966} 967``` 968 969## window.shiftAppWindowFocus<sup>11+</sup> 970shiftAppWindowFocus(sourceWindowId: number, targetWindowId: number): Promise<void> 971 972Shifts 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 child window. 973 974Ensure that the focusable property of the target window is **true** (see [setWindowFocusable()](#setwindowfocusable9)) and that [showWindow()](#showwindow9) is successfully executed. 975 976**Atomic service API**: This API can be used in atomic services since API version 12. 977 978**System capability**: SystemCapability.Window.SessionManager 979 980**Parameters** 981 982| Name | Type | Mandatory | Description | 983| -------------- | ------ | ----- | ----------------------- | 984| sourceWindowId | number | Yes | ID of the source window, which is having the focus.| 985| targetWindowId | number | Yes | ID of the target window. | 986 987**Return value** 988 989| Type | Description | 990| ------------------- | ------------------------- | 991| Promise<void> | Promise that returns no value.| 992 993**Error codes** 994 995For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 996 997| ID| Error Message | 998| ------- | --------------------------------------------- | 999| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1000| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1001| 1300002 | This window state is abnormal. | 1002| 1300003 | This window manager service works abnormally. | 1003| 1300004 | Unauthorized operation. | 1004 1005**Example** 1006 1007```ts 1008// EntryAbility.ets 1009import { UIAbility } from '@kit.AbilityKit'; 1010import { window } from '@kit.ArkUI'; 1011import { BusinessError } from '@kit.BasicServicesKit'; 1012 1013export default class EntryAbility extends UIAbility { 1014 onWindowStageCreate(windowStage: window.WindowStage) { 1015 // ... 1016 console.info('onWindowStageCreate'); 1017 let mainWindow: window.Window | undefined = undefined; 1018 let subWindow: window.Window | undefined = undefined; 1019 let mainWindowId: number = -1; 1020 let subWindowId: number = -1; 1021 1022 try { 1023 // Obtain the main window and ID of the application. 1024 windowStage.getMainWindow().then((data) => { 1025 if (data == null) { 1026 console.error('Failed to obtain the main window. Cause: The data is empty'); 1027 return; 1028 } 1029 mainWindow = data; 1030 mainWindowId = mainWindow.getWindowProperties().id; 1031 console.info('Succeeded in obtaining the main window'); 1032 }).catch((err: BusinessError) => { 1033 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1034 }); 1035 1036 // Create or obtain a child window and its ID. In this case, the child window has focus. 1037 windowStage.createSubWindow('testSubWindow').then((data) => { 1038 if (data == null) { 1039 console.error('Failed to obtain the sub window. Cause: The data is empty'); 1040 return; 1041 } 1042 subWindow = data; 1043 subWindowId = subWindow.getWindowProperties().id; 1044 subWindow.resize(500, 500); 1045 subWindow.showWindow(); 1046 1047 // Listen for the window status and ensure that the window is ready. 1048 subWindow.on("windowEvent", (windowEvent) => { 1049 if (windowEvent == window.WindowEventType.WINDOW_ACTIVE) { 1050 // Switch the focus. 1051 window.shiftAppWindowFocus(subWindowId, mainWindowId).then(() => { 1052 console.info('Succeeded in shifting app window focus'); 1053 }).catch((err: BusinessError) => { 1054 console.error(`Failed to shift app window focus. Cause code: ${err.code}, message: ${err.message}`); 1055 }); 1056 } 1057 }); 1058 }); 1059 } catch (exception) { 1060 console.error(`Failed to shift app focus. Cause code: ${exception.code}, message: ${exception.message}`); 1061 } 1062 } 1063} 1064``` 1065 1066## window.shiftAppWindowPointerEvent<sup>15+</sup> 1067shiftAppWindowPointerEvent(sourceWindowId: number, targetWindowId: number): Promise<void> 1068 1069Transfers an input event from one window to another within the same application, particularly in split-window scenarios. This API uses a promise to return the result. It takes effect only for the main window and its child windows on 2-in-1 devices. 1070 1071On 2-in-1 devices, the source window must be in a mouse-down state for this API to work; otherwise, the call does not take effect. After the input event is transferred, a mouse-up event is sent to the source window, and a mouse-down event is sent to the target window. 1072 1073**Atomic service API**: This API can be used in atomic services since API version 15. 1074 1075**System capability**: SystemCapability.Window.SessionManager 1076 1077**Parameters** 1078 1079| Name | Type | Mandatory | Description | 1080| -------------- | ------ | ----- | ----------------------- | 1081| sourceWindowId | number | Yes | ID of the source window. You are advised to call [getWindowProperties()](#getwindowproperties9) to obtain the window ID. | 1082| targetWindowId | number | Yes | ID of the target window. You are advised to call [getWindowProperties()](#getwindowproperties9) to obtain the window ID. | 1083 1084**Return value** 1085 1086| Type | Description | 1087| ------------------- | ------------------------- | 1088| Promise<void> | Promise that returns no value.| 1089 1090**Error codes** 1091 1092For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1093 1094| ID| Error Message | 1095| ------- | --------------------------------------------- | 1096| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1097| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1098| 1300002 | This window state is abnormal. | 1099| 1300003 | This window manager service works abnormally. | 1100| 1300004 | Unauthorized operation. | 1101 1102**Example** 1103 1104```ts 1105// ets/pages/Index.ets 1106import { window } from '@kit.ArkUI'; 1107import { BusinessError } from '@kit.BasicServicesKit'; 1108 1109@Entry 1110struct Index { 1111 build() { 1112 Row() { 1113 Column() { 1114 Blank('160') 1115 .color(Color.Blue) 1116 .onTouch((event: TouchEvent) => { 1117 if (event.type === TouchType.Down) { 1118 try { 1119 let sourceWindowId = 1; 1120 let targetWindowId = 2; 1121 let promise = window.shiftAppWindowPointerEvent(sourceWindowId, targetWindowId); 1122 promise.then(() => { 1123 console.info('Succeeded in shifting app window pointer event'); 1124 }).catch((err: BusinessError) => { 1125 console.error(`Failed to shift app window pointer event. Cause code: ${err.code}, message: ${err.message}`); 1126 }); 1127 } catch (exception) { 1128 console.error(`Failed to shift app pointer event. Cause code: ${exception.code}, message: ${exception.message}`); 1129 } 1130 } 1131 }) 1132 }.width('100%') 1133 }.height('100%').width('100%') 1134 } 1135} 1136``` 1137 1138## window.shiftAppWindowTouchEvent<sup>20+</sup> 1139shiftAppWindowTouchEvent(sourceWindowId: number, targetWindowId: number, fingerId: number): Promise<void> 1140 1141Moves touch screen input events from one window to another in scenarios where windows within the same application are being split or merged. This API uses a promise to return the result. It takes effect only for the main window and its child windows on 2-in-1 devices. 1142 1143On 2-in-1 devices, to transfer touch screen input events, the source window must call this API within the callback of the [onTouch](arkui-ts/ts-universal-events-touch.md#touchevent) event (the event type must be **TouchType.Down**). After a successful call, the system sends a touch-up event to the source window and a touch-down event to the target window. 1144 1145**Atomic service API**: This API can be used in atomic services since API version 20. 1146 1147**System capability**: SystemCapability.Window.SessionManager 1148 1149**Parameters** 1150 1151| Name | Type | Mandatory | Description | 1152| -------------- | ------ | ----- | ----------------------- | 1153| sourceWindowId | number | Yes | ID of the source window. You are advised to call [getWindowProperties()](#getwindowproperties9) to obtain the window ID. | 1154| targetWindowId | number | Yes | ID of the target window. You are advised to call [getWindowProperties()](#getwindowproperties9) to obtain the window ID. | 1155| fingerId | number | Yes | Finger ID of the touch event. You are advised to use the [touches](arkui-ts/ts-universal-events-touch.md#touchobject) property in the [touchEvent](arkui-ts/ts-universal-events-touch.md#touchevent) event to obtain the ID. | 1156 1157**Return value** 1158 1159| Type | Description | 1160| ------------------- | ------------------------- | 1161| Promise<void> | Promise that returns no value.| 1162 1163**Error codes** 1164 1165For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1166 1167| ID| Error Message | 1168| ------- | --------------------------------------------- | 1169| 801 | Capability not supported. Function shiftAppWindowTouchEvent can not work correctly due to limited device capabilities. | 1170| 1300002 | This window state is abnormal. | 1171| 1300003 | This window manager service works abnormally. | 1172| 1300004 | Unauthorized operation. | 1173| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range.| 1174 1175**Example** 1176 1177```ts 1178// ets/pages/Index.ets 1179import { window } from '@kit.ArkUI'; 1180import { BusinessError } from '@kit.BasicServicesKit'; 1181 1182@Entry 1183struct Index { 1184 build() { 1185 Row() { 1186 Column() { 1187 Blank('160') 1188 .color(Color.Blue) 1189 .onTouch((event: TouchEvent) => { 1190 // The source window touch event type must be TouchType.Down. 1191 if (event.type === TouchType.Down) { 1192 try { 1193 let sourceWindowId = 1; 1194 let targetWindowId = 2; 1195 let promise = window.shiftAppWindowTouchEvent(sourceWindowId, targetWindowId, event.touches[0].id); 1196 promise.then(() => { 1197 console.info(`Succeeded in shifting app window touch event`); 1198 }).catch((err: BusinessError) => { 1199 console.error(`Failed to shift app window touch event. Cause code: ${err.code}, message: ${err.message}`); 1200 }); 1201 } catch (exception) { 1202 console.error(`Failed to shift app touch event. Cause code: ${exception.code}, message: ${exception.message}`); 1203 } 1204 } 1205 }) 1206 }.width('100%') 1207 }.height('100%').width('100%') 1208 } 1209} 1210``` 1211 1212## window.getWindowsByCoordinate<sup>14+</sup> 1213 1214getWindowsByCoordinate(displayId: number, windowNumber?: number, x?: number, y?: number): Promise<Array<Window>> 1215 1216Obtains visible windows at the specified coordinates within the current application, sorted by their current layer order. The window at the topmost layer corresponds to index 0 of the array. This API uses a promise to return the result. 1217 1218**Atomic service API**: This API can be used in atomic services since API version 14. 1219 1220**System capability**: SystemCapability.Window.SessionManager 1221 1222**Parameters** 1223 1224| Name| Type | Mandatory| Description | 1225| ------ | ---------- |----|---------------------------------------------------------------------------| 1226| 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).| 1227| 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. | 1228| 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. | 1229| 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. | 1230 1231**Return value** 1232 1233| Type | Description | 1234| -------------------------------- |-------------------------| 1235| Promise<Array<[Window](#window)>> | Promise used to return an array of window objects.| 1236 1237**Error codes** 1238 1239For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1240 1241| ID | Error Message| 1242|----------| ------------------------------ | 1243| 401 | Parameter error. Possible cause: Incorrect parameter types. | 1244| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1245| 1300003 | This window manager service works abnormally. | 1246 1247```ts 1248import { UIAbility } from '@kit.AbilityKit'; 1249import { window } from '@kit.ArkUI'; 1250import { BusinessError } from '@kit.BasicServicesKit'; 1251 1252export default class EntryAbility extends UIAbility { 1253 1254 onWindowStageCreate(windowStage: window.WindowStage): void { 1255 try { 1256 let windowClass = windowStage.getMainWindowSync(); 1257 let properties = windowClass.getWindowProperties(); 1258 window.getWindowsByCoordinate(properties.displayId).then((data) => { 1259 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 1260 for (let window of data) { 1261 // do something with window 1262 } 1263 }).catch((err: BusinessError) => { 1264 console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`); 1265 }); 1266 window.getWindowsByCoordinate(properties.displayId, 2, 500, 500).then((data) => { 1267 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 1268 for (let window of data) { 1269 // do something with window 1270 } 1271 }).catch((err: BusinessError) => { 1272 console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`); 1273 }); 1274 } catch (exception) { 1275 console.error(`Failed to get window from point. Cause code: ${exception.code}, message: ${exception.message}`); 1276 } 1277 } 1278} 1279``` 1280 1281## window.getAllWindowLayoutInfo<sup>15+</sup> 1282 1283getAllWindowLayoutInfo(displayId: number): Promise<Array<WindowLayoutInfo>> 1284 1285Obtains the layout information array of all windows visible on a display. The layout information is arranged based on the current window stacking order, and the topmost window in the hierarchy is at index 0 of the array. This API uses a promise to return the result. 1286 1287**Atomic service API**: This API can be used in atomic services since API version 15. 1288 1289**System capability**: SystemCapability.Window.SessionManager 1290 1291**Parameters** 1292 1293| Name| Type | Mandatory| Description | 1294| ------ | ---------- |----|---------------------------------------------------------------------------| 1295| 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).| 1296 1297**Return value** 1298 1299| Type | Description | 1300| -------------------------------- |-------------------------| 1301| Promise<Array<[WindowLayoutInfo](#windowlayoutinfo15)>> | Promise used to return an array of window layout information objects.| 1302 1303**Error codes** 1304 1305For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1306 1307| ID | Error Message| 1308|----------| ------------------------------ | 1309| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1310| 801 | Capability not supported. function getAllWindowLayoutInfo can not work correctly due to limited device capabilities. | 1311| 1300003 | This window manager service works abnormally. | 1312 1313```ts 1314import { window } from '@kit.ArkUI'; 1315import { BusinessError } from '@kit.BasicServicesKit'; 1316 1317try { 1318 let displayId = 0; 1319 let promise = window.getAllWindowLayoutInfo(displayId); 1320 promise.then((data) => { 1321 console.info('Succeeded in obtaining all window layout info. Data: ' + JSON.stringify(data)); 1322 }).catch((err: BusinessError) => { 1323 console.error(`Failed to obtain all window layout info. Cause code: ${err.code}, message: ${err.message}`); 1324 }); 1325} catch (exception) { 1326 console.error(`Failed to obtain all window layout info. Cause code: ${exception.code}, message: ${exception.message}`); 1327} 1328``` 1329 1330## window.getGlobalWindowMode<sup>20+</sup> 1331 1332getGlobalWindowMode(displayId?: number): Promise<number> 1333 1334Obtains the window mode of the window that is in the foreground lifecycle on the specified screen. This API uses a promise to return the result. 1335 1336**Atomic service API**: This API can be used in atomic services since API version 20. 1337 1338**System capability**: SystemCapability.Window.SessionManager 1339 1340**Parameters** 1341 1342| Name| Type | Mandatory| Description | 1343| ------ | ---------- |----|---------------------------------------------------------------------------| 1344| displayId | number| No | Optional display ID, which is used to obtain the window mode information on the corresponding screen. This parameter must be an integer greater than or equal to 0. If it is less than 0, error code 1300016 is returned. If this parameter is not passed or is set to null or undefined, all screens are queried. If the specified screen does not exist, the return value is 0.| 1345 1346**Return value** 1347 1348| Type | Description | 1349| -------------------------------- |-------------------------| 1350| Promise<number> | Promise used to return the window mode. Each binary bit represents a window mode. For details about the supported window modes, see [GlobalWindowMode](#globalwindowmode20). The return value is the result of a bitwise OR operation on the corresponding window mode values. For example, if there are full-screen, floating, and PiP windows on the specified screen, the return value is `0b1\|0b100\|0b1000 = 13`.| | | 1351 1352**Error codes** 1353 1354For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1355 1356| ID | Error Message| 1357|----------| ------------------------------ | 1358| 801 | Capability not supported. function getGlobalWindowMode can not work correctly due to limited device capabilities. | 1359| 1300003 | This window manager service works abnormally. | 1360| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range. | 1361 1362```ts 1363import { window } from '@ohos.window'; 1364import { BusinessError } from '@kit.BasicServicesKit'; 1365 1366try { 1367 let displayId = 0; 1368 let promise = window.getGlobalWindowMode(displayId); 1369 promise.then((data) => { 1370 console.info(`Succeeded in obtaining global window mode. Data: ${data}`); 1371 }).catch((err: BusinessError) => { 1372 console.error(`Failed to obtain global window mode. Cause code: ${err.code}, message: ${err.message}`); 1373 }); 1374} catch (exception) { 1375 console.error(`Failed to obtain global window mode. Cause code: ${exception.code}, message: ${exception.message}`); 1376} 1377``` 1378 1379## window.create<sup>(deprecated)</sup> 1380 1381create(id: string, type: WindowType, callback: AsyncCallback<Window>): void 1382 1383Creates a child window. This API uses an asynchronous callback to return the result. 1384 1385> **NOTE** 1386> 1387> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 1388 1389**Model restriction**: This API can be used only in the FA model. 1390 1391**System capability**: SystemCapability.WindowManager.WindowManager.Core 1392 1393**Parameters** 1394 1395| Name | Type | Mandatory| Description | 1396| -------- | -------------------------------------- | ---- | ------------------------------------ | 1397| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1398| type | [WindowType](#windowtype7) | Yes | Window type. | 1399| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the child window created.| 1400 1401 1402**Example** 1403 1404```ts 1405import { BusinessError } from '@kit.BasicServicesKit'; 1406 1407let windowClass: window.Window | undefined = undefined; 1408window.create('test', window.WindowType.TYPE_APP, (err: BusinessError, data) => { 1409 const errCode: number = err.code; 1410 if (errCode) { 1411 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 1412 return; 1413 } 1414 windowClass = data; 1415 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 1416}); 1417``` 1418 1419## window.create<sup>(deprecated)</sup> 1420 1421create(id: string, type: WindowType): Promise<Window> 1422 1423Creates a child window. This API uses a promise to return the result. 1424 1425> **NOTE** 1426> 1427> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 1428 1429**Model restriction**: This API can be used only in the FA model. 1430 1431**System capability**: SystemCapability.WindowManager.WindowManager.Core 1432 1433**Parameters** 1434 1435| Name| Type | Mandatory| Description | 1436| ------ | ------------------------- | ---- | ---------- | 1437| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 1438| type | [WindowType](#windowtype7) | Yes | Window type.| 1439 1440**Return value** 1441 1442| Type | Description | 1443| -------------------------------- | --------------------------------------- | 1444| Promise<[Window](#window)> | Promise used to return the child window created.| 1445 1446 1447**Example** 1448 1449```ts 1450import { BusinessError } from '@kit.BasicServicesKit'; 1451 1452let windowClass: window.Window | undefined = undefined; 1453let promise = window.create('test', window.WindowType.TYPE_APP); 1454promise.then((data) => { 1455 windowClass = data; 1456 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 1457}).catch((err: BusinessError) => { 1458 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 1459}); 1460``` 1461 1462## window.create<sup>(deprecated)</sup> 1463 1464create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void 1465 1466Creates a system window. This API uses an asynchronous callback to return the result. 1467 1468> **NOTE** 1469> 1470> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 1471 1472**System capability**: SystemCapability.WindowManager.WindowManager.Core 1473 1474**Parameters** 1475 1476| Name | Type | Mandatory| Description | 1477| -------- | ------------------------------------------------------- | ---- | ------------------------------------ | 1478| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context. | 1479| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 1480| type | [WindowType](#windowtype7) | Yes | Window type. | 1481| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the child window created.| 1482 1483 1484**Example** 1485 1486```ts 1487import { BusinessError } from '@kit.BasicServicesKit'; 1488 1489let windowClass: window.Window | undefined = undefined; 1490window.create('test', window.WindowType.TYPE_SYSTEM_ALERT, (err: BusinessError, data) => { 1491 const errCode: number = err.code; 1492 if (errCode) { 1493 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 1494 return; 1495 } 1496 windowClass = data; 1497 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 1498 windowClass.resetSize(500, 1000); 1499}); 1500``` 1501 1502## window.create<sup>(deprecated)</sup> 1503 1504create(ctx: BaseContext, id: string, type: WindowType): Promise<Window> 1505 1506Creates a system window. This API uses a promise to return the result. 1507 1508> **NOTE** 1509> 1510> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 1511 1512**System capability**: SystemCapability.WindowManager.WindowManager.Core 1513 1514**Parameters** 1515 1516| Name| Type | Mandatory| Description | 1517| ------ | ------------------------- | ---- | ------------------------------------------------------------ | 1518| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1519| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1520| type | [WindowType](#windowtype7) | Yes | Window type. | 1521 1522**Return value** 1523 1524| Type | Description | 1525| -------------------------------- | --------------------------------------- | 1526| Promise<[Window](#window)> | Promise used to return the child window created.| 1527 1528 1529**Example** 1530 1531```ts 1532import { BusinessError } from '@kit.BasicServicesKit'; 1533 1534let windowClass: window.Window | undefined = undefined; 1535let promise = window.create('test', window.WindowType.TYPE_SYSTEM_ALERT); 1536promise.then((data) => { 1537 windowClass = data; 1538 console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); 1539}).catch((err: BusinessError) => { 1540 console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`); 1541}); 1542``` 1543 1544## window.find<sup>(deprecated)</sup> 1545 1546find(id: string, callback: AsyncCallback<Window>): void 1547 1548Finds a window based on the ID. This API uses an asynchronous callback to return the result. 1549 1550> **NOTE** 1551> 1552> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 1553 1554**System capability**: SystemCapability.WindowManager.WindowManager.Core 1555 1556**Parameters** 1557 1558| Name | Type | Mandatory| Description | 1559| -------- | -------------------------------------- | ---- | ------------------------------------ | 1560| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1561| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window found.| 1562 1563**Example** 1564 1565```ts 1566import { BusinessError } from '@kit.BasicServicesKit'; 1567 1568let windowClass: window.Window | undefined = undefined; 1569window.find('test', (err: BusinessError, data) => { 1570 const errCode: number = err.code; 1571 if (errCode) { 1572 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 1573 return; 1574 } 1575 windowClass = data; 1576 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 1577}); 1578``` 1579 1580## window.find<sup>(deprecated)</sup> 1581 1582find(id: string): Promise<Window> 1583 1584Finds a window based on the ID. This API uses a promise to return the result. 1585 1586> **NOTE** 1587> 1588> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 1589 1590**System capability**: SystemCapability.WindowManager.WindowManager.Core 1591 1592**Parameters** 1593 1594| Name| Type | Mandatory| Description | 1595| ------ | ------ | ---- | -------- | 1596| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1597 1598**Return value** 1599 1600| Type | Description | 1601| -------------------------------- | ------------------------------------- | 1602| Promise<[Window](#window)> | Promise used to return the window found.| 1603 1604**Example** 1605 1606```ts 1607import { BusinessError } from '@kit.BasicServicesKit'; 1608 1609let windowClass: window.Window | undefined = undefined; 1610let promise = window.find('test'); 1611promise.then((data) => { 1612 windowClass = data; 1613 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 1614}).catch((err: BusinessError) => { 1615 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 1616}); 1617``` 1618 1619## window.getTopWindow<sup>(deprecated)</sup> 1620 1621getTopWindow(callback: AsyncCallback<Window>): void 1622 1623Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 1624 1625> **NOTE** 1626> 1627> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 1628 1629**Model restriction**: This API can be used only in the FA model. 1630 1631**System capability**: SystemCapability.WindowManager.WindowManager.Core 1632 1633**Parameters** 1634 1635| Name | Type | Mandatory| Description | 1636| -------- | -------------------------------------- | ---- | -------------------------------------------- | 1637| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained.| 1638 1639**Example** 1640 1641```ts 1642import { BusinessError } from '@kit.BasicServicesKit'; 1643 1644let windowClass: window.Window | undefined = undefined; 1645window.getTopWindow((err: BusinessError, data) => { 1646 const errCode: number = err.code; 1647 if (errCode) { 1648 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1649 return; 1650 } 1651 windowClass = data; 1652 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1653}); 1654``` 1655 1656## window.getTopWindow<sup>(deprecated)</sup> 1657 1658getTopWindow(): Promise<Window> 1659 1660Obtains the top window of the current application. This API uses a promise to return the result. 1661 1662> **NOTE** 1663> 1664> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 1665 1666**Model restriction**: This API can be used only in the FA model. 1667 1668**System capability**: SystemCapability.WindowManager.WindowManager.Core 1669 1670**Return value** 1671 1672| Type | Description | 1673| -------------------------------- | ----------------------------------------------- | 1674| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1675 1676**Example** 1677 1678```ts 1679import { BusinessError } from '@kit.BasicServicesKit'; 1680 1681let windowClass: window.Window | undefined = undefined; 1682let promise = window.getTopWindow(); 1683promise.then((data)=> { 1684 windowClass = data; 1685 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1686}).catch((err: BusinessError)=>{ 1687 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1688}); 1689``` 1690 1691## window.getTopWindow<sup>(deprecated)</sup> 1692 1693getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 1694 1695Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 1696 1697> **NOTE** 1698> 1699> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 1700 1701**System capability**: SystemCapability.WindowManager.WindowManager.Core 1702 1703**Parameters** 1704 1705| Name | Type | Mandatory| Description | 1706| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1707| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1708| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. | 1709 1710**Example** 1711 1712```ts 1713// EntryAbility.ets 1714import { UIAbility } from '@kit.AbilityKit'; 1715import { BusinessError } from '@kit.BasicServicesKit'; 1716 1717export default class EntryAbility extends UIAbility { 1718 onWindowStageCreate(windowStage:window.WindowStage){ 1719 console.info('onWindowStageCreate'); 1720 let windowClass: window.Window | undefined = undefined; 1721 try { 1722 window.getTopWindow(this.context, (err: BusinessError, data) => { 1723 const errCode: number = err.code; 1724 if(errCode){ 1725 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1726 return ; 1727 } 1728 windowClass = data; 1729 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1730 }); 1731 } catch(error){ 1732 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1733 } 1734 } 1735} 1736``` 1737 1738## window.getTopWindow<sup>(deprecated)</sup> 1739 1740getTopWindow(ctx: BaseContext): Promise<Window> 1741 1742Obtains the top window of the current application. This API uses a promise to return the result. 1743 1744> **NOTE** 1745> 1746> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 1747 1748**System capability**: SystemCapability.WindowManager.WindowManager.Core 1749 1750**Parameters** 1751 1752| Name| Type | Mandatory| Description | 1753| ------ | ----------- | ---- | ------------------------------------------------------------ | 1754| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1755 1756**Return value** 1757 1758| Type | Description | 1759| -------------------------------- | ----------------------------------------------- | 1760| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1761 1762**Example** 1763 1764```ts 1765// EntryAbility.ets 1766import { UIAbility } from '@kit.AbilityKit'; 1767import { BusinessError } from '@kit.BasicServicesKit'; 1768 1769export default class EntryAbility extends UIAbility { 1770 onWindowStageCreate(windowStage:window.WindowStage) { 1771 console.info('onWindowStageCreate'); 1772 let windowClass: window.Window | undefined = undefined; 1773 let promise = window.getTopWindow(this.context); 1774 promise.then((data) => { 1775 windowClass = data; 1776 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1777 }).catch((error: BusinessError) => { 1778 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1779 }); 1780 } 1781} 1782``` 1783 1784## window.getVisibleWindowInfo<sup>18+</sup> 1785 1786getVisibleWindowInfo(): Promise<Array<WindowInfo>> 1787 1788Obtains information about visible main windows on the current screen. Visible main windows are main windows that are not returned to the background. This API uses a promise to return the result. 1789 1790**System capability**: SystemCapability.Window.SessionManager 1791 1792**Required permissions**: ohos.permission.VISIBLE_WINDOW_INFO 1793 1794**Return value** 1795 1796| Type| Description| 1797| ------------------- | ----------------------- | 1798| Promise<Array<[WindowInfo](#windowinfo18)>> | Promise used to return the information about visible windows.| 1799 1800**Error codes** 1801 1802For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1803 1804| ID| Error Message| 1805| ------- | ------------------------------ | 1806| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1807| 801 | Capability not supported. Function getVisibleWindowInfo can not work correctly due to limited device capabilities. | 1808| 1300003 | This window manager service works abnormally. | 1809 1810**Example** 1811 1812```ts 1813import { window } from '@kit.ArkUI'; 1814import { BusinessError } from '@kit.BasicServicesKit'; 1815 1816try { 1817 let promise = window.getVisibleWindowInfo(); 1818 promise.then((data) => { 1819 data.forEach(windowInfo=>{ 1820 console.info(`left:${windowInfo.rect.left}`); 1821 console.info(`top:${windowInfo.rect.top}`); 1822 console.info(`width:${windowInfo.rect.width}`); 1823 console.info(`height:${windowInfo.rect.height}`); 1824 console.info(`windowId:${windowInfo.windowId}`); 1825 console.info(`windowStatusType:${windowInfo.windowStatusType}`); 1826 console.info(`abilityName:${windowInfo.abilityName}`); 1827 console.info(`bundleName:${windowInfo.bundleName}`); 1828 console.info(`isFocused:${windowInfo.isFocused}`); 1829 }) 1830 }).catch((err: BusinessError) => { 1831 console.error('Failed to getWindowInfo. Cause: ' + JSON.stringify(err)); 1832 }); 1833} catch (exception) { 1834 console.error(`Failed to get visible window info. Cause code: ${exception.code}, message: ${exception.message}`); 1835} 1836``` 1837 1838## SpecificSystemBar<sup>11+</sup> 1839 1840type SpecificSystemBar = 'status' \| 'navigation' \| 'navigationIndicator' 1841 1842Defines the type of system bar that can be displayed or hidden. 1843 1844**System capability**: SystemCapability.Window.SessionManager 1845 1846**Atomic service API**: This API can be used in atomic services since API version 11. 1847 1848| Type | Description | 1849|------------|--------| 1850| 'status' | Status bar. | 1851| 'navigation' | <!--RP13--><!--RP13End-->Three-button navigation bar. | 1852| 'navigationIndicator' | Bottom navigation bar. <!--RP12-->OpenHarmony devices do not support this capability.<!--RP12End--> | 1853 1854## Window 1855 1856Represents a window instance, which is the basic unit managed by the window manager. 1857 1858In 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. 1859 1860### showWindow<sup>9+</sup> 1861 1862showWindow(callback: AsyncCallback<void>): void 1863 1864Shows this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application child window. For the main window of an application, this API moves it at the top when the main window is already displayed. 1865 1866**System capability**: SystemCapability.WindowManager.WindowManager.Core 1867 1868**Atomic service API**: This API can be used in atomic services since API version 11. 1869 1870**Parameters** 1871 1872| Name| Type| Mandatory| Description| 1873| -------- | ------------------------- | -- | --------- | 1874| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1875 1876**Error codes** 1877 1878For details about the error codes, see [Window Error Codes](errorcode-window.md). 1879 1880| ID| Error Message| 1881| ------- | ------------------------------ | 1882| 1300002 | This window state is abnormal. | 1883 1884**Example** 1885 1886```ts 1887import { BusinessError } from '@kit.BasicServicesKit'; 1888 1889windowClass.showWindow((err: BusinessError) => { 1890 const errCode: number = err.code; 1891 if (errCode) { 1892 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1893 return; 1894 } 1895 console.info('Succeeded in showing the window.'); 1896}); 1897``` 1898 1899### showWindow<sup>9+</sup> 1900 1901showWindow(): Promise<void> 1902 1903Shows this window. This API uses a promise to return the result. This API takes effect only for a system window or an application child window. For the main window of an application, this API moves it at the top when the main window is already displayed. 1904 1905**System capability**: SystemCapability.WindowManager.WindowManager.Core 1906 1907**Atomic service API**: This API can be used in atomic services since API version 11. 1908 1909**Return value** 1910 1911| Type| Description| 1912| ------------------- | ----------------------- | 1913| Promise<void> | Promise that returns no value.| 1914 1915**Error codes** 1916 1917For details about the error codes, see [Window Error Codes](errorcode-window.md). 1918 1919| ID| Error Message| 1920| ------- | ------------------------------ | 1921| 1300002 | This window state is abnormal. | 1922 1923**Example** 1924 1925```ts 1926import { BusinessError } from '@kit.BasicServicesKit'; 1927 1928let promise = windowClass.showWindow(); 1929promise.then(() => { 1930 console.info('Succeeded in showing the window.'); 1931}).catch((err: BusinessError) => { 1932 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1933}); 1934``` 1935 1936### showWindow<sup>20+</sup> 1937 1938showWindow(options: ShowWindowOptions): Promise<void> 1939 1940Shows this window. This API uses a promise to return the result. This API takes effect only for a system window or an application child window. For the main window of an application, this API moves it at the top when the main window is already displayed. You can pass parameters to control the window display behavior. 1941 1942**System capability**: SystemCapability.WindowManager.WindowManager 1943 1944**Atomic service API**: This API can be used in atomic services since API version 20. 1945 1946**Return value** 1947 1948| Type| Description| 1949| ------------------- | ----------------------- | 1950| Promise<void> | Promise that returns no value.| 1951 1952**Error codes** 1953 1954For details about the error codes, see [Window Error Codes](errorcode-window.md). 1955 1956| ID| Error Message| 1957| ------- | ------------------------------ | 1958| 801 | Capability not supported. Function showWindow can not work correctly due to limited device capabilities. | 1959| 1300002 | This window state is abnormal. | 1960| 1300004 | Unauthorized operation. | 1961| 1300016 | Parameter validation error. Possible cause: 1. The value of the parameter is out of the allowed range; 2. The length of the parameter exceeds the allowed length; 3. The parameter format is incorrect. | 1962 1963**Example** 1964 1965```ts 1966// EntryAbility.ets 1967import { window } from '@kit.ArkUI'; 1968import { UIAbility } from '@kit.AbilityKit'; 1969import { BusinessError } from '@kit.BasicServicesKit'; 1970 1971export default class EntryAbility extends UIAbility { 1972 onWindowStageCreate(windowStage: window.WindowStage): void { 1973 console.info('onWindowStageCreate'); 1974 // Create a child window. 1975 try { 1976 windowStage.createSubWindow('subWindow').then((data) => { 1977 if (data == null) { 1978 console.error('Failed to create the sub window. Cause: The data is empty'); 1979 return; 1980 } 1981 let options: window.ShowWindowOptions = { 1982 focusOnShow: false 1983 }; 1984 try { 1985 data.showWindow(options).then(() => { 1986 console.info('Succeeded in showing window'); 1987 }).catch((err: BusinessError) => { 1988 console.error(`Failed to show window. Cause code: ${err.code}, message: ${err.message}`); 1989 }); 1990 } catch (exception) { 1991 console.error(`Failed to show window. Cause code: ${exception.code}, message: ${exception.message}`); 1992 } 1993 }); 1994 } catch (exception) { 1995 console.error(`Failed to create the sub window. Cause code: ${exception.code}, message: ${exception.message}`); 1996 } 1997 } 1998} 1999``` 2000 2001### destroyWindow<sup>9+</sup> 2002 2003destroyWindow(callback: AsyncCallback<void>): void 2004 2005Destroys this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application child window. 2006 2007**System capability**: SystemCapability.WindowManager.WindowManager.Core 2008 2009**Atomic service API**: This API can be used in atomic services since API version 11. 2010 2011**Parameters** 2012 2013| Name| Type| Mandatory| Description| 2014| -------- | ------------------------- | -- | --------- | 2015| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 2016 2017**Error codes** 2018 2019For details about the error codes, see [Window Error Codes](errorcode-window.md). 2020 2021| ID| Error Message| 2022| ------- | -------------------------------------------- | 2023| 1300002 | This window state is abnormal. | 2024 2025**Example** 2026 2027```ts 2028import { BusinessError } from '@kit.BasicServicesKit'; 2029 2030windowClass.destroyWindow((err) => { 2031 const errCode: number = err.code; 2032 if (errCode) { 2033 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 2034 return; 2035 } 2036 console.info('Succeeded in destroying the window.'); 2037}); 2038``` 2039 2040### destroyWindow<sup>9+</sup> 2041 2042destroyWindow(): Promise<void> 2043 2044Destroys this window. This API uses a promise to return the result. This API takes effect only for a system window or an application child window. 2045 2046**System capability**: SystemCapability.WindowManager.WindowManager.Core 2047 2048**Atomic service API**: This API can be used in atomic services since API version 11. 2049 2050**Return value** 2051 2052| Type| Description| 2053| ------------------- | ------------------------ | 2054| Promise<void> | Promise that returns no value.| 2055 2056**Error codes** 2057 2058For details about the error codes, see [Window Error Codes](errorcode-window.md). 2059 2060| ID| Error Message| 2061| ------- | -------------------------------------------- | 2062| 1300002 | This window state is abnormal. | 2063 2064**Example** 2065 2066```ts 2067import { BusinessError } from '@kit.BasicServicesKit'; 2068 2069let promise = windowClass.destroyWindow(); 2070promise.then(() => { 2071 console.info('Succeeded in destroying the window.'); 2072}).catch((err: BusinessError) => { 2073 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 2074}); 2075``` 2076 2077### moveWindowTo<sup>9+</sup> 2078 2079moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void 2080 2081Moves this window. This API uses an asynchronous callback to return the result. 2082 2083<!--RP4--> 2084In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 2085 2086On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 2087 2088**System capability**: SystemCapability.WindowManager.WindowManager.Core 2089 2090**Atomic service API**: This API can be used in atomic services since API version 11. 2091 2092**Parameters** 2093 2094| Name| Type| Mandatory| Description| 2095| -------- | ------------------------- | -- | --------------------------------------------- | 2096| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 2097| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 2098| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 2099 2100**Error codes** 2101 2102For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2103 2104| ID| Error Message| 2105| ------- | -------------------------------------------- | 2106| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2107| 1300002 | This window state is abnormal. | 2108| 1300003 | This window manager service works abnormally. | 2109 2110**Example** 2111 2112```ts 2113import { BusinessError } from '@kit.BasicServicesKit'; 2114 2115try { 2116 windowClass.moveWindowTo(300, 300, (err: BusinessError) => { 2117 const errCode: number = err.code; 2118 if (errCode) { 2119 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 2120 return; 2121 } 2122 console.info('Succeeded in moving the window.'); 2123 }); 2124} catch (exception) { 2125 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 2126} 2127``` 2128 2129### moveWindowTo<sup>9+</sup> 2130 2131moveWindowTo(x: number, y: number): Promise<void> 2132 2133Moves 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). 2134 2135<!--RP4--> 2136In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 2137 2138For this API, the window moves relative to the display on 2-in-1 devices and to the parent window on other devices. If you want to move the window relative to the display on non-2-in-1 devices, use the [moveWindowToGlobal()](#movewindowtoglobal15) API. 2139 2140**System capability**: SystemCapability.WindowManager.WindowManager.Core 2141 2142**Atomic service API**: This API can be used in atomic services since API version 11. 2143 2144**Parameters** 2145 2146| Name| Type| Mandatory| Description| 2147| -- | ----- | -- | --------------------------------------------- | 2148| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 2149| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 2150 2151**Return value** 2152 2153| Type| Description| 2154| ------------------- | ------------------------ | 2155| Promise<void> | Promise that returns no value.| 2156 2157**Error codes** 2158 2159For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2160 2161| ID| Error Message| 2162| ------- | -------------------------------------------- | 2163| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2164| 1300002 | This window state is abnormal. | 2165| 1300003 | This window manager service works abnormally. | 2166 2167**Example** 2168 2169```ts 2170import { BusinessError } from '@kit.BasicServicesKit'; 2171 2172try { 2173 let promise = windowClass.moveWindowTo(300, 300); 2174 promise.then(() => { 2175 console.info('Succeeded in moving the window.'); 2176 }).catch((err: BusinessError) => { 2177 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 2178 }); 2179} catch (exception) { 2180 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 2181} 2182``` 2183 2184### moveWindowToAsync<sup>12+</sup> 2185 2186moveWindowToAsync(x: number, y: number): Promise<void> 2187 2188Moves this window. This API uses a promise to return the result. 2189 2190A value is returned once the call takes effect. You can use [getWindowProperties()](#getwindowproperties9) in the callback (see the code snippet below) to obtain the final effect immediately. 2191 2192This API takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). 2193 2194On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 2195 2196**System capability**: SystemCapability.Window.SessionManager 2197 2198**Atomic service API**: This API can be used in atomic services since API version 12. 2199 2200**Parameters** 2201 2202| Name| Type| Mandatory| Description| 2203| -- | ----- | -- | --------------------------------------------- | 2204| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 2205| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 2206 2207**Return value** 2208 2209| Type| Description| 2210| ------------------- | ------------------------ | 2211| Promise<void> | Promise that returns no value.| 2212 2213**Error codes** 2214 2215For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2216 2217| ID| Error Message| 2218| ------- | -------------------------------------------- | 2219| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2220| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2221| 1300002 | This window state is abnormal. | 2222| 1300003 | This window manager service works abnormally. | 2223| 1300010 | The operation in the current window status is invalid. | 2224 2225**Example** 2226 2227```ts 2228import { BusinessError } from '@kit.BasicServicesKit'; 2229 2230try { 2231 let promise = windowClass.moveWindowToAsync(300, 300); 2232 promise.then(() => { 2233 console.info('Succeeded in moving the window.'); 2234 let rect = windowClass?.getWindowProperties().windowRect; 2235 console.info(`Get window rect: ` + JSON.stringify(rect)); 2236 }).catch((err: BusinessError) => { 2237 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 2238 }); 2239} catch (exception) { 2240 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 2241} 2242``` 2243 2244### moveWindowToAsync<sup>15+</sup> 2245 2246moveWindowToAsync(x: number, y: number, moveConfiguration?: MoveConfiguration): Promise<void> 2247 2248Moves this window. This API uses a promise to return the result. A value is returned once the call takes effect. You can use [getWindowProperties()](#getwindowproperties9) in the callback (see the code snippet below) to obtain the final effect immediately. 2249 2250This API takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). 2251 2252On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 2253 2254**System capability**: SystemCapability.Window.SessionManager 2255 2256**Atomic service API**: This API can be used in atomic services since API version 15. 2257 2258**Parameters** 2259 2260| Name| Type| Mandatory| Description| 2261| -- | ----- | -- | --------------------------------------------- | 2262| 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 non-integer is passed in, the value is rounded down.| 2263| 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 non-integer is passed in, the value is rounded down.| 2264| moveConfiguration | [MoveConfiguration](#moveconfiguration15) | No| Window movement configuration. If this parameter is not set, the window will stay on the current display.| 2265 2266**Return value** 2267 2268| Type| Description| 2269| ------------------- | ------------------------ | 2270| Promise<void> | Promise that returns no value.| 2271 2272**Error codes** 2273 2274For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2275 2276| ID| Error Message| 2277| ------- | -------------------------------------------- | 2278| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2279| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2280| 1300002 | This window state is abnormal. | 2281| 1300003 | This window manager service works abnormally. | 2282| 1300010 | The operation in the current window status is invalid. | 2283 2284**Example** 2285 2286```ts 2287import { window } from '@kit.ArkUI'; 2288import { BusinessError } from '@kit.BasicServicesKit'; 2289 2290try { 2291 let moveConfiguration: window.MoveConfiguration = { 2292 displayId: 0 2293 }; 2294 let promise = windowClass.moveWindowToAsync(300, 300, moveConfiguration); 2295 promise.then(() => { 2296 console.info('Succeeded in moving the window.'); 2297 let rect = windowClass?.getWindowProperties().windowRect; 2298 console.info(`Get window rect: ` + JSON.stringify(rect)); 2299 }).catch((err: BusinessError) => { 2300 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 2301 }); 2302} catch (exception) { 2303 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 2304} 2305``` 2306 2307### moveWindowToGlobal<sup>13+</sup> 2308 2309moveWindowToGlobal(x: number, y: number): Promise<void> 2310 2311Moves this window based on the coordinates. This API uses a promise to return the result. A value is returned once the call takes effect. You can use [getWindowProperties()](#getwindowproperties9) in the callback (see the code snippet below) to obtain the final effect immediately. 2312 2313This operation is not supported in a window in full-screen mode. 2314 2315On non-2-in-1 devices, the child window moves along with the main window. 2316 2317**System capability**: SystemCapability.Window.SessionManager 2318 2319**Atomic service API**: This API can be used in atomic services since API version 13. 2320 2321**Parameters** 2322 2323| Name| Type| Mandatory| Description| 2324| -- | ----- | -- | --------------------------------------------- | 2325| 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.| 2326| 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.| 2327 2328**Return value** 2329 2330| Type| Description| 2331| ------------------- | ------------------------ | 2332| Promise<void> | Promise that returns no value.| 2333 2334**Error codes** 2335 2336For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2337 2338| ID| Error Message| 2339| ------- | -------------------------------------------- | 2340| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2341| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2342| 1300002 | This window state is abnormal. | 2343| 1300003 | This window manager service works abnormally. | 2344| 1300010 | The operation in the current window status is invalid. | 2345 2346**Example** 2347 2348```ts 2349import { BusinessError } from '@kit.BasicServicesKit'; 2350 2351try { 2352 let promise = windowClass.moveWindowToGlobal(300, 300); 2353 promise.then(() => { 2354 console.info('Succeeded in moving the window.'); 2355 let rect = windowClass?.getWindowProperties().windowRect; 2356 console.info(`Get window rect: ` + JSON.stringify(rect)); 2357 }).catch((err: BusinessError) => { 2358 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 2359 }); 2360} catch (exception) { 2361 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 2362} 2363``` 2364 2365### moveWindowToGlobal<sup>15+</sup> 2366 2367moveWindowToGlobal(x: number, y: number, moveConfiguration?: MoveConfiguration): Promise<void> 2368 2369Moves this window based on the coordinates. This API uses a promise to return the result. A value is returned once the call takes effect. You can use [getWindowProperties()](#getwindowproperties9) in the callback (see the code snippet below) to obtain the final effect immediately. 2370 2371This operation is not supported in a window in full-screen mode. 2372 2373On non-2-in-1 devices, the child window moves along with the main window. 2374 2375**System capability**: SystemCapability.Window.SessionManager 2376 2377**Atomic service API**: This API can be used in atomic services since API version 15. 2378 2379**Parameters** 2380 2381| Name| Type| Mandatory| Description| 2382| -- | ----- | -- | --------------------------------------------- | 2383| x | number | Yes| Distance that the window moves along the x-axis, in px, with the upper left corner of the target 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.| 2384| y | number | Yes| Distance that the window moves along the y-axis, in px, with the upper left corner of the target 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.| 2385| moveConfiguration | [MoveConfiguration](#moveconfiguration15) | No| Window movement configuration. If this parameter is not set, the window will stay on the current display.| 2386 2387**Return value** 2388 2389| Type| Description| 2390| ------------------- | ------------------------ | 2391| Promise<void> | Promise that returns no value.| 2392 2393**Error codes** 2394 2395For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2396 2397| ID| Error Message| 2398| ------- | -------------------------------------------- | 2399| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2400| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2401| 1300002 | This window state is abnormal. | 2402| 1300003 | This window manager service works abnormally. | 2403| 1300010 | The operation in the current window status is invalid. | 2404 2405**Example** 2406 2407```ts 2408import { window } from '@kit.ArkUI'; 2409import { BusinessError } from '@kit.BasicServicesKit'; 2410 2411try { 2412 let moveConfiguration: window.MoveConfiguration = { 2413 displayId: 0 2414 }; 2415 let promise = windowClass.moveWindowToGlobal(300, 300, moveConfiguration); 2416 promise.then(() => { 2417 console.info('Succeeded in moving the window.'); 2418 let rect = windowClass?.getWindowProperties().windowRect; 2419 console.info(`Get window rect: ` + JSON.stringify(rect)); 2420 }).catch((err: BusinessError) => { 2421 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 2422 }); 2423} catch (exception) { 2424 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 2425} 2426``` 2427 2428### resize<sup>9+</sup> 2429 2430resize(width: number, height: number, callback: AsyncCallback<void>): void 2431 2432Changes the size of this window. This API uses an asynchronous callback to return the result. 2433 2434The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 2435 2436The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 2437 2438The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 2439 2440The window width and height you set must meet the limits. The rules are as follows: 2441- 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. 2442- 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. 2443 2444This operation is not supported in a window in full-screen mode. 2445 2446**System capability**: SystemCapability.WindowManager.WindowManager.Core 2447 2448**Atomic service API**: This API can be used in atomic services since API version 11. 2449 2450**Parameters** 2451 2452| Name| Type| Mandatory| Description| 2453| -------- | ------------------------- | -- | ------------------------ | 2454| 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.| 2455| 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.| 2456| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 2457 2458**Error codes** 2459 2460For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2461 2462| ID| Error Message| 2463| ------- | -------------------------------------------- | 2464| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2465| 1300002 | This window state is abnormal. | 2466| 1300003 | This window manager service works abnormally. | 2467 2468**Example** 2469 2470```ts 2471import { BusinessError } from '@kit.BasicServicesKit'; 2472 2473try { 2474 windowClass.resize(500, 1000, (err: BusinessError) => { 2475 const errCode: number = err.code; 2476 if (errCode) { 2477 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 2478 return; 2479 } 2480 console.info('Succeeded in changing the window size.'); 2481 }); 2482} catch (exception) { 2483 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 2484} 2485``` 2486 2487### resize<sup>9+</sup> 2488 2489resize(width: number, height: number): Promise<void> 2490 2491Changes the size of this window. This API uses a promise to return the result. 2492 2493A 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). 2494 2495The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 2496 2497The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 2498 2499The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 2500 2501The window width and height you set must meet the limits. The rules are as follows: 2502- 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. 2503- 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. 2504 2505This operation is not supported in a window in full-screen mode. 2506 2507**System capability**: SystemCapability.WindowManager.WindowManager.Core 2508 2509**Atomic service API**: This API can be used in atomic services since API version 11. 2510 2511**Parameters** 2512 2513| Name| Type| Mandatory| Description| 2514| ------ | ------ | -- | ------------------------ | 2515| 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.| 2516| 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.| 2517 2518**Return value** 2519 2520| Type| Description| 2521| ------------------- | ------------------------ | 2522| Promise<void> | Promise that returns no value.| 2523 2524**Error codes** 2525 2526For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2527 2528| ID| Error Message| 2529| ------- | -------------------------------------------- | 2530| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2531| 1300002 | This window state is abnormal. | 2532| 1300003 | This window manager service works abnormally. | 2533 2534**Example** 2535 2536```ts 2537import { BusinessError } from '@kit.BasicServicesKit'; 2538 2539try { 2540 let promise = windowClass.resize(500, 1000); 2541 promise.then(() => { 2542 console.info('Succeeded in changing the window size.'); 2543 }).catch((err: BusinessError) => { 2544 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 2545 }); 2546} catch (exception) { 2547 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 2548} 2549``` 2550 2551### resizeAsync<sup>12+</sup> 2552 2553resizeAsync(width: number, height: number): Promise<void> 2554 2555Changes the size of this window. This API uses a promise to return the result. 2556 2557A value is returned once the call takes effect. You can use [getWindowProperties()](#getwindowproperties9) in the callback (see the code snippet below) to obtain the final effect immediately. 2558 2559The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 2560 2561The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 2562 2563The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 2564 2565The window width and height you set must meet the limits. The rules are as follows: 2566 2567- 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. 2568- 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. 2569 2570This operation is not supported in a window in full-screen mode. 2571 2572**System capability**: SystemCapability.Window.SessionManager 2573 2574**Atomic service API**: This API can be used in atomic services since API version 12. 2575 2576**Parameters** 2577 2578| Name| Type| Mandatory| Description| 2579| ------ | ------ | -- | ------------------------ | 2580| 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.| 2581| 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.| 2582 2583**Return value** 2584 2585| Type| Description| 2586| ------------------- | ------------------------ | 2587| Promise<void> | Promise that returns no value.| 2588 2589**Error codes** 2590 2591For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2592 2593| ID| Error Message| 2594| ------- | -------------------------------------------- | 2595| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2596| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2597| 1300002 | This window state is abnormal. | 2598| 1300003 | This window manager service works abnormally. | 2599| 1300010 | The operation in the current window status is invalid. | 2600 2601**Example** 2602 2603```ts 2604import { BusinessError } from '@kit.BasicServicesKit'; 2605 2606try { 2607 let promise = windowClass.resizeAsync(500, 1000); 2608 promise.then(() => { 2609 console.info('Succeeded in changing the window size.'); 2610 let rect = windowClass?.getWindowProperties().windowRect; 2611 console.info(`Get window rect: ` + JSON.stringify(rect)); 2612 }).catch((err: BusinessError) => { 2613 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 2614 }); 2615} catch (exception) { 2616 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 2617} 2618``` 2619 2620### getWindowProperties<sup>9+</sup> 2621 2622getWindowProperties(): WindowProperties 2623 2624Obtains the properties of this window. 2625 2626**System capability**: SystemCapability.WindowManager.WindowManager.Core 2627 2628**Atomic service API**: This API can be used in atomic services since API version 11. 2629 2630**Return value** 2631 2632| Type| Description| 2633| ------------------------------------- | ------------- | 2634| [WindowProperties](#windowproperties) | Window properties obtained.| 2635 2636**Error codes** 2637 2638For details about the error codes, see [Window Error Codes](errorcode-window.md). 2639 2640| ID| Error Message| 2641| ------- | ------------------------------ | 2642| 1300002 | This window state is abnormal. | 2643 2644**Example** 2645 2646```ts 2647try { 2648 let properties = windowClass.getWindowProperties(); 2649} catch (exception) { 2650 console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`); 2651} 2652``` 2653 2654### getWindowDensityInfo<sup>15+</sup> 2655 2656getWindowDensityInfo(): WindowDensityInfo 2657 2658Obtains the display density information of this window. 2659 2660**System capability**: SystemCapability.Window.SessionManager 2661 2662**Atomic service API**: This API can be used in atomic services since API version 15. 2663 2664**Return value** 2665 2666| Type| Description| 2667| ------------------------------------- | ------------- | 2668| [WindowDensityInfo](#windowdensityinfo15) | Display density information of the window. If the return value is [-1, -1, -1], the current device does not support this API.| 2669 2670**Error codes** 2671 2672For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2673 2674| ID| Error Message| 2675| ------- | ------------------------------ | 2676| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2677| 1300002 | This window state is abnormal. | 2678 2679**Example** 2680 2681```ts 2682try { 2683 let densityInfo = windowClass.getWindowDensityInfo(); 2684} catch (exception) { 2685 console.error(`Failed to obtain the window densityInfo. Cause code: ${exception.code}, message: ${exception.message}`); 2686} 2687``` 2688 2689### getGlobalRect<sup>13+</sup> 2690 2691getGlobalRect(): Rect 2692 2693Obtains the actual display area of this window on the screen. This API returns the result synchronously. 2694 2695This API can determine the actual on-screen location and size of a window that has been resized on certain devices. 2696 2697**System capability**: SystemCapability.Window.SessionManager 2698 2699**Atomic service API**: This API can be used in atomic services since API version 13. 2700 2701**Return value** 2702 2703| Type| Description| 2704| ------------------- | ------------------------ | 2705| [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.| 2706 2707**Error codes** 2708 2709For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2710 2711| ID| Error Message| 2712| ------- | -------------------------------------------- | 2713| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2714| 1300002 | This window state is abnormal. | 2715| 1300003 | This window manager service works abnormally. | 2716 2717**Example** 2718 2719```ts 2720try { 2721 let rect = windowClass.getGlobalRect(); 2722 console.info(`Succeeded in getting window rect: ` + JSON.stringify(rect)); 2723} catch (exception) { 2724 console.error(`Failed to get window rect. Cause code: ${exception.code}, message: ${exception.message}`); 2725} 2726``` 2727 2728### getWindowAvoidArea<sup>9+</sup> 2729 2730getWindowAvoidArea(type: AvoidAreaType): AvoidArea 2731 2732Obtains the avoid area of this application window, for example, the system bar area, notch, gesture area, and soft keyboard area. 2733 2734This API is typically used in three scenarios: 1. In the **onWindowStageCreate** callback, this API can be used to obtain the avoid area in the initial layout during application startup. 2. When a child window needs to be temporarily displayed and requires layout adjustments for the content, this API can be used. 3. After you create a floating window, modal window, or system window (**WindowType** is a system window) and call [setSystemAvoidAreaEnabled](#setsystemavoidareaenabled18) to enable the such window to access the avoid area, this API can be used. 2735 2736**System capability**: SystemCapability.WindowManager.WindowManager.Core 2737 2738**Atomic service API**: This API can be used in atomic services since API version 11. 2739 2740**Parameters** 2741 2742| Name| Type| Mandatory| Description| 2743| ---- |----------------------------------| -- | ------------------------------------------------------------ | 2744| type | [AvoidAreaType](#avoidareatype7) | Yes| Type of the area.| 2745 2746**Return value** 2747 2748| Type| Description| 2749|--------------------------| ----------------- | 2750| [AvoidArea](#avoidarea7) | Area where the window cannot be displayed.| 2751 2752**Error codes** 2753 2754For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2755 2756| ID| Error Message| 2757| ------- | ------------------------------ | 2758| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2759| 1300002 | This window state is abnormal. | 2760 2761**Example** 2762 2763```ts 2764let type = window.AvoidAreaType.TYPE_SYSTEM; 2765try { 2766 let avoidArea = windowClass.getWindowAvoidArea(type); 2767} catch (exception) { 2768 console.error(`Failed to obtain the area. Cause code: ${exception.code}, message: ${exception.message}`); 2769} 2770``` 2771 2772### setSystemAvoidAreaEnabled<sup>18+</sup> 2773 2774setSystemAvoidAreaEnabled(enabled: boolean): Promise<void> 2775 2776Enables the window to access the [avoid area](#avoidarea7) when you create a floating window, modal window, or system window (**WindowType** is a system window). 2777 2778This API is particularly useful in the following scenario: After creating the aforementioned types of windows, you should call this API to enable the window to access the avoid area before calling [getWindowAvoidArea()](#getwindowavoidarea9) or [on('avoidAreaChange')](#onavoidareachange9) to obtain the avoid area or listen for changes in the avoid area. 2779 2780**System capability**: SystemCapability.Window.SessionManager 2781 2782**Atomic service API**: This API can be used in atomic services since API version 18. 2783 2784**Parameters** 2785 2786| Name| Type| Mandatory| Description| 2787| ---- |----------------------------------| -- | ------------------------------------------------------------ | 2788| enabled | boolean | Yes| Whether the window is enabled to access the avoid area.<br>The value **true** means to enable the window to access the avoid area, and **false** means the opposite. The default value is **false**.| 2789 2790**Error codes** 2791 2792For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2793 2794| ID| Error Message| 2795| ------- | ------------------------------ | 2796| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2797| 1300002 | This window state is abnormal. | 2798| 1300003 | This window manager service works abnormally. | 2799| 1300004 | Unauthorized operation. | 2800 2801**Example** 2802 2803```ts 2804import { BusinessError } from '@kit.BasicServicesKit'; 2805 2806let windowClass: window.Window | undefined = undefined; 2807let config: window.Configuration = { 2808 name: "test", 2809 windowType: window.WindowType.TYPE_DIALOG, 2810 decorEnabled: true, 2811 ctx: this.context 2812}; 2813try { 2814 window.createWindow(config, (err: BusinessError, data) => { 2815 const errCode: number = err.code; 2816 if (errCode) { 2817 console.error(`Failed to create the system window. Cause code: ${err.code}, message: ${err.message}`); 2818 return; 2819 } 2820 windowClass = data; 2821 windowClass.setUIContent("pages/Test"); 2822 let enabled = true; 2823 let promise = windowClass.setSystemAvoidAreaEnabled(enabled); 2824 promise.then(() => { 2825 let type = window.AvoidAreaType.TYPE_SYSTEM; 2826 let avoidArea = windowClass?.getWindowAvoidArea(type); 2827 }).catch((err: BusinessError) => { 2828 console.error(`Failed to obtain the system window avoid area. Cause code: ${err.code}, message: ${err.message}`); 2829 }); 2830 }); 2831} catch (exception) { 2832 console.error(`Failed to create the system window. Cause code: ${exception.code}, message: ${exception.message}`); 2833} 2834``` 2835 2836### isSystemAvoidAreaEnabled<sup>18+</sup> 2837 2838isSystemAvoidAreaEnabled(): boolean 2839 2840Checks whether a floating window, modal window, or system window (**WindowType** is a system window) is enabled to access the [avoid area](#avoidarea7). 2841 2842**System capability**: SystemCapability.Window.SessionManager 2843 2844**Atomic service API**: This API can be used in atomic services since API version 18. 2845 2846**Return value** 2847 2848| Type| Description| 2849| ------------------------------------- | ------------- | 2850| boolean | Check result.<br>The value **true** means that the window is enabled to access the avoid area, and **false** means the opposite.| 2851 2852**Error codes** 2853 2854For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2855 2856| ID| Error Message| 2857| ------- | ------------------------------ | 2858| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2859| 1300002 | This window state is abnormal. | 2860| 1300003 | This window manager service works abnormally. | 2861| 1300004 | Unauthorized operation. | 2862 2863**Example** 2864 2865```ts 2866import { BusinessError } from '@kit.BasicServicesKit'; 2867 2868let windowClass: window.Window | undefined = undefined; 2869let config: window.Configuration = { 2870 name: "test", 2871 windowType: window.WindowType.TYPE_DIALOG, 2872 decorEnabled: true, 2873 ctx: this.context 2874}; 2875try { 2876 window.createWindow(config, (err: BusinessError, data) => { 2877 const errCode: number = err.code; 2878 if (errCode) { 2879 console.error(`Failed to create the system window. Cause code: ${err.code}, message: ${err.message}`); 2880 return; 2881 } 2882 windowClass = data; 2883 windowClass.setUIContent("pages/Test"); 2884 let enabled = true; 2885 let promise = windowClass.setSystemAvoidAreaEnabled(enabled); 2886 promise.then(() => { 2887 let enable = windowClass?.isSystemAvoidAreaEnabled(); 2888 }).catch((err: BusinessError) => { 2889 console.error(`Failed to obtain whether the system window can get avoid area. Cause code: ${err.code}, message: ${err.message}`); 2890 }); 2891 }); 2892} catch (exception) { 2893 console.error(`Failed to create the system window. Cause code: ${exception.code}, message: ${exception.message}`); 2894} 2895``` 2896 2897### setTitleAndDockHoverShown<sup>14+</sup> 2898 2899setTitleAndDockHoverShown(isTitleHoverShown?: boolean, isDockHoverShown?: boolean): Promise<void> 2900 2901Sets 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. 2902 2903**System capability**: SystemCapability.Window.SessionManager 2904 2905**Atomic service API**: This API can be used in atomic services since API version 14. 2906 2907**Parameters** 2908 2909| Name | Type | Mandatory| Description | 2910| ---------- | ------- | ---- | ------------------------------------------------------------ | 2911| isTitleHoverShown | boolean | No | Whether to show the window title bar.<br>The value **true** means to show the window title bar, and **false** means the opposite. The default value is **true**.<br>| 2912| isDockHoverShown | boolean | No | Whether to show the dock bar.<br>The value **true** means to show the dock bar, and **false** means the opposite. The default value is **true**.<br>| 2913 2914**Error codes** 2915 2916For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2917 2918| ID| Error Message| 2919| ------- | -------------------------------------------- | 2920| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2921| 1300002 | This window state is abnormal. | 2922| 1300004 | Unauthorized operation. | 2923 2924**Example** 2925 2926```ts 2927// EntryAbility.ets 2928import { UIAbility } from '@kit.AbilityKit'; 2929import { BusinessError } from '@kit.BasicServicesKit'; 2930import { window } from '@kit.ArkUI'; 2931 2932export default class EntryAbility extends UIAbility { 2933 // ... 2934 onWindowStageCreate(windowStage: window.WindowStage): void { 2935 // Load the page corresponding to the main window. 2936 windowStage.loadContent('pages/Index', (err) => { 2937 let mainWindow: window.Window | undefined = undefined; 2938 // Obtain the main window. 2939 windowStage.getMainWindow().then( 2940 data => { 2941 mainWindow = data; 2942 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 2943 // Call maximize to enable the full-screen mode for the window. 2944 mainWindow.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 2945 // Call setTitleAndDockHoverShown to hide the window title bar and dock bar. 2946 mainWindow.setTitleAndDockHoverShown(false, false); 2947 } 2948 ).catch((err: BusinessError) => { 2949 if(err.code){ 2950 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2951 } 2952 }); 2953 }); 2954 } 2955} 2956``` 2957 2958### setWindowLayoutFullScreen<sup>9+</sup> 2959 2960setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 2961 2962Sets whether the main window layout or the child window layout is immersive. This API uses a promise to return the result. <!--RP8-->From API version 14, this API does not take effect on 2-in-1 devices.<!--RP8End--> 2963- An immersive layout means that the layout does not avoid the status bar or <!--RP15-->three-button navigation bar<!--RP15End-->, and components may overlap with them. 2964- A non-immersive layout means that the layout avoids the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->, and components do not overlap with them. 2965 2966**System capability**: SystemCapability.WindowManager.WindowManager.Core 2967 2968**Atomic service API**: This API can be used in atomic services since API version 12. 2969 2970**Parameters** 2971 2972| Name| Type| Mandatory| Description| 2973| ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ | 2974| isLayoutFullScreen | boolean | Yes| Whether the layout of the window is immersive. (In immersive layout mode, the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> remain visible.) The value **true** means that the window layout is immersive, and **false** means the opposite.| 2975 2976**Return value** 2977 2978| Type| Description| 2979| ------------------- | ------------------------ | 2980| Promise<void> | Promise that returns no value.| 2981 2982**Error codes** 2983 2984For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2985 2986| ID| Error Message| 2987| ------- | -------------------------------------------- | 2988| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2989| 1300002 | This window state is abnormal. | 2990| 1300003 | This window manager service works abnormally. | 2991 2992**Example** 2993 2994```ts 2995// EntryAbility.ets 2996import { UIAbility } from '@kit.AbilityKit'; 2997import { BusinessError } from '@kit.BasicServicesKit'; 2998 2999export default class EntryAbility extends UIAbility { 3000 // ... 3001 onWindowStageCreate(windowStage: window.WindowStage): void { 3002 console.info('onWindowStageCreate'); 3003 let windowClass: window.Window | undefined = undefined; 3004 windowStage.getMainWindow((err: BusinessError, data) => { 3005 const errCode: number = err.code; 3006 if (errCode) { 3007 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3008 return; 3009 } 3010 windowClass = data; 3011 let isLayoutFullScreen = true; 3012 try { 3013 let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen); 3014 promise.then(() => { 3015 console.info('Succeeded in setting the window layout to full-screen mode.'); 3016 }).catch((err: BusinessError) => { 3017 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 3018 }); 3019 } catch (exception) { 3020 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 3021 } 3022 }); 3023 } 3024} 3025``` 3026 3027### setImmersiveModeEnabledState<sup>12+</sup> 3028 3029setImmersiveModeEnabledState(enabled: boolean): void 3030 3031Sets whether to enable the immersive layout for the main window. This API does not change the window mode or size. <!--RP8-->From API version 14, this API does not take effect on 2-in-1 devices.<!--RP8End--> 3032 3033**System capability**: SystemCapability.WindowManager.WindowManager.Core 3034 3035**Atomic service API**: This API can be used in atomic services since API version 12. 3036 3037**Parameters** 3038 3039| Name | Type | Mandatory| Description | 3040| ---------- | ------- | ---- | ------------------------------------------------------------ | 3041| enabled | boolean | Yes | Whether to enable the immersive layout.<br>The value **true** means to enable the immersive layout, and **false** means the opposite.| 3042 3043**Error codes** 3044 3045For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3046 3047| ID| Error Message| 3048| ------- | -------------------------------------------- | 3049| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3050| 1300002 | This window state is abnormal. | 3051| 1300003 | This window manager service works abnormally. | 3052| 1300004 | Unauthorized operation. | 3053 3054**Example** 3055 3056```ts 3057try { 3058 let enabled = false; 3059 windowClass.setImmersiveModeEnabledState(enabled); 3060} catch (exception) { 3061 console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 3062} 3063``` 3064 3065### getImmersiveModeEnabledState<sup>12+</sup> 3066 3067getImmersiveModeEnabledState(): boolean 3068 3069Checks whether the immersive layout is enabled for this window. 3070 3071**System capability**: SystemCapability.WindowManager.WindowManager.Core 3072 3073**Atomic service API**: This API can be used in atomic services since API version 12. 3074 3075**Return value** 3076| Type | Description | 3077| ------- | ------------------------------------------------------------------------------------ | 3078| boolean | Result indicating whether the immersive layout is enabled.<br>The value **true** means that the immersive layout is enabled, and **false** means the opposite.| 3079 3080**Error codes** 3081 3082For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3083 3084| ID| Error Message| 3085| -------- | -------------------------------------------- | 3086| 1300002 | This window state is abnormal. | 3087| 1300003 | This window manager service works abnormally. | 3088| 1300004 | Unauthorized operation. | 3089 3090**Example** 3091 3092```ts 3093try { 3094 let isEnabled = windowClass.getImmersiveModeEnabledState(); 3095} catch (exception) { 3096 console.error(`Failed to get the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 3097} 3098``` 3099 3100### setWindowDelayRaiseOnDrag<sup>19+</sup> 3101 3102setWindowDelayRaiseOnDrag(isEnabled: boolean): void 3103 3104Sets whether to enable delayed raising for the window. This parameter takes effect only for the main window and child windows. 3105 3106If this API is not called or **false** is passed, the main window and child windows are raised immediately upon a left mouse button press by default. 3107 3108When this API is called to enable delayed raising, in cross-window drag-and-drop situations, the window that contains the draggable component does not raise until the left mouse button is released, rather than raising immediately when the button is pressed. 3109 3110<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 3111 3112**System capability**: SystemCapability.Window.SessionManager 3113 3114**Atomic service API**: This API can be used in atomic services since API version 19. 3115 3116**Parameters** 3117 3118| Name | Type | Mandatory| Description | 3119| ---------- | ------- | ---- | ------------------------------------------------------------ | 3120| isEnabled | boolean | Yes | Whether to enable delayed raising.<br>The value **true** means to enable delayed raising, and **false** means the opposite.| 3121 3122**Error codes** 3123 3124For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3125 3126| ID| Error Message| 3127| ------- | -------------------------------------------- | 3128| 801 | Capability not supported.function setWindowDelayRaiseOnDrag can not work correctly due to limited device capabilities. | 3129| 1300002 | This window state is abnormal. | 3130 3131**Example** 3132 3133```ts 3134try { 3135 windowClass.setWindowDelayRaiseOnDrag(true); 3136} catch (exception) { 3137 console.error(`Failed to set window delay raise. Cause code: ${exception.code}, message: ${exception.message}`); 3138} 3139``` 3140 3141### setWindowSystemBarEnable<sup>9+</sup> 3142 3143setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 3144 3145<!--RP14-->Sets whether to show the status bar and three-button navigation bar in the main window. The visibility of the status bar and three-button navigation bar is controlled by **status** and **navigation**, respectively.<!--RP14End--> This API uses a promise to return the result.<br>From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 3146 3147The return value does not indicate that the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> are shown or hidden. This API does not take effect when it is called by a child window. The configuration does not take effect in non-full-screen mode (such as floating window or split-screen mode). 3148 3149**Atomic service API**: This API can be used in atomic services since API version 12. 3150 3151**System capability**: SystemCapability.WindowManager.WindowManager.Core 3152 3153**Parameters** 3154 3155| Name| Type | Mandatory| Description| 3156| ----- | ---------------------------- | -- | --------------------------------- | 3157| names | Array<'status'\|'navigation'> | Yes| Whether to show the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> in full-screen mode.<br>For example, to show all of them, set this parameter to **['status', 'navigation']**. If this parameter is set to [], they are hidden.| 3158 3159**Return value** 3160 3161| Type| Description| 3162| ------------------- | ------------------------ | 3163| Promise<void> | Promise that returns no value.| 3164 3165**Error codes** 3166 3167For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3168 3169| ID| Error Message| 3170| ------- | -------------------------------------------- | 3171| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3172| 1300002 | This window state is abnormal. | 3173| 1300003 | This window manager service works abnormally. | 3174 3175**Example** 3176 3177```ts 3178// The following assumes that all of them are hidden. 3179// EntryAbility.ets 3180import { UIAbility } from '@kit.AbilityKit'; 3181import { BusinessError } from '@kit.BasicServicesKit'; 3182 3183export default class EntryAbility extends UIAbility { 3184 // ... 3185 onWindowStageCreate(windowStage: window.WindowStage): void { 3186 console.info('onWindowStageCreate'); 3187 let windowClass: window.Window | undefined = undefined; 3188 windowStage.getMainWindow((err: BusinessError, data) => { 3189 const errCode: number = err.code; 3190 if (errCode) { 3191 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3192 return; 3193 } 3194 windowClass = data; 3195 let names: Array<'status' | 'navigation'> = []; 3196 try { 3197 let promise = windowClass.setWindowSystemBarEnable(names); 3198 promise.then(() => { 3199 console.info('Succeeded in setting the system bar to be invisible.'); 3200 }).catch((err: BusinessError) => { 3201 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 3202 }); 3203 } catch (exception) { 3204 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 3205 } 3206 }); 3207 } 3208} 3209``` 3210 3211### setSpecificSystemBarEnabled<sup>11+</sup> 3212 3213setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void> 3214 3215Sets whether to show the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> of the main window. This API uses a promise to return the result.<br>From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 3216 3217The return value does not indicate that the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> are shown or hidden. This API does not take effect when it is called by a child window. The configuration does not take effect in non-full-screen mode (such as floating window or split-screen mode). 3218 3219**System capability**: SystemCapability.Window.SessionManager 3220 3221**Atomic service API**: This API can be used in atomic services since API version 11. 3222 3223**Parameters** 3224 3225| Name| Type | Mandatory| Description| 3226| ----- | ---------------------------- | -- | --------------------------------- | 3227| name | [SpecificSystemBar](#specificsystembar11) | Yes| Type of the system bar to be shown or hidden.| 3228| enable | boolean | Yes| Whether to show the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> in full-screen mode. The value **true** means to show them, and **false** means the opposite.| 3229| enableAnimation<sup>12+</sup> | boolean | No| Whether to enable animation when the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> status changes. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.| 3230 3231**Return value** 3232 3233| Type| Description| 3234| ------------------- | ------------------------ | 3235| Promise<void> | Promise that returns no value.| 3236 3237**Error codes** 3238 3239For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3240 3241| ID| Error Message| 3242| ------- | -------------------------------------------- | 3243| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3244| 1300002 | This window state is abnormal. | 3245| 1300003 | This window manager service works abnormally. | 3246 3247**Example** 3248 3249```ts 3250// Here, the status bar is hidden. 3251// EntryAbility.ets 3252import { UIAbility } from '@kit.AbilityKit'; 3253import { BusinessError } from '@kit.BasicServicesKit'; 3254 3255export default class EntryAbility extends UIAbility { 3256 // ... 3257 onWindowStageCreate(windowStage: window.WindowStage): void { 3258 console.info('onWindowStageCreate'); 3259 let windowClass: window.Window | undefined = undefined; 3260 windowStage.getMainWindow((err: BusinessError, data) => { 3261 const errCode: number = err.code; 3262 if (errCode) { 3263 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3264 return; 3265 } 3266 windowClass = data; 3267 try { 3268 let promise = windowClass.setSpecificSystemBarEnabled('status', false); 3269 promise.then(() => { 3270 console.info('Succeeded in setting the system bar to be invisible.'); 3271 }).catch((err: BusinessError) => { 3272 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 3273 }); 3274 } catch (exception) { 3275 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 3276 } 3277 }); 3278 } 3279} 3280``` 3281 3282### setWindowSystemBarProperties<sup>9+</sup> 3283 3284setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 3285 3286Sets the properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar of the main window. This API uses a promise to return the result. <!--RP5-->This API does not take effect on 2-in-1 devices.<!--RP5End--> 3287 3288This API does not take effect when it is called by a child window. 3289 3290**System capability**: SystemCapability.WindowManager.WindowManager.Core 3291 3292**Atomic service API**: This API can be used in atomic services since API version 12. 3293 3294**Parameters** 3295 3296| Name | Type | Mandatory| Description | 3297| ------------------- | ------------------------------------------- | ---- | ---------------------- | 3298| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar.| 3299 3300**Return value** 3301 3302| Type | Description | 3303| ------------------- | ------------------------- | 3304| Promise<void> | Promise that returns no value.| 3305 3306**Error codes** 3307 3308For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3309 3310| ID| Error Message| 3311| ------- | -------------------------------------------- | 3312| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3313| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3314| 1300002 | This window state is abnormal. | 3315| 1300003 | This window manager service works abnormally. | 3316 3317**Example** 3318 3319```ts 3320// EntryAbility.ets 3321import { UIAbility } from '@kit.AbilityKit'; 3322import { BusinessError } from '@kit.BasicServicesKit'; 3323 3324export default class EntryAbility extends UIAbility { 3325 // ... 3326 onWindowStageCreate(windowStage: window.WindowStage): void { 3327 console.info('onWindowStageCreate'); 3328 let windowClass: window.Window | undefined = undefined; 3329 windowStage.getMainWindow((err: BusinessError, data) => { 3330 const errCode: number = err.code; 3331 if (errCode) { 3332 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3333 return; 3334 } 3335 windowClass = data; 3336 let SystemBarProperties: window.SystemBarProperties = { 3337 statusBarColor: '#ff00ff', 3338 navigationBarColor: '#00ff00', 3339 // The following properties are supported since API version 8. 3340 statusBarContentColor: '#ffffff', 3341 navigationBarContentColor: '#00ffff' 3342 }; 3343 try { 3344 let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties); 3345 promise.then(() => { 3346 console.info('Succeeded in setting the system bar properties.'); 3347 }).catch((err: BusinessError) => { 3348 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 3349 }); 3350 } catch (exception) { 3351 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 3352 } 3353 }); 3354 } 3355} 3356``` 3357 3358### getWindowSystemBarProperties<sup>12+</sup> 3359 3360getWindowSystemBarProperties(): SystemBarProperties 3361 3362Obtains the properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar in the main window. 3363 3364**System capability**: SystemCapability.WindowManager.WindowManager.Core 3365 3366**Atomic service API**: This API can be used in atomic services since API version 12. 3367 3368**Return value** 3369 3370| Type| Description| 3371| ------------------------------------- | ------------- | 3372| [SystemBarProperties](#systembarproperties) | Properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar.| 3373 3374**Error codes** 3375 3376For details about the error codes, see [Window Error Codes](errorcode-window.md). 3377 3378| ID| Error Message| 3379| ------- | ------------------------------ | 3380| 1300002 | This window state is abnormal. | 3381| 1300003 | This window manager service works abnormally. | 3382| 1300004 | Unauthorized operation. | 3383 3384 3385**Example** 3386 3387```ts 3388// EntryAbility.ets 3389import { UIAbility } from '@kit.AbilityKit'; 3390import { BusinessError } from '@kit.BasicServicesKit'; 3391 3392export default class EntryAbility extends UIAbility { 3393 // ... 3394 3395 onWindowStageCreate(windowStage: window.WindowStage) { 3396 let windowClass: window.Window | undefined = undefined; 3397 windowStage.getMainWindow((err: BusinessError, data) => { 3398 const errCode: number = err.code; 3399 if (errCode) { 3400 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3401 return; 3402 } 3403 windowClass = data; 3404 try { 3405 let systemBarProperty = windowClass.getWindowSystemBarProperties(); 3406 console.info('Success in obtaining system bar properties. Property: ' + JSON.stringify(systemBarProperty)); 3407 } catch (err) { 3408 console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`); 3409 } 3410 }); 3411 } 3412}; 3413``` 3414 3415### setStatusBarColor<sup>18+</sup> 3416 3417setStatusBarColor(color: ColorMetrics): Promise<void> 3418 3419Sets the text color of the status bar in the main window. This API uses a promise to return the result. 3420 3421Setting the status bar text color is not supported for child windows. Calling this API on a child window will have no effect. This API has no effect on 2-in-1 devices. 3422 3423**System capability**: SystemCapability.Window.SessionManager 3424 3425**Atomic service API**: This API can be used in atomic services since API version 18. 3426 3427**Parameters** 3428 3429| Name | Type | Mandatory| Description | 3430| ------------------- | ------------------------------------------- | ---- | ---------------------- | 3431| color | [ColorMetrics](js-apis-arkui-graphics.md#colormetrics12) | Yes | Text color of the status bar.| 3432 3433**Return value** 3434 3435| Type | Description | 3436| ------------------- | ------------------------- | 3437| Promise<void> | Promise that returns no value.| 3438 3439**Error codes** 3440 3441For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3442 3443| ID| Error Message| 3444| ------- | -------------------------------------------- | 3445| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3446| 801 | Capability not supported on this device. | 3447| 1300002 | This window state is abnormal. | 3448| 1300003 | This window manager service works abnormally. | 3449 3450**Example** 3451 3452```ts 3453// EntryAbility.ets 3454import { UIAbility } from '@kit.AbilityKit'; 3455import { BusinessError } from '@kit.BasicServicesKit'; 3456import { ColorMetrics, window } from '@kit.ArkUI'; 3457 3458export default class EntryAbility extends UIAbility { 3459 // ... 3460 onWindowStageCreate(windowStage: window.WindowStage): void { 3461 console.info('onWindowStageCreate'); 3462 let windowClass: window.Window | undefined = undefined; 3463 windowStage.getMainWindow((err: BusinessError, data) => { 3464 const errCode: number = err.code; 3465 if (errCode) { 3466 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3467 return; 3468 } 3469 windowClass = data; 3470 try { 3471 let promise = windowClass.setStatusBarColor(ColorMetrics.numeric(0x112233)); 3472 promise.then(() => { 3473 console.info('Succeeded in setting the status bar color.'); 3474 }).catch((err: BusinessError) => { 3475 console.error(`Set the status bar color failed. Cause code: ${err.code}, message: ${err.message}`); 3476 }); 3477 } catch (exception) { 3478 console.error(`Failed to set the status bar color. Cause code: ${exception.code}, message: ${exception.message}`); 3479 } 3480 }); 3481 } 3482} 3483``` 3484 3485### getStatusBarProperty<sup>18+</sup> 3486 3487getStatusBarProperty(): StatusBarProperty 3488 3489Obtains the properties (for example, text color) of the status bar in the main window. 3490 3491Calling this API is not supported for child window and will cause error code 1300002. 3492 3493**System capability**: SystemCapability.Window.SessionManager 3494 3495**Atomic service API**: This API can be used in atomic services since API version 18. 3496 3497**Return value** 3498 3499| Type| Description| 3500| ------------------------------------- | ------------- | 3501| [StatusBarProperty](#statusbarproperty18) | Status bar properties, such as its color.| 3502 3503**Error codes** 3504 3505For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3506 3507| ID| Error Message| 3508| ------- | ------------------------------ | 3509| 801 | Capability not supported on this device. | 3510| 1300002 | This window state is abnormal. | 3511 3512**Example** 3513 3514```ts 3515// EntryAbility.ets 3516import { UIAbility } from '@kit.AbilityKit'; 3517import { BusinessError } from '@kit.BasicServicesKit'; 3518import { window } from '@kit.ArkUI'; 3519 3520export default class EntryAbility extends UIAbility { 3521 // ... 3522 onWindowStageCreate(windowStage: window.WindowStage) { 3523 let windowClass: window.Window | undefined = undefined; 3524 windowStage.getMainWindow((err: BusinessError, data) => { 3525 const errCode: number = err.code; 3526 if (errCode) { 3527 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3528 return; 3529 } 3530 windowClass = data; 3531 try { 3532 let statusBarProperty = windowClass.getStatusBarProperty(); 3533 console.info('Succeeded in obtaining system bar properties. Property: ' + JSON.stringify(statusBarProperty)); 3534 } catch (err) { 3535 console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`); 3536 } 3537 }); 3538 } 3539}; 3540``` 3541 3542### setPreferredOrientation<sup>9+</sup> 3543 3544setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 3545 3546Sets the preferred orientation for the main window. This API uses an asynchronous callback to return the result. <!--RP9-->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 child window mode.<!--RP9End--> 3547 3548**System capability**: SystemCapability.WindowManager.WindowManager.Core 3549 3550**Atomic service API**: This API can be used in atomic services since API version 11. 3551 3552**Parameters** 3553 3554| Name | Type | Mandatory| Description | 3555| ------------------- | ------------------------------------------- | ---- | ---------------------- | 3556| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 3557| 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.| 3558 3559**Error codes** 3560 3561For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3562 3563| ID| Error Message| 3564| ------- | ------------------------------ | 3565| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3566| 1300002 | This window state is abnormal. | 3567 3568**Example** 3569 3570```ts 3571// EntryAbility.ets 3572import { UIAbility } from '@kit.AbilityKit'; 3573import { BusinessError } from '@kit.BasicServicesKit'; 3574 3575export default class EntryAbility extends UIAbility { 3576 // ... 3577 onWindowStageCreate(windowStage: window.WindowStage): void { 3578 console.info('onWindowStageCreate'); 3579 let windowClass: window.Window | undefined = undefined; 3580 windowStage.getMainWindow((err: BusinessError, data) => { 3581 const errCode: number = err.code; 3582 if (errCode) { 3583 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3584 return; 3585 } 3586 windowClass = data; 3587 let orientation = window.Orientation.AUTO_ROTATION; 3588 try { 3589 windowClass.setPreferredOrientation(orientation, (err: BusinessError) => { 3590 const errCode: number = err.code; 3591 if (errCode) { 3592 console.error(`Failed to set window orientation. Cause code: ${err.code}, message: ${err.message}`); 3593 return; 3594 } 3595 console.info('Succeeded in setting window orientation.'); 3596 }); 3597 } catch (exception) { 3598 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 3599 } 3600 }); 3601 } 3602} 3603``` 3604 3605### setPreferredOrientation<sup>9+</sup> 3606 3607setPreferredOrientation(orientation: Orientation): Promise<void> 3608 3609Sets the preferred orientation for the main window. This API uses a promise to return the result. <!--RP9-->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 child window mode.<!--RP9End--> 3610 3611**System capability**: SystemCapability.WindowManager.WindowManager.Core 3612 3613**Atomic service API**: This API can be used in atomic services since API version 11. 3614 3615**Parameters** 3616 3617| Name | Type | Mandatory| Description | 3618| ------------------- | ------------------------------------------- | ---- | ---------------------- | 3619| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 3620 3621**Return value** 3622 3623| Type | Description | 3624| ------------------- | ------------------------- | 3625| Promise<void> | Promise that returns no value.| 3626 3627**Error codes** 3628 3629For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3630 3631| ID| Error Message| 3632| ------- | ------------------------------ | 3633| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3634| 1300002 | This window state is abnormal. | 3635 3636**Example** 3637 3638```ts 3639// EntryAbility.ets 3640import { UIAbility } from '@kit.AbilityKit'; 3641import { BusinessError } from '@kit.BasicServicesKit'; 3642 3643export default class EntryAbility extends UIAbility { 3644 // ... 3645 onWindowStageCreate(windowStage: window.WindowStage): void { 3646 console.info('onWindowStageCreate'); 3647 let windowClass: window.Window | undefined = undefined; 3648 windowStage.getMainWindow((err: BusinessError, data) => { 3649 const errCode: number = err.code; 3650 if (errCode) { 3651 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3652 return; 3653 } 3654 windowClass = data; 3655 let orientation = window.Orientation.AUTO_ROTATION; 3656 try { 3657 let promise = windowClass.setPreferredOrientation(orientation); 3658 promise.then(() => { 3659 console.info('Succeeded in setting the window orientation.'); 3660 }).catch((err: BusinessError) => { 3661 console.error(`Failed to set the window orientation. Cause code: ${err.code}, message: ${err.message}`); 3662 }); 3663 } catch (exception) { 3664 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 3665 } 3666 }); 3667 } 3668} 3669``` 3670 3671### getPreferredOrientation<sup>12+</sup> 3672 3673getPreferredOrientation(): Orientation 3674 3675Obtains the orientation of the main window. This API can be called only by the main window. 3676 3677**System capability**: SystemCapability.WindowManager.WindowManager.Core 3678 3679**Atomic service API**: This API can be used in atomic services since API version 12. 3680 3681**Return value** 3682 3683| Type| Description| 3684|------------------------------| ------------------ | 3685| [Orientation](#orientation9) | Orientation.| 3686 3687**Error codes** 3688 3689For details about the error codes, see [Window Error Codes](errorcode-window.md). 3690 3691| ID| Error Message| 3692| ------- | ------------------------------ | 3693| 1300002 | This window state is abnormal. | 3694 3695**Example** 3696 3697```ts 3698// EntryAbility.ets 3699import { UIAbility } from '@kit.AbilityKit'; 3700import { BusinessError } from '@kit.BasicServicesKit'; 3701export default class EntryAbility extends UIAbility { 3702 // ... 3703 3704 onWindowStageCreate(windowStage: window.WindowStage) { 3705 console.info('onWindowStageCreate'); 3706 let windowClass: window.Window | undefined = undefined; 3707 windowStage.getMainWindow((err: BusinessError, data) => { 3708 const errCode: number = err.code; 3709 if (errCode) { 3710 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3711 return; 3712 } 3713 windowClass = data; 3714 try { 3715 let orientation = windowClass.getPreferredOrientation(); 3716 } catch (exception) { 3717 console.error(`Failed to get window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 3718 } 3719 }); 3720 } 3721}; 3722``` 3723 3724### getUIContext<sup>10+</sup> 3725 3726getUIContext(): UIContext 3727 3728Obtain a **UIContext** instance. 3729 3730**Model restriction**: This API can be used only in the stage model. 3731 3732**System capability**: SystemCapability.WindowManager.WindowManager.Core 3733 3734**Atomic service API**: This API can be used in atomic services since API version 11. 3735 3736**Return value** 3737 3738| Type | Description | 3739| ---------- | ---------------------- | 3740| [UIContext](js-apis-arkui-UIContext.md#uicontext) | **UIContext** instance obtained.| 3741 3742**Error codes** 3743 3744For details about the error codes, see [Window Error Codes](errorcode-window.md). 3745 3746| ID| Error Message| 3747| ------- | ------------------------------ | 3748| 1300002 | This window state is abnormal. | 3749 3750**Example** 3751 3752```ts 3753// EntryAbility.ets 3754import { UIAbility } from '@kit.AbilityKit'; 3755import { window, UIContext } from '@kit.ArkUI'; 3756import { BusinessError } from '@kit.BasicServicesKit'; 3757 3758export default class EntryAbility extends UIAbility { 3759 onWindowStageCreate(windowStage: window.WindowStage) { 3760 // Load content for the main window. 3761 windowStage.loadContent("pages/page2", (err: BusinessError) => { 3762 let errCode: number = err.code; 3763 if (errCode) { 3764 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3765 return; 3766 } 3767 console.info('Succeeded in loading the content.'); 3768 // Obtain the main window. 3769 let windowClass: window.Window | undefined = undefined; 3770 windowStage.getMainWindow((err: BusinessError, data) => { 3771 let errCode: number = err.code; 3772 if (errCode) { 3773 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 3774 return; 3775 } 3776 windowClass = data; 3777 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 3778 // Obtain a UIContext instance. 3779 let uiContext: UIContext | null = null; 3780 uiContext = windowClass.getUIContext(); 3781 }); 3782 }); 3783 } 3784}; 3785``` 3786 3787### setUIContent<sup>9+</sup> 3788 3789setUIContent(path: string, callback: AsyncCallback<void>): void 3790 3791Loads 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. 3792 3793**System capability**: SystemCapability.WindowManager.WindowManager.Core 3794 3795**Atomic service API**: This API can be used in atomic services since API version 11. 3796 3797**Parameters** 3798 3799| Name| Type| Mandatory| Description| 3800| -------- | ------------------------- | -- | -------------------- | 3801| 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.| 3802| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 3803 3804**Error codes** 3805 3806For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3807 3808| ID| Error Message| 3809| ------- | -------------------------------------------- | 3810| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3811| 1300002 | This window state is abnormal. | 3812 3813**Example** 3814 3815```ts 3816import { BusinessError } from '@kit.BasicServicesKit'; 3817 3818try { 3819 windowClass.setUIContent('pages/page2/page3', (err: BusinessError) => { 3820 const errCode: number = err.code; 3821 if (errCode) { 3822 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3823 return; 3824 } 3825 console.info('Succeeded in loading the content.'); 3826 }); 3827} catch (exception) { 3828 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 3829} 3830``` 3831 3832### setUIContent<sup>9+</sup> 3833 3834setUIContent(path: string): Promise<void> 3835 3836Loads 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. 3837 3838**System capability**: SystemCapability.WindowManager.WindowManager.Core 3839 3840**Atomic service API**: This API can be used in atomic services since API version 11. 3841 3842**Parameters** 3843 3844| Name| Type| Mandatory| Description| 3845| ---- | ------ | -- | ------------------ | 3846| 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.| 3847 3848**Return value** 3849 3850| Type| Description| 3851| ------------------- | ------------------------ | 3852| Promise<void> | Promise that returns no value.| 3853 3854**Error codes** 3855 3856For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3857 3858| ID| Error Message| 3859| ------- | -------------------------------------------- | 3860| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3861| 1300002 | This window state is abnormal. | 3862 3863**Example** 3864 3865```ts 3866import { BusinessError } from '@kit.BasicServicesKit'; 3867 3868try { 3869 let promise = windowClass.setUIContent('pages/page2/page3'); 3870 promise.then(() => { 3871 console.info('Succeeded in loading the content.'); 3872 }).catch((err: BusinessError) => { 3873 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3874 }); 3875} catch (exception) { 3876 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 3877} 3878``` 3879 3880### loadContent<sup>9+</sup> 3881 3882loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 3883 3884Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3885 3886**Model restriction**: This API can be used only in the stage model. 3887 3888**System capability**: SystemCapability.WindowManager.WindowManager.Core 3889 3890**Atomic service API**: This API can be used in atomic services since API version 11. 3891 3892**Parameters** 3893 3894| Name | Type | Mandatory| Description | 3895| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 3896| 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.| 3897| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 3898| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 3899 3900**Error codes** 3901 3902For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3903 3904| ID| Error Message| 3905| ------- | -------------------------------------------- | 3906| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter.| 3907| 1300002 | This window state is abnormal. | 3908 3909**Example** 3910 3911```ts 3912import { BusinessError } from '@kit.BasicServicesKit'; 3913 3914let storage: LocalStorage = new LocalStorage(); 3915storage.setOrCreate('storageSimpleProp', 121); 3916windowClass.loadContent('pages/page2', storage, (err: BusinessError) => { 3917 const errCode: number = err.code; 3918 if (errCode) { 3919 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3920 return; 3921 } 3922 console.info('Succeeded in loading the content.'); 3923}); 3924``` 3925 3926### loadContent<sup>9+</sup> 3927 3928loadContent(path: string, storage: LocalStorage): Promise<void> 3929 3930Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3931 3932**Model restriction**: This API can be used only in the stage model. 3933 3934**System capability**: SystemCapability.WindowManager.WindowManager.Core 3935 3936**Atomic service API**: This API can be used in atomic services since API version 11. 3937 3938**Parameters** 3939 3940| Name | Type | Mandatory| Description | 3941| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 3942| 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.| 3943| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 3944 3945**Return value** 3946 3947| Type | Description | 3948| ------------------- | ------------------------- | 3949| Promise<void> | Promise that returns no value.| 3950 3951**Error codes** 3952 3953For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3954 3955| ID| Error Message| 3956| ------- | -------------------------------------------- | 3957| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter.| 3958| 1300002 | This window state is abnormal. | 3959 3960**Example** 3961 3962```ts 3963import { BusinessError } from '@kit.BasicServicesKit'; 3964 3965let storage: LocalStorage = new LocalStorage(); 3966storage.setOrCreate('storageSimpleProp', 121); 3967let promise = windowClass.loadContent('pages/page2', storage); 3968promise.then(() => { 3969 console.info('Succeeded in loading the content.'); 3970}).catch((err: BusinessError) => { 3971 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3972}); 3973``` 3974 3975### loadContentByName<sup>11+</sup> 3976 3977loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 3978 3979Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3980 3981**Model restriction**: This API can be used only in the stage model. 3982 3983**System capability**: SystemCapability.WindowManager.WindowManager.Core 3984 3985**Atomic service API**: This API can be used in atomic services since API version 11. 3986 3987**Parameters** 3988 3989| Name | Type | Mandatory| Description | 3990| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3991| name | string | Yes | Name of the named route page. | 3992| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 3993| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 3994 3995**Error codes** 3996 3997For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3998 3999| ID| Error Message | 4000| -------- | --------------------------------------------- | 4001| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4002| 1300002 | This window state is abnormal. | 4003 4004**Example** 4005<!--code_no_check--> 4006```ts 4007import { BusinessError } from '@kit.BasicServicesKit'; 4008import * as Index from '../pages/Index'; // Import the named route page. 4009 4010console.info('onWindowStageCreate'); 4011let storage: LocalStorage = new LocalStorage(); 4012storage.setOrCreate('storageSimpleProp', 121); 4013try { 4014 (windowClass as window.Window).loadContentByName(Index.entryName, storage, (err: BusinessError) => { 4015 const errCode: number = err.code; 4016 if (errCode) { 4017 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 4018 return; 4019 } 4020 console.info('Succeeded in loading the content.'); 4021 }); 4022} catch (exception) { 4023 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 4024} 4025``` 4026<!--code_no_check--> 4027```ts 4028// ets/pages/Index.ets 4029export const entryName : string = 'Index'; 4030@Entry({routeName: entryName, useSharedStorage: true}) 4031@Component 4032export struct Index { 4033 @State message: string = 'Hello World' 4034 @LocalStorageLink('storageSimpleProp') storageSimpleProp: number = 1; 4035 build() { 4036 Row() { 4037 Column() { 4038 Text(this.message) 4039 .fontSize(50) 4040 .fontWeight(FontWeight.Bold) 4041 } 4042 .width('100%') 4043 } 4044 .height('100%') 4045 } 4046} 4047``` 4048 4049### loadContentByName<sup>11+</sup> 4050 4051loadContentByName(name: string, callback: AsyncCallback<void>): void 4052 4053Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 4054 4055**Model restriction**: This API can be used only in the stage model. 4056 4057**System capability**: SystemCapability.WindowManager.WindowManager.Core 4058 4059**Atomic service API**: This API can be used in atomic services since API version 11. 4060 4061**Parameters** 4062 4063| Name | Type | Mandatory| Description | 4064| -------- | ------------------------- | ---- | ---------------- | 4065| name | string | Yes | Name of the named route page.| 4066| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 4067 4068**Error codes** 4069 4070For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4071 4072| ID| Error Message | 4073| -------- | --------------------------------------------- | 4074| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4075| 1300002 | This window state is abnormal. | 4076 4077**Example** 4078<!--code_no_check--> 4079```ts 4080import { BusinessError } from '@kit.BasicServicesKit'; 4081import * as Index from '../pages/Index'; // Import the named route page. 4082 4083try { 4084 (windowClass as window.Window).loadContentByName(Index.entryName, (err: BusinessError) => { 4085 const errCode: number = err.code; 4086 if (errCode) { 4087 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 4088 return; 4089 } 4090 console.info('Succeeded in loading the content.'); 4091 }); 4092} catch (exception) { 4093 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 4094} 4095``` 4096<!--code_no_check--> 4097```ts 4098// ets/pages/Index.ets 4099export const entryName : string = 'Index'; 4100@Entry({routeName: entryName}) 4101@Component 4102export struct Index { 4103 @State message: string = 'Hello World' 4104 build() { 4105 Row() { 4106 Column() { 4107 Text(this.message) 4108 .fontSize(50) 4109 .fontWeight(FontWeight.Bold) 4110 } 4111 .width('100%') 4112 } 4113 .height('100%') 4114 } 4115} 4116``` 4117 4118### loadContentByName<sup>11+</sup> 4119 4120loadContentByName(name: string, storage?: LocalStorage): Promise<void> 4121 4122Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 4123 4124**Model restriction**: This API can be used only in the stage model. 4125 4126**System capability**: SystemCapability.WindowManager.WindowManager.Core 4127 4128**Atomic service API**: This API can be used in atomic services since API version 11. 4129 4130**Parameters** 4131 4132| Name | Type | Mandatory| Description | 4133| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 4134| name | string | Yes | Name of the named route page. | 4135| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 4136 4137**Return value** 4138 4139| Type | Description | 4140| ------------------- | ------------------------- | 4141| Promise<void> | Promise that returns no value.| 4142 4143**Error codes** 4144 4145For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4146 4147| ID| Error Message | 4148| -------- | --------------------------------------------- | 4149| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4150| 1300002 | This window state is abnormal. | 4151 4152**Example** 4153<!--code_no_check--> 4154```ts 4155import { BusinessError } from '@kit.BasicServicesKit'; 4156import * as Index from '../pages/Index'; // Import the named route page. 4157 4158let storage: LocalStorage = new LocalStorage(); 4159storage.setOrCreate('storageSimpleProp', 121); 4160try { 4161 let promise = (windowClass as window.Window).loadContentByName(Index.entryName, storage); 4162 promise.then(() => { 4163 console.info('Succeeded in loading the content.'); 4164 }).catch((err: BusinessError) => { 4165 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 4166 }); 4167} catch (exception) { 4168 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 4169} 4170``` 4171<!--code_no_check--> 4172```ts 4173// ets/pages/Index.ets 4174export const entryName : string = 'Index'; 4175@Entry({routeName: entryName, useSharedStorage: true}) 4176@Component 4177export struct Index { 4178 @State message: string = 'Hello World' 4179 @LocalStorageLink('storageSimpleProp') storageSimpleProp: number = 1; 4180 build() { 4181 Row() { 4182 Column() { 4183 Text(this.message) 4184 .fontSize(50) 4185 .fontWeight(FontWeight.Bold) 4186 } 4187 .width('100%') 4188 } 4189 .height('100%') 4190 } 4191} 4192``` 4193 4194### isWindowShowing<sup>9+</sup> 4195 4196isWindowShowing(): boolean 4197 4198Checks whether this window is displayed. 4199 4200**System capability**: SystemCapability.WindowManager.WindowManager.Core 4201 4202**Atomic service API**: This API can be used in atomic services since API version 11. 4203 4204**Return value** 4205 4206| Type| Description| 4207| ------- | ------------------------------------------------------------------ | 4208| boolean | Whether the window is displayed. The value **true** means that the window is displayed, and **false** means the opposite.| 4209 4210**Error codes** 4211 4212For details about the error codes, see [Window Error Codes](errorcode-window.md). 4213 4214| ID| Error Message| 4215| ------- | ------------------------------ | 4216| 1300002 | This window state is abnormal. | 4217 4218**Example** 4219 4220```ts 4221try { 4222 let data = windowClass.isWindowShowing(); 4223 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 4224} catch (exception) { 4225 console.error(`Failed to check whether the window is showing. Cause code: ${exception.code}, message: ${exception.message}`); 4226} 4227``` 4228 4229### on('windowSizeChange')<sup>7+</sup> 4230 4231on(type: 'windowSizeChange', callback: Callback<Size>): void 4232 4233Subscribes to the window size change event. 4234 4235**System capability**: SystemCapability.WindowManager.WindowManager.Core 4236 4237**Atomic service API**: This API can be used in atomic services since API version 11. 4238 4239**Parameters** 4240 4241| Name | Type | Mandatory| Description | 4242| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4243| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 4244| callback | Callback<[Size](#size7)> | Yes | Callback used to return the window size. | 4245 4246**Error codes** 4247 4248For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4249 4250| ID| Error Message| 4251| ------- | -------------------------------------------- | 4252| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4253 4254**Example** 4255 4256```ts 4257try { 4258 windowClass.on('windowSizeChange', (data) => { 4259 console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data)); 4260 }); 4261} catch (exception) { 4262 console.error(`Failed to enable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 4263} 4264``` 4265 4266### off('windowSizeChange')<sup>7+</sup> 4267 4268off(type: 'windowSizeChange', callback?: Callback<Size>): void 4269 4270Unsubscribes from the window size change event. 4271 4272**System capability**: SystemCapability.WindowManager.WindowManager.Core 4273 4274**Atomic service API**: This API can be used in atomic services since API version 11. 4275 4276**Parameters** 4277 4278| Name | Type | Mandatory| Description | 4279| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 4280| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 4281| 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. | 4282 4283**Error codes** 4284 4285For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4286 4287| ID| Error Message| 4288| ------- | -------------------------------------------- | 4289| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4290 4291**Example** 4292 4293```ts 4294const callback = (size: window.Size) => { 4295 // ... 4296} 4297try { 4298 // Enable listening through the on API. 4299 windowClass.on('windowSizeChange', callback); 4300 // Disable the listening of a specified callback. 4301 windowClass.off('windowSizeChange', callback); 4302 // Unregister all the callbacks that have been registered through on(). 4303 windowClass.off('windowSizeChange'); 4304} catch (exception) { 4305 console.error(`Failed to disable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 4306} 4307``` 4308 4309### on('avoidAreaChange')<sup>9+</sup> 4310 4311on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void 4312 4313Subscribes to the event indicating changes to the area where this window cannot be displayed. 4314<!--RP7-->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.<!--RP7End--> 4315 4316**System capability**: SystemCapability.WindowManager.WindowManager.Core 4317 4318**Atomic service API**: This API can be used in atomic services since API version 11. 4319 4320**Parameters** 4321 4322| Name | Type | Mandatory| Description | 4323| -------- |----------------------------------| ---- |--------------------------------------| 4324| 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.| 4325| callback | Callback<[AvoidAreaOptions](#avoidareaoptions12)> | Yes | Callback used to return the area and area type.| 4326 4327**Error codes** 4328 4329For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4330 4331| ID| Error Message| 4332| ------- | -------------------------------------------- | 4333| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4334 4335**Example** 4336 4337```ts 4338try { 4339 windowClass.on('avoidAreaChange', (data) => { 4340 console.info('Succeeded in enabling the listener for system avoid area changes. type:' + 4341 JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area)); 4342 }); 4343} catch (exception) { 4344 console.error(`Failed to enable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4345} 4346``` 4347 4348### off('avoidAreaChange')<sup>9+</sup> 4349 4350off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaOptions>): void 4351 4352Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 4353 4354**System capability**: SystemCapability.WindowManager.WindowManager.Core 4355 4356**Atomic service API**: This API can be used in atomic services since API version 11. 4357 4358**Parameters** 4359 4360| Name | Type | Mandatory| Description | 4361| -------- |----------------------------------|------|------------------------------------| 4362| 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.| 4363| 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.| 4364 4365**Error codes** 4366 4367For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4368 4369| ID| Error Message| 4370| ------- | -------------------------------------------- | 4371| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 4372 4373**Example** 4374 4375```ts 4376interface Param { 4377 type: window.AvoidAreaType, 4378 area: window.AvoidArea 4379} 4380const callback = (data: Param) => { 4381 // ... 4382} 4383try { 4384 windowClass.on('avoidAreaChange', callback); 4385 4386 windowClass.off('avoidAreaChange', callback); 4387 // Unregister all the callbacks that have been registered through on(). 4388 windowClass.off('avoidAreaChange'); 4389} catch (exception) { 4390 console.error(`Failed to enable or disable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4391} 4392``` 4393 4394### on('keyboardHeightChange')<sup>7+</sup> 4395 4396on(type: 'keyboardHeightChange', callback: Callback<number>): void 4397 4398Subscribes to the event indicating soft keyboard height changes in the fixed state. 4399 4400The system notifies the keyboard height change when the soft keyboard is invoked by the window and overlaps with the window. 4401 4402Since 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). 4403 4404**Atomic service API**: This API can be used in atomic services since API version 12. 4405 4406**System capability**: SystemCapability.WindowManager.WindowManager.Core 4407 4408**Parameters** 4409 4410| Name | Type | Mandatory| Description | 4411| -------- | ------------------- | ---- |-------------------------------------------| 4412| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 4413| callback | Callback<number> | Yes | Callback used to return the current keyboard height, which is an integer, in px. | 4414 4415**Error codes** 4416 4417For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4418 4419| ID| Error Message| 4420| ------- | -------------------------------------------- | 4421| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4422 4423**Example** 4424 4425```ts 4426import { BusinessError } from '@kit.BasicServicesKit'; 4427 4428try { 4429 windowClass.on('keyboardHeightChange', (data) => { 4430 console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data)); 4431 }); 4432} catch (exception) { 4433 console.error(`Failed to enable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 4434} 4435``` 4436 4437### off('keyboardHeightChange')<sup>7+</sup> 4438 4439off(type: 'keyboardHeightChange', callback?: Callback<number>): void 4440 4441Unsubscribes from the event indicating soft keyboard height changes in the fixed state so that the application does not receive notifications of soft keyboard height changes. 4442 4443Since 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). 4444 4445**Atomic service API**: This API can be used in atomic services since API version 12. 4446 4447**System capability**: SystemCapability.WindowManager.WindowManager.Core 4448 4449**Parameters** 4450 4451| Name | Type | Mandatory| Description | 4452| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4453| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 4454| 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. | 4455 4456**Error codes** 4457 4458For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4459 4460| ID| Error Message| 4461| ------- | -------------------------------------------- | 4462| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4463 4464**Example** 4465 4466```ts 4467import { BusinessError } from '@kit.BasicServicesKit'; 4468 4469const callback = (height: number) => { 4470 // ... 4471} 4472try { 4473 windowClass.on('keyboardHeightChange', callback); 4474 4475 windowClass.off('keyboardHeightChange', callback); 4476 // Unregister all the callbacks that have been registered through on(). 4477 windowClass.off('keyboardHeightChange'); 4478} catch (exception) { 4479 console.error(`Failed to disable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 4480} 4481``` 4482 4483### on('keyboardWillShow')<sup>20+</sup> 4484 4485on(type: 'keyboardWillShow', callback: Callback<KeyboardInfo>): void 4486 4487Subscribes to the event indicating that the soft keyboard in the fixed state is about to show, or the soft keyboard is transitioning from the floating state to the fixed state. 4488 4489For details about the APIs used to set the soft keyboard to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4490 4491**Atomic service API**: This API can be used in atomic services since API version 20. 4492 4493**System capability**: SystemCapability.Window.SessionManager 4494 4495**Parameters** 4496 4497| Name | Type | Mandatory| Description | 4498| -------- | ------------------- | ---- |-------------------------------------------| 4499| type | string | Yes | Event type. The value is fixed at **'keyboardWillShow'**, indicating the soft keyboard in the fixed state is about to show.| 4500| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | Yes | Callback used to return the information about the soft keyboard. | 4501 4502**Error codes** 4503 4504For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4505 4506| ID| Error Message| 4507| ------- | -------------------------------------------- | 4508| 801 | Capability not supported. Function keyboardWillShow can not work correctly due to limited device capabilities. | 4509| 1300002 | This window state is abnormal. | 4510 4511**Example** 4512 4513```ts 4514import { BusinessError } from '@kit.BasicServicesKit'; 4515 4516const callback = (keyboardInfo: window.KeyboardInfo) => { 4517 console.info(`Keyboard will show animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 4518} 4519try { 4520 windowClass.on('keyboardWillShow', callback); 4521 console.info(`Register keyboard will show animation success`); 4522} catch (exception) { 4523 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4524} 4525``` 4526 4527### off('keyboardWillShow')<sup>20</sup> 4528 4529off(type: 'keyboardWillShow', callback?: Callback<KeyboardInfo>): void 4530 4531Unsubscribes from the event indicating that the soft keyboard in the fixed state is about to show. For details about the APIs used to set the input method panel to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4532 4533**Atomic service API**: This API can be used in atomic services since API version 20. 4534 4535**System capability**: SystemCapability.Window.SessionManager 4536 4537**Parameters** 4538 4539| Name | Type | Mandatory| Description | 4540| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4541| type | string | Yes | Event type. The value is fixed at **'keyboardWillShow'**, indicating the soft keyboard in the fixed state is about to show.| 4542| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | No | Callback used to return the information about the soft keyboard. 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. | 4543 4544**Error codes** 4545 4546For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4547 4548| ID| Error Message| 4549| ------- | -------------------------------------------- | 4550| 801 | Capability not supported. Function keyboardWillShow can not work correctly due to limited device capabilities. | 4551| 1300002 | This window state is abnormal. | 4552 4553**Example** 4554 4555```ts 4556import { BusinessError } from '@kit.BasicServicesKit'; 4557 4558const callback = (keyboardInfo: window.KeyboardInfo) => { 4559 console.info(`Keyboard will show animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 4560} 4561try { 4562 windowClass.on('keyboardWillShow', callback); 4563 windowClass.off('keyboardWillShow', callback); 4564 // Unregister all the callbacks that have been registered through on(). 4565 windowClass.off('keyboardWillShow'); 4566 console.info(`Unregister keyboard will show animation success`); 4567} catch (exception) { 4568 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4569} 4570``` 4571 4572### on('keyboardWillHide')<sup>20+</sup> 4573 4574on(type: 'keyboardWillHide', callback: Callback<KeyboardInfo>): void 4575 4576Subscribes to the event indicating that the soft keyboard in the fixed state is about to hide, or the soft keyboard is transitioning from the fixed state to the floating state. 4577 4578For details about the APIs used to set the soft keyboard to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4579 4580**Atomic service API**: This API can be used in atomic services since API version 20. 4581 4582**System capability**: SystemCapability.Window.SessionManager 4583 4584**Parameters** 4585 4586| Name | Type | Mandatory| Description | 4587| -------- | ------------------- | ---- |-------------------------------------------| 4588| type | string | Yes | Event type. The value is fixed at **'keyboardWillHide'**, indicating the soft keyboard in the fixed state is about to hide.| 4589| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | Yes | Callback used to return the information about the soft keyboard. | 4590 4591**Error codes** 4592 4593For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4594 4595| ID| Error Message| 4596| ------- | -------------------------------------------- | 4597| 801 | Capability not supported. Function keyboardWillHide can not work correctly due to limited device capabilities. | 4598| 1300002 | This window state is abnormal. | 4599 4600**Example** 4601 4602```ts 4603import { BusinessError } from '@kit.BasicServicesKit'; 4604 4605const callback = (keyboardInfo: window.KeyboardInfo) => { 4606 console.info(`Keyboard will hide animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 4607} 4608try { 4609 windowClass.on('keyboardWillHide', callback); 4610 console.info(`Register keyboard will hide animation success`); 4611} catch (exception) { 4612 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4613} 4614``` 4615 4616### off('keyboardWillHide')<sup>20+</sup> 4617 4618off(type: 'keyboardWillHide', callback?: Callback<KeyboardInfo>): void 4619 4620Unsubscribes from the event indicating that the soft keyboard in the fixed state is about to hide. For details about the APIs used to set the input method panel to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4621 4622**Atomic service API**: This API can be used in atomic services since API version 20. 4623 4624**System capability**: SystemCapability.Window.SessionManager 4625 4626**Parameters** 4627 4628| Name | Type | Mandatory| Description | 4629| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4630| type | string | Yes | Event type. The value is fixed at **'keyboardWillHide'**, indicating the soft keyboard in the fixed state is about to hide.| 4631| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | No | Callback used to return the information about the soft keyboard. 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. | 4632 4633**Error codes** 4634 4635For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4636 4637| ID| Error Message| 4638| ------- | -------------------------------------------- | 4639| 801 | Capability not supported. Function keyboardWillHide can not work correctly due to limited device capabilities. | 4640| 1300002 | This window state is abnormal. | 4641 4642**Example** 4643 4644```ts 4645import { BusinessError } from '@kit.BasicServicesKit'; 4646 4647const callback = (keyboardInfo: window.KeyboardInfo) => { 4648 console.info(`Keyboard will hide animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 4649} 4650try { 4651 windowClass.on('keyboardWillHide', callback); 4652 windowClass.off('keyboardWillHide', callback); 4653 // Unregister all the callbacks that have been registered through on(). 4654 windowClass.off('keyboardWillHide'); 4655 console.info(`Unregister keyboard will hide animation success`); 4656} catch (exception) { 4657 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4658} 4659``` 4660 4661### on('keyboardDidShow')<sup>18+</sup> 4662 4663on(type: 'keyboardDidShow', callback: Callback<KeyboardInfo>): void 4664 4665Subscribes to the event indicating that the show animation of the soft keyboard in the fixed state is completed, or when the soft keyboard finishes transitioning from the floating state to the fixed state. 4666 4667For details about the APIs used to set the soft keyboard to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4668 4669**Atomic service API**: This API can be used in atomic services since API version 18. 4670 4671**System capability**: SystemCapability.Window.SessionManager 4672 4673**Parameters** 4674 4675| Name | Type | Mandatory| Description | 4676| -------- | ------------------- | ---- |-------------------------------------------| 4677| type | string | Yes | Event type. The value is fixed at **'keyboardDidShow'**, indicating the show animation of the soft keyboard in the fixed state is completed.| 4678| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | Yes | Callback used to return the information about the soft keyboard. | 4679 4680**Error codes** 4681 4682For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4683 4684| ID| Error Message| 4685| ------- | -------------------------------------------- | 4686| 801 | Capability not supported. Function keyboardDidShow can not work correctly due to limited device capabilities. | 4687| 1300002 | This window state is abnormal. | 4688 4689**Example** 4690 4691```ts 4692import { BusinessError } from '@kit.BasicServicesKit'; 4693 4694try { 4695 windowClass.on('keyboardDidShow', (keyboardInfo) => { 4696 console.info('keyboard show animation completion. keyboardInfo: ' + JSON.stringify(keyboardInfo)); 4697 }); 4698} catch (exception) { 4699 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4700} 4701``` 4702 4703### off('keyboardDidShow')<sup>18+</sup> 4704 4705off(type: 'keyboardDidShow', callback?: Callback<KeyboardInfo>): void 4706 4707Unsubscribes from the event indicating that the show animation of the soft keyboard in the fixed state is completed, For details about the APIs used to set the input method panel to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4708 4709**Atomic service API**: This API can be used in atomic services since API version 18. 4710 4711**System capability**: SystemCapability.Window.SessionManager 4712 4713**Parameters** 4714 4715| Name | Type | Mandatory| Description | 4716| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4717| type | string | Yes | Event type. The value is fixed at **'keyboardDidShow'**, indicating the show animation of the soft keyboard in the fixed state is completed.| 4718| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | No | Callback used to return the information about the soft keyboard. 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. | 4719 4720**Error codes** 4721 4722For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4723 4724| ID| Error Message| 4725| ------- | -------------------------------------------- | 4726| 801 | Capability not supported. Function keyboardDidShow can not work correctly due to limited device capabilities. | 4727| 1300002 | This window state is abnormal. | 4728 4729**Example** 4730 4731```ts 4732import { BusinessError } from '@kit.BasicServicesKit'; 4733 4734const callback = (keyboardInfo: window.KeyboardInfo) => { 4735 // ... 4736} 4737try { 4738 windowClass.on('keyboardDidShow', callback); 4739 windowClass.off('keyboardDidShow', callback); 4740 // Unregister all the callbacks that have been registered through on(). 4741 windowClass.off('keyboardDidShow'); 4742} catch (exception) { 4743 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4744} 4745``` 4746 4747### on('keyboardDidHide')<sup>18+</sup> 4748 4749on(type: 'keyboardDidHide', callback: Callback<KeyboardInfo>): void 4750 4751Subscribes to the event indicating that the hide animation of the soft keyboard in the fixed state is completed, or when the soft keyboard finishes transitioning from the fixed state to the floating state. 4752 4753For details about the APIs used to set the soft keyboard to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4754 4755**Atomic service API**: This API can be used in atomic services since API version 18. 4756 4757**System capability**: SystemCapability.Window.SessionManager 4758 4759**Parameters** 4760 4761| Name | Type | Mandatory| Description | 4762| -------- | ------------------- | ---- |-------------------------------------------| 4763| type | string | Yes | Event type. The value is fixed at **'keyboardDidHide'**, indicating the hide animation of the soft keyboard in the fixed state is completed.| 4764| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | Yes | Callback used to return the information about the soft keyboard. | 4765 4766**Error codes** 4767 4768For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4769 4770| ID| Error Message| 4771| ------- | -------------------------------------------- | 4772| 801 | Capability not supported. Function keyboardDidHide can not work correctly due to limited device capabilities. | 4773| 1300002 | This window state is abnormal. | 4774 4775**Example** 4776 4777```ts 4778import { BusinessError } from '@kit.BasicServicesKit'; 4779 4780try { 4781 windowClass.on('keyboardDidHide', (keyboardInfo) => { 4782 console.info('keyboard hide animation completion. keyboardInfo: ' + JSON.stringify(keyboardInfo)); 4783 }); 4784} catch (exception) { 4785 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4786} 4787``` 4788 4789### off('keyboardDidHide')<sup>18+</sup> 4790 4791off(type: 'keyboardDidHide', callback?: Callback<KeyboardInfo>): void 4792 4793Unsubscribes from the event indicating that the hide animation of the soft keyboard in the fixed state is completed, For details about the APIs used to set the input method panel to the fixed or floating state, see [Input Method Service](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10). 4794 4795**Atomic service API**: This API can be used in atomic services since API version 18. 4796 4797**System capability**: SystemCapability.Window.SessionManager 4798 4799**Parameters** 4800 4801| Name | Type | Mandatory| Description | 4802| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4803| type | string | Yes | Event type. The value is fixed at **'keyboardDidHide'**, indicating the hide animation of the soft keyboard in the fixed state is completed.| 4804| callback | Callback<[KeyboardInfo](#keyboardinfo18)> | No | Callback used to return the information about the soft keyboard. 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. | 4805 4806**Error codes** 4807 4808For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4809 4810| ID| Error Message| 4811| ------- | -------------------------------------------- | 4812| 801 | Capability not supported. Function keyboardDidHide can not work correctly due to limited device capabilities. | 4813| 1300002 | This window state is abnormal. | 4814 4815**Example** 4816 4817```ts 4818import { BusinessError } from '@kit.BasicServicesKit'; 4819 4820const callback = (keyboardInfo: window.KeyboardInfo) => { 4821 // ... 4822} 4823try { 4824 windowClass.on('keyboardDidHide', callback); 4825 windowClass.off('keyboardDidHide', callback); 4826 // Unregister all the callbacks that have been registered through on(). 4827 windowClass.off('keyboardDidHide'); 4828} catch (exception) { 4829 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4830} 4831``` 4832 4833### on('touchOutside')<sup>11+</sup> 4834 4835on(type: 'touchOutside', callback: Callback<void>): void 4836 4837Subscribes to the touch event outside this window. 4838 4839**System capability**: SystemCapability.WindowManager.WindowManager.Core 4840 4841**Atomic service API**: This API can be used in atomic services since API version 11. 4842 4843**Parameters** 4844 4845| Name | Type | Mandatory| Description | 4846| -------- | ------------------- | ---- | ------------------------------------------------------------ | 4847| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 4848| callback | Callback<void> | Yes | Callback used to return the touch event outside this window. | 4849 4850**Error codes** 4851 4852For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4853 4854| ID| Error Message| 4855| ------- | -------------------------------------------- | 4856| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4857 4858**Example** 4859 4860```ts 4861try { 4862 windowClass.on('touchOutside', () => { 4863 console.info('touch outside'); 4864 }); 4865} catch (exception) { 4866 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4867} 4868``` 4869 4870### off('touchOutside')<sup>11+</sup> 4871 4872off(type: 'touchOutside', callback?: Callback<void>): void 4873 4874Unsubscribes from the touch event outside this window. 4875 4876**System capability**: SystemCapability.WindowManager.WindowManager.Core 4877 4878**Atomic service API**: This API can be used in atomic services since API version 11. 4879 4880**Parameters** 4881 4882| Name | Type | Mandatory| Description | 4883| -------- |----------------------| ---- |--------------------------------------| 4884| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 4885| 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. | 4886 4887**Error codes** 4888 4889For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4890 4891| ID| Error Message| 4892| ------- | -------------------------------------------- | 4893| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4894 4895**Example** 4896 4897```ts 4898const callback = () => { 4899 // ... 4900} 4901try { 4902 windowClass.on('touchOutside', callback); 4903 windowClass.off('touchOutside', callback); 4904 // Unregister all the callbacks that have been registered through on(). 4905 windowClass.off('touchOutside'); 4906} catch (exception) { 4907 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4908} 4909``` 4910 4911### on('screenshot')<sup>9+</sup> 4912 4913on(type: 'screenshot', callback: Callback<void>): void 4914 4915Subscribes to the screenshot event. 4916 4917**Atomic service API**: This API can be used in atomic services since API version 12. 4918 4919**System capability**: SystemCapability.WindowManager.WindowManager.Core 4920 4921**Parameters** 4922 4923| Name | Type | Mandatory| Description | 4924| -------- | ------------------- | ---- | ------------------------------------------------------------ | 4925| 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.| 4926| callback | Callback<void> | Yes | Callback invoked when a screenshot event occurs. | 4927 4928**Error codes** 4929 4930For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4931 4932| ID| Error Message| 4933| ------- | -------------------------------------------- | 4934| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4935 4936**Example** 4937 4938```ts 4939try { 4940 windowClass.on('screenshot', () => { 4941 console.info('screenshot happened'); 4942 }); 4943} catch (exception) { 4944 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4945} 4946``` 4947 4948### off('screenshot')<sup>9+</sup> 4949 4950off(type: 'screenshot', callback?: Callback<void>): void 4951 4952Unsubscribes from the screenshot event. 4953 4954**Atomic service API**: This API can be used in atomic services since API version 12. 4955 4956**System capability**: SystemCapability.WindowManager.WindowManager.Core 4957 4958**Parameters** 4959 4960| Name | Type | Mandatory| Description | 4961| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 4962| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event.| 4963| 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.| 4964 4965**Error codes** 4966 4967For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4968 4969| ID| Error Message| 4970| ------- | -------------------------------------------- | 4971| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4972 4973**Example** 4974 4975```ts 4976let callback = () => { 4977 console.info('screenshot happened'); 4978}; 4979try { 4980 windowClass.on('screenshot', callback); 4981 windowClass.off('screenshot', callback); 4982 // Unregister all the callbacks that have been registered through on(). 4983 windowClass.off('screenshot'); 4984} catch (exception) { 4985 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4986} 4987``` 4988 4989### on('dialogTargetTouch')<sup>10+</sup> 4990 4991on(type: 'dialogTargetTouch', callback: Callback<void>): void 4992 4993Subscribes 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. 4994 4995**Atomic service API**: This API can be used in atomic services since API version 12. 4996 4997**System capability**: SystemCapability.WindowManager.WindowManager.Core 4998 4999**Parameters** 5000 5001| Name | Type | Mandatory| Description | 5002| -------- | ------------------- | ---- | ------------------------------------------------------------ | 5003| 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.| 5004| callback | Callback<void>| Yes | Callback invoked when a click or touch event occurs in the window covered by the modal window.| 5005 5006**Error codes** 5007 5008For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5009 5010| ID| Error Message| 5011| ------- | -------------------------------------------- | 5012| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5013 5014**Example** 5015 5016```ts 5017try { 5018 windowClass.on('dialogTargetTouch', () => { 5019 console.info('touch dialog target'); 5020 }); 5021} catch (exception) { 5022 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5023} 5024``` 5025 5026### off('dialogTargetTouch')<sup>10+</sup> 5027 5028off(type: 'dialogTargetTouch', callback?: Callback<void>): void 5029 5030Unsubscribes from the touch event of the target window in the modal window mode. 5031 5032**Atomic service API**: This API can be used in atomic services since API version 12. 5033 5034**System capability**: SystemCapability.WindowManager.WindowManager.Core 5035 5036**Parameters** 5037 5038| Name | Type | Mandatory| Description | 5039| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 5040| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the touch event of the target window in the modal window mode.| 5041| 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.| 5042 5043**Error codes** 5044 5045For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5046 5047| ID| Error Message| 5048| ------- | -------------------------------------------- | 5049| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5050 5051**Example** 5052 5053```ts 5054const callback = () => { 5055 // ... 5056} 5057try { 5058 windowClass.on('dialogTargetTouch', callback); 5059 windowClass.off('dialogTargetTouch', callback); 5060 // Unregister all the callbacks that have been registered through on(). 5061 windowClass.off('dialogTargetTouch'); 5062} catch (exception) { 5063 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5064} 5065``` 5066 5067### on('windowEvent')<sup>10+</sup> 5068 5069on(type: 'windowEvent', callback: Callback<WindowEventType>): void 5070 5071Subscribes to the window lifecycle change event. 5072 5073**System capability**: SystemCapability.WindowManager.WindowManager.Core 5074 5075**Atomic service API**: This API can be used in atomic services since API version 11. 5076 5077**Parameters** 5078 5079| Name | Type | Mandatory| Description | 5080| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 5081| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 5082| callback | Callback<[WindowEventType](#windoweventtype10)> | Yes | Callback used to return the window lifecycle state. | 5083 5084**Error codes** 5085 5086For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5087 5088| ID| Error Message| 5089| ------- | -------------------------------------------- | 5090| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5091 5092**Example** 5093 5094```ts 5095try { 5096 windowClass.on('windowEvent', (data) => { 5097 console.info('Window event happened. Event:' + JSON.stringify(data)); 5098 }); 5099} catch (exception) { 5100 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5101} 5102``` 5103 5104### off('windowEvent')<sup>10+</sup> 5105 5106off(type: 'windowEvent', callback?: Callback<WindowEventType>): void 5107 5108Unsubscribes from the window lifecycle change event. 5109 5110**System capability**: SystemCapability.WindowManager.WindowManager.Core 5111 5112**Atomic service API**: This API can be used in atomic services since API version 11. 5113 5114**Parameters** 5115 5116| Name | Type | Mandatory| Description | 5117| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 5118| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 5119| 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. | 5120 5121**Error codes** 5122 5123For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5124 5125| ID| Error Message| 5126| ------- | -------------------------------------------- | 5127| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5128 5129**Example** 5130 5131```ts 5132const callback = (windowEventType: window.WindowEventType) => { 5133 // ... 5134} 5135try { 5136 // Enable listening through the on API. 5137 windowClass.on('windowEvent', callback); 5138 // Disable the listening of a specified callback. 5139 windowClass.off('windowEvent', callback); 5140 // Unregister all the callbacks that have been registered through on(). 5141 windowClass.off('windowEvent'); 5142} catch (exception) { 5143 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5144} 5145``` 5146 5147### on('displayIdChange')<sup>14+</sup> 5148 5149on(type: 'displayIdChange', callback: Callback<number>): void 5150 5151Subscribes to the display change event of this window. For example, this event is triggered when the window is moved to a different display. 5152 5153**Atomic service API**: This API can be used in atomic services since API version 14. 5154 5155**System capability**: SystemCapability.Window.SessionManager 5156 5157**Parameters** 5158 5159| Name | Type | Mandatory| Description | 5160| -------- | --------------------------| ---- | ------------------------------------------------------------ | 5161| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.| 5162| 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. | 5163 5164**Error codes** 5165 5166For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5167 5168| ID| Error Message| 5169| ------- | ------------------------------ | 5170| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5171| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5172| 1300002 | This window state is abnormal. | 5173 5174**Example** 5175 5176```ts 5177try { 5178 windowClass.on('displayIdChange', (data) => { 5179 console.info('Window displayId changed, displayId=' + JSON.stringify(data)); 5180 }); 5181} catch (exception) { 5182 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5183} 5184``` 5185### off('displayIdChange')<sup>14+</sup> 5186 5187off(type: 'displayIdChange', callback?: Callback<number>): void 5188 5189Unsubscribes from the display change event of this window. 5190 5191**Atomic service API**: This API can be used in atomic services since API version 14. 5192 5193**System capability**: SystemCapability.Window.SessionManager 5194 5195**Parameters** 5196 5197| Name | Type | Mandatory| Description | 5198| -------- |----------------------------| ---- |--------------------------------------| 5199| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.| 5200| 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. | 5201 5202**Error codes** 5203 5204For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5205 5206| ID| Error Message| 5207| ------- | ------------------------------ | 5208| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5209| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5210| 1300002 | This window state is abnormal. | 5211 5212**Example** 5213 5214```ts 5215const callback = (displayId: number) => { 5216 // ... 5217} 5218try { 5219 // Enable listening through the on API. 5220 windowClass.on('displayIdChange', callback); 5221 // Disable the listening of a specified callback. 5222 windowClass.off('displayIdChange', callback); 5223 // Unregister all the callbacks that have been registered through on(). 5224 windowClass.off('displayIdChange'); 5225} catch (exception) { 5226 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5227} 5228``` 5229 5230### on('windowVisibilityChange')<sup>11+</sup> 5231 5232on(type: 'windowVisibilityChange', callback: Callback<boolean>): void 5233 5234Subscribes to the visibility status change event of this window. 5235 5236**Atomic service API**: This API can be used in atomic services since API version 12. 5237 5238**System capability**: SystemCapability.Window.SessionManager 5239 5240**Parameters** 5241 5242| Name | Type | Mandatory| Description | 5243| -------- | --------------------------| ---- | ------------------------------------------------------------ | 5244| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 5245| 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. | 5246 5247**Error codes** 5248 5249For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5250 5251| ID| Error Message| 5252| ------- | ------------------------------ | 5253| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5254| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5255| 1300002 | This window state is abnormal. | 5256| 1300003 | This window manager service works abnormally. | 5257 5258**Example** 5259 5260```ts 5261try { 5262 windowClass.on('windowVisibilityChange', (boolean) => { 5263 console.info('Window visibility changed, isVisible=' + boolean); 5264 }); 5265} catch (exception) { 5266 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5267} 5268``` 5269 5270### off('windowVisibilityChange')<sup>11+</sup> 5271 5272off(type: 'windowVisibilityChange', callback?: Callback<boolean>): void 5273 5274Unsubscribes from the visibility status change event of this window. 5275 5276**Atomic service API**: This API can be used in atomic services since API version 12. 5277 5278**System capability**: SystemCapability.Window.SessionManager 5279 5280**Parameters** 5281 5282| Name | Type | Mandatory| Description | 5283| -------- |----------------------------| ---- |--------------------------------------| 5284| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 5285| 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. | 5286 5287**Error codes** 5288 5289For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5290 5291| ID| Error Message| 5292| ------- | ------------------------------ | 5293| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5294| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5295| 1300002 | This window state is abnormal. | 5296| 1300003 | This window manager service works abnormally. | 5297 5298**Example** 5299 5300```ts 5301const callback = (bool: boolean) => { 5302 // ... 5303} 5304try { 5305 // Enable listening through the on API. 5306 windowClass.on('windowVisibilityChange', callback); 5307 // Disable the listening of a specified callback. 5308 windowClass.off('windowVisibilityChange', callback); 5309 // Unregister all the callbacks that have been registered through on(). 5310 windowClass.off('windowVisibilityChange'); 5311} catch (exception) { 5312 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5313} 5314``` 5315 5316### on('systemDensityChange')<sup>15+</sup> 5317 5318on(type: 'systemDensityChange', callback: Callback<number>): void 5319 5320Subscribes to the system density change event, which is triggered when the system's display size scale factor changes for the screen where the window is located. 5321 5322**Atomic service API**: This API can be used in atomic services since API version 15. 5323 5324**System capability**: SystemCapability.Window.SessionManager 5325 5326**Parameters** 5327 5328| Name | Type | Mandatory| Description | 5329| -------- | --------------------------| ---- | ------------------------------------------------------------ | 5330| type | string | Yes | Event type. The value is fixed at **'systemDensityChange'**, indicating the system density change event.| 5331| callback | Callback<number> | Yes | Callback invoked when the system's display size scale factor changes. The callback contains a parameter of the number type, indicating the new scale factor. | 5332 5333**Error codes** 5334 5335 5336For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5337 5338| ID| Error Message| 5339| ------- | ------------------------------ | 5340| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5341| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5342| 1300002 | This window state is abnormal. | 5343 5344**Example** 5345 5346```ts 5347const callback = (density: number) => { 5348 console.info('System density changed, density=' + JSON.stringify(density)); 5349} 5350try { 5351 windowClass.on('systemDensityChange', callback); 5352} catch (exception) { 5353 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5354} 5355``` 5356### off('systemDensityChange')<sup>15+</sup> 5357 5358off(type: 'systemDensityChange', callback?: Callback<number>): void 5359 5360Unsubscribes from the system density change event. 5361 5362**Atomic service API**: This API can be used in atomic services since API version 15. 5363 5364**System capability**: SystemCapability.Window.SessionManager 5365 5366**Parameters** 5367 5368| Name | Type | Mandatory| Description | 5369| -------- |----------------------------| ---- |--------------------------------------| 5370| type | string | Yes | Event type. The value is fixed at **'systemDensityChange'**, indicating the system density change event.| 5371| callback | Callback<number> | No | Callback invoked when the system's display size scale factor 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. | 5372 5373**Error codes** 5374 5375For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5376 5377| ID| Error Message| 5378| ------- | ------------------------------ | 5379| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5380| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5381| 1300002 | This window state is abnormal. | 5382 5383**Example** 5384 5385```ts 5386const callback = (density: number) => { 5387 // ... 5388} 5389try { 5390 // Enable listening through the on API. 5391 windowClass.on('systemDensityChange', callback); 5392 // Disable the listening of a specified callback. 5393 windowClass.off('systemDensityChange', callback); 5394 // Unregister all the callbacks that have been registered through on(). 5395 windowClass.off('systemDensityChange'); 5396} catch (exception) { 5397 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5398} 5399``` 5400 5401### on('noInteractionDetected')<sup>12+</sup> 5402 5403on(type: 'noInteractionDetected', timeout: number, callback: Callback<void>): void 5404 5405Subscribes to non-interaction events in a window within the specified period. 5406 5407Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 5408 5409**Atomic service API**: This API can be used in atomic services since API version 12. 5410 5411**System capability**: SystemCapability.Window.SessionManager 5412 5413**Parameters** 5414 5415| Name | Type | Mandatory| Description | 5416| -------- | --------------------------| ---- | ------------------------------------------------------------ | 5417| 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.| 5418| timeout | number | Yes | Period during which no interaction is performed, in seconds. The value must be an integer. Negative numbers and decimals are invalid.| 5419| callback | Callback<void> | Yes | Callback invoked when there is no interaction event in the current window within the specified period. | 5420 5421**Error codes** 5422 5423For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5424 5425| ID| Error Message| 5426| ------- | ------------------------------ | 5427| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5428| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5429| 1300002 | This window state is abnormal. | 5430| 1300003 | This window manager service works abnormally. | 5431 5432**Example** 5433 5434```ts 5435try { 5436 windowClass.on('noInteractionDetected', 60, () => { 5437 console.info('no interaction in 60s'); 5438 }); 5439} catch (exception) { 5440 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5441} 5442``` 5443 5444### off('noInteractionDetected')<sup>12+</sup> 5445 5446off(type: 'noInteractionDetected', callback?: Callback<void>): void 5447 5448Unsubscribes from non-interaction events in a window within the specified period. 5449 5450Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 5451 5452**Atomic service API**: This API can be used in atomic services since API version 12. 5453 5454**System capability**: SystemCapability.Window.SessionManager 5455 5456**Parameters** 5457 5458| Name | Type | Mandatory| Description | 5459| -------- |----------------------------| ---- |--------------------------------------| 5460| 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.| 5461| 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.| 5462 5463**Error codes** 5464 5465For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5466 5467| ID| Error Message| 5468| ------- | ------------------------------ | 5469| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5470| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5471| 1300002 | This window state is abnormal. | 5472| 1300003 | This window manager service works abnormally. | 5473 5474**Example** 5475 5476```ts 5477const callback = () => { 5478 // ... 5479} 5480try { 5481 windowClass.on('noInteractionDetected', 60, callback); 5482 windowClass.off('noInteractionDetected', callback); 5483 // Unregister all the callbacks that have been registered through on(). 5484 windowClass.off('noInteractionDetected'); 5485} catch (exception) { 5486 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5487} 5488``` 5489 5490### on('windowStatusChange')<sup>11+</sup> 5491 5492on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void 5493 5494Subscribes to the window status change event. A notification is sent when the window status changes (the window properties may not be updated). 5495 5496**Atomic service API**: This API can be used in atomic services since API version 12. 5497 5498**System capability**: SystemCapability.Window.SessionManager 5499 5500**Parameters** 5501 5502| Name | Type | Mandatory| Description | 5503| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 5504| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 5505| callback | Callback<[WindowStatusType](#windowstatustype11)> | Yes | Callback used to return the window status. | 5506 5507**Error codes** 5508 5509For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5510 5511| ID| Error Message| 5512| ------- | ------------------------------ | 5513| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5514| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5515 5516**Example** 5517 5518```ts 5519try { 5520 windowClass.on('windowStatusChange', (WindowStatusType) => { 5521 console.info('Succeeded in enabling the listener for window status changes. Data: ' + JSON.stringify(WindowStatusType)); 5522 }); 5523} catch (exception) { 5524 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5525} 5526``` 5527 5528### off('windowStatusChange')<sup>11+</sup> 5529 5530off(type: 'windowStatusChange', callback?: Callback<WindowStatusType>): void 5531 5532Unsubscribes from the window status change event. 5533 5534**Atomic service API**: This API can be used in atomic services since API version 12. 5535 5536**System capability**: SystemCapability.Window.SessionManager 5537 5538**Parameters** 5539 5540| Name | Type | Mandatory| Description | 5541| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 5542| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 5543| 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. | 5544 5545**Error codes** 5546 5547For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5548 5549| ID| Error Message| 5550| ------- | ------------------------------ | 5551| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5552| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5553 5554**Example** 5555 5556```ts 5557const callback = (windowStatusType: window.WindowStatusType) => { 5558 // ... 5559} 5560try { 5561 windowClass.on('windowStatusChange', callback); 5562 windowClass.off('windowStatusChange', callback); 5563 // Unregister all the callbacks that have been registered through on(). 5564 windowClass.off('windowStatusChange'); 5565} catch (exception) { 5566 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5567} 5568``` 5569 5570### on('windowStatusDidChange')<sup>20+</sup> 5571 5572on(type: 'windowStatusDidChange', callback: Callback<WindowStatusType>): void 5573 5574Subscribes to the event indicating that the window status has changed (the [Rect](#rect7) property of the window has been updated). 5575 5576**Atomic service API**: This API can be used in atomic services since API version 20. 5577 5578**System capability**: SystemCapability.Window.SessionManager 5579 5580**Parameters** 5581 5582| Name | Type | Mandatory| Description | 5583| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 5584| type | string | Yes | Event type. The value is fixed at **'windowStatusDidChange'**, indicating that the window status has changed.| 5585| callback | Callback<[WindowStatusType](#windowstatustype11)> | Yes | Callback used to return the window status. | 5586 5587**Error codes** 5588 5589For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5590 5591| ID| Error Message| 5592| ------- | ------------------------------ | 5593| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5594| 1300002 | This window state is abnormal. | 5595 5596**Example** 5597 5598```ts 5599try { 5600 windowClass.on('windowStatusDidChange', (WindowStatusType) => { 5601 console.info(`Succeeded in enabling the listener for window status changes. Data: ${JSON.stringify(WindowStatusType)}`); 5602 }); 5603} catch (exception) { 5604 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5605} 5606``` 5607 5608### off('windowStatusDidChange')<sup>20+</sup> 5609 5610off(type: 'windowStatusDidChange', callback?: Callback<WindowStatusType>): void 5611 5612Unsubscribes from the event indicating that the window status has changed. 5613 5614**Atomic service API**: This API can be used in atomic services since API version 20. 5615 5616**System capability**: SystemCapability.Window.SessionManager 5617 5618**Parameters** 5619 5620| Name | Type | Mandatory| Description | 5621| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 5622| type | string | Yes | Event type. The value is fixed at **'windowStatusDidChange'**, indicating that the window status has changed.| 5623| 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. | 5624 5625**Error codes** 5626 5627For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 5628 5629| ID| Error Message| 5630| ------- | ------------------------------ | 5631| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5632| 1300002 | This window state is abnormal. | 5633 5634**Example** 5635 5636```ts 5637const callback = (windowStatusType: window.WindowStatusType) => { 5638 // ... 5639} 5640try { 5641 windowClass.on('windowStatusDidChange', callback); 5642 windowClass.off('windowStatusDidChange', callback); 5643 // Unregister all the callbacks that have been registered through on(). 5644 windowClass.off('windowStatusDidChange'); 5645} catch (exception) { 5646 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5647} 5648``` 5649 5650### setWindowGrayScale<sup>12+</sup> 5651 5652setWindowGrayScale(grayScale: number): Promise<void> 5653 5654Sets 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. 5655 5656**Atomic service API**: This API can be used in atomic services since API version 12. 5657 5658**System capability**: SystemCapability.Window.SessionManager 5659 5660**Parameters** 5661 5662| Name| Type| Mandatory| Description | 5663| --------- | ------ | -- | ---------------------------------------- | 5664| 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.| 5665 5666**Return value** 5667 5668| Type| Description| 5669| ------------------- | ------------------------ | 5670| Promise<void> | Promise that returns no value.| 5671 5672**Error codes** 5673 5674For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5675 5676| ID| Error Message| 5677| ------- | --------------------------------------------- | 5678| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5679| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5680| 1300002 | This window state is abnormal. | 5681| 1300003 | This window manager service works abnormally. | 5682 5683**Example** 5684 5685```ts 5686import { BusinessError } from '@kit.BasicServicesKit'; 5687 5688windowClass?.setUIContent('pages/Index', (error: BusinessError) => { 5689 if (error.code) { 5690 console.error(`Failed to set the content. Cause code: ${error.code}`); 5691 return; 5692 } 5693 console.info('Succeeded in setting the content.'); 5694 let grayScale: number = 0.5; 5695 try { 5696 if (canIUse("SystemCapability.Window.SessionManager")) { 5697 let promise = windowClass?.setWindowGrayScale(grayScale); 5698 promise?.then(() => { 5699 console.info('Succeeded in setting the grayScale.'); 5700 }).catch((err: BusinessError) => { 5701 console.error(`Failed to set the grayScale. Cause code: ${err.code}, message: ${err.message}`); 5702 }); 5703 } 5704 } catch (exception) { 5705 console.error(`Failed to set the grayScale. Cause code: ${exception.code}, message: ${exception.message}`); 5706 } 5707}); 5708``` 5709 5710### on('windowTitleButtonRectChange')<sup>11+</sup> 5711 5712on(type: 'windowTitleButtonRectChange', callback: Callback<TitleButtonRect>): void 5713 5714Subscribes 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. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 5715 5716<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 5717 5718**Atomic service API**: This API can be used in atomic services since API version 12. 5719 5720**System capability**: SystemCapability.Window.SessionManager 5721 5722**Parameters** 5723 5724| Name | Type | Mandatory| Description | 5725| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 5726| 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.| 5727| callback | Callback<[TitleButtonRect](#titlebuttonrect11)> | Yes | Callback used to return the new rectangle.| 5728 5729**Error codes** 5730 5731For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5732 5733| ID| Error Message | 5734| -------- | ------------------------------ | 5735| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5736| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5737| 1300002 | This window state is abnormal. | 5738 5739**Example** 5740 5741```ts 5742windowClass.setUIContent('pages/WindowPage').then(() => { 5743 try { 5744 windowClass?.on('windowTitleButtonRectChange', (titleButtonRect) => { 5745 console.info('Succeeded in enabling the listener for window title buttons area changes. Data: ' + JSON.stringify(titleButtonRect)); 5746 }); 5747 } catch (exception) { 5748 console.error(`Failed to enable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 5749 } 5750}) 5751``` 5752 5753### off('windowTitleButtonRectChange')<sup>11+</sup> 5754 5755off(type: 'windowTitleButtonRectChange', callback?: Callback<TitleButtonRect>): void 5756 5757Unsubscribes 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. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 5758 5759<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 5760 5761**Atomic service API**: This API can be used in atomic services since API version 12. 5762 5763**System capability**: SystemCapability.Window.SessionManager 5764 5765**Parameters** 5766 5767| Name | Type | Mandatory| Description | 5768| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 5769| 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.| 5770| 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.| 5771 5772**Error codes** 5773 5774For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5775 5776| ID| Error Message | 5777| -------- | ------------------------------ | 5778| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5779| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5780| 1300002 | This window state is abnormal. | 5781 5782**Example** 5783 5784```ts 5785windowClass.setUIContent('pages/WindowPage').then(() => { 5786 const callback = (titleButtonRect: window.TitleButtonRect) => { 5787 // ... 5788 } 5789 try { 5790 // Enable listening through the on API. 5791 windowClass?.on('windowTitleButtonRectChange', callback); 5792 // Disable the listening of a specified callback. 5793 windowClass?.off('windowTitleButtonRectChange', callback); 5794 // Unregister all the callbacks that have been registered through on(). 5795 windowClass?.off('windowTitleButtonRectChange'); 5796 } catch (exception) { 5797 console.error(`Failed to disable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 5798 } 5799}) 5800``` 5801 5802### on('windowRectChange')<sup>12+</sup> 5803 5804on(type: 'windowRectChange', callback: Callback<RectChangeOptions>): void 5805 5806Subscribes to window rectangle (position and size) change events. 5807 5808**System capability**: SystemCapability.Window.SessionManager 5809 5810**Atomic service API**: This API can be used in atomic services since API version 12. 5811 5812**Parameters** 5813 5814| Name | Type | Mandatory| Description | 5815| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 5816| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event.| 5817| callback | Callback<[RectChangeOptions](#rectchangeoptions12)> | Yes | Callback used to return the value and reason of the window rectangle change. | 5818 5819**Error codes** 5820 5821For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5822 5823| ID| Error Message| 5824| ------- | -------------------------------------------- | 5825| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5826| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5827| 1300002 | This window state is abnormal. | 5828| 1300003 | This window manager service works abnormally. | 5829 5830**Example** 5831 5832```ts 5833try { 5834 windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 5835 console.info(`Succeeded window rect changes. Data: ` + JSON.stringify(data)); 5836 }); 5837} catch (exception) { 5838 console.error(`Failed to disable the listener for window rect changes. Cause code: ${exception.code}, message: ${exception.message}`); 5839} 5840``` 5841 5842### off('windowRectChange')<sup>12+</sup> 5843 5844off(type: 'windowRectChange', callback?: Callback<RectChangeOptions>): void 5845 5846Unsubscribes from window rectangle (position and size) change events. 5847 5848**System capability**: SystemCapability.Window.SessionManager 5849 5850**Atomic service API**: This API can be used in atomic services since API version 12. 5851 5852**Parameters** 5853 5854| Name | Type | Mandatory| Description | 5855| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 5856| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event. | 5857| 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.| 5858 5859**Error codes** 5860 5861For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5862 5863| ID| Error Message| 5864| ------- | -------------------------------------------- | 5865| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5866| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5867| 1300002 | This window state is abnormal. | 5868| 1300003 | This window manager service works abnormally. | 5869 5870**Example** 5871 5872```ts 5873const callback = (rectChangeOptions: window.RectChangeOptions) => { 5874 // ... 5875} 5876 5877try { 5878 windowClass.on('windowRectChange', callback); 5879 windowClass.off('windowRectChange', callback); 5880 // Unregister all the callbacks that have been registered through on(). 5881 windowClass.off('windowRectChange'); 5882} catch (exception) { 5883 console.error(`Failed to disable the listener for window rect changes. Cause code: ${exception.code}, message: ${exception.message}`); 5884} 5885``` 5886 5887### on('subWindowClose')<sup>12+</sup> 5888 5889on(type: 'subWindowClose', callback: Callback<void>): void 5890 5891Subscribes to the event indicating that the child window is closed. This event is triggered only when the user clicks the system-provided close button in the upper right corner to close the child window. It is not triggered when the child window is closed in other ways. 5892 5893If the event is subscribed to multiple times, only the most recently subscribed-to event takes effect. 5894 5895The callback function in this API is executed synchronously. For asynchronous close events of child windows, refer to [on('windowWillClose')](#onwindowwillclose15). 5896 5897If there is an existing event subscribed to by calling [on('windowWillClose')](#onwindowwillclose15), only the [on('windowWillClose')](#onwindowwillclose15) API will be responded to. 5898 5899**Atomic service API**: This API can be used in atomic services since API version 12. 5900 5901**System capability**: SystemCapability.Window.SessionManager 5902 5903**Parameters** 5904 5905| Name | Type | Mandatory| Description | 5906| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 5907| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the child window close event.| 5908| callback | Callback<void> | Yes | Callback invoked when the close button in the upper right corner of the child window is clicked. It does not return any parameter. The return value of the internal logic of the callback function determines whether to continue to close the child window. If **true** of the Boolean type is returned, the child window is not closed. If **false** or other non-Boolean types are returned, the child window is closed. | 5909 5910**Error codes** 5911 5912For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5913 5914| ID| Error Message| 5915| ------- | -------------------------------------------- | 5916| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5917| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5918| 1300002 | This window state is abnormal. | 5919| 1300004 | Unauthorized operation. | 5920 5921**Example** 5922 5923```ts 5924const callback = () => { 5925 // ... 5926 return true; 5927} 5928try { 5929 windowClass.on('subWindowClose', callback); 5930} catch (exception) { 5931 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5932} 5933``` 5934 5935### off('subWindowClose')<sup>12+</sup> 5936 5937off(type: 'subWindowClose', callback?: Callback<void>): void 5938 5939Unsubscribes from the event indicating that the child window is closed. 5940 5941**Atomic service API**: This API can be used in atomic services since API version 12. 5942 5943**System capability**: SystemCapability.Window.SessionManager 5944 5945**Parameters** 5946 5947| Name | Type | Mandatory| Description | 5948| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 5949| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the child window close event. | 5950| callback | Callback<void> | No | Callback invoked when the close button in the upper right corner of the child window is clicked. It does not return any parameter. The return value of the internal logic of the callback function determines whether to continue to close the child window. If **true** of the Boolean type is returned, the child window is not closed. If **false** or other non-Boolean types are returned, the child window is closed. 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.| 5951 5952**Error codes** 5953 5954For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5955 5956| ID| Error Message| 5957| ------- | -------------------------------------------- | 5958| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 5959| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5960| 1300002 | This window state is abnormal. | 5961| 1300004 | Unauthorized operation. | 5962 5963**Example** 5964 5965```ts 5966const callback = () => { 5967 // ... 5968 return true; 5969} 5970try { 5971 windowClass.on('subWindowClose', callback); 5972 windowClass.off('subWindowClose', callback); 5973 // Unregister all the callbacks that have been registered through on(). 5974 windowClass.off('subWindowClose'); 5975} catch (exception) { 5976 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5977} 5978``` 5979 5980### on('windowWillClose')<sup>15+</sup> 5981 5982on(type: 'windowWillClose', callback: Callback<void, Promise<boolean>>): void 5983 5984Subscribes to the event indicating that the main window or child window will be closed. This event is triggered only when the user clicks the close button in the system-provided title bar to close the window. It is not triggered when the window is closed in other ways. 5985 5986The callback function in this API is executed synchronously. For synchronous close events of child windows, refer to [on('subWindowClose')](#onsubwindowclose12). For synchronous close events of the main window, refer to [on('windowStageClose')](#onwindowstageclose14). 5987 5988<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> <br> 5989 5990**Atomic service API**: This API can be used in atomic services since API version 15. 5991 5992**System capability**: SystemCapability.Window.SessionManager 5993 5994**Parameters** 5995 5996| Name | Type | Mandatory| Description | 5997| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 5998| type | string | Yes | Event type. The value is fixed at **'windowWillClose'**, indicating the window close event.| 5999| callback | Callback<void, Promise<boolean>> | Yes | Callback invoked when the close button in the upper right corner of the window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Promise<boolean> type. In the returned Promise function, **resolve(true)** means not to close the window, and **resolve(false)** or **reject** means to continue to close the window.| 6000 6001**Error codes** 6002 6003For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6004 6005| ID| Error Message| 6006| ------- | -------------------------------------------- | 6007| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 6008| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6009| 1300002 | This window state is abnormal. | 6010| 1300004 | Unauthorized operation. | 6011 6012**Example** 6013 6014```ts 6015// EntryAbility.ets 6016import { UIAbility } from '@kit.AbilityKit'; 6017import { window } from '@kit.ArkUI'; 6018 6019export default class EntryAbility extends UIAbility { 6020 6021 onWindowStageCreate(windowStage: window.WindowStage) { 6022 console.info('onWindowStageCreate'); 6023 const callback = () => { 6024 // ... 6025 return new Promise<boolean>((resolve, reject) => { 6026 // Whether to close the window. 6027 let result: boolean = true; 6028 resolve(result); 6029 }); 6030 } 6031 try { 6032 let windowClass = windowStage.getMainWindowSync(); 6033 windowClass.on('windowWillClose', callback); 6034 } catch (exception) { 6035 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 6036 } 6037 } 6038} 6039``` 6040 6041### off('windowWillClose')<sup>15+</sup> 6042 6043off(type: 'windowWillClose', callback?: Callback<void, Promise<boolean>>): void 6044 6045Unsubscribes from the event indicating that the main window or child window will be closed. 6046 6047<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> <br> 6048 6049**Atomic service API**: This API can be used in atomic services since API version 15. 6050 6051**System capability**: SystemCapability.Window.SessionManager 6052 6053**Parameters** 6054 6055| Name | Type | Mandatory| Description | 6056| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 6057| type | string | Yes | Event type. The value is fixed at **'windowWillClose'**, indicating the window close event.| 6058| callback | Callback<void, Promise<boolean>> | No | Callback invoked when the close button in the upper right corner of the window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Promise<boolean> type. In the returned Promise function, **resolve(true)** means not to close the window, and **resolve(false)** or **reject** means to continue to close the window.| 6059 6060**Error codes** 6061 6062For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6063 6064| ID| Error Message| 6065| ------- | -------------------------------------------- | 6066| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 6067| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6068| 1300002 | This window state is abnormal. | 6069| 1300004 | Unauthorized operation. | 6070 6071**Example** 6072 6073```ts 6074// EntryAbility.ets 6075import { UIAbility } from '@kit.AbilityKit'; 6076import { window } from '@kit.ArkUI'; 6077 6078export default class EntryAbility extends UIAbility { 6079 6080 onWindowStageCreate(windowStage: window.WindowStage) { 6081 console.info('onWindowStageCreate'); 6082 try { 6083 const callback = () => { 6084 // ... 6085 return new Promise<boolean>((resolve, reject) => { 6086 // Whether to close the window. 6087 let result: boolean = true; 6088 resolve(result); 6089 }); 6090 } 6091 let windowClass = windowStage.getMainWindowSync(); 6092 windowClass.on('windowWillClose', callback); 6093 windowClass.off('windowWillClose', callback); 6094 // Unregister all the callbacks that have been registered through on(). 6095 windowClass.off('windowWillClose'); 6096 } catch (exception) { 6097 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 6098 } 6099 } 6100} 6101``` 6102 6103### on('windowHighlightChange')<sup>15+</sup> 6104 6105on(type: 'windowHighlightChange', callback: Callback<boolean>): void 6106 6107Subscribes to the highlighted state change event of the window. 6108 6109**Atomic service API**: This API can be used in atomic services since API version 15. 6110 6111**System capability**: SystemCapability.Window.SessionManager 6112 6113**Parameters** 6114 6115| Name | Type | Mandatory| Description | 6116| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 6117| type | string | Yes | Event type. The value is fixed at **'windowHighlightChange'**, indicating the window highlighted state change event.| 6118| callback | Callback<boolean> | Yes | Callback used to return the highlighted state of the window. which is a Boolean value. The value **true** means that the window is highlighted, and **false** means the opposite. | 6119 6120**Error codes** 6121 6122For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6123 6124| ID| Error Message| 6125| ------- | -------------------------------------------- | 6126| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6127| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6128| 1300002 | This window state is abnormal. | 6129| 1300003 | This window manager service works abnormally. | 6130 6131**Example** 6132 6133```ts 6134try { 6135 windowClass.on('windowHighlightChange', (data: boolean) => { 6136 console.info(`Window highlight Change: ${data}`); 6137 }); 6138} catch (exception) { 6139 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 6140} 6141``` 6142 6143### off('windowHighlightChange')<sup>15+</sup> 6144 6145off(type: 'windowHighlightChange', callback?: Callback<boolean>): void 6146 6147Unsubscribes from the highlighted state change event of the window. 6148 6149**Atomic service API**: This API can be used in atomic services since API version 15. 6150 6151**System capability**: SystemCapability.Window.SessionManager 6152 6153**Parameters** 6154 6155| Name | Type | Mandatory| Description | 6156| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 6157| type | string | Yes | Event type. The value is fixed at **'windowHighlightChange'**, indicating the window highlighted state change event. | 6158| callback | Callback<boolean> | No | Callback used to return the highlighted state 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.| 6159 6160**Error codes** 6161 6162For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6163 6164| ID| Error Message| 6165| ------- | -------------------------------------------- | 6166| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6167| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6168| 1300002 | This window state is abnormal. | 6169| 1300003 | This window manager service works abnormally. | 6170 6171**Example** 6172 6173```ts 6174const callback = (data: boolean) => { 6175 // ... 6176} 6177try { 6178 // Enable listening through the on API. 6179 windowClass.on('windowHighlightChange', callback); 6180 // Disable the listening of a specified callback. 6181 windowClass.off('windowHighlightChange', callback); 6182 // Unregister all the callbacks that have been registered through on(). 6183 windowClass.off('windowHighlightChange'); 6184} catch (exception) { 6185 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 6186} 6187``` 6188 6189### on('rotationChange')<sup>19+</sup> 6190 6191on(type: 'rotationChange', callback: RotationChangeCallback<RotationChangeInfo, RotationChangeResult | void>): void 6192 6193Subscribes to the window rotation change event. If the window rotation event type in [RotationChangeInfo](#rotationchangeinfo19) is **WINDOW_WILL_ROTATE**, [RotationChangeResult](#rotationchangeresult19) must be returned. If the window rotation event type is **WINDOW_DID_ROTATE**, [RotationChangeResult](#rotationchangeresult19) does not take effect. 6194 6195If a window registers multiple callbacks of the same type, only the return value of the most recently registered callback will be effective. The system provides a timeout protection mechanism. If the window does not return [RotationChangeResult](#rotationchangeresult19) within 20 ms, the system does not process the return value. 6196 6197<!--RP10-->This API has no effect on 2-in-1 devices.<!--RP10End--> 6198 6199**Atomic service API**: This API can be used in atomic services since API version 19. 6200 6201**System capability**: SystemCapability.Window.SessionManager 6202 6203**Parameters** 6204 6205| Name | Type | Mandatory| Description | 6206| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 6207| type | string | Yes | Event type. The value is fixed at **'rotationChange'**, indicating the window rotation change event.| 6208| callback | RotationChangeCallback<[RotationChangeInfo](#rotationchangeinfo19), [RotationChangeResult](#rotationchangeresult19) \| void> | Yes| Callback used to return [RotationChangeInfo](#rotationchangeinfo19) and [RotationChangeResult](#rotationchangeresult19). | 6209 6210**Error codes** 6211 6212For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6213 6214| ID| Error Message| 6215| ------- | -------------------------------------------- | 6216| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6217| 1300002 | This window state is abnormal. | 6218| 1300003 | This window manager service works abnormally. | 6219 6220**Example** 6221 6222```ts 6223function calculateRect(info: window.RotationChangeInfo): window.Rect { 6224 // calculate result with info 6225 let rect : window.Rect = { 6226 left: 0, 6227 top: 0, 6228 width: 500, 6229 height: 600, 6230 } 6231 return rect; 6232} 6233 6234const callback = (info: window.RotationChangeInfo): window.RotationChangeResult | void => { 6235 let result: window.RotationChangeResult = { 6236 rectType: window.RectType.RELATIVE_TO_SCREEN, 6237 windowRect: { 6238 left: 0, 6239 top: 0, 6240 width: 0, 6241 height: 0, 6242 } 6243 }; 6244 if (info.type === window.RotationChangeType.WINDOW_WILL_ROTATE) { 6245 result.rectType = window.RectType.RELATIVE_TO_SCREEN; 6246 result.windowRect = calculateRect(info); 6247 return result; 6248 } else { 6249 // do something after rotate 6250 return; 6251 } 6252} 6253 6254try { 6255 windowClass.on('rotationChange', callback); 6256} catch (exception) { 6257 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 6258} 6259``` 6260 6261### off('rotationChange')<sup>19+</sup> 6262 6263off(type: 'rotationChange', callback?: RotationChangeCallback<RotationChangeInfo, RotationChangeResult | void>): void 6264 6265Unsubscribes from the window rotation change event. 6266 6267<!--RP10-->This API has no effect on 2-in-1 devices.<!--RP10End--> 6268 6269**Atomic service API**: This API can be used in atomic services since API version 19. 6270 6271**System capability**: SystemCapability.Window.SessionManager 6272 6273**Parameters** 6274 6275| Name | Type | Mandatory| Description | 6276| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 6277| type | string | Yes | Event type. The value is fixed at **'rotationChange'**, indicating the window rotation change event. | 6278| callback | RotationChangeCallback<info: [RotationChangeInfo](#rotationchangeinfo19), [RotationChangeResult](#rotationchangeresult19) \| void> | No | Callback used to return the result. 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.| 6279 6280**Error codes** 6281 6282For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6283 6284| ID| Error Message| 6285| ------- | -------------------------------------------- | 6286| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6287| 1300002 | This window state is abnormal. | 6288| 1300003 | This window manager service works abnormally. | 6289 6290**Example** 6291 6292```ts 6293const callback = (info: window.RotationChangeInfo): window.RotationChangeResult | void => { 6294 // ... 6295 return; 6296} 6297try { 6298 windowClass.off('rotationChange', callback); 6299 // Unregister all the callbacks that have been registered through on(). 6300 windowClass.off('rotationChange'); 6301} catch (exception) { 6302 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 6303} 6304``` 6305 6306### on('uiExtensionSecureLimitChange')<sup>20+</sup> 6307 6308on(type: 'uiExtensionSecureLimitChange', callback: Callback<boolean>): void 6309 6310Subscribes to the event indicating changes in the security restrictions of the UIExtensionAbility within the window. You are advised to initiate the subscription right after the window is created. 6311 6312**Atomic service API**: This API can be used in atomic services since API version 20. 6313 6314**System capability**: SystemCapability.Window.SessionManager 6315 6316**Parameters** 6317 6318| Name | Type | Mandatory| Description | 6319| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 6320| type | string | Yes | Event type. The value is fixed at **'uiExtensionSecureLimitChange'**, indicating that the UIExtensionAbility security restrictions in the window changes.| 6321| callback | Callback<boolean> | Yes | Callback used to return the result. The value **true** means that at least one UIExtensionAbility within the window has enabled the hiding of unsafe windows, and **false** means that all UIExtensionAbilities within the window have disabled the hiding of unsafe windows. | 6322 6323**Error codes** 6324 6325For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6326 6327| ID| Error Message| 6328| ------- | -------------------------------------------- | 6329| 801 | Capability not supported.Function on('uiExtensionSecureLimitChange') can not work correctly due to limited device capabilities. | 6330| 1300002 | This window state is abnormal. | 6331| 1300003 | This window manager service works abnormally. | 6332 6333**Example** 6334 6335```ts 6336try { 6337 windowClass.on('uiExtensionSecureLimitChange', (data: boolean) => { 6338 console.info(`Window secure limit Change: ${data}`); 6339 }); 6340} catch (exception) { 6341 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 6342} 6343``` 6344 6345### off('uiExtensionSecureLimitChange')<sup>20+</sup> 6346 6347off(type: 'uiExtensionSecureLimitChange', callback?: Callback<boolean>): void 6348 6349Unsubscribes from the event indicating changes in the security restrictions of the UIExtensionAbility within the window. 6350 6351**Atomic service API**: This API can be used in atomic services since API version 20. 6352 6353**System capability**: SystemCapability.Window.SessionManager 6354 6355**Parameters** 6356 6357| Name | Type | Mandatory| Description | 6358| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 6359| type | string | Yes | Event type. The value is fixed at **'uiExtensionSecureLimitChange'**, indicating that the UIExtensionAbility security restrictions in the window changes. | 6360| callback | Callback<boolean> | No | Callback used to return the result. 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.| 6361 6362**Error codes** 6363 6364For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6365 6366| ID| Error Message| 6367| ------- | -------------------------------------------- | 6368| 801 | Capability not supported.Function off('uiExtensionSecureLimitChange') can not work correctly due to limited device capabilities. | 6369| 1300002 | This window state is abnormal. | 6370| 1300003 | This window manager service works abnormally. | 6371 6372**Example** 6373 6374```ts 6375const callback = (data: boolean) => { 6376 // ... 6377} 6378try { 6379 // Enable listening through the on API. 6380 windowClass.on('uiExtensionSecureLimitChange', callback); 6381 // Disable the listening of a specified callback. 6382 windowClass.off('uiExtensionSecureLimitChange', callback); 6383 // Unregister all the callbacks that have been registered through on(). 6384 windowClass.off('uiExtensionSecureLimitChange'); 6385} catch (exception) { 6386 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 6387} 6388``` 6389 6390### isWindowSupportWideGamut<sup>9+</sup> 6391 6392isWindowSupportWideGamut(callback: AsyncCallback<boolean>): void 6393 6394Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 6395 6396**Atomic service API**: This API can be used in atomic services since API version 12. 6397 6398**System capability**: SystemCapability.WindowManager.WindowManager.Core 6399 6400**Parameters** 6401 6402| Name| Type| Mandatory| Description| 6403| -------- | ---------------------------- | -- | -------------------------------------------------------------------------------- | 6404| 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.| 6405 6406**Error codes** 6407 6408For details about the error codes, see [Window Error Codes](errorcode-window.md). 6409 6410| ID| Error Message| 6411| ------- | ------------------------------ | 6412| 1300002 | This window state is abnormal. | 6413 6414**Example** 6415 6416```ts 6417import { BusinessError } from '@kit.BasicServicesKit'; 6418 6419windowClass.isWindowSupportWideGamut((err: BusinessError, data) => { 6420 const errCode: number = err.code; 6421 if (errCode) { 6422 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 6423 return; 6424 } 6425 console.info(`Succeeded in checking whether the window support WideGamut Data: ${data}`); 6426}); 6427``` 6428 6429### isWindowSupportWideGamut<sup>9+</sup> 6430 6431isWindowSupportWideGamut(): Promise<boolean> 6432 6433Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 6434 6435**Atomic service API**: This API can be used in atomic services since API version 12. 6436 6437**System capability**: SystemCapability.WindowManager.WindowManager.Core 6438 6439**Return value** 6440 6441| Type| Description| 6442| ---------------------- | ------------------------------------------------------------------------------------ | 6443| 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.| 6444 6445**Error codes** 6446 6447For details about the error codes, see [Window Error Codes](errorcode-window.md). 6448 6449| ID| Error Message| 6450| ------- | ------------------------------ | 6451| 1300002 | This window state is abnormal. | 6452 6453**Example** 6454 6455```ts 6456import { BusinessError } from '@kit.BasicServicesKit'; 6457 6458let promise = windowClass.isWindowSupportWideGamut(); 6459promise.then((data) => { 6460 console.info(`Succeeded in checking whether the window support WideGamut. Data: ${data}`); 6461}).catch((err: BusinessError) => { 6462 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 6463}); 6464``` 6465 6466### setWindowColorSpace<sup>9+</sup> 6467 6468setWindowColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 6469 6470Sets a color space for this window. This API uses an asynchronous callback to return the result. 6471 6472**Atomic service API**: This API can be used in atomic services since API version 12. 6473 6474**System capability**: SystemCapability.WindowManager.WindowManager.Core 6475 6476**Parameters** 6477 6478| Name| Type| Mandatory| Description| 6479| ---------- | ------------------------- | -- | ----------- | 6480| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 6481| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 6482 6483**Error codes** 6484 6485For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6486 6487| ID| Error Message| 6488| ------- | ------------------------------ | 6489| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6490| 1300002 | This window state is abnormal. | 6491 6492**Example** 6493 6494```ts 6495import { BusinessError } from '@kit.BasicServicesKit'; 6496 6497try { 6498 windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 6499 const errCode: number = err.code; 6500 if (errCode) { 6501 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 6502 return; 6503 } 6504 console.info('Succeeded in setting window colorspace.'); 6505 }); 6506} catch (exception) { 6507 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 6508} 6509``` 6510 6511### setWindowColorSpace<sup>9+</sup> 6512 6513setWindowColorSpace(colorSpace:ColorSpace): Promise<void> 6514 6515Sets a color space for this window. This API uses a promise to return the result. 6516 6517**Atomic service API**: This API can be used in atomic services since API version 12. 6518 6519**System capability**: SystemCapability.WindowManager.WindowManager.Core 6520 6521**Parameters** 6522 6523| Name| Type| Mandatory| Description| 6524| ---------- | ------------------------- | -- | ------------- | 6525| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 6526 6527**Return value** 6528 6529| Type| Description| 6530| ------------------- | ------------------------ | 6531| Promise<void> | Promise that returns no value.| 6532 6533**Error codes** 6534 6535For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6536 6537| ID| Error Message| 6538| ------- | ------------------------------ | 6539| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6540| 1300002 | This window state is abnormal. | 6541 6542**Example** 6543 6544```ts 6545import { BusinessError } from '@kit.BasicServicesKit'; 6546 6547try { 6548 let promise = windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT); 6549 promise.then(() => { 6550 console.info('Succeeded in setting window colorspace.'); 6551 }).catch((err: BusinessError) => { 6552 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 6553 }); 6554} catch (exception) { 6555 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 6556} 6557``` 6558 6559### getWindowColorSpace<sup>9+</sup> 6560 6561getWindowColorSpace(): ColorSpace 6562 6563Obtains the color space of this window. 6564 6565**Atomic service API**: This API can be used in atomic services since API version 12. 6566 6567**System capability**: SystemCapability.WindowManager.WindowManager.Core 6568 6569**Return value** 6570 6571| Type| Description| 6572| ------------------------- | ------------- | 6573| [ColorSpace](#colorspace8) | Color space obtained.| 6574 6575**Error codes** 6576 6577For details about the error codes, see [Window Error Codes](errorcode-window.md). 6578 6579| ID| Error Message| 6580| ------- | ------------------------------ | 6581| 1300002 | This window state is abnormal. | 6582 6583**Example** 6584 6585```ts 6586import { BusinessError } from '@kit.BasicServicesKit'; 6587 6588try { 6589 let colorSpace = windowClass.getWindowColorSpace(); 6590 console.info(`Succeeded in getting the window color space. ColorSpace: ${colorSpace}`); 6591} catch (exception) { 6592 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 6593} 6594``` 6595 6596### setWindowBackgroundColor<sup>9+</sup> 6597 6598setWindowBackgroundColor(color: string | ColorMetrics): void 6599 6600Sets 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. 6601 6602**System capability**: SystemCapability.WindowManager.WindowManager.Core 6603 6604**Atomic service API**: This API can be used in atomic services since API version 11. 6605 6606**Parameters** 6607 6608| Name| Type| Mandatory| Description| 6609| ----- | ------ | -- | ----------------------------------------------------------------------- | 6610| color | string \| [ColorMetrics](js-apis-arkui-graphics.md#colormetrics12)<sup>18+</sup> | Yes| Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**.<br>Since API version 18, this parameter supports the ColorMetrics type.| 6611 6612**Error codes** 6613 6614For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6615 6616| ID| Error Message| 6617| ------- | ------------------------------ | 6618| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6619| 1300002 | This window state is abnormal. | 6620 6621**Example** 6622 6623```ts 6624import { BusinessError } from '@kit.BasicServicesKit'; 6625import { ColorMetrics } from '@kit.ArkUI'; 6626 6627let storage: LocalStorage = new LocalStorage(); 6628storage.setOrCreate('storageSimpleProp', 121); 6629windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 6630 let errCode: number = err.code; 6631 if (errCode) { 6632 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 6633 return; 6634 } 6635 console.info('Succeeded in loading the content.'); 6636 let color1: string = '#00ff33'; 6637 let color2: ColorMetrics = ColorMetrics.numeric(0xff112233); 6638 try { 6639 windowClass?.setWindowBackgroundColor(color1); 6640 windowClass?.setWindowBackgroundColor(color2); 6641 } catch (exception) { 6642 console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`); 6643 }; 6644}); 6645``` 6646 6647### setWindowBrightness<sup>9+</sup> 6648 6649setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void 6650 6651Sets the screen brightness for the main window. This API uses an asynchronous callback to return the result. 6652 6653- For non-2-in-1 devices, 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. 6654- For 2-in-1 devices, Control Panel has the same priority as this API. Event if this API is called to set the window-specific screen brightness, Control Panel can adjust the overall system screen brightness. 6655 6656**System capability**: SystemCapability.WindowManager.WindowManager.Core 6657 6658**Atomic service API**: This API can be used in atomic services since API version 11. 6659 6660**Parameters** 6661 6662| Name| Type| Mandatory| Description | 6663| ---------- | ------------------------- | -- |-------------------------------------------| 6664| brightness | number | Yes| Brightness to set. The value is a floating point number in the range [0.0, 1.0] or is set to **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.| 6665| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 6666 6667**Error codes** 6668 6669For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6670 6671| ID| Error Message| 6672| ------- | -------------------------------------------- | 6673| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6674| 1300002 | This window state is abnormal. | 6675| 1300003 | This window manager service works abnormally. | 6676 6677**Example** 6678 6679```ts 6680// EntryAbility.ets 6681import { UIAbility } from '@kit.AbilityKit'; 6682import { BusinessError } from '@kit.BasicServicesKit'; 6683 6684export default class EntryAbility extends UIAbility { 6685 // ... 6686 onWindowStageCreate(windowStage: window.WindowStage): void { 6687 console.info('onWindowStageCreate'); 6688 let windowClass: window.Window | undefined = undefined; 6689 windowStage.getMainWindow((err: BusinessError, data) => { 6690 const errCode: number = err.code; 6691 if (errCode) { 6692 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6693 return; 6694 } 6695 windowClass = data; 6696 let brightness: number = 1.0; 6697 try { 6698 windowClass.setWindowBrightness(brightness, (err: BusinessError) => { 6699 const errCode: number = err.code; 6700 if (errCode) { 6701 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 6702 return; 6703 } 6704 console.info('Succeeded in setting the brightness.'); 6705 }); 6706 } catch (exception) { 6707 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 6708 } 6709 }); 6710 } 6711} 6712``` 6713 6714### setWindowBrightness<sup>9+</sup> 6715 6716setWindowBrightness(brightness: number): Promise<void> 6717 6718Sets the screen brightness for the main window. This API uses a promise to return the result. 6719 6720- For non-2-in-1 devices, 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. 6721- For 2-in-1 devices, Control Panel has the same priority as this API. Event if this API is called to set the window-specific screen brightness, Control Panel can adjust the overall system screen brightness. 6722 6723**System capability**: SystemCapability.WindowManager.WindowManager.Core 6724 6725**Atomic service API**: This API can be used in atomic services since API version 11. 6726 6727**Parameters** 6728 6729| Name| Type| Mandatory| Description | 6730| ---------- | ------ | -- |----------------------------------------| 6731| brightness | number | Yes| Brightness to set. The value is a floating point number in the range [0.0, 1.0] or is set to **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.| 6732 6733**Return value** 6734 6735| Type| Description| 6736| ------------------- | ------------------------ | 6737| Promise<void> | Promise that returns no value.| 6738 6739**Error codes** 6740 6741For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6742 6743| ID| Error Message| 6744| ------- | -------------------------------------------- | 6745| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6746| 1300002 | This window state is abnormal. | 6747| 1300003 | This window manager service works abnormally. | 6748 6749**Example** 6750 6751```ts 6752// EntryAbility.ets 6753import { UIAbility } from '@kit.AbilityKit'; 6754import { BusinessError } from '@kit.BasicServicesKit'; 6755 6756export default class EntryAbility extends UIAbility { 6757 // ... 6758 onWindowStageCreate(windowStage: window.WindowStage): void { 6759 console.info('onWindowStageCreate'); 6760 let windowClass: window.Window | undefined = undefined; 6761 windowStage.getMainWindow((err: BusinessError, data) => { 6762 const errCode: number = err.code; 6763 if (errCode) { 6764 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6765 return; 6766 } 6767 windowClass = data; 6768 let brightness: number = 1.0; 6769 try { 6770 let promise = windowClass.setWindowBrightness(brightness); 6771 promise.then(() => { 6772 console.info('Succeeded in setting the brightness.'); 6773 }).catch((err: BusinessError) => { 6774 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 6775 }); 6776 } catch (exception) { 6777 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 6778 } 6779 }); 6780 } 6781} 6782``` 6783 6784### setWindowFocusable<sup>9+</sup> 6785 6786setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 6787 6788Sets whether this window is focusable. This API uses an asynchronous callback to return the result. 6789 6790**Atomic service API**: This API can be used in atomic services since API version 12. 6791 6792**System capability**: SystemCapability.WindowManager.WindowManager.Core 6793 6794**Parameters** 6795 6796| Name| Type| Mandatory| Description| 6797| ----------- | ------------------------- | -- | ------------------------------------------------------- | 6798| isFocusable | boolean | Yes| Whether the window is focusable. The value **true** means that the window is focusable, and **false** means the opposite.| 6799| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 6800 6801**Error codes** 6802 6803For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6804 6805| ID| Error Message| 6806| ------- | -------------------------------------------- | 6807| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6808| 1300002 | This window state is abnormal. | 6809| 1300003 | This window manager service works abnormally. | 6810 6811**Example** 6812 6813```ts 6814import { BusinessError } from '@kit.BasicServicesKit'; 6815 6816let isFocusable: boolean = true; 6817try { 6818 windowClass.setWindowFocusable(isFocusable, (err: BusinessError) => { 6819 const errCode: number = err.code; 6820 if (errCode) { 6821 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 6822 return; 6823 } 6824 console.info('Succeeded in setting the window to be focusable.'); 6825 }); 6826} catch (exception) { 6827 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 6828} 6829``` 6830 6831### setWindowFocusable<sup>9+</sup> 6832 6833setWindowFocusable(isFocusable: boolean): Promise<void> 6834 6835Sets whether this window is focusable. This API uses a promise to return the result. 6836 6837**Atomic service API**: This API can be used in atomic services since API version 12. 6838 6839**System capability**: SystemCapability.WindowManager.WindowManager.Core 6840 6841**Parameters** 6842 6843| Name| Type| Mandatory| Description| 6844| ----------- | ------- | -- | -------------------------------------------------------- | 6845| isFocusable | boolean | Yes| Whether the window is focusable. The value **true** means that the window is focusable, and **false** means the opposite. | 6846 6847**Return value** 6848 6849| Type| Description| 6850| ------------------- | ------------------------ | 6851| Promise<void> | Promise that returns no value.| 6852 6853**Error codes** 6854 6855For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6856 6857| ID| Error Message| 6858| ------- | -------------------------------------------- | 6859| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6860| 1300002 | This window state is abnormal. | 6861| 1300003 | This window manager service works abnormally. | 6862 6863**Example** 6864 6865```ts 6866import { BusinessError } from '@kit.BasicServicesKit'; 6867 6868let isFocusable: boolean = true; 6869try { 6870 let promise = windowClass.setWindowFocusable(isFocusable); 6871 promise.then(() => { 6872 console.info('Succeeded in setting the window to be focusable.'); 6873 }).catch((err: BusinessError) => { 6874 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 6875 }); 6876} catch (exception) { 6877 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 6878} 6879``` 6880 6881### setStartWindowBackgroundColor<sup>20+</sup> 6882 6883setStartWindowBackgroundColor(moduleName: string, abilityName: string, color: ColorMetrics): Promise<void> 6884 6885Sets the background color of the splash screen of the UIAbility based on the specified module name and ability name in the same application. This API uses a promise to return the result. 6886 6887This API takes effect for all processes of the same application, for example, in multi-instance or clone scenarios. 6888 6889**Atomic service API**: This API can be used in atomic services since API version 20. 6890 6891**System capability**: SystemCapability.Window.SessionManager 6892 6893**Parameters** 6894 6895| Name | Type | Mandatory| Description | 6896| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 6897| moduleName | string | Yes | Module name of the UIAbility. The value is a string of 0 to 200 characters. Only the module names within the same application can be set.| 6898| abilityName | string | Yes | Name of the UIAbility. The value is a string of 0 to 200 characters. Only the ability names within the same application can be set.| 6899| color | [ColorMetrics](js-apis-arkui-graphics.md#colormetrics12) | Yes | Background color of the splash screen. | 6900 6901**Return value** 6902 6903| Type| Description| 6904| ------------------- | ------------------------ | 6905| Promise<void> | Promise that returns no value.| 6906 6907**Error codes** 6908 6909For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6910 6911| ID| Error Message| 6912| ------- | -------------------------------------------- | 6913| 801 | Capability not supported.function setStartWindowBackgroundColor can not to work correctly due to limited device capabilities. | 6914| 1300003 | This window manager service works abnormally. | 6915| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range. | 6916 6917**Example** 6918 6919```ts 6920// EntryAbility.ets 6921import { UIAbility } from '@kit.AbilityKit'; 6922import { BusinessError } from '@kit.BasicServicesKit'; 6923import { ColorMetrics, window } from '@kit.ArkUI'; 6924 6925try { 6926 let promise = 6927 window.setStartWindowBackgroundColor("entry", "EntryAbility", ColorMetrics.numeric(0xff000000)); 6928 promise.then(() => { 6929 console.log('Succeeded in setting the starting window color.'); 6930 }).catch((err: BusinessError) => { 6931 console.error(`Set the starting window color failed. Cause code: ${err.code}, message: ${err.message}`); 6932 }); 6933} catch (exception) { 6934 console.error(`Failed to set the starting window color. Cause code: ${exception.code}, message: ${exception.message}`); 6935} 6936``` 6937 6938### setWindowKeepScreenOn<sup>9+</sup> 6939 6940setWindowKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 6941 6942Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 6943 6944Set **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. 6945 6946**System capability**: SystemCapability.WindowManager.WindowManager.Core 6947 6948**Atomic service API**: This API can be used in atomic services since API version 11. 6949 6950**Parameters** 6951 6952| Name| Type| Mandatory| Description| 6953| -------------- | ------------------------- | -- | ---------------------------------------------------- | 6954| 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. | 6955| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 6956 6957**Error codes** 6958 6959For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6960 6961| ID| Error Message| 6962| ------- | -------------------------------------------- | 6963| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6964| 1300002 | This window state is abnormal. | 6965| 1300003 | This window manager service works abnormally. | 6966 6967**Example** 6968 6969```ts 6970import { BusinessError } from '@kit.BasicServicesKit'; 6971 6972let isKeepScreenOn: boolean = true; 6973try { 6974 windowClass.setWindowKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 6975 const errCode: number = err.code; 6976 if (errCode) { 6977 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 6978 return; 6979 } 6980 console.info('Succeeded in setting the screen to be always on.'); 6981 }); 6982} catch (exception) { 6983 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 6984} 6985``` 6986 6987### setWindowKeepScreenOn<sup>9+</sup> 6988 6989setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 6990 6991Sets whether to keep the screen always on. This API uses a promise to return the result. 6992 6993Set **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. 6994 6995**System capability**: SystemCapability.WindowManager.WindowManager.Core 6996 6997**Atomic service API**: This API can be used in atomic services since API version 11. 6998 6999**Parameters** 7000 7001| Name| Type| Mandatory| Description| 7002| -------------- | ------- | -- | --------------------------------------------------- | 7003| 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.| 7004 7005**Return value** 7006 7007| Type| Description| 7008| ------------------- | ------------------------ | 7009| Promise<void> | Promise that returns no value.| 7010 7011**Error codes** 7012 7013For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7014 7015| ID| Error Message| 7016| ------- | -------------------------------------------- | 7017| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7018| 1300002 | This window state is abnormal. | 7019| 1300003 | This window manager service works abnormally. | 7020 7021**Example** 7022 7023```ts 7024import { BusinessError } from '@kit.BasicServicesKit'; 7025 7026let isKeepScreenOn: boolean = true; 7027try { 7028 let promise = windowClass.setWindowKeepScreenOn(isKeepScreenOn); 7029 promise.then(() => { 7030 console.info('Succeeded in setting the screen to be always on.'); 7031 }).catch((err: BusinessError) => { 7032 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 7033 }); 7034} catch (exception) { 7035 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 7036} 7037``` 7038 7039### setWindowPrivacyMode<sup>9+</sup> 7040 7041setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 7042 7043Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 7044 7045A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 7046 7047**System capability**: SystemCapability.WindowManager.WindowManager.Core 7048 7049**Atomic service API**: This API can be used in atomic services since API version 12. 7050 7051**Required permissions**: ohos.permission.PRIVACY_WINDOW 7052 7053**Parameters** 7054 7055| Name| Type| Mandatory| Description| 7056| ------------- | ------------------------- | -- | ------------------------------------------------------ | 7057| 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. | 7058| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 7059 7060**Error codes** 7061 7062For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7063 7064| ID| Error Message| 7065| ------- | ------------------------------ | 7066| 201 | Permission verification failed. The application does not have the permission required to call the API. | 7067| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7068| 1300002 | This window state is abnormal. | 7069 7070**Example** 7071 7072```ts 7073import { BusinessError } from '@kit.BasicServicesKit'; 7074 7075let isPrivacyMode: boolean = true; 7076try { 7077 windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => { 7078 const errCode: number = err.code; 7079 if (errCode) { 7080 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 7081 return; 7082 } 7083 console.info('Succeeded in setting the window to privacy mode.'); 7084 }); 7085} catch (exception) { 7086 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 7087} 7088``` 7089 7090### setWindowPrivacyMode<sup>9+</sup> 7091 7092setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 7093 7094Sets whether this window is in privacy mode. This API uses a promise to return the result. 7095 7096A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 7097 7098**System capability**: SystemCapability.WindowManager.WindowManager.Core 7099 7100**Atomic service API**: This API can be used in atomic services since API version 12. 7101 7102**Required permissions**: ohos.permission.PRIVACY_WINDOW 7103 7104**Parameters** 7105 7106| Name| Type| Mandatory| Description| 7107| ------------- | ------- | -- | ----------------------------------------------------- | 7108| 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.| 7109 7110**Return value** 7111 7112| Type| Description| 7113| ------------------- | ------------------------ | 7114| Promise<void> | Promise that returns no value.| 7115 7116**Error codes** 7117 7118For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7119 7120| ID| Error Message| 7121| ------- | ------------------------------ | 7122| 201 | Permission verification failed. The application does not have the permission required to call the API. | 7123| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7124| 1300002 | This window state is abnormal. | 7125 7126**Example** 7127 7128```ts 7129import { BusinessError } from '@kit.BasicServicesKit'; 7130 7131let isPrivacyMode: boolean = true; 7132try { 7133 let promise = windowClass.setWindowPrivacyMode(isPrivacyMode); 7134 promise.then(() => { 7135 console.info('Succeeded in setting the window to privacy mode.'); 7136 }).catch((err: BusinessError) => { 7137 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 7138 }); 7139} catch (exception) { 7140 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 7141} 7142``` 7143 7144### setWindowTouchable<sup>9+</sup> 7145 7146setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 7147 7148Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 7149 7150**Atomic service API**: This API can be used in atomic services since API version 12. 7151 7152**System capability**: SystemCapability.WindowManager.WindowManager.Core 7153 7154**Parameters** 7155 7156| Name| Type| Mandatory| Description| 7157| ----------- | ------------------------- | -- | ----------------------------------------------- | 7158| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 7159| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 7160 7161**Error codes** 7162 7163For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7164 7165| ID| Error Message| 7166| ------- | -------------------------------------------- | 7167| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7168| 1300002 | This window state is abnormal. | 7169| 1300003 | This window manager service works abnormally. | 7170 7171**Example** 7172 7173```ts 7174import { BusinessError } from '@kit.BasicServicesKit'; 7175 7176let isTouchable = true; 7177try { 7178 windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => { 7179 const errCode: number = err.code; 7180 if (errCode) { 7181 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 7182 return; 7183 } 7184 console.info('Succeeded in setting the window to be touchable.'); 7185 }); 7186} catch (exception) { 7187 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 7188} 7189``` 7190 7191### setWindowTouchable<sup>9+</sup> 7192 7193setWindowTouchable(isTouchable: boolean): Promise<void> 7194 7195Sets whether this window is touchable. This API uses a promise to return the result. 7196 7197**Atomic service API**: This API can be used in atomic services since API version 12. 7198 7199**System capability**: SystemCapability.WindowManager.WindowManager.Core 7200 7201**Parameters** 7202 7203| Name| Type| Mandatory| Description| 7204| ----------- | ------- | -- | ----------------------------------------------- | 7205| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 7206 7207**Return value** 7208 7209| Type| Description| 7210| ------------------- | ------------------------- | 7211| Promise<void> | Promise that returns no value.| 7212 7213**Error codes** 7214 7215For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7216 7217| ID| Error Message| 7218| ------- | -------------------------------------------- | 7219| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7220| 1300002 | This window state is abnormal. | 7221| 1300003 | This window manager service works abnormally. | 7222 7223**Example** 7224 7225```ts 7226import { BusinessError } from '@kit.BasicServicesKit'; 7227 7228let isTouchable: boolean = true; 7229try { 7230 let promise = windowClass.setWindowTouchable(isTouchable); 7231 promise.then(() => { 7232 console.info('Succeeded in setting the window to be touchable.'); 7233 }).catch((err: BusinessError) => { 7234 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 7235 }); 7236} catch (exception) { 7237 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 7238} 7239``` 7240 7241### snapshot<sup>9+</sup> 7242 7243snapshot(callback: AsyncCallback<image.PixelMap>): void 7244 7245Captures this window. This API uses an asynchronous callback to return the result. If privacy mode is enabled for the current window (using [setWindowPrivacyMode](#setwindowprivacymode9)), taking a screenshot will result in a blank screen. 7246 7247**Atomic service API**: This API can be used in atomic services since API version 12. 7248 7249**System capability**: SystemCapability.WindowManager.WindowManager.Core 7250 7251**Parameters** 7252 7253| Name | Type | Mandatory | Description | 7254| -------- | ------------------------------------------------------------ | --------- | ----------------------------------- | 7255| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. | 7256 7257**Error codes** 7258 7259For details about the error codes, see [Window Error Codes](errorcode-window.md). 7260 7261| ID | Error Message | 7262| ------- | ------------------------------ | 7263| 1300002 | This window state is abnormal. | 7264 7265**Example** 7266 7267```ts 7268import { BusinessError } from '@kit.BasicServicesKit'; 7269import { image } from '@kit.ImageKit'; 7270 7271windowClass.snapshot((err: BusinessError, pixelMap: image.PixelMap) => { 7272 const errCode: number = err.code; 7273 if (errCode) { 7274 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 7275 return; 7276 } 7277 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 7278 pixelMap.release(); // Release the memory in time after the PixelMap is used. 7279}); 7280``` 7281 7282### snapshot<sup>9+</sup> 7283 7284snapshot(): Promise<image.PixelMap> 7285 7286Captures this window. If privacy mode is enabled for the current window (using [setWindowPrivacyMode](#setwindowprivacymode9)), taking a screenshot will result in a blank screen. 7287 7288**Atomic service API**: This API can be used in atomic services since API version 12. 7289 7290**System capability**: SystemCapability.WindowManager.WindowManager.Core 7291 7292**Return value** 7293 7294| Type | Description | 7295| ------------------------------------------------------------ | --------------------------------------------- | 7296| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot. | 7297 7298**Error codes** 7299 7300For details about the error codes, see [Window Error Codes](errorcode-window.md). 7301 7302| ID | Error Message | 7303| ------- | ------------------------------ | 7304| 1300002 | This window state is abnormal. | 7305 7306**Example** 7307 7308```ts 7309import { BusinessError } from '@kit.BasicServicesKit'; 7310import { image } from '@kit.ImageKit'; 7311 7312let promise = windowClass.snapshot(); 7313promise.then((pixelMap: image.PixelMap) => { 7314 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 7315 pixelMap.release(); // Release the memory in time after the PixelMap is used. 7316}).catch((err: BusinessError) => { 7317 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 7318}); 7319``` 7320 7321### snapshotIgnorePrivacy<sup>18+</sup> 7322 7323snapshotIgnorePrivacy(): Promise<image.PixelMap> 7324 7325Captures this window. This API can be called to obtain the screenshot of the current window even if privacy mode is enabled for the current window (using [setWindowPrivacyMode](#setwindowprivacymode9)). 7326 7327**Atomic service API**: This API can be used in atomic services since API version 18. 7328 7329**System capability**: SystemCapability.Window.SessionManager 7330 7331**Return value** 7332 7333| Type | Description | 7334| ------------------------------------------------------------ | --------------------------------------------- | 7335| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot. | 7336 7337**Error codes** 7338 7339For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7340 7341| ID | Error Message | 7342| ------- | ------------------------------------------------------------ | 7343| 801 | Capability not supported. Function snapshotIgnorePrivacy can not work correctly due to limited device capabilities. | 7344| 1300002 | This window state is abnormal. | 7345 7346**Example** 7347 7348```ts 7349import { BusinessError } from '@kit.BasicServicesKit'; 7350import { image } from '@kit.ImageKit'; 7351 7352let promise = windowClass.snapshotIgnorePrivacy(); 7353promise.then((pixelMap: image.PixelMap) => { 7354 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 7355 pixelMap.release(); // Release the memory in time after the PixelMap is used. 7356}).catch((err: BusinessError) => { 7357 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 7358}); 7359``` 7360 7361### setAspectRatio<sup>10+</sup> 7362 7363setAspectRatio(ratio: number): Promise<void> 7364 7365Sets the aspect ratio of the window content layout. This API uses a promise to return the result. 7366 7367When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**. 7368 7369This 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. 7370 7371**Atomic service API**: This API can be used in atomic services since API version 12. 7372 7373**System capability**: SystemCapability.WindowManager.WindowManager.Core 7374 7375**Parameters** 7376 7377| Name | Type | Mandatory | Description | 7378| ----- | ------ | --------- | ------------------------------------------------------------ | 7379| 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**. | 7380 7381**Return value** 7382 7383| Type | Description | 7384| ------------------- | ------------------------------ | 7385| Promise<void> | Promise that returns no value. | 7386 7387**Error codes** 7388 7389For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7390 7391| ID | Error Message | 7392| ------- | ------------------------------------------------------------ | 7393| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 7394| 1300002 | This window state is abnormal. | 7395| 1300004 | Unauthorized operation. | 7396 7397**Example** 7398<!--code_no_check--> 7399```ts 7400// EntryAbility.ets 7401import { UIAbility } from '@kit.AbilityKit'; 7402import { BusinessError } from '@kit.BasicServicesKit'; 7403 7404export default class EntryAbility extends UIAbility { 7405 7406 // ... 7407 onWindowStageCreate(windowStage: window.WindowStage) { 7408 console.info('onWindowStageCreate'); 7409 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 7410 if (!windowClass) { 7411 console.info('windowClass is null'); 7412 } 7413 try { 7414 let ratio = 1.0; 7415 let promise = windowClass.setAspectRatio(ratio); 7416 promise.then(() => { 7417 console.info('Succeeded in setting aspect ratio of window.'); 7418 }).catch((err: BusinessError) => { 7419 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 7420 }); 7421 } catch (exception) { 7422 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 7423 } 7424 } 7425} 7426``` 7427 7428### setAspectRatio<sup>10+</sup> 7429 7430setAspectRatio(ratio: number, callback: AsyncCallback<void>): void 7431 7432Sets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 7433 7434When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**. 7435 7436This 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. 7437 7438**Atomic service API**: This API can be used in atomic services since API version 12. 7439 7440**System capability**: SystemCapability.WindowManager.WindowManager.Core 7441 7442**Parameters** 7443 7444| Name | Type | Mandatory | Description | 7445| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 7446| 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**. | 7447| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7448 7449**Error codes** 7450 7451For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7452 7453| ID | Error Message | 7454| ------- | ------------------------------------------------------------ | 7455| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 7456| 1300002 | This window state is abnormal. | 7457| 1300004 | Unauthorized operation. | 7458 7459**Example** 7460<!--code_no_check--> 7461```ts 7462// EntryAbility.ets 7463import { UIAbility } from '@kit.AbilityKit'; 7464import { BusinessError } from '@kit.BasicServicesKit'; 7465 7466export default class EntryAbility extends UIAbility { 7467 7468 // ... 7469 onWindowStageCreate(windowStage: window.WindowStage) { 7470 console.info('onWindowStageCreate'); 7471 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 7472 if (!windowClass) { 7473 console.info('Failed to load the content. Cause: windowClass is null'); 7474 } 7475 try { 7476 let ratio = 1.0; 7477 windowClass.setAspectRatio(ratio, (err: BusinessError) => { 7478 const errCode: number = err.code; 7479 if (errCode) { 7480 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 7481 return; 7482 } 7483 console.info('Succeeded in setting the aspect ratio of window.'); 7484 }); 7485 } catch (exception) { 7486 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 7487 } 7488 } 7489} 7490 7491``` 7492 7493### resetAspectRatio<sup>10+</sup> 7494 7495resetAspectRatio(): Promise<void> 7496 7497Resets the aspect ratio of the window content layout. This API uses a promise to return the result. 7498 7499This 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. 7500 7501**Atomic service API**: This API can be used in atomic services since API version 12. 7502 7503**System capability**: SystemCapability.WindowManager.WindowManager.Core 7504 7505**Return value** 7506 7507| Type | Description | 7508| ------------------- | ------------------------------ | 7509| Promise<void> | Promise that returns no value. | 7510 7511**Error codes** 7512 7513For details about the error codes, see [Window Error Codes](errorcode-window.md). 7514 7515| ID | Error Message | 7516| ------- | ------------------------------ | 7517| 1300002 | This window state is abnormal. | 7518| 1300004 | Unauthorized operation. | 7519 7520**Example** 7521<!--code_no_check--> 7522```ts 7523// EntryAbility.ets 7524import { UIAbility } from '@kit.AbilityKit'; 7525import { BusinessError } from '@kit.BasicServicesKit'; 7526 7527export default class EntryAbility extends UIAbility { 7528 7529 // ... 7530 onWindowStageCreate(windowStage: window.WindowStage) { 7531 console.info('onWindowStageCreate'); 7532 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 7533 if (!windowClass) { 7534 console.info('Failed to load the content. Cause: windowClass is null'); 7535 } 7536 try { 7537 let promise = windowClass.resetAspectRatio(); 7538 promise.then(() => { 7539 console.info('Succeeded in resetting aspect ratio of window.'); 7540 }).catch((err: BusinessError) => { 7541 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 7542 }); 7543 } catch (exception) { 7544 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 7545 } 7546 } 7547} 7548``` 7549 7550### resetAspectRatio<sup>10+</sup> 7551 7552resetAspectRatio(callback: AsyncCallback<void>): void 7553 7554Resets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 7555 7556This 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. 7557 7558**Atomic service API**: This API can be used in atomic services since API version 12. 7559 7560**System capability**: SystemCapability.WindowManager.WindowManager.Core 7561 7562**Parameters** 7563 7564| Name | Type | Mandatory | Description | 7565| -------- | ------------------------- | --------- | ----------------------------------- | 7566| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7567 7568**Error codes** 7569 7570For details about the error codes, see [Window Error Codes](errorcode-window.md). 7571 7572| ID | Error Message | 7573| ------- | ------------------------------ | 7574| 1300002 | This window state is abnormal. | 7575| 1300004 | Unauthorized operation. | 7576 7577**Example** 7578<!--code_no_check--> 7579```ts 7580// EntryAbility.ets 7581import { UIAbility } from '@kit.AbilityKit'; 7582import { BusinessError } from '@kit.BasicServicesKit'; 7583 7584export default class EntryAbility extends UIAbility { 7585 7586 // ... 7587 onWindowStageCreate(windowStage: window.WindowStage) { 7588 console.info('onWindowStageCreate'); 7589 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 7590 if (!windowClass) { 7591 console.info('Failed to load the content. Cause: windowClass is null'); 7592 } 7593 try { 7594 windowClass.resetAspectRatio((err: BusinessError) => { 7595 const errCode: number = err.code; 7596 if (errCode) { 7597 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 7598 return; 7599 } 7600 console.info('Succeeded in resetting aspect ratio of window.'); 7601 }); 7602 } catch (exception) { 7603 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 7604 } 7605 } 7606} 7607``` 7608 7609### minimize<sup>11+</sup> 7610 7611minimize(callback: AsyncCallback<void>): void 7612 7613The behavior of this API varies based on the caller: 7614 7615- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. For 2-in-1 devices, it can be restored by calling [restore()](#restore14). 7616 7617- Hides the child window or floating window if the caller is a child window. The child window or floating window cannot be restored in the dock bar. It can be made visible again by calling [showWindow()](#showwindow9). 7618 7619This API uses an asynchronous callback to return the result. 7620 7621**Atomic service API**: This API can be used in atomic services since API version 12. 7622 7623**System capability**: SystemCapability.Window.SessionManager 7624 7625**Parameters** 7626 7627| Name | Type | Mandatory | Description | 7628| -------- | ------------------------- | --------- | ----------------------------------- | 7629| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7630 7631**Error codes** 7632 7633For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7634 7635| ID | Error Message | 7636| ------- | ------------------------------------------------------------ | 7637| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7638| 1300002 | This window state is abnormal. | 7639| 1300003 | This window manager service works abnormally. | 7640 7641**Example** 7642 7643```ts 7644import { BusinessError } from '@kit.BasicServicesKit'; 7645 7646windowClass.minimize((err: BusinessError) => { 7647 const errCode: number = err.code; 7648 if (errCode) { 7649 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 7650 return; 7651 } 7652 console.info('Succeeded in minimizing the window.'); 7653}); 7654``` 7655 7656### minimize<sup>11+</sup> 7657 7658minimize(): Promise<void> 7659 7660The behavior of this API varies based on the caller: 7661 7662- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. For 2-in-1 devices, it can be restored by calling [restore()](#restore14). 7663 7664- Hides the child window or floating window if the caller is a child window. The child window or floating window cannot be restored in the dock bar. It can be made visible again by calling [showWindow()](#showwindow9). 7665 7666This API uses a promise to return the result. 7667 7668**Atomic service API**: This API can be used in atomic services since API version 12. 7669 7670**System capability**: SystemCapability.Window.SessionManager 7671 7672**Return value** 7673 7674| Type | Description | 7675| ------------------- | ------------------------------ | 7676| Promise<void> | Promise that returns no value. | 7677 7678**Error codes** 7679 7680For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7681 7682| ID | Error Message | 7683| ------- | ------------------------------------------------------------ | 7684| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7685| 1300002 | This window state is abnormal. | 7686| 1300003 | This window manager service works abnormally. | 7687 7688**Example** 7689 7690```ts 7691import { BusinessError } from '@kit.BasicServicesKit'; 7692 7693let promise = windowClass.minimize(); 7694promise.then(() => { 7695 console.info('Succeeded in minimizing the window.'); 7696}).catch((err: BusinessError) => { 7697 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 7698}); 7699``` 7700 7701### maximize<sup>12+</sup> 7702maximize(presentation?: MaximizePresentation): Promise<void> 7703 7704Maximizes the window. The main window can use this API to maximize. For child windows, you need to set **maximizeSupported** to **true** when creating the window and then call this API to maximize. This API uses a promise to return the result. 7705 7706<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7707 7708**Atomic service API**: This API can be used in atomic services since API version 12. 7709 7710**System capability**: SystemCapability.Window.SessionManager 7711 7712**Parameters** 7713 7714| Name | Type | Mandatory | Description | 7715| ------------ | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 7716| presentation | [MaximizePresentation](#maximizepresentation12) | No | Layout of the main window or child window when maximized. The default value is **window.MaximizePresentation.ENTER_IMMERSIVE**, indicating that the window enters the immersive layout when maximized. | 7717 7718**Return value** 7719 7720| Type | Description | 7721| ------------------- | ------------------------------ | 7722| Promise<void> | Promise that returns no value. | 7723 7724**Error codes** 7725 7726For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7727 7728| ID | Error Message | 7729| ------- | ------------------------------------------------------------ | 7730| 801 | Capability not supported. Function maximize can not work correctly due to limited device capabilities. | 7731| 1300002 | This window state is abnormal. | 7732| 1300003 | This window manager service works abnormally. | 7733| 1300004 | Unauthorized operation. | 7734 7735**Example** 7736 7737```ts 7738// EntryAbility.ets 7739import { UIAbility } from '@kit.AbilityKit'; 7740import { BusinessError } from '@kit.BasicServicesKit'; 7741export default class EntryAbility extends UIAbility { 7742 // ... 7743 7744 onWindowStageCreate(windowStage: window.WindowStage) { 7745 console.info('onWindowStageCreate'); 7746 let windowClass: window.Window | undefined = undefined; 7747 windowStage.getMainWindow((err: BusinessError, data) => { 7748 const errCode: number = err.code; 7749 if (errCode) { 7750 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7751 return; 7752 } 7753 windowClass = data; 7754 let promise = windowClass.maximize(); 7755 // let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 7756 promise.then(() => { 7757 console.info('Succeeded in maximizing the window.'); 7758 }).catch((err: BusinessError) => { 7759 console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`); 7760 }); 7761 }); 7762 } 7763}; 7764``` 7765 7766### setResizeByDragEnabled<sup>14+</sup> 7767setResizeByDragEnabled(enable: boolean, callback: AsyncCallback<void>): void 7768 7769Sets whether to enable the main window or child window with decorations to resize itself by dragging. This API uses an asynchronous callback to return the result. 7770 7771**Atomic service API**: This API can be used in atomic services since API version 14. 7772 7773**System capability**: SystemCapability.Window.SessionManager 7774 7775**Parameters** 7776 7777| Name | Type | Mandatory | Description | 7778| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 7779| 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. | 7780| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7781 7782**Error codes** 7783 7784For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7785 7786| ID | Error Message | 7787| ------- | ------------------------------------------------------------ | 7788| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7789| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7790| 1300002 | This window state is abnormal. | 7791| 1300003 | This window manager service works abnormally. | 7792 7793**Example** 7794 7795```ts 7796try { 7797 let enabled = false; 7798 windowClass.setResizeByDragEnabled(enabled, (err) => { 7799 if (err.code) { 7800 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 7801 return; 7802 } 7803 console.info(`Succeeded in setting the function of disabling the resize by drag window.`); 7804 }); 7805} catch (exception) { 7806 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${exception.code}, message: ${exception.message}`); 7807} 7808``` 7809 7810### setResizeByDragEnabled<sup>14+</sup> 7811setResizeByDragEnabled(enable: boolean): Promise<void> 7812 7813Sets whether to enable the main window or child window with decorations to resize itself by dragging. This API uses a promise to return the result. 7814 7815**Atomic service API**: This API can be used in atomic services since API version 14. 7816 7817**System capability**: SystemCapability.Window.SessionManager 7818 7819**Parameters** 7820 7821| Name | Type | Mandatory | Description | 7822| ------ | ------- | --------- | ------------------------------------------------------------ | 7823| 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. | 7824 7825**Return value** 7826 7827| Type | Description | 7828| ------------------- | ------------------------------ | 7829| Promise<void> | Promise that returns no value. | 7830 7831**Error codes** 7832 7833For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7834 7835| ID | Error Message | 7836| ------- | ------------------------------------------------------------ | 7837| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7838| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7839| 1300002 | This window state is abnormal. | 7840| 1300003 | This window manager service works abnormally. | 7841 7842**Example** 7843 7844```ts 7845import { BusinessError } from '@kit.BasicServicesKit'; 7846 7847try { 7848 let enabled = false; 7849 let promise = windowClass.setResizeByDragEnabled(enabled); 7850 promise.then(() => { 7851 console.info(`Succeeded in setting the function of disabling the resize by drag window.`); 7852 }).catch((err: BusinessError) => { 7853 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 7854 }); 7855} catch (exception) { 7856 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${exception.code}, message: ${exception.message}`); 7857} 7858``` 7859 7860### recover<sup>11+</sup> 7861 7862recover(): Promise<void> 7863 7864Restores 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. 7865 7866<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7867 7868**Atomic service API**: This API can be used in atomic services since API version 12. 7869 7870**System capability**: SystemCapability.Window.SessionManager 7871 7872**Return value** 7873 7874| Type | Description | 7875| ------------------- | ------------------------------ | 7876| Promise<void> | Promise that returns no value. | 7877 7878**Error codes** 7879 7880For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7881 7882| ID | Error Message | 7883| ------- | ------------------------------------------------------------ | 7884| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7885| 1300001 | Repeated operation. | 7886| 1300002 | This window state is abnormal. | 7887 7888**Example** 7889 7890```ts 7891// EntryAbility.ets 7892import { UIAbility } from '@kit.AbilityKit'; 7893import { BusinessError } from '@kit.BasicServicesKit'; 7894 7895export default class EntryAbility extends UIAbility { 7896 // ... 7897 onWindowStageCreate(windowStage: window.WindowStage): void { 7898 console.info('onWindowStageCreate'); 7899 let windowClass: window.Window | undefined = undefined; 7900 windowStage.getMainWindow((err: BusinessError, data) => { 7901 const errCode: number = err.code; 7902 if (errCode) { 7903 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7904 return; 7905 } 7906 windowClass = data; 7907 let promise = windowClass.recover(); 7908 promise.then(() => { 7909 console.info('Succeeded in recovering the window.'); 7910 }).catch((err: BusinessError) => { 7911 console.error(`Failed to recover the window. Cause code: ${err.code}, message: ${err.message}`); 7912 }); 7913 }); 7914 } 7915} 7916``` 7917 7918### restore<sup>14+</sup> 7919 7920restore(): Promise<void> 7921 7922Restores 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. 7923 7924This API takes effect only in the multi-window stack layout when the main window is minimized and the UIAbility is in the **onForeground** state. 7925 7926<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7927 7928**Atomic service API**: This API can be used in atomic services since API version 14. 7929 7930**System capability**: SystemCapability.Window.SessionManager 7931 7932**Return value** 7933 7934| Type | Description | 7935| ------------------- | ------------------------------ | 7936| Promise<void> | Promise that returns no value. | 7937 7938**Error codes** 7939 7940For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7941 7942| **ID** | **Error Message** | 7943| ------- | ------------------------------------------------------------ | 7944| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7945| 1300002 | This window state is abnormal. | 7946| 1300003 | This window manager service works abnormally. | 7947| 1300004 | Unauthorized operation. | 7948 7949**Example** 7950 7951```ts 7952// EntryAbility.ets 7953import { UIAbility } from '@kit.AbilityKit'; 7954import { BusinessError } from '@kit.BasicServicesKit'; 7955 7956export default class EntryAbility extends UIAbility { 7957 onWindowStageCreate(windowStage: window.WindowStage): void { 7958 try { 7959 let windowClass = windowStage.getMainWindowSync(); 7960 // Call minimize() to minimize the main window. 7961 windowClass.minimize(); 7962 // Set the delay function to restore the main window after a delay of 5 seconds. 7963 setTimeout(()=>{ 7964 // Call restore() to restore the main window. 7965 let promise = windowClass.restore(); 7966 promise.then(() => { 7967 console.info('Succeeded in restoring the window.'); 7968 }).catch((err: BusinessError) => { 7969 console.error(`Failed to restore the window. Cause code: ${err.code}, message: ${err.message}`); 7970 }); 7971 }, 5000); 7972 } catch (exception) { 7973 console.error(`Failed to restore the window. Cause code: ${exception.code}, message: ${exception.message}`); 7974 } 7975 } 7976} 7977``` 7978 7979### getWindowLimits<sup>11+</sup> 7980 7981getWindowLimits(): WindowLimits 7982 7983Obtains the size limits of this application window. 7984 7985**Atomic service API**: This API can be used in atomic services since API version 12. 7986 7987**System capability**: SystemCapability.Window.SessionManager 7988 7989**Return value** 7990 7991| Type | Description | 7992| ------------------------------- | ------------------- | 7993| [WindowLimits](#windowlimits11) | Window size limits. | 7994 7995**Error codes** 7996 7997For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7998 7999| ID | Error Message | 8000| :------ | :----------------------------------------------------------- | 8001| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8002| 1300002 | This window state is abnormal. | 8003 8004**Example** 8005 8006```ts 8007try { 8008 let windowLimits = windowClass.getWindowLimits(); 8009} catch (exception) { 8010 console.error(`Failed to obtain the window limits of window. Cause code: ${exception.code}, message: ${exception.message}`); 8011} 8012``` 8013 8014### setWindowLimits<sup>11+</sup> 8015 8016setWindowLimits(windowLimits: WindowLimits): Promise<WindowLimits> 8017 8018Sets the size limits for this application window. This API uses a promise to return the result. 8019By 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. 8020 8021**Atomic service API**: This API can be used in atomic services since API version 12. 8022 8023**System capability**: SystemCapability.Window.SessionManager 8024 8025**Parameters** 8026 8027| Name | Type | Mandatory | Description | 8028| :----------- | :------------------------------ | :-------- | :------------------------- | 8029| windowLimits | [WindowLimits](#windowlimits11) | Yes | Target size limits, in px. | 8030 8031**Return value** 8032 8033| Type | Description | 8034| :--------------------------------------------- | :----------------------------------------------------------- | 8035| 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. | 8036 8037**Error codes** 8038 8039For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8040 8041| ID | Error Message | 8042| :------ | :----------------------------------------------------------- | 8043| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 8044| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8045| 1300002 | This window state is abnormal. | 8046| 1300003 | This window manager service works abnormally. | 8047| 1300004 | Unauthorized operation. | 8048 8049**Example** 8050 8051```ts 8052import { BusinessError } from '@kit.BasicServicesKit'; 8053try { 8054 let windowLimits: window.WindowLimits = { 8055 maxWidth: 1500, 8056 maxHeight: 1000, 8057 minWidth: 500, 8058 minHeight: 400 8059 }; 8060 let promise = windowClass.setWindowLimits(windowLimits); 8061 promise.then((data) => { 8062 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 8063 }).catch((err: BusinessError) => { 8064 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 8065 }); 8066} catch (exception) { 8067 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 8068} 8069``` 8070 8071### setWindowLimits<sup>15+</sup> 8072 8073setWindowLimits(windowLimits: WindowLimits, isForcible: boolean): Promise<WindowLimits> 8074 8075Sets the size limits for this application window. This API uses a promise to return the result. 8076 8077By 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. 8078 8079This API can be used only on 2-in-1 devices. 8080 8081**Atomic service API**: This API can be used in atomic services since API version 15. 8082 8083**System capability**: SystemCapability.Window.SessionManager 8084 8085**Parameters** 8086 8087| Name | Type | Mandatory | Description | 8088| :----------- | :------------------------------ | :-------- | :----------------------------------------------------------- | 8089| windowLimits | [WindowLimits](#windowlimits11) | Yes | Target size limits, in px. | 8090| isForcible | boolean | Yes | Whether to forcibly set the window size limits.<br>If this parameter is set to **true**, the minimum width and height of the window are determined by the lower value between the system size limits and 40 vp, and the maximum width and height depend on the system size limits.<br>If this parameter is set to **false**, the minimum and maximum window width and height are restricted by the system size limits. | 8091 8092**Return value** 8093 8094| Type | Description | 8095| :--------------------------------------------- | :----------------------------------------------------------- | 8096| Promise<[WindowLimits](#windowlimits11)> | Promise used to return the new window size limits. Depending on the value of **isForcible**, the return value represents the intersection between the value passed and the system size limits. | 8097 8098**Error codes** 8099 8100For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8101 8102| ID | Error Message | 8103| :------ | :----------------------------------------------------------- | 8104| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 8105| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8106| 1300002 | This window state is abnormal. | 8107| 1300003 | This window manager service works abnormally. | 8108| 1300004 | Unauthorized operation. | 8109 8110**Example** 8111 8112```ts 8113import { BusinessError } from '@kit.BasicServicesKit'; 8114try { 8115 let windowLimits: window.WindowLimits = { 8116 maxWidth: 1500, 8117 maxHeight: 1000, 8118 minWidth: 100, 8119 minHeight: 100 8120 }; 8121 let promise = windowClass.setWindowLimits(windowLimits, true); 8122 promise.then((data) => { 8123 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 8124 }).catch((err: BusinessError) => { 8125 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 8126 }); 8127} catch (exception) { 8128 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 8129} 8130``` 8131 8132### setWindowMask<sup>12+</sup> 8133 8134setWindowMask(windowMask: Array<Array<number>>): Promise<void>; 8135 8136Sets a mask for this window to get an irregularly shaped window. This API uses a promise to return the result. 8137 8138The mask is used to describe the shape of the irregularly shaped window. 8139 8140This API is available only for child windows and global floating windows. 8141 8142When the size of an irregularly shaped window changes, the actual display content is the intersection of the mask size and the window size. 8143 8144Error code 1300002 may be returned only when multiple threads operate the same window. Error code 401 is returned when the window is destroyed. 8145 8146<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 8147 8148**Atomic service API**: This API can be used in atomic services since API version 12. 8149 8150**System capability**: SystemCapability.Window.SessionManager 8151 8152**Parameters** 8153 8154| Name | Type | Mandatory | Description | 8155| :--------- | :------------------------------- | :-------- | :----------------------------------------------------------- | 8156| 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. | 8157 8158**Return value** 8159 8160| Type | Description | 8161| :------------------ | :----------------------------- | 8162| Promise<void> | Promise that returns no value. | 8163 8164**Error codes** 8165 8166For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8167 8168| ID | Error Message | 8169| :------ | :----------------------------------------------------------- | 8170| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8171| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8172| 1300002 | This window state is abnormal. | 8173| 1300003 | This window manager service works abnormally. | 8174| 1300004 | Unauthorized operation. | 8175 8176**Example** 8177 8178```ts 8179import { BusinessError } from '@kit.BasicServicesKit'; 8180try { 8181 let windowMask: Array<Array<number>> = [ 8182 [0, 0, 0, 1, 0, 0, 0], 8183 [0, 0, 1, 1, 1, 0, 0], 8184 [0, 1, 1, 0, 1, 1, 0], 8185 [1, 1, 0, 0, 0, 1, 1] 8186 ]; 8187 let promise = windowClass.setWindowMask(windowMask); 8188 promise.then(() => { 8189 console.info('Succeeded in setting the window mask.'); 8190 }).catch((err: BusinessError) => { 8191 console.error(`Failed to set the window mask. Cause code: ${err.code}, message: ${err.message}`); 8192 }); 8193} catch (exception) { 8194 console.error(`Failed to set the window mask. Cause code: ${exception.code}, message: ${exception.message}`); 8195} 8196``` 8197 8198### keepKeyboardOnFocus<sup>11+</sup> 8199 8200keepKeyboardOnFocus(keepKeyboardFlag: boolean): void 8201 8202Sets 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 child window. 8203 8204**Atomic service API**: This API can be used in atomic services since API version 12. 8205 8206**System capability**: SystemCapability.Window.SessionManager 8207 8208**Parameters** 8209 8210| Name | Type | Mandatory | Description | 8211| ---------------- | ------- | --------- | ------------------------------------------------------------ | 8212| 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. | 8213 8214**Error codes** 8215 8216For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8217 8218| ID | Error Message | 8219| ------- | ------------------------------------------------------------ | 8220| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8221| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8222| 1300002 | This window state is abnormal. | 8223| 1300004 | Unauthorized operation. | 8224 8225**Example** 8226 8227```ts 8228try { 8229 windowClass.keepKeyboardOnFocus(true); 8230} catch (exception) { 8231 console.error(`Failed to keep keyboard onFocus. Cause code: ${exception.code}, message: ${exception.message}`); 8232} 8233``` 8234 8235### setWindowDecorVisible<sup>11+</sup> 8236 8237setWindowDecorVisible(isVisible: boolean): void 8238 8239Sets 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. 8240 8241When 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). 8242 8243**Atomic service API**: This API can be used in atomic services since API version 12. 8244 8245**System capability**: SystemCapability.Window.SessionManager 8246 8247**Parameters** 8248 8249| Name | Type | Mandatory | Description | 8250| --------- | ------- | --------- | ------------------------------------------------------------ | 8251| isVisible | boolean | Yes | Whether the title bar is visible. The value **true** means that the title bar is visible and **false** means the opposite. | 8252 8253**Error codes** 8254 8255For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8256 8257| ID | Error Message | 8258| ------- | ------------------------------------------------------------ | 8259| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8260| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8261| 1300002 | This window state is abnormal. | 8262 8263**Example** 8264 8265```ts 8266import { BusinessError } from '@kit.BasicServicesKit'; 8267let storage: LocalStorage = new LocalStorage(); 8268storage.setOrCreate('storageSimpleProp', 121); 8269windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 8270 let errCode: number = err.code; 8271 if (errCode) { 8272 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8273 return; 8274 } 8275 console.info('Succeeded in loading the content.'); 8276 let isVisible = false; 8277 // Call setWindowDecorVisible. 8278 try { 8279 windowClass?.setWindowDecorVisible(isVisible); 8280 } catch (exception) { 8281 console.error(`Failed to set the visibility of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 8282 } 8283}); 8284``` 8285 8286### getWindowDecorVisible<sup>18+</sup> 8287 8288getWindowDecorVisible(): boolean 8289 8290Checks whether the title bar of this window is visible. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 8291 8292<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 8293 8294**Atomic service API**: This API can be used in atomic services since API version 18. 8295 8296**System capability**: SystemCapability.Window.SessionManager 8297 8298**Return value** 8299 8300| Type | Description | 8301| ------- | ------------------------------------------------------------ | 8302| boolean | Check result. The value **true** means that the title bar is visible, and **false** means the opposite. | 8303 8304**Error codes** 8305 8306For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8307 8308| ID | Error Message | 8309| ------- | ------------------------------------------------------------ | 8310| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8311| 1300002 | This window state is abnormal. | 8312 8313**Example** 8314 8315```ts 8316let isVisible: boolean | undefined = undefined; 8317windowClass.setUIContent('pages/WindowPage').then(() => { 8318 try { 8319 isVisible = windowClass?.getWindowDecorVisible(); 8320 } catch (exception) { 8321 console.error(`Failed to get the window decor visibility. Cause code: ${exception.code}, message: ${exception.message}`); 8322 } 8323}) 8324``` 8325 8326### setWindowTitle<sup>15+</sup> 8327 8328setWindowTitle(titleName: string): Promise<void> 8329 8330Sets the window title. This API uses a promise to return the result. The setting takes effect for a window with a title bar. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 8331 8332This API can be used only 2-in-1 devices and tablets. 8333 8334**Atomic service API**: This API can be used in atomic services since API version 15. 8335 8336**System capability**: SystemCapability.Window.SessionManager 8337 8338**Parameters** 8339 8340| Name | Type | Mandatory | Description | 8341| --------- | ------ | --------- | ------------------------------------------------------------ | 8342| titleName | string | Yes | Window title. The title display area should not go past the left side of the three-button area of the system. Any part that goes beyond will show as an ellipsis. | 8343 8344**Return value** 8345 8346| Type | Description | 8347| ------------------- | ------------------------------ | 8348| Promise<void> | Promise that returns no value. | 8349 8350**Error codes** 8351 8352For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8353 8354| ID | Error Message | 8355| ------- | ------------------------------------------------------------ | 8356| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8357| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8358| 1300002 | This window state is abnormal. | 8359 8360**Example** 8361 8362```ts 8363import { window } from '@kit.ArkUI'; 8364import { BusinessError } from '@kit.BasicServicesKit'; 8365 8366let windowClass: window.Window | undefined = undefined; 8367try { 8368 let promise = window.getLastWindow(this.context); 8369 promise.then((data) => { 8370 windowClass = data; 8371 let title = "title"; 8372 windowClass.setWindowTitle(title).then(() => { 8373 console.info('Succeeded in setting the window title.'); 8374 }).catch((err: BusinessError) => { 8375 console.error(`Failed to set the window title. Cause code: ${err.code}, message: ${err.message}`); 8376 }); 8377 }).catch((err: BusinessError) => { 8378 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 8379 }); 8380} catch (exception) { 8381 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 8382} 8383``` 8384 8385### setWindowTitleMoveEnabled<sup>14+</sup> 8386 8387setWindowTitleMoveEnabled(enabled: boolean): void 8388 8389Enables or disables the capability to move the window (either main window or child window) by dragging its title bar and to maximize the window with a double-click. 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. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 8390 8391<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 8392 8393**Atomic service API**: This API can be used in atomic services since API version 14. 8394 8395**System capability**: SystemCapability.Window.SessionManager 8396 8397**Parameters** 8398 8399| Name | Type | Mandatory | Description | 8400| ------- | ------- | --------- | ------------------------------------------------------------ | 8401| 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 the opposite. | 8402 8403**Error codes** 8404 8405For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8406 8407| ID | Error Message | 8408| ------- | ------------------------------------------------------------ | 8409| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8410| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8411| 1300002 | This window state is abnormal. | 8412| 1300004 | Unauthorized operation. | 8413 8414**Example** 8415 8416```ts 8417// EntryAbility.ets 8418import { UIAbility } from '@kit.AbilityKit'; 8419 8420export default class EntryAbility extends UIAbility { 8421 onWindowStageCreate(windowStage: window.WindowStage): void { 8422 try { 8423 windowStage.loadContent("pages/Index").then(() =>{ 8424 let windowClass = windowStage.getMainWindowSync(); 8425 let enabled = false; 8426 windowClass.setWindowTitleMoveEnabled(enabled); 8427 console.info(`Succeeded in setting the the window title move enabled: ${enabled}`); 8428 }); 8429 } catch (exception) { 8430 console.error(`Failed to set the window title move enabled. Cause code: ${exception.code}, message: ${exception.message}`); 8431 } 8432 } 8433} 8434``` 8435 8436### setSubWindowModal<sup>12+</sup> 8437 8438setSubWindowModal(isModal: boolean): Promise<void> 8439 8440Enables the modal property of the child window. This API uses a promise to return the result. 8441 8442This API must be called by a child window and the setting takes effect for the child window. 8443 8444After the modal property is enabled, the parent window does not respond to user interactions until the child window is closed or the child window's modal property is disabled. 8445 8446If this API is called by a main window, an error is reported. 8447 8448**Atomic service API**: This API can be used in atomic services since API version 12. 8449 8450**System capability**: SystemCapability.Window.SessionManager 8451 8452**Parameters** 8453 8454| Name | Type | Mandatory | Description | 8455| ------- | ------- | --------- | ------------------------------------------------------------ | 8456| isModal | boolean | Yes | Whether to enable the modal property of the child window. The value **true** means to enable the modal property, and **false** means the opposite. | 8457 8458 8459**Return value** 8460 8461| Type | Description | 8462| ------------------- | ------------------------------ | 8463| Promise<void> | Promise that returns no value. | 8464 8465**Error codes** 8466 8467For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8468 8469| ID | Error Message | 8470| ------- | ------------------------------------------------------------ | 8471| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8472| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8473| 1300002 | This window state is abnormal. | 8474| 1300003 | This window manager service works abnormally. | 8475| 1300004 | Unauthorized operation. | 8476 8477**Example** 8478 8479```ts 8480// EntryAbility.ets 8481import { UIAbility } from '@kit.AbilityKit'; 8482import { BusinessError } from '@kit.BasicServicesKit'; 8483 8484export default class EntryAbility extends UIAbility { 8485 // ... 8486 onWindowStageCreate(windowStage: window.WindowStage): void { 8487 console.info('onWindowStageCreate'); 8488 let windowClass: window.Window | undefined = undefined; 8489 // Create a child window. 8490 try { 8491 let subWindow = windowStage.createSubWindow("testSubWindow"); 8492 subWindow.then((data) => { 8493 if (data == null) { 8494 console.error("Failed to create the subWindow. Cause: The data is empty"); 8495 return; 8496 } 8497 windowClass = data; 8498 let promise = windowClass.setSubWindowModal(true); 8499 promise.then(() => { 8500 console.info('Succeeded in setting subwindow modal'); 8501 }).catch((err: BusinessError) => { 8502 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 8503 }); 8504 }); 8505 } catch (exception) { 8506 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 8507 } 8508 } 8509} 8510``` 8511 8512### setSubWindowModal<sup>14+</sup> 8513 8514setSubWindowModal(isModal: boolean, modalityType: ModalityType): Promise<void> 8515 8516Sets the modality type of the child window. This API uses a promise to return the result. 8517 8518When the child window is of the window-modal type, its parent window does not respond to user interactions until the child window is closed or the child window's modal property is disabled. 8519 8520When the child window 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 child window is closed or the child window's modal property is disabled. 8521 8522This API is used to set the modality type. To disable the modal property, you are advised to use [setSubWindowModal<sup>12+</sup>](#setsubwindowmodal12). 8523 8524If this API is called by a main window, an error is reported. 8525 8526**Atomic service API**: This API can be used in atomic services since API version 14. 8527 8528**System capability**: SystemCapability.Window.SessionManager 8529 8530**Parameters** 8531 8532| Name | Type | Mandatory | Description | 8533| ------------ | ------------------------------- | --------- | ------------------------------------------------------------ | 8534| isModal | boolean | Yes | Whether to enable the modal property of the child window. The value **true** means to enable the modal property, and **false** means the opposite. Currently, this parameter can only be set to **true**. | 8535| modalityType | [ModalityType](#modalitytype14) | Yes | Modality type of the child window. | 8536 8537**Return value** 8538 8539| Type | Description | 8540| ------------------- | ------------------------------ | 8541| Promise<void> | Promise that returns no value. | 8542 8543**Error codes** 8544 8545For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8546 8547| ID | Error Message | 8548| ------- | ------------------------------------------------------------ | 8549| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8550| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8551| 1300002 | This window state is abnormal. | 8552| 1300003 | This window manager service works abnormally. | 8553| 1300004 | Unauthorized operation. | 8554 8555**Example** 8556 8557```ts 8558// EntryAbility.ets 8559import { UIAbility } from '@kit.AbilityKit'; 8560import { BusinessError } from '@kit.BasicServicesKit'; 8561import { window } from '@kit.ArkUI'; 8562 8563export default class EntryAbility extends UIAbility { 8564 // ... 8565 onWindowStageCreate(windowStage: window.WindowStage): void { 8566 console.info('onWindowStageCreate'); 8567 let windowClass: window.Window | undefined = undefined; 8568 // Create a child window. 8569 try { 8570 let subWindow = windowStage.createSubWindow("testSubWindow"); 8571 subWindow.then((data) => { 8572 if (data == null) { 8573 console.error("Failed to create the subWindow. Cause: The data is empty"); 8574 return; 8575 } 8576 windowClass = data; 8577 let promise = windowClass.setSubWindowModal(true, window.ModalityType.WINDOW_MODALITY); 8578 promise.then(() => { 8579 console.info('Succeeded in setting subwindow modal'); 8580 }).catch((err: BusinessError) => { 8581 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 8582 }); 8583 }); 8584 } catch (exception) { 8585 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 8586 } 8587 } 8588} 8589``` 8590 8591### setWindowDecorHeight<sup>11+</sup> 8592 8593setWindowDecorHeight(height: number): void 8594 8595<!--RP1--> 8596Sets 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. 8597<!--RP1End--> 8598 8599When 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. 8600 8601**Atomic service API**: This API can be used in atomic services since API version 12. 8602 8603**System capability**: SystemCapability.Window.SessionManager 8604 8605**Parameters** 8606 8607| Name | Type | Mandatory | Description | 8608| ------ | ------ | --------- | ------------------------------------------------------------ | 8609| 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. | 8610 8611**Error codes** 8612 8613For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8614 8615| ID | Error Message | 8616| ------- | ------------------------------------------------------------ | 8617| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 8618| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8619| 1300002 | This window state is abnormal. | 8620 8621**Example** 8622 8623```ts 8624windowClass.setUIContent('pages/WindowPage').then(() => { 8625 let height: number = 50; 8626 try { 8627 windowClass?.setWindowDecorHeight(height); 8628 console.info(`Succeeded in setting the height of window decor: ${height}`); 8629 } catch (exception) { 8630 console.error(`Failed to set the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 8631 } 8632}) 8633``` 8634 8635### setDecorButtonStyle<sup>14+</sup> 8636 8637setDecorButtonStyle(dectorStyle: DecorButtonStyle): void 8638 8639Sets the button style of the decoration bar. The setting takes effect only for the main window and child windows. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 8640 8641<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 8642 8643**Atomic service API**: This API can be used in atomic services since API version 14. 8644 8645**System capability**: SystemCapability.Window.SessionManager 8646 8647**Parameters** 8648 8649| Name | Type | Mandatory | Description | 8650| ----------- | --------------------------------------- | --------- | ----------------------------------- | 8651| dectorStyle | [DecorButtonStyle](#decorbuttonstyle14) | Yes | Button style of the decoration bar. | 8652 8653**Error codes** 8654 8655For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8656 8657| ID | Error Message | 8658| ------- | ------------------------------------------------------------ | 8659| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8660| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8661| 1300002 | This window state is abnormal. | 8662| 1300004 | Unauthorized operation. | 8663 8664**Example** 8665 8666```ts 8667// EntryAbility.ets 8668import { UIAbility } from '@kit.AbilityKit'; 8669import { ConfigurationConstant } from '@kit.AbilityKit'; 8670 8671export default class EntryAbility extends UIAbility { 8672 onWindowStageCreate(windowStage: window.WindowStage): void { 8673 try { 8674 windowStage.loadContent("pages/Index").then(() =>{ 8675 let windowClass = windowStage.getMainWindowSync(); 8676 let colorMode : ConfigurationConstant.ColorMode = ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT; 8677 let style: window.DecorButtonStyle = { 8678 colorMode: colorMode, 8679 buttonBackgroundSize: 28, 8680 spacingBetweenButtons: 12, 8681 closeButtonRightMargin: 20, 8682 buttonIconSize: 20, 8683 buttonBackgroundCornerRadius: 4 8684 }; 8685 windowClass.setDecorButtonStyle(style); 8686 console.info('Succeeded in setting the style of button. Data: ' + JSON.stringify(style)); 8687 }); 8688 } catch (exception) { 8689 console.error(`Failed to set the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 8690 } 8691 } 8692} 8693``` 8694 8695### getDecorButtonStyle<sup>14+</sup> 8696 8697getDecorButtonStyle(): DecorButtonStyle 8698 8699Obtains the button style of the decoration bar. The setting takes effect only for the main window and child windows. 8700 8701<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 8702 8703**Atomic service API**: This API can be used in atomic services since API version 14. 8704 8705**System capability**: SystemCapability.Window.SessionManager 8706 8707**Return value** 8708 8709| Type | Description | 8710| --------------------------------------- | ------------------------------------------------------------ | 8711| [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. | 8712 8713**Error codes** 8714 8715For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8716 8717| ID | Error Message | 8718| ------- | ------------------------------------------------------------ | 8719| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8720| 1300002 | This window state is abnormal. | 8721| 1300003 | This window manager service works abnormally. | 8722| 1300004 | Unauthorized operation. | 8723 8724**Example** 8725 8726```ts 8727try { 8728 let decorButtonStyle = windowClass.getDecorButtonStyle(); 8729 console.info('Succeeded in getting the style of button. Data: ' + JSON.stringify(decorButtonStyle)); 8730} catch (exception) { 8731 console.error(`Failed to get the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 8732} 8733``` 8734 8735### getWindowDecorHeight<sup>11+</sup> 8736 8737getWindowDecorHeight(): number 8738 8739<!--RP2--> 8740Obtains 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. 8741<!--RP2End--> 8742 8743**Atomic service API**: This API can be used in atomic services since API version 12. 8744 8745**System capability**: SystemCapability.Window.SessionManager 8746 8747**Return value** 8748 8749| Type | Description | 8750| ------ | ------------------------------------------------------------ | 8751| number | Height of the title bar. The value is an integer in the range [37,112]. The unit is vp. | 8752 8753**Error codes** 8754 8755For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8756 8757| ID | Error Message | 8758| ------- | ------------------------------------------------------------ | 8759| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8760| 1300002 | This window state is abnormal. | 8761 8762**Example** 8763 8764```ts 8765windowClass.setUIContent('pages/WindowPage').then(() => { 8766 try { 8767 let height = windowClass?.getWindowDecorHeight(); 8768 console.info(`Succeeded in getting the height of window decor: ${height}`); 8769 } catch (exception) { 8770 console.error(`Failed to get the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 8771 } 8772}) 8773``` 8774 8775### getTitleButtonRect<sup>11+</sup> 8776 8777getTitleButtonRect(): TitleButtonRect 8778 8779Obtains the rectangle that holds the minimize, maximize, and close buttons on the title bar of the main window or the decorated child window. 8780 8781**Atomic service API**: This API can be used in atomic services since API version 12. 8782 8783**System capability**: SystemCapability.Window.SessionManager 8784 8785**Return value** 8786 8787| Type | Description | 8788| ------------------------------------- | ------------------------------------------------------------ | 8789| [TitleButtonRect](#titlebuttonrect11) | Rectangle obtained, which is located in the upper right corner of the window. | 8790 8791**Error codes** 8792 8793For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8794 8795| ID | Error Message | 8796| ------- | ------------------------------------------------------------ | 8797| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8798| 1300002 | This window state is abnormal. | 8799 8800**Example** 8801 8802```ts 8803// EntryAbility.ets 8804import { UIAbility } from '@kit.AbilityKit'; 8805import { BusinessError } from '@kit.BasicServicesKit'; 8806 8807export default class EntryAbility extends UIAbility { 8808 // ... 8809 onWindowStageCreate(windowStage: window.WindowStage): void { 8810 console.info('onWindowStageCreate'); 8811 let windowClass: window.Window | undefined = undefined; 8812 windowStage.getMainWindow((err: BusinessError, data) => { 8813 const errCode: number = err.code; 8814 if (errCode) { 8815 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8816 return; 8817 } 8818 windowClass = data; 8819 try { 8820 let titleButtonArea = windowClass.getTitleButtonRect(); 8821 console.info('Succeeded in obtaining the area of title buttons. Data: ' + JSON.stringify(titleButtonArea)); 8822 } catch (exception) { 8823 console.error(`Failed to get the area of title buttons. Cause code: ${exception.code}, message: ${exception.message}`); 8824 } 8825 }); 8826 } 8827} 8828``` 8829 8830### getWindowStatus<sup>12+</sup> 8831 8832getWindowStatus(): WindowStatusType 8833 8834Obtains the mode of this window. 8835 8836**Atomic service API**: This API can be used in atomic services since API version 12. 8837 8838**System capability**: SystemCapability.Window.SessionManager 8839 8840**Return value** 8841 8842| Type | Description | 8843| --------------------------------------- | ------------ | 8844| [WindowStatusType](#windowstatustype11) | Window mode. | 8845 8846**Error codes** 8847 8848For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8849 8850| ID | Error Message | 8851| ------- | ------------------------------------------------------------ | 8852| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8853| 1300002 | This window state is abnormal. | 8854 8855**Example** 8856 8857```ts 8858try { 8859 let windowStatusType = windowClass.getWindowStatus(); 8860} catch (exception) { 8861 console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); 8862} 8863``` 8864 8865### isFocused<sup>12+</sup> 8866 8867isFocused(): boolean 8868 8869Checks whether this window is focused. 8870 8871**System capability**: SystemCapability.WindowManager.WindowManager.Core 8872 8873**Atomic service API**: This API can be used in atomic services since API version 12. 8874 8875**Return value** 8876 8877| Type | Description | 8878| ------- | ------------------------------------------------------------ | 8879| boolean | Result indicating whether the window is focused. The value **true** means that the window is focused, and **false** means the opposite. | 8880 8881**Error codes** 8882 8883For details about the error codes, see [Window Error Codes](errorcode-window.md). 8884 8885| ID | Error Message | 8886| ------- | ------------------------------ | 8887| 1300002 | This window state is abnormal. | 8888 8889**Example** 8890 8891```ts 8892try { 8893 let focus = windowClass.isFocused(); 8894 console.info('Succeeded in checking whether the window is focused. Data: ' + JSON.stringify(focus)); 8895} catch (exception) { 8896 console.error(`Failed to check whether the window is focused. Cause code: ${exception.code}, message: ${exception.message}`); 8897} 8898``` 8899 8900### createSubWindowWithOptions<sup>12+</sup> 8901 8902createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 8903 8904Creates a child window under the main window, another child window, or floating window. This API uses a promise to return the result. 8905 8906<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 8907 8908**Model restriction**: This API can be used only in the stage model. 8909 8910**System capability**: SystemCapability.Window.SessionManager 8911 8912**Atomic service API**: This API can be used in atomic services since API version 12. 8913 8914**Parameters** 8915 8916| Name | Type | Mandatory | Description | 8917| ------- | --------------------------------------- | --------- | ---------------------------------------------- | 8918| name | string | Yes | Name of the child window. | 8919| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the child window. | 8920 8921**Return value** 8922 8923| Type | Description | 8924| -------------------------------- | -------------------------------------------------------- | 8925| Promise<[Window](#window)> | Promise used to used to return the child window created. | 8926 8927**Error codes** 8928 8929For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8930 8931| ID | Error Message | 8932| ------- | ------------------------------------------------------------ | 8933| 401 | Parameter error. Possible cause: Incorrect parameter types. | 8934| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8935| 1300002 | This window state is abnormal. | 8936| 1300003 | This window manager service works abnormally. | 8937| 1300004 | Unauthorized operation. | 8938 8939**Example** 8940 8941```ts 8942import { BusinessError } from '@kit.BasicServicesKit'; 8943 8944try { 8945 let options : window.SubWindowOptions = { 8946 title: 'title', 8947 decorEnabled: true, 8948 isModal: true 8949 }; 8950 let promise = windowClass.createSubWindowWithOptions('mySubWindow', options); 8951 promise.then((data) => { 8952 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 8953 }).catch((err: BusinessError) => { 8954 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 8955 }); 8956} catch (exception) { 8957 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 8958} 8959``` 8960 8961### setParentWindow<sup>19+</sup> 8962 8963setParentWindow(windowId: number): Promise<void> 8964 8965Sets a new parent window for this child window. The new parent window can be a main window, another child window, or a floating window. This API uses a promise to return the result. 8966 8967If the child window is focused and the new parent window is in the foreground, the new parent window will be raised. 8968 8969If the child window is focused and the new parent window has a modal child window with a higher level, the focus will be transferred to that modal child window. 8970 8971This API can be used only on 2-in-1 devices. 8972 8973**System capability**: SystemCapability.Window.SessionManager 8974 8975**Atomic service API**: This API can be used in atomic services since API version 19. 8976 8977**Parameters** 8978 8979| Name | Type | Mandatory | Description | 8980| -------- | ------ | --------- | ------------------------------------------------------------ | 8981| windowId | number | Yes | Parent window ID, which must be an integer. You are advised to call [getWindowProperties()](#getwindowproperties9) to obtain the parent window ID. | 8982 8983**Return value** 8984 8985| Type | Description | 8986| ------------------- | ------------------------------ | 8987| Promise<void> | Promise that returns no value. | 8988 8989**Error codes** 8990 8991For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8992 8993| ID | Error Message | 8994| ------- | ------------------------------------------------------------ | 8995| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8996| 1300002 | This window state is abnormal. | 8997| 1300003 | This window manager service works abnormally. | 8998| 1300004 | Unauthorized operation. | 8999| 1300009 | The parent window is invaild. | 9000 9001**Example** 9002 9003```ts 9004import { BusinessError } from '@kit.BasicServicesKit'; 9005 9006try { 9007 let windowClass: window.Window = window.findWindow("subWindow"); 9008 let newParentWindow: window.Window = window.findWindow("newParentWindow"); 9009 let newParentWindowId: number = newParentWindow.getWindowProperties().id; 9010 let promise = windowClass.setParentWindow(newParentWindowId); 9011 promise.then(() => { 9012 console.info('Succeeded in setting the new parent window.'); 9013 }).catch((err: BusinessError) => { 9014 console.error(`Failed to set the new parent window. Cause code: ${err.code}, message: ${err.message}`); 9015 }); 9016} catch (exception) { 9017 console.error(`Failed to set the new parent window. Cause code: ${exception.code}, message: ${exception.message}`); 9018} 9019``` 9020 9021### getParentWindow<sup>19+</sup> 9022 9023getParentWindow(): Window 9024 9025Obtains the parent window of this child window. 9026 9027This API can be used only on 2-in-1 devices. 9028 9029**System capability**: SystemCapability.Window.SessionManager 9030 9031**Atomic service API**: This API can be used in atomic services since API version 19. 9032 9033**Return value** 9034 9035| Type | Description | 9036| ----------------- | -------------- | 9037| [Window](#window) | Parent window. | 9038 9039**Error codes** 9040 9041For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9042 9043| ID | Error Message | 9044| ------- | ------------------------------------------------------------ | 9045| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9046| 1300002 | This window state is abnormal. | 9047| 1300004 | Unauthorized operation. | 9048| 1300009 | The parent window is invaild. | 9049 9050**Example** 9051 9052```ts 9053try { 9054 let windowClass: window.Window = window.findWindow("subWindow"); 9055 let parentWindow: window.Window = windowClass.getParentWindow(); 9056 let properties = parentWindow.getWindowProperties(); 9057 console.info('Succeeded in obtaining parent window properties. Property: ' + JSON.stringify(properties)); 9058} catch (exception) { 9059 console.error(`Failed to get the parent window. Cause code: ${exception.code}, message: ${exception.message}`); 9060} 9061``` 9062 9063### setWindowTitleButtonVisible<sup>14+</sup> 9064 9065setWindowTitleButtonVisible(isMaximizeButtonVisible: boolean, isMinimizeButtonVisible: boolean, isCloseButtonVisible?: boolean): void 9066 9067Shows or hides the maximize, minimize, and close buttons on the title bar of the main window. 9068 9069<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 9070 9071**Atomic service API**: This API can be used in atomic services since API version 14. 9072 9073**System capability**: SystemCapability.Window.SessionManager 9074 9075**Parameters** 9076 9077| Name | Type | Mandatory | Description | 9078| ----------------------- | ------- | --------- | ------------------------------------------------------------ | 9079| isMaximizeButtonVisible | boolean | Yes | Whether to show the maximize button. The value **true** means to show the button, and **false** means the opposite. If the maximize button is hidden, the corresponding restore button is also hidden in the maximize scenario. | 9080| isMinimizeButtonVisible | boolean | Yes | Whether to show the minimize button. The value **true** means to show the button, and **false** means the opposite. | 9081| isCloseButtonVisible | boolean | No | Whether to show the close button. The value **true** means to show the button, and **false** means the opposite. | 9082 9083**Error codes** 9084 9085For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9086 9087| ID | Error Message | 9088| ------- | ------------------------------------------------------------ | 9089| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9090| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9091| 1300002 | This window state is abnormal. | 9092| 1300004 | Unauthorized operation. | 9093 9094**Example** 9095 9096```ts 9097// EntryAbility.ets 9098import { UIAbility } from '@kit.AbilityKit'; 9099import { BusinessError } from '@kit.BasicServicesKit'; 9100import { window } from '@kit.ArkUI'; 9101 9102export default class EntryAbility extends UIAbility { 9103 onWindowStageCreate(windowStage: window.WindowStage): void { 9104 // Load the page corresponding to the main window. 9105 windowStage.loadContent('pages/Index', (err) => { 9106 let mainWindow: window.Window | undefined = undefined; 9107 // Obtain the main window. 9108 windowStage.getMainWindow().then( 9109 data => { 9110 mainWindow = data; 9111 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 9112 // Call setWindowTitleButtonVisible to hide the maximize, minimize, and close buttons on the title bar of the main window. 9113 mainWindow.setWindowTitleButtonVisible(false, false, false); 9114 } 9115 ).catch((err: BusinessError) => { 9116 if(err.code){ 9117 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9118 } 9119 }); 9120 }); 9121 } 9122} 9123``` 9124 9125### setWindowTopmost<sup>14+</sup> 9126 9127setWindowTopmost(isWindowTopmost: boolean): Promise<void> 9128 9129Places the main window above all the other windows of the application. This API uses a promise to return the result. 9130 9131Applications use custom shortcut keys to pin or unpin the main window. 9132 9133<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 9134 9135**Atomic service API**: This API can be used in atomic services since API version 14. 9136 9137**System capability**: SystemCapability.Window.SessionManager 9138 9139**Required permissions**: ohos.permission.WINDOW_TOPMOST 9140 9141**Parameters** 9142 9143| Name | Type | Mandatory | Description | 9144| --------------- | ------- | --------- | ------------------------------------------------------------ | 9145| 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. | 9146 9147 9148**Error codes** 9149 9150For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9151 9152| ID | Error Message | 9153| ------- | ------------------------------------------------------------ | 9154| 201 | Permission verification failed. The application does not have the permission required to call the API. | 9155| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9156| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9157| 1300002 | This window state is abnormal. | 9158| 1300004 | Unauthorized operation. | 9159 9160**Example** 9161 9162```ts 9163// ets/pages/Index.ets 9164import { window } from '@kit.ArkUI'; 9165import { common } from '@kit.AbilityKit'; 9166import { BusinessError } from '@kit.BasicServicesKit'; 9167 9168let windowClass: window.Window | undefined; 9169let keyUpEventAry: string[] = []; 9170 9171@Entry 9172@Component 9173struct Index { 9174 private context = (this.getUIContext()?.getHostContext() as common.UIAbilityContext); 9175 9176 build() { 9177 RelativeContainer() { 9178 Button("Pin") 9179 .onClick(() => { 9180 try { 9181 let promiseCtx = window.getLastWindow(this.context); 9182 promiseCtx.then((data) => { 9183 windowClass = data; 9184 // The value true means to pin the window on top, and false means to unpin the window. 9185 let isWindowTopmost: boolean = true; 9186 let promiseTopmost = windowClass.setWindowTopmost(isWindowTopmost); 9187 promiseTopmost.then(() => { 9188 console.info('Succeeded in setting the main window to be topmost.'); 9189 }).catch((err: BusinessError) => { 9190 console.error(`Failed to set the main window to be topmost. Cause code: ${err.code}, message: ${err.message}`); 9191 }); 9192 }) 9193 } catch (exception) { 9194 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`) 9195 } 9196 }) 9197 } 9198 .height('100%') 9199 .width('100%') 9200 .onKeyEvent((event) => { 9201 if(event) { 9202 if(event.type === KeyType.Down) { 9203 keyUpEventAry = []; 9204 } 9205 if(event.type === KeyType.Up) { 9206 keyUpEventAry.push(event.keyText); 9207 // Press Ctrl+T to pin or unpin the main window. 9208 if(windowClass && keyUpEventAry.includes('KEYCODE_CTRL_LEFT') && keyUpEventAry.includes('KEYCODE_T')) { 9209 let isWindowTopmost: boolean = false; 9210 windowClass.setWindowTopmost(isWindowTopmost); 9211 } 9212 } 9213 } 9214 }) 9215 } 9216} 9217``` 9218 9219### raiseToAppTop<sup>14+</sup> 9220 9221raiseToAppTop(): Promise<void> 9222 9223Brings a child window to the top. This action is limited to child windows of the same type under the same parent window within the current application. For child windows with a custom zLevel property, it only applies to child windows with the same zLevel value under the same parent window within the current application. This API uses a promise to return the result. 9224 9225Before calling this API, ensure that the child window has been created and [showWindow()](#showwindow9) has been successfully executed. 9226 9227**System capability**: SystemCapability.WindowManager.WindowManager.Core 9228 9229**Return value** 9230 9231| Type | Description | 9232| ------------------- | ------------------------------ | 9233| Promise<void> | Promise that returns no value. | 9234 9235**Error codes** 9236 9237For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9238 9239| ID | Error Message | 9240| ------- | --------------------------------------------- | 9241| 1300002 | This window state is abnormal. | 9242| 1300003 | This window manager service works abnormally. | 9243| 1300004 | Unauthorized operation. | 9244| 1300009 | The parent window is invalid. | 9245 9246**Example** 9247 9248```ts 9249// EntryAbility.ets 9250import { window } from '@kit.ArkUI'; 9251import { UIAbility } from '@kit.AbilityKit'; 9252import { BusinessError } from '@kit.BasicServicesKit'; 9253 9254export default class EntryAbility extends UIAbility { 9255 // ... 9256 onWindowStageCreate(windowStage: window.WindowStage): void { 9257 console.info('onWindowStageCreate'); 9258 // Create a child window. 9259 windowStage.createSubWindow('testSubWindow').then((subWindow) => { 9260 if (subWindow == null) { 9261 console.error('Failed to create the subWindow. Cause: The data is empty'); 9262 return; 9263 } 9264 subWindow.showWindow().then(() => { 9265 subWindow.raiseToAppTop().then(() => { 9266 console.info('Succeeded in raising window to app top'); 9267 }).catch((err: BusinessError)=>{ 9268 console.error(`Failed to raise window to app top. Cause code: ${err.code}, message: ${err.message}`); 9269 }); 9270 }); 9271 }); 9272 } 9273} 9274``` 9275 9276### setRaiseByClickEnabled<sup>14+</sup> 9277 9278setRaiseByClickEnabled(enable: boolean): Promise<void> 9279 9280Sets whether to enable a child window to raise itself by click. This API uses a promise to return the result. 9281 9282Generally, when a child window is clicked, it is brought to the forefront among sibling child windows of the same type that share the same parent window within the application. If the **enable** parameter is set to **false**, when the child window is clicked, it still stays in its existing position. 9283 9284Before calling this API, ensure that the child window has been created and [showWindow()](#showwindow9) has been successfully executed. 9285 9286**System capability**: SystemCapability.Window.SessionManager 9287 9288**Parameters** 9289 9290| Name | Type | Mandatory | Description | 9291| ------ | ------- | --------- | ------------------------------------------------------------ | 9292| enable | boolean | Yes | Whether a child window can be raised by clicking. The value **true** means that the child window can be raised by clicking, and **false** means the opposite. | 9293 9294**Return value** 9295 9296| Type | Description | 9297| ------------------- | ------------------------------ | 9298| Promise<void> | Promise that returns no value. | 9299 9300**Error codes** 9301 9302For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9303 9304| ID | Error Message | 9305| ------- | ------------------------------------------------------------ | 9306| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9307| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9308| 1300002 | This window state is abnormal. | 9309| 1300003 | This window manager service works abnormally. | 9310| 1300004 | Unauthorized operation. | 9311| 1300009 | The parent window is invalid. | 9312 9313**Example** 9314 9315```ts 9316// EntryAbility.ets 9317import { window } from '@kit.ArkUI'; 9318import { UIAbility } from '@kit.AbilityKit'; 9319import { BusinessError } from '@kit.BasicServicesKit'; 9320 9321export default class EntryAbility extends UIAbility { 9322 // ... 9323 onWindowStageCreate(windowStage: window.WindowStage): void { 9324 console.info('onWindowStageCreate'); 9325 // Create a child window. 9326 windowStage.createSubWindow("testSubWindow").then((subWindow) => { 9327 if (subWindow == null) { 9328 console.error('Failed to create the subWindow. Cause: The data is empty'); 9329 return; 9330 } 9331 subWindow.showWindow().then(() => { 9332 try { 9333 let enabled = false; 9334 subWindow.setRaiseByClickEnabled(enabled).then(() => { 9335 console.info('Succeeded in disabling the raise-by-click function.'); 9336 }).catch((err: BusinessError) => { 9337 console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`); 9338 }); 9339 } catch (err) { 9340 console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`); 9341 } 9342 }); 9343 }); 9344 } 9345} 9346``` 9347 9348### enableLandscapeMultiWindow<sup>12+</sup> 9349 9350enableLandscapeMultiWindow(): Promise<void> 9351 9352Enables 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. 9353 9354This 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. 9355 9356**Atomic service API**: This API can be used in atomic services since API version 12. 9357 9358**System capability**: SystemCapability.Window.SessionManager 9359 9360**Return value** 9361 9362| Type | Description | 9363| ------------------- | ------------------------------ | 9364| Promise<void> | Promise that returns no value. | 9365 9366**Error codes** 9367 9368For details about the error codes, see [Window Error Codes](errorcode-window.md). 9369 9370| ID | Error Message | 9371| ------- | --------------------------------------------- | 9372| 1300002 | This window state is abnormal. | 9373| 1300003 | This window manager service works abnormally. | 9374 9375**Example** 9376 9377```ts 9378// EntryAbility.ets 9379import { UIAbility } from '@kit.AbilityKit'; 9380import { BusinessError } from '@kit.BasicServicesKit'; 9381import { window } from '@kit.ArkUI'; 9382 9383export default class EntryAbility extends UIAbility { 9384 // ... 9385 onWindowStageCreate(windowStage: window.WindowStage): void { 9386 console.info('onWindowStageCreate'); 9387 let windowClass: window.Window | undefined = undefined; 9388 windowStage.getMainWindow((err: BusinessError, data) => { 9389 const errCode: number = err.code; 9390 if (errCode) { 9391 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9392 return; 9393 } 9394 windowClass = data; 9395 let promise = windowClass.enableLandscapeMultiWindow(); 9396 promise.then(() => { 9397 console.info('Succeeded in making multi-window become landscape.'); 9398 }).catch((err: BusinessError) => { 9399 console.error(`Failed to make multi-window become landscape. Cause code: ${err.code}, message: ${err.message}`); 9400 }); 9401 }); 9402 } 9403} 9404``` 9405 9406### disableLandscapeMultiWindow<sup>12+</sup> 9407 9408disableLandscapeMultiWindow(): Promise<void> 9409 9410Disables the landscape multi-window mode for the UI page that supports the horizontal layout. 9411 9412This 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. 9413 9414**Atomic service API**: This API can be used in atomic services since API version 12. 9415 9416**System capability**: SystemCapability.Window.SessionManager 9417 9418**Return value** 9419 9420| Type | Description | 9421| ------------------- | ------------------------------ | 9422| Promise<void> | Promise that returns no value. | 9423 9424**Error codes** 9425 9426For details about the error codes, see [Window Error Codes](errorcode-window.md). 9427 9428| ID | Error Message | 9429| ------- | --------------------------------------------- | 9430| 1300002 | This window state is abnormal. | 9431| 1300003 | This window manager service works abnormally. | 9432 9433**Example** 9434 9435```ts 9436// EntryAbility.ets 9437import { UIAbility } from '@kit.AbilityKit'; 9438import { BusinessError } from '@kit.BasicServicesKit'; 9439import { window } from '@kit.ArkUI'; 9440 9441export default class EntryAbility extends UIAbility { 9442 // ... 9443 onWindowStageCreate(windowStage: window.WindowStage): void { 9444 console.info('onWindowStageCreate'); 9445 let windowClass: window.Window | undefined = undefined; 9446 windowStage.getMainWindow((err: BusinessError, data) => { 9447 const errCode: number = err.code; 9448 if (errCode) { 9449 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9450 return; 9451 } 9452 windowClass = data; 9453 let promise = windowClass.disableLandscapeMultiWindow(); 9454 promise.then(() => { 9455 console.info('Succeeded in making multi-window become not landscape.'); 9456 }).catch((err: BusinessError) => { 9457 console.error(`Failed to make multi-window become not landscape. Cause code: ${err.code}, message: ${err.message}`); 9458 }); 9459 }); 9460 } 9461} 9462``` 9463 9464### setDialogBackGestureEnabled<sup>12+</sup> 9465 9466setDialogBackGestureEnabled(enabled: boolean): Promise<void> 9467 9468Sets 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. 9469 9470**System capability**: SystemCapability.Window.SessionManager 9471 9472**Atomic service API**: This API can be used in atomic services since API version 12. 9473 9474**Parameters** 9475 9476| Name | Type | Mandatory | Description | 9477| ------- | ------- | --------- | ------------------------------------------------------------ | 9478| enabled | boolean | Yes | Whether to respond to the back gesture event.<br>The value **true** means to respond to the back gesture event and trigger the **onBackPress** callback, and **false** means the opposite.<br> | 9479 9480**Return value** 9481 9482| Type | Description | 9483| ------------------- | ------------------------------ | 9484| Promise<void> | Promise that returns no value. | 9485 9486**Error codes** 9487 9488For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9489 9490| ID | Error Message | 9491| ------- | ------------------------------------------------------------ | 9492| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9493| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9494| 1300002 | This window state is abnormal. | 9495| 1300003 | This window manager service works abnormally. | 9496| 1300004 | Unauthorized operation. | 9497 9498**Example** 9499 9500```ts 9501// EntryAbility.ets 9502import { UIAbility } from '@kit.AbilityKit'; 9503import { BusinessError } from '@kit.BasicServicesKit'; 9504 9505export default class EntryAbility extends UIAbility { 9506 onWindowStageCreate(windowStage: window.WindowStage): void { 9507 console.info('onWindowStageCreate'); 9508 let windowClass: window.Window | undefined = undefined; 9509 let config: window.Configuration = { 9510 name: "test", 9511 windowType: window.WindowType.TYPE_DIALOG, 9512 ctx: this.context 9513 }; 9514 try { 9515 window.createWindow(config, (err: BusinessError, data) => { 9516 const errCode: number = err.code; 9517 if (errCode) { 9518 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 9519 return; 9520 } 9521 windowClass = data; 9522 windowClass.setUIContent("pages/Index"); 9523 let enabled = true; 9524 let promise = windowClass.setDialogBackGestureEnabled(enabled); 9525 promise.then(() => { 9526 console.info('Succeeded in setting dialog window to respond back gesture.'); 9527 }).catch((err: BusinessError) => { 9528 console.error(`Failed to set dialog window to respond back gesture. Cause code: ${err.code}, message: ${err.message}`); 9529 }); 9530 }); 9531 } catch (exception) { 9532 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 9533 } 9534 } 9535} 9536``` 9537 9538```ts 9539// ets/pages/Index.ets 9540@Entry 9541@Component 9542struct Index { 9543 @State message: string = 'Hello World' 9544 build() { 9545 RelativeContainer() { 9546 Text(this.message) 9547 .id('HelloWorld') 9548 .fontSize(50) 9549 .fontWeight(FontWeight.Bold) 9550 } 9551 .height('100%') 9552 .width('100%') 9553 } 9554 9555 onBackPress(): boolean | void { 9556 console.info('Succeeded in setting dialog window to respond back gesture.'); 9557 return true; 9558 } 9559} 9560``` 9561 9562### startMoving<sup>14+</sup> 9563 9564startMoving(): Promise<void> 9565 9566Starts moving this window. This API uses a promise to return the result. 9567 9568The window moves along with the cursor or touch point 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**. 9569 9570<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 9571 9572This API takes effect only for the main window, child window, and system window. If it is called for other device types or window types, an error is reported. 9573 9574**System capability**: SystemCapability.Window.SessionManager 9575 9576**Atomic service API**: This API can be used in atomic services since API version 14. 9577 9578**Return value** 9579 9580| Type | Description | 9581| ------------------- | ------------------------------ | 9582| Promise<void> | Promise that returns no value. | 9583 9584**Error codes** 9585 9586For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9587 9588| ID | Error Message | 9589| ------- | ------------------------------------------------------------ | 9590| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9591| 1300001 | Repeated operation. | 9592| 1300002 | This window state is abnormal. | 9593| 1300003 | This window manager service works abnormally. | 9594| 1300004 | Unauthorized operation. | 9595 9596**Example** 9597 9598```ts 9599// ets/pages/Index.ets 9600import { BusinessError } from '@kit.BasicServicesKit'; 9601 9602@Entry 9603@Component 9604struct Index { 9605 build() { 9606 Row() { 9607 Column() { 9608 Blank('160') 9609 .color(Color.Blue) 9610 .onTouch((event: TouchEvent) => { 9611 if (event.type === TouchType.Down) { 9612 try { 9613 let windowClass: window.Window = window.findWindow("subWindow"); 9614 windowClass.startMoving().then(() => { 9615 console.info('Succeeded in starting moving window.') 9616 }).catch((err: BusinessError) => { 9617 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 9618 }); 9619 } catch (exception) { 9620 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 9621 } 9622 } 9623 }) 9624 }.width('100%') 9625 }.height('100%').width('100%') 9626 } 9627} 9628``` 9629 9630### startMoving<sup>15+</sup> 9631 9632startMoving(offsetX: number, offsetY: number): Promise<void> 9633 9634Specifies the cursor position within the window and moves the window. This API uses a promise to return the result. 9635 9636When windows within the same application are split or merged, and the mouse is pressed down to move the new window directly, the cursor may move outside the window if it moves too quickly. This API allows you to set the cursor position within the window during movement. It first adjusts the window to the cursor position before starting to move the window. 9637 9638The 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**. 9639 9640<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 9641 9642**System capability**: SystemCapability.Window.SessionManager 9643 9644**Atomic service API**: This API can be used in atomic services since API version 15. 9645 9646**Parameters** 9647 9648| Name | Type | Mandatory | Description | 9649| ------- | ------ | --------- | ------------------------------------------------------------ | 9650| offsetX | number | Yes | X-axis offset of the cursor position relative to the upper left corner of the window during movement, measured in px. This parameter only accepts integer values; any floating-point input will be rounded down. Negative values or values exceeding the window width are invalid. The window width can be obtained from [WindowProperties](#windowproperties). | 9651| offsetY | number | Yes | Y-axis offset of the cursor position relative to the upper left corner of the window during movement, measured in px. This parameter only accepts integer values; any floating-point input will be rounded down. Negative values or values exceeding the window height are invalid. The window height can be obtained from [WindowProperties](#windowproperties). | 9652 9653**Return value** 9654 9655| Type | Description | 9656| ------------------- | ------------------------------ | 9657| Promise<void> | Promise that returns no value. | 9658 9659**Error codes** 9660 9661For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9662 9663| ID | Error Message | 9664| ------- | ------------------------------------------------------------ | 9665| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9666| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9667| 1300001 | Repeated operation. | 9668| 1300002 | This window state is abnormal. | 9669| 1300003 | This window manager service works abnormally. | 9670| 1300004 | Unauthorized operation. | 9671 9672**Example** 9673 9674```ts 9675// ets/pages/Index.ets 9676import { BusinessError } from '@kit.BasicServicesKit'; 9677 9678@Entry 9679@Component 9680struct Index { 9681 build() { 9682 Row() { 9683 Column() { 9684 Blank('160') 9685 .color(Color.Blue) 9686 .onTouch((event: TouchEvent) => { 9687 if (event.type === TouchType.Down) { 9688 try { 9689 let windowClass: window.Window = window.findWindow("subWindow"); 9690 windowClass.startMoving(100, 50).then(() => { 9691 console.info('Succeeded in starting moving window.') 9692 }).catch((err: BusinessError) => { 9693 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 9694 }); 9695 } catch (exception) { 9696 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 9697 } 9698 } 9699 }) 9700 }.width('100%') 9701 }.height('100%').width('100%') 9702 } 9703} 9704``` 9705 9706### stopMoving<sup>15+</sup> 9707 9708stopMoving(): Promise<void> 9709 9710Stops window movement when a window is being dragged. This API uses a promise to return the result. 9711 9712<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 9713 9714**System capability**: SystemCapability.Window.SessionManager 9715 9716**Atomic service API**: This API can be used in atomic services since API version 15. 9717 9718**Return value** 9719 9720| Type | Description | 9721| ------------------- | ------------------------------ | 9722| Promise<void> | Promise that returns no value. | 9723 9724**Error codes** 9725 9726For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9727 9728| ID | Error Message | 9729| ------- | ------------------------------------------------------------ | 9730| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9731| 1300002 | This window state is abnormal. | 9732| 1300003 | This window manager service works abnormally. | 9733| 1300004 | Unauthorized operation. | 9734 9735**Example** 9736 9737```ts 9738// EntryAbility.ets 9739import { UIAbility } from '@kit.AbilityKit'; 9740import { window } from '@kit.ArkUI'; 9741import { BusinessError } from '@kit.BasicServicesKit'; 9742 9743export default class EntryAbility extends UIAbility { 9744 9745 onWindowStageCreate(windowStage: window.WindowStage) { 9746 try { 9747 let windowClass = windowStage.getMainWindowSync(); 9748 windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 9749 if (data.reason === window.RectChangeReason.MOVE) { 9750 windowClass.stopMoving().then(() => { 9751 console.info('Succeeded in stopping moving window.') 9752 }).catch((err: BusinessError) => { 9753 console.error(`Failed to stop moving. Cause code: ${err.code}, message: ${err.message}`); 9754 }); 9755 } 9756 }); 9757 } catch (exception) { 9758 console.error(`Failed to stop moving window. Cause code: ${exception.code}, message: ${exception.message}`); 9759 } 9760 } 9761} 9762``` 9763 9764### setGestureBackEnabled<sup>13+<sup> 9765 9766setGestureBackEnabled(enabled: boolean): Promise<void> 9767 9768Sets 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. 9769 9770When 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. 9771 9772When 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. 9773 9774**System capability**: SystemCapability.Window.SessionManager 9775 9776**Atomic service API**: This API can be used in atomic services since API version 13. 9777 9778**Parameters** 9779 9780| Name | Type | Mandatory | Description | 9781| ------- | ------- | --------- | ------------------------------------------------------------ | 9782| enabled | boolean | Yes | Whether to enable the back gesture feature. The value **true** means to enable the feature, and **false** means the opposite. | 9783 9784**Return value** 9785 9786| Type | Description | 9787| ------------------- | ------------------------------ | 9788| Promise<void> | Promise that returns no value. | 9789 9790**Error codes** 9791 9792For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9793 9794| ID | Error Message | 9795| ------- | ------------------------------------------------------------ | 9796| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9797| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9798| 1300002 | This window state is abnormal. | 9799| 1300003 | This window manager service works abnormally. | 9800| 1300004 | Unauthorized operation. | 9801 9802**Example** 9803 9804```ts 9805// EntryAbility.ets 9806import { UIAbility } from '@kit.AbilityKit'; 9807import { BusinessError } from '@kit.BasicServicesKit'; 9808import { window } from '@kit.ArkUI'; 9809 9810export default class EntryAbility extends UIAbility { 9811 // ... 9812 onWindowStageCreate(windowStage: window.WindowStage): void { 9813 console.info('onWindowStageCreate'); 9814 let windowClass: window.Window | undefined = undefined; 9815 windowStage.getMainWindow((err: BusinessError, data) => { 9816 const errCode: number = err.code; 9817 if (errCode) { 9818 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9819 return; 9820 } 9821 windowClass = data; 9822 9823 // Disable the back gesture feature in the current window. 9824 try { 9825 let gestureBackEnabled: boolean = false; 9826 let promise = windowClass.setGestureBackEnabled(gestureBackEnabled); 9827 promise.then(() => { 9828 console.info(`Succeeded in setting gesture back disabled`); 9829 }).catch((err: BusinessError) => { 9830 console.error(`Failed to set gesture back disabled, Cause code: ${err.code}, message: ${err.message}`); 9831 }); 9832 } catch(exception) { 9833 console.error(`Failed to set gesture back disabled, Cause code: ${exception.code}, message: ${exception.message}`); 9834 } 9835 }); 9836 } 9837} 9838``` 9839 9840### isGestureBackEnabled<sup>13+<sup> 9841 9842isGestureBackEnabled(): boolean 9843 9844Checks 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. 9845 9846**System capability**: SystemCapability.Window.SessionManager 9847 9848**Atomic service API**: This API can be used in atomic services since API version 13. 9849 9850**Return value** 9851 9852| Type | Description | 9853| ------- | ------------------------------------------------------------ | 9854| 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. | 9855 9856**Error codes** 9857 9858For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9859 9860| ID | Error Message | 9861| ------- | ------------------------------------------------------------ | 9862| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9863| 1300002 | This window state is abnormal. | 9864| 1300003 | This window manager service works abnormally. | 9865| 1300004 | Unauthorized operation. | 9866 9867**Example** 9868 9869```ts 9870// EntryAbility.ets 9871import { UIAbility } from '@kit.AbilityKit'; 9872import { BusinessError } from '@kit.BasicServicesKit'; 9873import { window } from '@kit.ArkUI'; 9874 9875export default class EntryAbility extends UIAbility { 9876 // ... 9877 onWindowStageCreate(windowStage: window.WindowStage): void { 9878 console.info('onWindowStageCreate'); 9879 let windowClass: window.Window | undefined = undefined; 9880 windowStage.getMainWindow((err: BusinessError, data) => { 9881 const errCode: number = err.code; 9882 if (errCode) { 9883 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9884 return; 9885 } 9886 windowClass = data; 9887 9888 // Check whether the back gesture feature is enabled in the current window. 9889 try { 9890 let gestureBackEnabled: boolean = windowClass.isGestureBackEnabled(); 9891 console.info(`Succeeded in obtaining gesture back enabled status: ${gestureBackEnabled}`); 9892 } catch (exception) { 9893 console.error(`Failed to get gesture back enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 9894 } 9895 }); 9896 } 9897} 9898``` 9899 9900### setWindowShadowRadius<sup>17+</sup> 9901 9902setWindowShadowRadius(radius: number): void 9903 9904Sets the blur radius of the shadow on the edges of a child window or floating window. This API can be used only on 2-in-1 devices or tablets. 9905 9906**System capability**: SystemCapability.Window.SessionManager 9907 9908**Atomic service API**: This API can be used in atomic services since API version 17. 9909 9910**Parameters** 9911 9912| Name | Type | Mandatory | Description | 9913| ------ | ------ | --------- | ------------------------------------------------------------ | 9914| radius | number | Yes | Radius of the shadow, measured in px. The value is a floating point number greater than or equal to 0.0, and the value **0.0** means that the shadow is disabled for the window borders. | 9915 9916**Error codes** 9917 9918For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9919 9920| ID | Error Message | 9921| ------- | ------------------------------------------------------------ | 9922| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 9923| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9924| 1300002 | This window state is abnormal. | 9925| 1300004 | Unauthorized operation. | 9926 9927**Example** 9928 9929```ts 9930try { 9931 windowClass.setWindowShadowRadius(4.0); 9932} catch (exception) { 9933 console.error(`Failed to set shadow. Cause code: ${exception.code}, message: ${exception.message}`); 9934} 9935``` 9936 9937### setWindowCornerRadius<sup>17+</sup> 9938 9939setWindowCornerRadius(cornerRadius: number): Promise<void> 9940 9941Sets the radius of the rounded corners for a child window or floating window. This API uses a promise to return the result. 9942 9943<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 9944 9945If the radius of the rounded corner is too large, it may cause the three buttons (maximize, minimize, and close) to be clipped and make their hotspots less recognizable. Set an appropriate radius based on the window size. 9946 9947Before calling this API, you can call [getWindowCornerRadius()](#getwindowcornerradius17) to obtain the default radius of rounded corners of the window. 9948 9949**System capability**: SystemCapability.Window.SessionManager 9950 9951**Atomic service API**: This API can be used in atomic services since API version 17. 9952 9953**Parameters** 9954 9955| Name | Type | Mandatory | Description | 9956| ------------ | ------ | --------- | ------------------------------------------------------------ | 9957| cornerRadius | number | Yes | Radius of the rounded corners, measured in vp. The value is a floating point number greater than or equal to 0.0. The value **0.0** means that the window does not use rounded corners. | 9958 9959**Return value** 9960 9961| Type | Description | 9962| ------------------- | ------------------------------ | 9963| Promise<void> | Promise that returns no value. | 9964 9965**Error codes** 9966 9967For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9968 9969| ID | Error Message | 9970| ------- | ------------------------------------------------------------ | 9971| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 9972| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9973| 1300002 | This window state is abnormal. | 9974| 1300003 | This window manager service works abnormally. | 9975| 1300004 | Unauthorized operation. | 9976 9977**Example** 9978 9979```ts 9980import { BusinessError } from '@kit.BasicServicesKit'; 9981 9982try{ 9983 let promise = windowClass.setWindowCornerRadius(1.0); 9984 promise.then(() => { 9985 console.info('Succeeded in setting window corner radius.'); 9986 }).catch((err: BusinessError) => { 9987 console.error(`Failed to set window corner radius. Cause code: ${err.code}, message: ${err.message}`); 9988 }); 9989} catch (exception) { 9990 console.error(`Failed to set corner radius. Cause code: ${exception.code}, message: ${exception.message}`); 9991} 9992 9993``` 9994 9995### getWindowCornerRadius<sup>17+</sup> 9996 9997getWindowCornerRadius(): number 9998 9999Obtains the radius of rounded corners of a child window or floating window. If [setWindowCornerRadius()](#setwindowcornerradius17) is not called to set the radius of rounded corners, this API returns the default radius of rounded corners. 10000 10001<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 10002 10003**System capability**: SystemCapability.Window.SessionManager 10004 10005**Atomic service API**: This API can be used in atomic services since API version 17. 10006 10007**Return value** 10008 10009| Type | Description | 10010| ------ | ------------------------------------------------------------ | 10011| number | Radius of the rounded corner of the child window or floating window, measured in vp. | 10012 10013**Error codes** 10014 10015For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10016 10017| ID | Error Message | 10018| ------- | ------------------------------------------------------------ | 10019| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10020| 1300002 | This window state is abnormal. | 10021| 1300004 | Unauthorized operation. | 10022 10023**Example** 10024 10025```ts 10026try { 10027 let cornerRadius = windowClass.getWindowCornerRadius(); 10028} catch (exception) { 10029 console.error(`Failed to get corner radius. Cause code: ${exception.code}, message: ${exception.message}`); 10030} 10031``` 10032 10033### setExclusivelyHighlighted<sup>15+<sup> 10034 10035setExclusivelyHighlighted(exclusivelyHighlighted: boolean): Promise<void> 10036 10037Sets the exclusive highlight property for the window. When a window set to exclusive highlight gains focus, other windows in the current parent-child window chain that are in the highlighted state will lose their highlighted state. This API uses a promise to return the result. 10038 10039This API does not take effect for the main window, modal window, and dialog boxes. 10040 10041**System capability**: SystemCapability.Window.SessionManager 10042 10043**Atomic service API**: This API can be used in atomic services since API version 15. 10044 10045**Parameters** 10046 10047| Name | Type | Mandatory | Description | 10048| ---------------------- | ------- | --------- | ------------------------------------------------------------ | 10049| exclusivelyHighlighted | boolean | Yes | Whether to set exclusive highlight for the window. The value **true** means to set exclusive highlight for the window, and **false** means the opposite. | 10050 10051**Return value** 10052 10053| Type | Description | 10054| ------------------- | ------------------------------ | 10055| Promise<void> | Promise that returns no value. | 10056 10057**Error codes** 10058 10059For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10060 10061| ID | Error Message | 10062| ------- | ------------------------------------------------------------ | 10063| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 10064| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10065| 1300002 | This window state is abnormal. | 10066| 1300003 | This window manager service works abnormally. | 10067| 1300004 | Unauthorized operation. | 10068 10069**Example** 10070 10071```ts 10072import { BusinessError } from '@kit.BasicServicesKit'; 10073 10074let exclusivelyHighlighted: boolean = true; 10075try { 10076 let promise = windowClass.setExclusivelyHighlighted(exclusivelyHighlighted); 10077 promise.then(() => { 10078 console.info('Succeeded in setting the window to be exclusively highlight.'); 10079 }).catch((err: BusinessError) => { 10080 console.error(`Failed to set the window to be exclusively highlight. Cause code: ${err.code}, message: ${err.message}`); 10081 }); 10082} catch (exception) { 10083 console.error(`Failed to set the window to be exclusively highlight. Cause code: ${exception.code}, message: ${exception.message}`); 10084} 10085``` 10086 10087### isWindowHighlighted<sup>18+<sup> 10088 10089isWindowHighlighted(): boolean 10090 10091Checks whether the window is active. To obtain the active state, call this API when the [WindowEventType](#windoweventtype10) lifecycle is **WINDOW_ACTIVE**. 10092 10093You can use [on('windowHighlightChange')](#onwindowhighlightchange15) to listen for status changes and then execute the corresponding service. 10094 10095**System capability**: SystemCapability.Window.SessionManager 10096 10097**Atomic service API**: This API can be used in atomic services since API version 18. 10098 10099**Return value** 10100 10101| Type | Description | 10102| ------- | ------------------------------------------------------------ | 10103| boolean | Check result. The value **true** means that the window is active, and **false** means the opposite. | 10104 10105**Error codes** 10106 10107For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10108 10109| ID | Error Message | 10110| ------- | ------------------------------------------------------------ | 10111| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10112| 1300002 | This window state is abnormal. | 10113 10114**Example** 10115 10116```ts 10117import { BusinessError } from '@kit.BasicServicesKit'; 10118 10119try { 10120 let isHighlighted = windowClass.isWindowHighlighted(); 10121 console.info(`Succeeded in getting the window highlight status: ${isHighlighted}`); 10122} catch (exception) { 10123 console.error(`Failed to get the window highlight status.. Cause code: ${exception.code}, message: ${exception.message}`); 10124} 10125``` 10126 10127### setFollowParentMultiScreenPolicy<sup>17+<sup> 10128 10129setFollowParentMultiScreenPolicy(enabled: boolean): Promise<void> 10130 10131Sets whether a child window can span multiple screens and be simultaneously displayed while its parent window is being dragged or resized. This API uses a promise to return the result. 10132 10133By default, when a child window follows its parent window's layout changes (by using [moveWindowTo()](#movewindowto9)), it does not support spanning multiple screens and being simultaneously displayed. 10134 10135However, calling this API on the child window enables it to span multiple screens and be simultaneously displayed during the layout adjustment process. 10136 10137<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 10138 10139**System capability**: SystemCapability.Window.SessionManager 10140 10141**Atomic service API**: This API can be used in atomic services since API version 17. 10142 10143**Parameters** 10144 10145| Name | Type | Mandatory | Description | 10146| ------- | ------- | --------- | ------------------------------------------------------------ | 10147| enabled | boolean | Yes | Whether the child window can span multiple screens and be simultaneously displayed while its parent window is being dragged or resized. The value **true** means that the child window can span multiple screens and be simultaneously displayed while its parent window is being dragged or resized, and **false** means the opposite. | 10148 10149**Return value** 10150 10151| Type | Description | 10152| ------------------- | ------------------------------ | 10153| Promise<void> | Promise that returns no value. | 10154 10155**Error codes** 10156 10157For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10158 10159| ID | Error Message | 10160| ------- | ------------------------------------------------------------ | 10161| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10162| 801 | Capability not supported.Function setFollowParentMultiScreenPolicy can not work correctly due to limited device capabilities. | 10163| 1300002 | This window state is abnormal. | 10164| 1300003 | This window manager service works abnormally. | 10165| 1300004 | Unauthorized operation. | 10166 10167**Example** 10168 10169```ts 10170import { BusinessError } from '@kit.BasicServicesKit'; 10171 10172try { 10173 let windowClass: window.Window = window.findWindow("subWindow"); 10174 let enabled: boolean = true; 10175 let promise = windowClass?.setFollowParentMultiScreenPolicy(enabled); 10176 promise.then(() => { 10177 console.info('Succeeded in setting the sub window supports multi-screen simultaneous display') 10178 }).catch((err: BusinessError) => { 10179 console.error(`Failed to set the sub window supports multi-screen simultaneous display. Cause code: ${err.code}, message: ${err.message}`); 10180 }); 10181} catch (exception) { 10182 console.error(`Failed to set the sub window supports multi-screen simultaneous display. Cause code: ${exception.code}, message: ${exception.message}`); 10183} 10184``` 10185 10186### setFollowParentWindowLayoutEnabled<sup>17+</sup> 10187 10188setFollowParentWindowLayoutEnabled(enabled: boolean): Promise<void> 10189 10190Sets whether the layout information (position and size) of a child window or modal window (a window with **WindowType** set to **TYPE_DIALOG**) follows the main window. This API uses a promise to return the result. 10191 101921. This API applies only to first-level child windows or modal windows of the main window. 10193 101942. Once this API is called on a child window or modal window, its layout information will immediately match the main window and remain synchronized. This effect will persist until this API is called again with **false**. 10195 101963. If this API is called on a child window or modal window, subsequent calls to APIs like **moveTo** or **resize** to modify the layout information will not take effect. 10197 101984. When a child window or modal window stops using this functionality, its layout information (position and size) may not be a specific value. The application needs to reset it. 10199 10200Once this API is successfully called, the [setRelativePositionToParentWindowEnabled()](#setrelativepositiontoparentwindowenabled20) API will no longer take effect. 10201 10202**Model restriction**: This API can be used only in the stage model. 10203 10204**Atomic service API**: This API can be used in atomic services since API version 17. 10205 10206**System capability**: SystemCapability.Window.SessionManager 10207 10208**Parameters** 10209 10210| Name | Type | Mandatory | Description | 10211| ------- | ------- | --------- | ------------------------------------------------------------ | 10212| enabled | boolean | Yes | Whether to follow the layout of the main window. The value **true** means to follow the layout of the main window, and **false** means the opposite. | 10213 10214**Return value** 10215 10216| Type | Description | 10217| ------------------- | ------------------------------ | 10218| Promise<void> | Promise that returns no value. | 10219 10220**Error codes** 10221 10222For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10223 10224| ID | Error Message | 10225| ------- | ------------------------------------------------------------ | 10226| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10227| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10228| 1300002 | This window state is abnormal. | 10229| 1300003 | This window manager service works abnormally. | 10230| 1300004 | Unauthorized operation. | 10231 10232**Example** 10233 10234```ts 10235// EntryAbility.ets 10236import { window } from '@kit.ArkUI'; 10237import { BusinessError } from '@kit.BasicServicesKit'; 10238import { UIAbility } from '@kit.AbilityKit'; 10239 10240export default class EntryAbility extends UIAbility { 10241 onWindowStageCreate(windowStage: window.WindowStage): void { 10242 windowStage.loadContent('pages/Index', (loadError) => { 10243 if (loadError.code) { 10244 console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`); 10245 return; 10246 } 10247 console.info("Succeeded in loading the content."); 10248 windowStage.createSubWindow("subWindow").then((subWindow: window.Window) => { 10249 if (subWindow == null) { 10250 console.error("Failed to create the subWindow. Cause: The data is empty"); 10251 return; 10252 } 10253 subWindow.setFollowParentWindowLayoutEnabled(true).then(() => { 10254 console.info("after set follow parent window layout") 10255 }).catch((error: BusinessError) => { 10256 console.error(`setFollowParentWindowLayoutEnabled failed. ${error.code} ${error.message}`); 10257 }) 10258 }).catch((error: BusinessError) => { 10259 console.error(`createSubWindow failed. ${error.code} ${error.message}`); 10260 }) 10261 }); 10262 } 10263} 10264``` 10265 10266### setRelativePositionToParentWindowEnabled<sup>20+<sup> 10267 10268setRelativePositionToParentWindowEnabled(enabled: boolean, anchor?: WindowAnchor, offsetX?: number, offsetY?: number): Promise<void> 10269 10270Sets whether a first-level child window can maintain a fixed relative position to the main window. This API uses a promise to return the result. 10271 10272The relative position is defined by the offset between the anchor points of the child window and the main window. Both the child window and the main window use the same type of anchor point. 10273 102741. This API applies only to level-1 child windows that are not maximized. 10275 102762. Once this API is called on a child window, its display position will immediately follow the main window and maintain a fixed relative position. This effect will persist until this API is called again with **false**. 10277 102783. If this API is called on a child window, subsequent calls to APIs like [moveWindowTo()](#movewindowto9) or [maximize()](#maximize12) to modify the window's position or size will not take effect. 10279 10280Once this API is successfully called, the [setFollowParentWindowLayoutEnabled()](#setfollowparentwindowlayoutenabled17) API will no longer take effect. 10281 10282<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 10283 10284**System capability**: SystemCapability.Window.SessionManager 10285 10286**Atomic service API**: This API can be used in atomic services since API version 20. 10287 10288**Parameters** 10289 10290| Name | Type | Mandatory | Description | 10291| ------- | ------------------------------- | --------- | ------------------------------------------------------------ | 10292| enabled | boolean | Yes | Whether to maintain a fixed relative position to the main window. The value **true** means to maintain a fixed relative position to the main window, and **false** means the opposite. | 10293| anchor | [WindowAnchor](#windowanchor20) | No | Type of anchor point used to maintain the relative position. This parameter takes effect only when **enabled** is set to **true**. The default value is **window.WindowAnchor.TopStart**, indicating that the default anchor point is the top-left corner of the window. | 10294| offsetX | number | No | X-axis offset between the anchor points of the child window and the main window, in px. This parameter takes effect only when **enabled** is set to **true**. Only integer values are supported, and floating-point numbers are rounded down. The default value is **0**. | 10295| offsetY | number | No | Y-axis offset between the anchor points of the child window and the main window, in px. This parameter takes effect only when **enabled** is set to **true**. Only integer values are supported, and floating-point numbers are rounded down. The default value is **0**. | 10296 10297**Return value** 10298 10299| Type | Description | 10300| ------------------- | ------------------------------ | 10301| Promise<void> | Promise that returns no value. | 10302 10303**Error codes** 10304 10305For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10306 10307| ID | Error Message | 10308| ------- | ------------------------------------------------------------ | 10309| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10310| 801 | Capability not supported.Function setRelativePositionToParentWindowEnabled can not work correctly due to limited device capabilities. | 10311| 1300002 | This window state is abnormal. | 10312| 1300003 | This window manager service works abnormally. | 10313| 1300004 | Unauthorized operation. | 10314 10315**Example** 10316 10317```ts 10318import { BusinessError } from '@kit.BasicServicesKit'; 10319 10320try { 10321 let windowClass: window.Window = window.findWindow("subWindow"); 10322 let enabled: boolean = true; 10323 let promise = windowClass?.setRelativePositionToParentWindowEnabled(enabled); 10324 promise.then(() => { 10325 console.info('Succeeded in setting the sub window supports relative position to parent window.') 10326 }).catch((err: BusinessError) => { 10327 console.error(`Failed to set the sub window supports relative position to parent window. Cause code: ${err.code}, message: ${err.message}`); 10328 }); 10329} catch (exception) { 10330 console.error(`Failed to set the sub window supports relative position to parent window. Cause code: ${exception.code}, message: ${exception.message}`); 10331} 10332``` 10333 10334### setWindowTransitionAnimation<sup>20+</sup> 10335 10336setWindowTransitionAnimation(transitionType: WindowTransitionType, animation: TransitionAnimation): Promise<void> 10337 10338Adds a transition animation to windows in specific scenarios. 10339 10340Currently, this API can be used only on the main window of an application. 10341 10342<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 10343 10344**Model restriction**: This API can be used only in the stage model. 10345 10346**Atomic service API**: This API can be used in atomic services since API version 20. 10347 10348**System capability**: SystemCapability.Window.SessionManager 10349 10350**Parameters** 10351 10352| Name | Type | Mandatory | Description | 10353| -------------- | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 10354| transitionType | [WindowTransitionType](#windowtransitiontype20) | Yes | Scene of the transition animation. Currently, only the destruction scene is supported. | 10355| animation | [TransitionAnimation](#transitionanimation20) | Yes | Configuration of the transition animation. | 10356 10357**Return value** 10358 10359| Type | Description | 10360| ------------------- | ------------------------------ | 10361| Promise<void> | Promise that returns no value. | 10362 10363**Error codes** 10364 10365For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10366 10367| ID | Error Message | 10368| ------- | ------------------------------------------------------------ | 10369| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10370| 1300002 | This window state is abnormal. | 10371| 1300003 | This window manager service works abnormally. | 10372| 1300004 | Unauthorized operation. | 10373| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range; 2. Invalid parameter length. | 10374 10375**Example** 10376 10377```typescript 10378// EntryAbility.ets 10379import { BusinessError } from '@kit.BasicServicesKit'; 10380import { UIAbility } from '@kit.AbilityKit'; 10381import { window } from '@kit.ArkUI'; 10382 10383export default class EntryAbility extends UIAbility { 10384 // ... 10385 onWindowStageCreate(windowStage: window.WindowStage): void { 10386 console.info('onWindowStageCreate'); 10387 let windowClass: window.Window | undefined = undefined; 10388 windowStage.getMainWindow((err: BusinessError, data) => { 10389 const errCode: number = err.code; 10390 if (errCode) { 10391 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10392 return; 10393 } 10394 windowClass = data; 10395 try { 10396 const animationConfig: window.WindowAnimationConfig = { 10397 duration: 1000, 10398 curve: window.WindowAnimationCurve.LINEAR, 10399 }; 10400 const transitionAnimation: window.TransitionAnimation = { 10401 opacity: 0.5, 10402 config: animationConfig 10403 }; 10404 let promise = windowClass.setWindowTransitionAnimation(window.WindowTransitionType.DESTROY, transitionAnimation); 10405 promise.then((data) => { 10406 console.info('Succeeded in setting window transition animation. Cause:' + JSON.stringify(data)); 10407 }).catch((err: BusinessError) => { 10408 console.error(`Failed to set window transition animation. Cause code: ${err.code}, message: ${err.message}`); 10409 }); 10410 } catch (exception) { 10411 console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); 10412 } 10413 }) 10414 } 10415} 10416``` 10417 10418### getWindowTransitionAnimation<sup>20+</sup> 10419 10420getWindowTransitionAnimation(transitionType: WindowTransitionType): TransitionAnimation | undefined 10421 10422Obtains the window transition animation configuration in a specific scenario. 10423 10424Currently, this API can be used only on the main window of an application. 10425 10426<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 10427 10428**Model restriction**: This API can be used only in the stage model. 10429 10430**Atomic service API**: This API can be used in atomic services since API version 20. 10431 10432**System capability**: SystemCapability.Window.SessionManager 10433 10434**Parameters** 10435 10436| Name | Type | Mandatory | Description | 10437| -------------- | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 10438| transitionType | [WindowTransitionType](#windowtransitiontype20) | Yes | Scene of the transition animation. Currently, only the destruction scene is supported. | 10439 10440**Return value** 10441 10442| Type | Description | 10443| ---------------------------------------------------------- | ------------------------------------------------------------ | 10444| [TransitionAnimation](#transitionanimation20) \| undefined | Transition animation configuration in the corresponding scene. If the [setWindowTransitionAnimation](#setwindowtransitionanimation20) API is not used, undefined is returned. | 10445 10446**Error codes** 10447 10448For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10449 10450| ID | Error Message | 10451| ------- | ------------------------------------------------------------ | 10452| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10453| 1300002 | This window state is abnormal. | 10454| 1300003 | This window manager service works abnormally. | 10455| 1300004 | Unauthorized operation. | 10456| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range; 2. Invalid parameter length. | 10457 10458**Example** 10459 10460```typescript 10461// EntryAbility.ets 10462import { BusinessError } from '@kit.BasicServicesKit'; 10463import { UIAbility } from '@kit.AbilityKit'; 10464import { window } from '@kit.ArkUI'; 10465 10466export default class EntryAbility extends UIAbility { 10467 // ... 10468 onWindowStageCreate(windowStage: window.WindowStage): void { 10469 console.info('onWindowStageCreate'); 10470 let windowClass: window.Window | undefined = undefined; 10471 windowStage.getMainWindow((err: BusinessError, data) => { 10472 const errCode: number = err.code; 10473 if (errCode) { 10474 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10475 return; 10476 } 10477 windowClass = data; 10478 try { 10479 let transitionAnimationResult = windowClass.getWindowTransitionAnimation(window.WindowTransitionType.DESTROY); 10480 console.info('Succeeded in getting window transition animation: ' + JSON.stringify(transitionAnimationResult)); 10481 } catch (exception) { 10482 console.error(`Failed to obtain the window transition animation. Cause code: ${exception.code}, message: ${exception.message}`); 10483 } 10484 }) 10485 } 10486} 10487``` 10488 10489### setWindowSystemBarProperties<sup>(deprecated)</sup> 10490 10491setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 10492 10493Sets the properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar of the main window. This API uses an asynchronous callback to return the result. <!--RP5-->This API does not take effect on 2-in-1 devices.<!--RP5End--> 10494 10495This API does not take effect when it is called by a child window. 10496 10497> **NOTE** 10498> 10499> 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. 10500 10501**System capability**: SystemCapability.WindowManager.WindowManager.Core 10502 10503**Atomic service API**: This API can be used in atomic services since API version 12. 10504 10505**Parameters** 10506 10507| Name | Type | Mandatory | Description | 10508| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 10509| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar. | 10510| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10511 10512**Error codes** 10513 10514For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10515 10516| ID | Error Message | 10517| ------- | ------------------------------------------------------------ | 10518| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10519| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10520| 1300002 | This window state is abnormal. | 10521| 1300003 | This window manager service works abnormally. | 10522 10523**Example** 10524 10525```ts 10526// EntryAbility.ets 10527import { UIAbility } from '@kit.AbilityKit'; 10528import { BusinessError } from '@kit.BasicServicesKit'; 10529 10530export default class EntryAbility extends UIAbility { 10531 // ... 10532 onWindowStageCreate(windowStage: window.WindowStage): void { 10533 console.info('onWindowStageCreate'); 10534 let windowClass: window.Window | undefined = undefined; 10535 windowStage.getMainWindow((err: BusinessError, data) => { 10536 const errCode: number = err.code; 10537 if (errCode) { 10538 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10539 return; 10540 } 10541 windowClass = data; 10542 let SystemBarProperties: window.SystemBarProperties = { 10543 statusBarColor: '#ff00ff', 10544 navigationBarColor: '#00ff00', 10545 // The following properties are supported since API version 8. 10546 statusBarContentColor: '#ffffff', 10547 navigationBarContentColor: '#00ffff' 10548 }; 10549 try { 10550 windowClass.setWindowSystemBarProperties(SystemBarProperties, (err: BusinessError) => { 10551 const errCode: number = err.code; 10552 if (errCode) { 10553 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 10554 return; 10555 } 10556 console.info('Succeeded in setting the system bar properties.'); 10557 }); 10558 } catch (exception) { 10559 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 10560 } 10561 }); 10562 } 10563} 10564``` 10565 10566### setSubWindowZLevel<sup>18+</sup> 10567 10568setSubWindowZLevel(zLevel: number): Promise<void> 10569 10570Sets the z-level of the current child window. Child windows with modal properties are not supported. This API uses a promise to return the result. 10571 10572Changing the z-level of a child window using this API will not cause a focus switch. You are advised to use [shiftAppWindowFocus()](#windowshiftappwindowfocus11) for focus switching. 10573 10574**System capability**: SystemCapability.Window.SessionManager 10575 10576**Atomic service API**: This API can be used in atomic services since API version 18. 10577 10578**Parameters** 10579 10580| Name | Type | Mandatory | Description | 10581| :----- | :----- | :-------- | :----------------------------------------------------------- | 10582| zLevel | number | Yes | Z-level of the child window. The default value is 0, and the value range is [–10000, 10000]. Only integers are supported, and floating-point numbers will be rounded down. | 10583 10584**Return value** 10585 10586| Type | Description | 10587| ------------------- | ------------------------------ | 10588| Promise<void> | Promise that returns no value. | 10589 10590**Error codes** 10591 10592For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10593 10594| ID | Error Message | 10595| ------- | ------------------------------------------------------------ | 10596| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 10597| 801 | Capability not supported. Function setSubWindowZLevel can not work correctly due to limited device capabilities. | 10598| 1300002 | This window state is abnormal. | 10599| 1300003 | This window manager service works abnormally. | 10600| 1300004 | Unauthorized operation. | 10601| 1300009 | The parent window is invalid. | 10602 10603**Example** 10604 10605```ts 10606// EntryAbility.ets 10607import { window } from '@kit.ArkUI'; 10608import { UIAbility } from '@kit.AbilityKit'; 10609import { BusinessError } from '@kit.BasicServicesKit'; 10610 10611export default class EntryAbility extends UIAbility { 10612 // ... 10613 onWindowStageCreate(windowStage: window.WindowStage): void { 10614 console.info('onWindowStageCreate'); 10615 let zLevel: number = 1; 10616 // Create a child window. 10617 try { 10618 windowStage.createSubWindow('testSubWindow').then((subWindow) => { 10619 if (subWindow == null) { 10620 console.error('Failed to create the sub window. Cause: The sub window is null'); 10621 return; 10622 } 10623 subWindow.setSubWindowZLevel(zLevel).then(() => { 10624 console.info('Succeeded in setting sub window zLevel.'); 10625 }).catch((err: BusinessError) => { 10626 console.error(`Failed to set sub window zLevel. Cause code: ${err.code}, message: ${err.message}`); 10627 }); 10628 }); 10629 } catch (err) { 10630 console.error(`Failed to create the sub window or set zLevel. Cause code: ${err.code}, message: ${err.message}`); 10631 } 10632 } 10633} 10634``` 10635 10636### getSubWindowZLevel<sup>18+</sup> 10637 10638getSubWindowZLevel(): number 10639 10640Obtains the z-level of the current child window. This API cannot be called by the main window or system window. 10641 10642**System capability**: SystemCapability.Window.SessionManager 10643 10644**Atomic service API**: This API can be used in atomic services since API version 18. 10645 10646**Return value** 10647 10648| Type | Description | 10649| ------ | ---------------------------- | 10650| number | Z-level of the child window. | 10651 10652**Error codes** 10653 10654For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10655 10656| ID | Error Message | 10657| ------- | ------------------------------------------------------------ | 10658| 801 | Capability not supported. Function getSubWindowZLevel can not work correctly due to limited device capabilities. | 10659| 1300002 | This window state is abnormal. | 10660| 1300004 | Unauthorized operation. | 10661 10662**Example** 10663 10664```ts 10665// EntryAbility.ets 10666import { window } from '@kit.ArkUI'; 10667import { UIAbility } from '@kit.AbilityKit'; 10668 10669export default class EntryAbility extends UIAbility { 10670 // ... 10671 onWindowStageCreate(windowStage: window.WindowStage): void { 10672 console.info('onWindowStageCreate'); 10673 let subWindowZLevel = -1; 10674 // Create a child window. 10675 windowStage.createSubWindow('testSubWindow').then((subWindow) => { 10676 if (subWindow == null) { 10677 console.error('Failed to create the sub window. Cause: The sub window is null'); 10678 return; 10679 } 10680 try { 10681 subWindowZLevel = subWindow.getSubWindowZLevel(); 10682 console.info(`Succeeded in obtaining sub window zLevel: ${subWindowZLevel}`); 10683 } catch (err) { 10684 console.error(`Failed to obtain the sub window zLevel. Cause code: ${err.code}, message: ${err.message}`); 10685 } 10686 }); 10687 } 10688} 10689``` 10690 10691### setWindowSystemBarEnable<sup>(deprecated)</sup> 10692 10693setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 10694 10695<!--RP14-->Sets whether to show the status bar and three-button navigation bar in the main window. The visibility of the status bar and three-button navigation bar is controlled by **status** and **navigation**, respectively.<!--RP14End--> This API uses an asynchronous callback to return the result.<br>From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 10696 10697The return value does not indicate that the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> are shown or hidden. This API does not take effect when it is called by a child window. The configuration does not take effect in non-full-screen mode (such as floating window or split-screen mode). 10698 10699> **NOTE** 10700> 10701> 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. 10702 10703**Atomic service API**: This API can be used in atomic services since API version 12. 10704 10705**System capability**: SystemCapability.WindowManager.WindowManager.Core 10706 10707**Parameters** 10708 10709| Name | Type | Mandatory | Description | 10710| -------- | ----------------------------- | --------- | ------------------------------------------------------------ | 10711| names | Array<'status'\|'navigation'> | Yes | Whether to show the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> in full-screen mode.<br>For example, to show all of them, set this parameter to **['status', 'navigation']**. If this parameter is set to [], they are hidden. | 10712| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10713 10714**Error codes** 10715 10716For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10717 10718| ID | Error Message | 10719| ------- | ------------------------------------------------------------ | 10720| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10721| 1300002 | This window state is abnormal. | 10722| 1300003 | This window manager service works abnormally. | 10723 10724**Example** 10725 10726```ts 10727// The following assumes that all of them are hidden. 10728// EntryAbility.ets 10729import { UIAbility } from '@kit.AbilityKit'; 10730import { BusinessError } from '@kit.BasicServicesKit'; 10731 10732export default class EntryAbility extends UIAbility { 10733 // ... 10734 onWindowStageCreate(windowStage: window.WindowStage): void { 10735 console.info('onWindowStageCreate'); 10736 let windowClass: window.Window | undefined = undefined; 10737 windowStage.getMainWindow((err: BusinessError, data) => { 10738 const errCode: number = err.code; 10739 if (errCode) { 10740 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10741 return; 10742 } 10743 windowClass = data; 10744 let names: Array<'status' | 'navigation'> = []; 10745 try { 10746 windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => { 10747 const errCode: number = err.code; 10748 if (errCode) { 10749 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 10750 return; 10751 } 10752 console.info('Succeeded in setting the system bar to be invisible.'); 10753 }); 10754 } catch (exception) { 10755 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 10756 } 10757 }); 10758 } 10759} 10760``` 10761 10762### setWindowLayoutFullScreen<sup>(deprecated)</sup> 10763 10764setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 10765 10766Sets whether the main window layout or the child window layout is immersive. This API uses an asynchronous callback to return the result. 10767- An immersive layout means that the layout does not avoid the status bar or <!--RP15-->three-button navigation bar<!--RP15End-->, and components may overlap with them. 10768- A non-immersive layout means that the layout avoids the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->, and components do not overlap with them. 10769 10770> **NOTE** 10771> 10772> 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. 10773 10774**System capability**: SystemCapability.WindowManager.WindowManager.Core 10775 10776**Atomic service API**: This API can be used in atomic services since API version 12. 10777 10778**Parameters** 10779 10780| Name | Type | Mandatory | Description | 10781| ------------------ | ------------------------- | --------- | ------------------------------------------------------------ | 10782| isLayoutFullScreen | boolean | Yes | Whether the layout of the window is immersive. (In immersive layout mode, the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> remain visible.) The value **true** means that the window layout is immersive, and **false** means the opposite. | 10783| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10784 10785**Error codes** 10786 10787For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10788 10789| ID | Error Message | 10790| ------- | ------------------------------------------------------------ | 10791| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10792| 1300002 | This window state is abnormal. | 10793| 1300003 | This window manager service works abnormally. | 10794 10795**Example** 10796 10797```ts 10798// EntryAbility.ets 10799import { UIAbility } from '@kit.AbilityKit'; 10800import { BusinessError } from '@kit.BasicServicesKit'; 10801 10802export default class EntryAbility extends UIAbility { 10803 // ... 10804 onWindowStageCreate(windowStage: window.WindowStage): void { 10805 console.info('onWindowStageCreate'); 10806 let windowClass: window.Window | undefined = undefined; 10807 windowStage.getMainWindow((err: BusinessError, data) => { 10808 const errCode: number = err.code; 10809 if (errCode) { 10810 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10811 return; 10812 } 10813 windowClass = data; 10814 let isLayoutFullScreen = true; 10815 try { 10816 windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 10817 const errCode: number = err.code; 10818 if (errCode) { 10819 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 10820 return; 10821 } 10822 console.info('Succeeded in setting the window layout to full-screen mode.'); 10823 }); 10824 } catch (exception) { 10825 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 10826 } 10827 }); 10828 } 10829} 10830``` 10831 10832### show<sup>(deprecated)</sup> 10833 10834show(callback: AsyncCallback<void>): void 10835 10836Shows this window. This API uses an asynchronous callback to return the result. 10837 10838> **NOTE** 10839> 10840> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9) instead. 10841 10842**System capability**: SystemCapability.WindowManager.WindowManager.Core 10843 10844**Parameters** 10845 10846| Name | Type | Mandatory | Description | 10847| -------- | ------------------------- | --------- | ----------------------------------- | 10848| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10849 10850**Example** 10851 10852```ts 10853import { BusinessError } from '@kit.BasicServicesKit'; 10854 10855windowClass.show((err: BusinessError) => { 10856 const errCode: number = err.code; 10857 if (errCode) { 10858 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 10859 return; 10860 } 10861 console.info('Succeeded in showing the window.'); 10862}); 10863``` 10864 10865### show<sup>(deprecated)</sup> 10866 10867show(): Promise<void> 10868 10869Shows this window. This API uses a promise to return the result. 10870 10871> **NOTE** 10872> 10873> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9-1) instead. 10874 10875**System capability**: SystemCapability.WindowManager.WindowManager.Core 10876 10877**Return value** 10878 10879| Type | Description | 10880| ------------------- | ------------------------------ | 10881| Promise<void> | Promise that returns no value. | 10882 10883**Example** 10884 10885```ts 10886import { BusinessError } from '@kit.BasicServicesKit'; 10887 10888let promise = windowClass.show(); 10889promise.then(() => { 10890 console.info('Succeeded in showing the window.'); 10891}).catch((err: BusinessError) => { 10892 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 10893}); 10894``` 10895 10896### destroy<sup>(deprecated)</sup> 10897 10898destroy(callback: AsyncCallback<void>): void 10899 10900Destroys this window. This API uses an asynchronous callback to return the result. 10901 10902> **NOTE** 10903> 10904> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9) instead. 10905 10906**System capability**: SystemCapability.WindowManager.WindowManager.Core 10907 10908**Parameters** 10909 10910| Name | Type | Mandatory | Description | 10911| -------- | ------------------------- | --------- | ----------------------------------- | 10912| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10913 10914**Example** 10915 10916```ts 10917import { BusinessError } from '@kit.BasicServicesKit'; 10918 10919windowClass.destroy((err: BusinessError) => { 10920 const errCode: number = err.code; 10921 if (err.code) { 10922 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 10923 return; 10924 } 10925 console.info('Succeeded in destroying the window.'); 10926}); 10927``` 10928 10929### destroy<sup>(deprecated)</sup> 10930 10931destroy(): Promise<void> 10932 10933Destroys this window. This API uses a promise to return the result. 10934 10935> **NOTE** 10936> 10937> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9-1) instead. 10938 10939**System capability**: SystemCapability.WindowManager.WindowManager.Core 10940 10941**Return value** 10942 10943| Type | Description | 10944| ------------------- | ------------------------------ | 10945| Promise<void> | Promise that returns no value. | 10946 10947**Example** 10948 10949```ts 10950import { BusinessError } from '@kit.BasicServicesKit'; 10951 10952let promise = windowClass.destroy(); 10953promise.then(() => { 10954 console.info('Succeeded in destroying the window.'); 10955}).catch((err: BusinessError) => { 10956 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 10957}); 10958``` 10959 10960### moveTo<sup>(deprecated)</sup> 10961 10962moveTo(x: number, y: number, callback: AsyncCallback<void>): void 10963 10964Moves this window. This API uses an asynchronous callback to return the result. 10965 10966This operation is not supported in a window in full-screen mode. 10967 10968> **NOTE** 10969> 10970> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9) instead. 10971 10972**System capability**: SystemCapability.WindowManager.WindowManager.Core 10973 10974**Parameters** 10975 10976| Name | Type | Mandatory | Description | 10977| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 10978| x | number | Yes | Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 10979| y | number | Yes | Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 10980| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10981 10982**Example** 10983 10984```ts 10985import { BusinessError } from '@kit.BasicServicesKit'; 10986 10987windowClass.moveTo(300, 300, (err: BusinessError) => { 10988 const errCode: number = err.code; 10989 if (errCode) { 10990 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 10991 return; 10992 } 10993 console.info('Succeeded in moving the window.'); 10994}); 10995``` 10996 10997### moveTo<sup>(deprecated)</sup> 10998 10999moveTo(x: number, y: number): Promise<void> 11000 11001Moves this window. This API uses a promise to return the result. 11002 11003This operation is not supported in a window in full-screen mode. 11004 11005> **NOTE** 11006> 11007> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9-1) instead. 11008 11009**System capability**: SystemCapability.WindowManager.WindowManager.Core 11010 11011**Parameters** 11012 11013| Name | Type | Mandatory | Description | 11014| ---- | ------ | --------- | ------------------------------------------------------------ | 11015| x | number | Yes | Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 11016| y | number | Yes | Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 11017 11018**Return value** 11019 11020| Type | Description | 11021| ------------------- | ------------------------------ | 11022| Promise<void> | Promise that returns no value. | 11023 11024**Example** 11025 11026```ts 11027import { BusinessError } from '@kit.BasicServicesKit'; 11028 11029let promise = windowClass.moveTo(300, 300); 11030promise.then(() => { 11031 console.info('Succeeded in moving the window.'); 11032}).catch((err: BusinessError) => { 11033 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 11034}); 11035``` 11036 11037### resetSize<sup>(deprecated)</sup> 11038 11039resetSize(width: number, height: number, callback: AsyncCallback<void>): void 11040 11041Changes the size of this window. This API uses an asynchronous callback to return the result. 11042 11043- The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 11044- The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 11045 11046The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 11047 11048The window width and height you set must meet the limits. The rules are as follows: 11049- 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. 11050- 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. 11051 11052This operation is not supported in a window in full-screen mode. 11053 11054> **NOTE** 11055> 11056> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9) instead. 11057 11058**System capability**: SystemCapability.WindowManager.WindowManager.Core 11059 11060**Parameters** 11061 11062| Name | Type | Mandatory | Description | 11063| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 11064| 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. | 11065| 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. | 11066| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11067 11068**Example** 11069 11070```ts 11071import { BusinessError } from '@kit.BasicServicesKit'; 11072 11073windowClass.resetSize(500, 1000, (err: BusinessError) => { 11074 const errCode: number = err.code; 11075 if (errCode) { 11076 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 11077 return; 11078 } 11079 console.info('Succeeded in changing the window size.'); 11080}); 11081``` 11082 11083### resetSize<sup>(deprecated)</sup> 11084 11085resetSize(width: number, height: number): Promise<void> 11086 11087Changes the size of this window. This API uses a promise to return the result. 11088 11089- The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 11090- The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 11091 11092The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 11093 11094The window width and height you set must meet the limits. The rules are as follows: 11095- 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. 11096- 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. 11097 11098This operation is not supported in a window in full-screen mode. 11099 11100> **NOTE** 11101> 11102> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9-1) instead. 11103 11104**System capability**: SystemCapability.WindowManager.WindowManager.Core 11105 11106**Parameters** 11107 11108| Name | Type | Mandatory | Description | 11109| ------ | ------ | --------- | ------------------------------------------------------------ | 11110| 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. | 11111| 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. | 11112 11113**Return value** 11114 11115| Type | Description | 11116| ------------------- | ------------------------------ | 11117| Promise<void> | Promise that returns no value. | 11118 11119**Example** 11120 11121```ts 11122import { BusinessError } from '@kit.BasicServicesKit'; 11123 11124let promise = windowClass.resetSize(500, 1000); 11125promise.then(() => { 11126 console.info('Succeeded in changing the window size.'); 11127}).catch((err: BusinessError) => { 11128 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 11129}); 11130``` 11131 11132### getProperties<sup>(deprecated)</sup> 11133 11134getProperties(callback: AsyncCallback<WindowProperties>): void 11135 11136Obtains the properties of this window. This API uses an asynchronous callback to return the result. 11137 11138> **NOTE** 11139> 11140> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 11141 11142**System capability**: SystemCapability.WindowManager.WindowManager.Core 11143 11144**Parameters** 11145 11146| Name | Type | Mandatory | Description | 11147| -------- | ---------------------------------------------------------- | --------- | ---------------------------------------------- | 11148| callback | AsyncCallback<[WindowProperties](#windowproperties)> | Yes | Callback used to return the window properties. | 11149 11150**Example** 11151 11152```ts 11153import { BusinessError } from '@kit.BasicServicesKit'; 11154 11155windowClass.getProperties((err: BusinessError, data) => { 11156 const errCode: number = err.code; 11157 if (errCode) { 11158 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 11159 return; 11160 } 11161 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 11162}); 11163``` 11164 11165### getProperties<sup>(deprecated)</sup> 11166 11167getProperties(): Promise<WindowProperties> 11168 11169Obtains the properties of this window. This API uses a promise to return the result. 11170 11171> **NOTE** 11172> 11173> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 11174 11175**System capability**: SystemCapability.WindowManager.WindowManager.Core 11176 11177**Return value** 11178 11179| Type | Description | 11180| ---------------------------------------------------- | --------------------------------------------- | 11181| Promise<[WindowProperties](#windowproperties)> | Promise used to return the window properties. | 11182 11183**Example** 11184 11185```ts 11186import { BusinessError } from '@kit.BasicServicesKit'; 11187 11188let promise = windowClass.getProperties(); 11189promise.then((data) => { 11190 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 11191}).catch((err: BusinessError) => { 11192 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 11193}); 11194``` 11195 11196### getAvoidArea<sup>(deprecated)</sup> 11197 11198getAvoidArea(type: [AvoidAreaType](#avoidareatype7), callback: AsyncCallback<[AvoidArea](#avoidarea7)>): void 11199 11200Obtains 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. 11201 11202> **NOTE** 11203> 11204> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 11205 11206**System capability**: SystemCapability.WindowManager.WindowManager.Core 11207 11208**Parameters** 11209 11210| Name | Type | Mandatory | Description | 11211| -------- | --------------------------------------------- | --------- | --------------------------------- | 11212| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. | 11213| callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 11214 11215**Example** 11216 11217```ts 11218import { BusinessError } from '@kit.BasicServicesKit'; 11219 11220let type = window.AvoidAreaType.TYPE_SYSTEM; 11221windowClass.getAvoidArea(type, (err: BusinessError, data) => { 11222 const errCode: number = err.code; 11223 if (errCode) { 11224 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 11225 return; 11226 } 11227 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 11228}); 11229``` 11230 11231### getAvoidArea<sup>(deprecated)</sup> 11232 11233getAvoidArea(type: [AvoidAreaType](#avoidareatype7)): Promise<[AvoidArea](#avoidarea7)> 11234 11235Obtains 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. 11236 11237> **NOTE** 11238> 11239> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 11240 11241**System capability**: SystemCapability.WindowManager.WindowManager.Core 11242 11243**Parameters** 11244 11245| Name | Type | Mandatory | Description | 11246| ---- | -------------------------------- | --------- | ----------------- | 11247| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. | 11248 11249**Return value** 11250 11251| Type | Description | 11252| --------------------------------------- | -------------------------------- | 11253| Promise<[AvoidArea](#avoidarea7)> | Promise used to return the area. | 11254 11255**Example** 11256 11257```ts 11258import { BusinessError } from '@kit.BasicServicesKit'; 11259 11260let type = window.AvoidAreaType.TYPE_SYSTEM; 11261let promise = windowClass.getAvoidArea(type); 11262promise.then((data) => { 11263 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 11264}).catch((err: BusinessError) => { 11265 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 11266}); 11267``` 11268 11269### setFullScreen<sup>(deprecated)</sup> 11270 11271setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void 11272 11273Sets whether the main window or the child window is in full-screen mode. This API uses an asynchronous callback to return the result. 11274- Full-screen mode means that the layout does not avoid the status bar or <!--RP15-->three-button navigation bar<!--RP15End-->, and components may overlap with them. 11275- Non-full-screen mode means that the layout avoids the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->, and components do not overlap with them. 11276 11277> **NOTE** 11278> 11279> 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. 11280 11281**System capability**: SystemCapability.WindowManager.WindowManager.Core 11282 11283**Parameters** 11284 11285| Name | Type | Mandatory | Description | 11286| ------------ | ------------------------- | --------- | ------------------------------------------------------------ | 11287| isFullScreen | boolean | Yes | Whether to set full-screen mode (full-screen mode affects the display of the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->). The value **true** means to set full-screen mode, and **false** means the opposite. | 11288| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11289 11290**Example** 11291 11292```ts 11293// EntryAbility.ets 11294import { UIAbility } from '@kit.AbilityKit'; 11295import { BusinessError } from '@kit.BasicServicesKit'; 11296 11297export default class EntryAbility extends UIAbility { 11298 // ... 11299 onWindowStageCreate(windowStage: window.WindowStage): void { 11300 console.info('onWindowStageCreate'); 11301 let windowClass: window.Window | undefined = undefined; 11302 windowStage.getMainWindow((err: BusinessError, data) => { 11303 const errCode: number = err.code; 11304 if (errCode) { 11305 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11306 return; 11307 } 11308 windowClass = data; 11309 let isFullScreen: boolean = true; 11310 windowClass.setFullScreen(isFullScreen, (err: BusinessError) => { 11311 const errCode: number = err.code; 11312 if (errCode) { 11313 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 11314 return; 11315 } 11316 console.info('Succeeded in enabling the full-screen mode.'); 11317 }); 11318 }); 11319 } 11320} 11321``` 11322 11323### setFullScreen<sup>(deprecated)</sup> 11324 11325setFullScreen(isFullScreen: boolean): Promise<void> 11326 11327Sets whether the main window or the child window is in full-screen mode. This API uses a promise to return the result. 11328- Full-screen mode means that the layout does not avoid the status bar or <!--RP15-->three-button navigation bar<!--RP15End-->, and components may overlap with them. 11329- Non-full-screen mode means that the layout avoids the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->, and components do not overlap with them. 11330 11331> **NOTE** 11332> 11333> 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. 11334 11335**System capability**: SystemCapability.WindowManager.WindowManager.Core 11336 11337**Parameters** 11338 11339| Name | Type | Mandatory | Description | 11340| ------------ | ------- | --------- | ------------------------------------------------------------ | 11341| isFullScreen | boolean | Yes | Whether to set full-screen mode (full-screen mode affects the display of the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->). The value **true** means to set full-screen mode, and **false** means the opposite. | 11342 11343**Return value** 11344 11345| Type | Description | 11346| ------------------- | ------------------------------ | 11347| Promise<void> | Promise that returns no value. | 11348 11349**Example** 11350 11351```ts 11352// EntryAbility.ets 11353import { UIAbility } from '@kit.AbilityKit'; 11354import { BusinessError } from '@kit.BasicServicesKit'; 11355 11356export default class EntryAbility extends UIAbility { 11357 // ... 11358 onWindowStageCreate(windowStage: window.WindowStage): void { 11359 console.info('onWindowStageCreate'); 11360 let windowClass: window.Window | undefined = undefined; 11361 windowStage.getMainWindow((err: BusinessError, data) => { 11362 const errCode: number = err.code; 11363 if (errCode) { 11364 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11365 return; 11366 } 11367 windowClass = data; 11368 let isFullScreen: boolean = true; 11369 let promise = windowClass.setFullScreen(isFullScreen); 11370 promise.then(() => { 11371 console.info('Succeeded in enabling the full-screen mode.'); 11372 }).catch((err: BusinessError) => { 11373 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 11374 }); 11375 }); 11376 } 11377} 11378``` 11379 11380### setLayoutFullScreen<sup>(deprecated)</sup> 11381 11382setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 11383 11384Sets whether the main window layout or the child window layout is immersive. This API uses an asynchronous callback to return the result. 11385- An immersive layout means that the layout does not avoid the status bar or <!--RP15-->three-button navigation bar<!--RP15End-->, and components may overlap with them. 11386- A non-immersive layout means that the layout avoids the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->, and components do not overlap with them. 11387 11388> **NOTE** 11389> 11390> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9) instead. 11391 11392**System capability**: SystemCapability.WindowManager.WindowManager.Core 11393 11394**Parameters** 11395 11396| Name | Type | Mandatory | Description | 11397| ------------------ | ------------------------- | --------- | ------------------------------------------------------------ | 11398| isLayoutFullScreen | boolean | Yes | Whether the layout of the window is immersive. (Immersive layout mode does not affect the display of the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->.) The value **true** means that the window layout is immersive, and **false** means the opposite. | 11399| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11400 11401**Example** 11402 11403```ts 11404// EntryAbility.ets 11405import { UIAbility } from '@kit.AbilityKit'; 11406import { BusinessError } from '@kit.BasicServicesKit'; 11407 11408export default class EntryAbility extends UIAbility { 11409 // ... 11410 onWindowStageCreate(windowStage: window.WindowStage): void { 11411 console.info('onWindowStageCreate'); 11412 let windowClass: window.Window | undefined = undefined; 11413 windowStage.getMainWindow((err: BusinessError, data) => { 11414 const errCode: number = err.code; 11415 if (errCode) { 11416 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11417 return; 11418 } 11419 windowClass = data; 11420 let isLayoutFullScreen: boolean = true; 11421 windowClass.setLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 11422 const errCode: number = err.code; 11423 if (errCode) { 11424 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 11425 return; 11426 } 11427 console.info('Succeeded in setting the window layout to full-screen mode.'); 11428 }); 11429 }); 11430 } 11431} 11432``` 11433 11434### setLayoutFullScreen<sup>(deprecated)</sup> 11435 11436setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 11437 11438Sets whether the main window layout or the child window layout is immersive. This API uses a promise to return the result. 11439- An immersive layout means that the layout does not avoid the status bar or <!--RP15-->three-button navigation bar<!--RP15End-->, and components may overlap with them. 11440- A non-immersive layout means that the layout avoids the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->, and components do not overlap with them. 11441 11442> **NOTE** 11443> 11444> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9-1) instead. 11445 11446**System capability**: SystemCapability.WindowManager.WindowManager.Core 11447 11448**Parameters** 11449 11450| Name | Type | Mandatory | Description | 11451| ------------------ | ------- | --------- | ------------------------------------------------------------ | 11452| isLayoutFullScreen | boolean | Yes | Whether the layout of the window is immersive. (Immersive layout mode does not affect the display of the status bar and <!--RP15-->three-button navigation bar<!--RP15End-->.) The value **true** means that the window layout is immersive, and **false** means the opposite. | 11453 11454**Return value** 11455 11456| Type | Description | 11457| ------------------- | ------------------------------ | 11458| Promise<void> | Promise that returns no value. | 11459 11460**Example** 11461 11462```ts 11463// EntryAbility.ets 11464import { UIAbility } from '@kit.AbilityKit'; 11465import { BusinessError } from '@kit.BasicServicesKit'; 11466 11467export default class EntryAbility extends UIAbility { 11468 // ... 11469 onWindowStageCreate(windowStage: window.WindowStage): void { 11470 console.info('onWindowStageCreate'); 11471 let windowClass: window.Window | undefined = undefined; 11472 windowStage.getMainWindow((err: BusinessError, data) => { 11473 const errCode: number = err.code; 11474 if (errCode) { 11475 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11476 return; 11477 } 11478 windowClass = data; 11479 let isLayoutFullScreen: boolean = true; 11480 let promise = windowClass.setLayoutFullScreen(isLayoutFullScreen); 11481 promise.then(() => { 11482 console.info('Succeeded in setting the window layout to full-screen mode.'); 11483 }).catch((err: BusinessError) => { 11484 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 11485 }); 11486 }); 11487 } 11488} 11489``` 11490 11491### setSystemBarEnable<sup>(deprecated)</sup> 11492 11493setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 11494 11495<!--RP14-->Sets whether to show the status bar and three-button navigation bar in the main window. The visibility of the status bar and three-button navigation bar is controlled by **status** and **navigation**, respectively.<!--RP14End--> This API uses an asynchronous callback to return the result.<br>From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 11496 11497The return value does not indicate that the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> are shown or hidden. This API does not take effect when it is called by a child window. The configuration does not take effect in non-full-screen mode (such as floating window or split-screen mode). 11498 11499> **NOTE** 11500> 11501> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) instead. 11502 11503**System capability**: SystemCapability.WindowManager.WindowManager.Core 11504 11505**Parameters** 11506 11507| Name | Type | Mandatory | Description | 11508| -------- | ----------------------------- | --------- | ------------------------------------------------------------ | 11509| names | Array<'status'\|'navigation'> | Yes | Whether to show the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> in full-screen mode.<br>For example, to show all of them, set this parameter to **['status', 'navigation']**. If this parameter is set to [], they are hidden. | 11510| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11511 11512 11513**Example** 11514 11515```ts 11516// The following assumes that all of them are hidden. 11517// EntryAbility.ets 11518import { UIAbility } from '@kit.AbilityKit'; 11519import { BusinessError } from '@kit.BasicServicesKit'; 11520 11521export default class EntryAbility extends UIAbility { 11522 // ... 11523 onWindowStageCreate(windowStage: window.WindowStage): void { 11524 console.info('onWindowStageCreate'); 11525 let windowClass: window.Window | undefined = undefined; 11526 windowStage.getMainWindow((err: BusinessError, data) => { 11527 const errCode: number = err.code; 11528 if (errCode) { 11529 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11530 return; 11531 } 11532 windowClass = data; 11533 let names: Array<'status' | 'navigation'> = []; 11534 windowClass.setSystemBarEnable(names, (err: BusinessError) => { 11535 const errCode: number = err.code; 11536 if (errCode) { 11537 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 11538 return; 11539 } 11540 console.info('Succeeded in setting the system bar to be invisible.'); 11541 }); 11542 }); 11543 } 11544} 11545``` 11546 11547### setSystemBarEnable<sup>(deprecated)</sup> 11548 11549setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 11550 11551<!--RP14-->Sets whether to show the status bar and three-button navigation bar in the main window. The visibility of the status bar and three-button navigation bar is controlled by **status** and **navigation**, respectively.<!--RP14End--> This API uses a promise to return the result.<br>From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 11552 11553The return value does not indicate that the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> are shown or hidden. This API does not take effect when it is called by a child window. The configuration does not take effect in non-full-screen mode (such as floating window or split-screen mode). 11554 11555> **NOTE** 11556> 11557> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9-1) instead. 11558 11559**System capability**: SystemCapability.WindowManager.WindowManager.Core 11560 11561**Parameters** 11562 11563| Name | Type | Mandatory | Description | 11564| ----- | ----------------------------- | --------- | ------------------------------------------------------------ | 11565| names | Array<'status'\|'navigation'> | Yes | Whether to show the status bar and <!--RP15-->three-button navigation bar<!--RP15End--> in full-screen mode.<br>For example, to show all of them, set this parameter to **['status', 'navigation']**. If this parameter is set to [], they are hidden. | 11566 11567**Return value** 11568 11569| Type | Description | 11570| ------------------- | ------------------------------ | 11571| Promise<void> | Promise that returns no value. | 11572 11573 11574**Example** 11575 11576```ts 11577// The following assumes that all of them are hidden. 11578// EntryAbility.ets 11579import { UIAbility } from '@kit.AbilityKit'; 11580import { BusinessError } from '@kit.BasicServicesKit'; 11581 11582export default class EntryAbility extends UIAbility { 11583 // ... 11584 onWindowStageCreate(windowStage: window.WindowStage): void { 11585 console.info('onWindowStageCreate'); 11586 let windowClass: window.Window | undefined = undefined; 11587 windowStage.getMainWindow((err: BusinessError, data) => { 11588 const errCode: number = err.code; 11589 if (errCode) { 11590 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11591 return; 11592 } 11593 windowClass = data; 11594 let names: Array<'status' | 'navigation'> = []; 11595 let promise = windowClass.setSystemBarEnable(names); 11596 promise.then(() => { 11597 console.info('Succeeded in setting the system bar to be invisible.'); 11598 }).catch((err: BusinessError) => { 11599 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 11600 }); 11601 }); 11602 } 11603} 11604``` 11605 11606### setSystemBarProperties<sup>(deprecated)</sup> 11607 11608setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 11609 11610Sets the properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar of the main window. This API uses an asynchronous callback to return the result. <!--RP5-->This API does not take effect on 2-in-1 devices.<!--RP5End--> 11611 11612This API does not take effect when it is called by a child window. The configuration does not take effect in non-full-screen mode (such as floating window or split-screen mode). 11613 11614> **NOTE** 11615> 11616> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9) instead. 11617 11618**System capability**: SystemCapability.WindowManager.WindowManager.Core 11619 11620**Parameters** 11621 11622| Name | Type | Mandatory | Description | 11623| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 11624| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar. | 11625| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11626 11627**Example** 11628 11629```ts 11630// EntryAbility.ets 11631import { UIAbility } from '@kit.AbilityKit'; 11632import { BusinessError } from '@kit.BasicServicesKit'; 11633 11634export default class EntryAbility extends UIAbility { 11635 // ... 11636 onWindowStageCreate(windowStage: window.WindowStage): void { 11637 console.info('onWindowStageCreate'); 11638 let windowClass: window.Window | undefined = undefined; 11639 windowStage.getMainWindow((err: BusinessError, data) => { 11640 const errCode: number = err.code; 11641 if (errCode) { 11642 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11643 return; 11644 } 11645 windowClass = data; 11646 let SystemBarProperties: window.SystemBarProperties = { 11647 statusBarColor: '#ff00ff', 11648 navigationBarColor: '#00ff00', 11649 // The following properties are supported since API version 8. 11650 statusBarContentColor: '#ffffff', 11651 navigationBarContentColor: '#00ffff' 11652 }; 11653 windowClass.setSystemBarProperties(SystemBarProperties, (err) => { 11654 const errCode: number = err.code; 11655 if (errCode) { 11656 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 11657 return; 11658 } 11659 console.info('Succeeded in setting the system bar properties.'); 11660 }); 11661 }); 11662 } 11663} 11664``` 11665 11666### setSystemBarProperties<sup>(deprecated)</sup> 11667 11668setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 11669 11670Sets the properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar of the main window. This API uses a promise to return the result. <!--RP5-->This API does not take effect on 2-in-1 devices.<!--RP5End--> 11671 11672This API does not take effect when it is called by a child window. 11673 11674> **NOTE** 11675> 11676> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9-1) instead. 11677 11678**System capability**: SystemCapability.WindowManager.WindowManager.Core 11679 11680**Parameters** 11681 11682| Name | Type | Mandatory | Description | 11683| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 11684| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the <!--Del-->three-button navigation bar and <!--DelEnd-->status bar. | 11685 11686**Return value** 11687 11688| Type | Description | 11689| ------------------- | ------------------------------ | 11690| Promise<void> | Promise that returns no value. | 11691 11692**Example** 11693 11694```ts 11695// EntryAbility.ets 11696import { UIAbility } from '@kit.AbilityKit'; 11697import { BusinessError } from '@kit.BasicServicesKit'; 11698 11699export default class EntryAbility extends UIAbility { 11700 // ... 11701 onWindowStageCreate(windowStage: window.WindowStage): void { 11702 console.info('onWindowStageCreate'); 11703 let windowClass: window.Window | undefined = undefined; 11704 windowStage.getMainWindow((err: BusinessError, data) => { 11705 const errCode: number = err.code; 11706 if (errCode) { 11707 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 11708 return; 11709 } 11710 windowClass = data; 11711 let SystemBarProperties: window.SystemBarProperties = { 11712 statusBarColor: '#ff00ff', 11713 navigationBarColor: '#00ff00', 11714 // The following properties are supported since API version 8. 11715 statusBarContentColor: '#ffffff', 11716 navigationBarContentColor: '#00ffff' 11717 }; 11718 let promise = windowClass.setSystemBarProperties(SystemBarProperties); 11719 promise.then(() => { 11720 console.info('Succeeded in setting the system bar properties.'); 11721 }).catch((err: BusinessError) => { 11722 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 11723 }); 11724 }); 11725 } 11726} 11727``` 11728 11729### loadContent<sup>(deprecated)</sup> 11730 11731loadContent(path: string, callback: AsyncCallback<void>): void 11732 11733Loads content from a page to this window. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 11734 11735> **NOTE** 11736> 11737> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9) instead. 11738 11739**System capability**: SystemCapability.WindowManager.WindowManager.Core 11740 11741**Parameters** 11742 11743| Name | Type | Mandatory | Description | 11744| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 11745| 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. | 11746| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11747 11748**Example** 11749 11750```ts 11751import { BusinessError } from '@kit.BasicServicesKit'; 11752 11753windowClass.loadContent('pages/page2/page3', (err: BusinessError) => { 11754 const errCode: number = err.code; 11755 if (errCode) { 11756 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 11757 return; 11758 } 11759 console.info('Succeeded in loading the content.'); 11760}); 11761``` 11762 11763### loadContent<sup>(deprecated)</sup> 11764 11765loadContent(path: string): Promise<void> 11766 11767Loads content from a page to this window. This API uses a promise to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 11768 11769> **NOTE** 11770> 11771> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9-1) instead. 11772 11773**System capability**: SystemCapability.WindowManager.WindowManager.Core 11774 11775**Parameters** 11776 11777| Name | Type | Mandatory | Description | 11778| ---- | ------ | --------- | ------------------------------------------------------------ | 11779| 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. | 11780 11781**Return value** 11782 11783| Type | Description | 11784| ------------------- | ------------------------------ | 11785| Promise<void> | Promise that returns no value. | 11786 11787**Example** 11788 11789```ts 11790import { BusinessError } from '@kit.BasicServicesKit'; 11791 11792let promise = windowClass.loadContent('pages/page2/page3'); 11793promise.then(() => { 11794 console.info('Succeeded in loading the content.'); 11795}).catch((err: BusinessError) => { 11796 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 11797}); 11798``` 11799 11800### isShowing<sup>(deprecated)</sup> 11801 11802isShowing(callback: AsyncCallback<boolean>): void 11803 11804Checks whether this window is displayed. This API uses an asynchronous callback to return the result. 11805 11806> **NOTE** 11807> 11808> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 11809 11810**System capability**: SystemCapability.WindowManager.WindowManager.Core 11811 11812**Parameters** 11813 11814| Name | Type | Mandatory | Description | 11815| -------- | ---------------------------- | --------- | ------------------------------------------------------------ | 11816| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the window is displayed, and **false** means the opposite. | 11817 11818**Example** 11819 11820```ts 11821import { BusinessError } from '@kit.BasicServicesKit'; 11822 11823windowClass.isShowing((err: BusinessError, data) => { 11824 const errCode: number = err.code; 11825 if (errCode) { 11826 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 11827 return; 11828 } 11829 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 11830}); 11831``` 11832 11833### isShowing<sup>(deprecated)</sup> 11834 11835isShowing(): Promise<boolean> 11836 11837Checks whether this window is displayed. This API uses a promise to return the result. 11838 11839> **NOTE** 11840> 11841> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 11842 11843**System capability**: SystemCapability.WindowManager.WindowManager.Core 11844 11845**Return value** 11846 11847| Type | Description | 11848| ---------------------- | ------------------------------------------------------------ | 11849| Promise<boolean> | Promise used to return the result. The value **true** means that the window is displayed, and **false** means the opposite. | 11850 11851**Example** 11852 11853```ts 11854import { BusinessError } from '@kit.BasicServicesKit'; 11855 11856let promise = windowClass.isShowing(); 11857promise.then((data) => { 11858 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 11859}).catch((err: BusinessError) => { 11860 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 11861}); 11862``` 11863 11864### on('systemAvoidAreaChange')<sup>(deprecated)</sup> 11865 11866on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void 11867 11868Subscribes to the event indicating changes to the area where this window cannot be displayed. 11869 11870> **NOTE** 11871> 11872> This API is supported since API version 7 and deprecated since API version 9. Use [on('avoidAreaChange')](#onavoidareachange9) instead. 11873 11874**System capability**: SystemCapability.WindowManager.WindowManager.Core 11875 11876**Parameters** 11877 11878| Name | Type | Mandatory | Description | 11879| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------ | 11880| 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. | 11881| callback | Callback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 11882 11883 11884**Example** 11885 11886```ts 11887windowClass.on('systemAvoidAreaChange', (data) => { 11888 console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data)); 11889}); 11890``` 11891 11892### off('systemAvoidAreaChange')<sup>(deprecated)</sup> 11893 11894off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void 11895 11896Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 11897 11898> **NOTE** 11899> 11900> This API is supported since API version 7 and deprecated since API version 9. Use [off('avoidAreaChange')](#offavoidareachange9) instead. 11901 11902**System capability**: SystemCapability.WindowManager.WindowManager.Core 11903 11904**Parameters** 11905 11906| Name | Type | Mandatory | Description | 11907| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------ | 11908| 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. | 11909| 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. | 11910 11911**Example** 11912 11913```ts 11914const callback = (avoidArea: window.AvoidArea) => { 11915 // ... 11916} 11917windowClass.on('systemAvoidAreaChange', callback); 11918windowClass.off('systemAvoidAreaChange', callback); 11919// Unregister all the callbacks that have been registered through on(). 11920windowClass.off('systemAvoidAreaChange'); 11921``` 11922 11923### isSupportWideGamut<sup>(deprecated)</sup> 11924 11925isSupportWideGamut(callback: AsyncCallback<boolean>): void 11926 11927Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 11928 11929> **NOTE** 11930> 11931> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9) instead. 11932 11933**System capability**: SystemCapability.WindowManager.WindowManager.Core 11934 11935**Parameters** 11936 11937| Name | Type | Mandatory | Description | 11938| -------- | ---------------------------- | --------- | ------------------------------------------------------------ | 11939| 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. | 11940 11941**Example** 11942 11943```ts 11944import { BusinessError } from '@kit.BasicServicesKit'; 11945 11946windowClass.isSupportWideGamut((err: BusinessError, data) => { 11947 const errCode: number = err.code; 11948 if (errCode) { 11949 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 11950 return; 11951 } 11952 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 11953}); 11954``` 11955 11956### isSupportWideGamut<sup>(deprecated)</sup> 11957 11958isSupportWideGamut(): Promise<boolean> 11959 11960Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 11961 11962> **NOTE** 11963> 11964> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9-1) instead. 11965 11966**System capability**: SystemCapability.WindowManager.WindowManager.Core 11967 11968**Return value** 11969 11970| Type | Description | 11971| ---------------------- | ------------------------------------------------------------ | 11972| 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. | 11973 11974**Example** 11975 11976```ts 11977import { BusinessError } from '@kit.BasicServicesKit'; 11978 11979let promise = windowClass.isSupportWideGamut(); 11980promise.then((data) => { 11981 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 11982}).catch((err: BusinessError) => { 11983 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 11984}); 11985``` 11986 11987### setColorSpace<sup>(deprecated)</sup> 11988 11989setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 11990 11991Sets a color space for this window. This API uses an asynchronous callback to return the result. 11992 11993> **NOTE** 11994> 11995> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9) instead. 11996 11997**System capability**: SystemCapability.WindowManager.WindowManager.Core 11998 11999**Parameters** 12000 12001| Name | Type | Mandatory | Description | 12002| ---------- | -------------------------- | --------- | ----------------------------------- | 12003| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set. | 12004| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12005 12006 12007**Example** 12008 12009```ts 12010import { BusinessError } from '@kit.BasicServicesKit'; 12011 12012windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 12013 const errCode: number = err.code; 12014 if (errCode) { 12015 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 12016 return; 12017 } 12018 console.info('Succeeded in setting window colorspace.'); 12019}); 12020``` 12021 12022### setColorSpace<sup>(deprecated)</sup> 12023 12024setColorSpace(colorSpace:ColorSpace): Promise<void> 12025 12026Sets a color space for this window. This API uses a promise to return the result. 12027 12028> **NOTE** 12029> 12030> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9-1) instead. 12031 12032**System capability**: SystemCapability.WindowManager.WindowManager.Core 12033 12034**Parameters** 12035 12036| Name | Type | Mandatory | Description | 12037| ---------- | -------------------------- | --------- | ------------------- | 12038| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set. | 12039 12040**Return value** 12041 12042| Type | Description | 12043| ------------------- | ------------------------------ | 12044| Promise<void> | Promise that returns no value. | 12045 12046 12047**Example** 12048 12049```ts 12050import { BusinessError } from '@kit.BasicServicesKit'; 12051 12052let promise = windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT); 12053promise.then(() => { 12054 console.info('Succeeded in setting window colorspace.'); 12055}).catch((err: BusinessError) => { 12056 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 12057}); 12058``` 12059 12060### getColorSpace<sup>(deprecated)</sup> 12061 12062getColorSpace(callback: AsyncCallback<ColorSpace>): void 12063 12064Obtains the color space of this window. This API uses an asynchronous callback to return the result. 12065 12066> **NOTE** 12067> 12068> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 12069 12070**System capability**: SystemCapability.WindowManager.WindowManager.Core 12071 12072**Parameters** 12073 12074| Name | Type | Mandatory | Description | 12075| -------- | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 12076| 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. | 12077 12078**Example** 12079 12080```ts 12081import { BusinessError } from '@kit.BasicServicesKit'; 12082 12083windowClass.getColorSpace((err: BusinessError, data) => { 12084 const errCode: number = err.code; 12085 if (errCode) { 12086 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 12087 return; 12088 } 12089 console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data)); 12090}); 12091``` 12092 12093### getColorSpace<sup>(deprecated)</sup> 12094 12095getColorSpace(): Promise<ColorSpace> 12096 12097Obtains the color space of this window. This API uses a promise to return the result. 12098 12099> **NOTE** 12100> 12101> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 12102 12103**System capability**: SystemCapability.WindowManager.WindowManager.Core 12104 12105**Return value** 12106 12107| Type | Description | 12108| ----------------------------------------- | ----------------------------------------------- | 12109| Promise<[ColorSpace](#colorspace8)> | Promise used to return the current color space. | 12110 12111**Example** 12112 12113```ts 12114import { BusinessError } from '@kit.BasicServicesKit'; 12115 12116let promise = windowClass.getColorSpace(); 12117promise.then((data) => { 12118 console.info('Succeeded in getting window color space. Cause:' + JSON.stringify(data)); 12119}).catch((err: BusinessError) => { 12120 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 12121}); 12122``` 12123 12124### setBackgroundColor<sup>(deprecated)</sup> 12125 12126setBackgroundColor(color: string, callback: AsyncCallback<void>): void 12127 12128Sets 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. 12129 12130> **NOTE** 12131> 12132> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 12133 12134**System capability**: SystemCapability.WindowManager.WindowManager.Core 12135 12136**Parameters** 12137 12138| Name | Type | Mandatory | Description | 12139| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 12140| 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'**. | 12141| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12142 12143 12144**Example** 12145 12146```ts 12147import { BusinessError } from '@kit.BasicServicesKit'; 12148 12149let color: string = '#00ff33'; 12150windowClass.setBackgroundColor(color, (err: BusinessError) => { 12151 const errCode: number = err.code; 12152 if (errCode) { 12153 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 12154 return; 12155 } 12156 console.info('Succeeded in setting the background color.'); 12157}); 12158``` 12159 12160### setBackgroundColor<sup>(deprecated)</sup> 12161 12162setBackgroundColor(color: string): Promise<void> 12163 12164Sets 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. 12165 12166> **NOTE** 12167> 12168> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 12169 12170**System capability**: SystemCapability.WindowManager.WindowManager.Core 12171 12172**Parameters** 12173 12174| Name | Type | Mandatory | Description | 12175| ----- | ------ | --------- | ------------------------------------------------------------ | 12176| 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'**. | 12177 12178**Return value** 12179 12180| Type | Description | 12181| ------------------- | ------------------------------ | 12182| Promise<void> | Promise that returns no value. | 12183 12184 12185**Example** 12186 12187```ts 12188import { BusinessError } from '@kit.BasicServicesKit'; 12189 12190let color: string = '#00ff33'; 12191let promise = windowClass.setBackgroundColor(color); 12192promise.then(() => { 12193 console.info('Succeeded in setting the background color.'); 12194}).catch((err: BusinessError) => { 12195 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 12196}); 12197``` 12198 12199### setBrightness<sup>(deprecated)</sup> 12200 12201setBrightness(brightness: number, callback: AsyncCallback<void>): void 12202 12203Sets the screen brightness for this window. This API uses an asynchronous callback to return the result. 12204 12205When 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. 12206 12207> **NOTE** 12208> 12209> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9) instead. 12210 12211**System capability**: SystemCapability.WindowManager.WindowManager.Core 12212 12213**Parameters** 12214 12215| Name | Type | Mandatory | Description | 12216| ---------- | ------------------------- | --------- | ------------------------------------------------------------ | 12217| brightness | number | Yes | Brightness to set. The value is a floating point number in the range [0.0, 1.0] or is set to **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness. | 12218| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12219 12220 12221**Example** 12222 12223```ts 12224import { BusinessError } from '@kit.BasicServicesKit'; 12225 12226let brightness: number = 1; 12227windowClass.setBrightness(brightness, (err: BusinessError) => { 12228 const errCode: number = err.code; 12229 if (errCode) { 12230 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 12231 return; 12232 } 12233 console.info('Succeeded in setting the brightness.'); 12234}); 12235``` 12236 12237### setBrightness<sup>(deprecated)</sup> 12238 12239setBrightness(brightness: number): Promise<void> 12240 12241Sets the screen brightness for this window. This API uses a promise to return the result. 12242 12243When 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. 12244 12245> **NOTE** 12246> 12247> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9-1) instead. 12248 12249**System capability**: SystemCapability.WindowManager.WindowManager.Core 12250 12251**Parameters** 12252 12253| Name | Type | Mandatory | Description | 12254| ---------- | ------ | --------- | ------------------------------------------------------------ | 12255| brightness | number | Yes | Brightness to set. The value is a floating point number in the range [0.0, 1.0] or is set to **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness. | 12256 12257**Return value** 12258 12259| Type | Description | 12260| ------------------- | ------------------------------ | 12261| Promise<void> | Promise that returns no value. | 12262 12263 12264**Example** 12265 12266```ts 12267import { BusinessError } from '@kit.BasicServicesKit'; 12268 12269let brightness: number = 1; 12270let promise = windowClass.setBrightness(brightness); 12271promise.then(() => { 12272 console.info('Succeeded in setting the brightness.'); 12273}).catch((err: BusinessError) => { 12274 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 12275}); 12276``` 12277 12278### setDimBehind<sup>(deprecated)</sup> 12279 12280setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void 12281 12282Sets the dimness of the window that is not on top. This API uses an asynchronous callback to return the result. 12283 12284> **NOTE** 12285> 12286> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 12287 12288**System capability**: SystemCapability.WindowManager.WindowManager.Core 12289 12290**Parameters** 12291 12292| Name | Type | Mandatory | Description | 12293| -------------- | ------------------------- | --------- | ------------------------------------------------------------ | 12294| 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. | 12295| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12296 12297**Example** 12298 12299```ts 12300import { BusinessError } from '@kit.BasicServicesKit'; 12301 12302windowClass.setDimBehind(0.5, (err: BusinessError) => { 12303 const errCode: number = err.code; 12304 if (errCode) { 12305 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 12306 return; 12307 } 12308 console.info('Succeeded in setting the dimness.'); 12309}); 12310``` 12311 12312### setDimBehind<sup>(deprecated)</sup> 12313 12314setDimBehind(dimBehindValue: number): Promise<void> 12315 12316Sets the dimness of the window that is not on top. This API uses a promise to return the result. 12317 12318> **NOTE** 12319> 12320> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 12321 12322**System capability**: SystemCapability.WindowManager.WindowManager.Core 12323 12324**Parameters** 12325 12326| Name | Type | Mandatory | Description | 12327| -------------- | ------ | --------- | ------------------------------------------------------------ | 12328| dimBehindValue | number | Yes | Dimness of the window to set. The value ranges from 0 to 1. The value **1** indicates the dimmest. | 12329 12330**Return value** 12331 12332| Type | Description | 12333| ------------------- | ------------------------------ | 12334| Promise<void> | Promise that returns no value. | 12335 12336**Example** 12337 12338```ts 12339import { BusinessError } from '@kit.BasicServicesKit'; 12340 12341let promise = windowClass.setDimBehind(0.5); 12342promise.then(() => { 12343 console.info('Succeeded in setting the dimness.'); 12344}).catch((err: BusinessError) => { 12345 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 12346}); 12347``` 12348 12349### setFocusable<sup>(deprecated)</sup> 12350 12351setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 12352 12353Sets 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. 12354 12355> **NOTE** 12356> 12357> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9) instead. 12358 12359**System capability**: SystemCapability.WindowManager.WindowManager.Core 12360 12361**Parameters** 12362 12363| Name | Type | Mandatory | Description | 12364| ----------- | ------------------------- | --------- | ------------------------------------------------------------ | 12365| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 12366| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12367 12368 12369**Example** 12370 12371```ts 12372import { BusinessError } from '@kit.BasicServicesKit'; 12373 12374let isFocusable: boolean = true; 12375windowClass.setFocusable(isFocusable, (err: BusinessError) => { 12376 const errCode: number = err.code; 12377 if (errCode) { 12378 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 12379 return; 12380 } 12381 console.info('Succeeded in setting the window to be focusable.'); 12382}); 12383``` 12384 12385### setFocusable<sup>(deprecated)</sup> 12386 12387setFocusable(isFocusable: boolean): Promise<void> 12388 12389Sets 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. 12390 12391> **NOTE** 12392> 12393> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9-1) instead. 12394 12395**System capability**: SystemCapability.WindowManager.WindowManager.Core 12396 12397**Parameters** 12398 12399| Name | Type | Mandatory | Description | 12400| ----------- | ------- | --------- | ------------------------------------------------------------ | 12401| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 12402 12403**Return value** 12404 12405| Type | Description | 12406| ------------------- | ------------------------------ | 12407| Promise<void> | Promise that returns no value. | 12408 12409 12410**Example** 12411 12412```ts 12413import { BusinessError } from '@kit.BasicServicesKit'; 12414 12415let isFocusable: boolean = true; 12416let promise = windowClass.setFocusable(isFocusable); 12417promise.then(() => { 12418 console.info('Succeeded in setting the window to be focusable.'); 12419}).catch((err: BusinessError) => { 12420 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 12421}); 12422``` 12423 12424### setKeepScreenOn<sup>(deprecated)</sup> 12425 12426setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 12427 12428Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 12429 12430> **NOTE** 12431> 12432> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9) instead. 12433 12434**System capability**: SystemCapability.WindowManager.WindowManager.Core 12435 12436**Parameters** 12437 12438| Name | Type | Mandatory | Description | 12439| -------------- | ------------------------- | --------- | ------------------------------------------------------------ | 12440| 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. | 12441| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12442 12443 12444**Example** 12445 12446```ts 12447import { BusinessError } from '@kit.BasicServicesKit'; 12448 12449let isKeepScreenOn: boolean = true; 12450windowClass.setKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 12451 const errCode: number = err.code; 12452 if (errCode) { 12453 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 12454 return; 12455 } 12456 console.info('Succeeded in setting the screen to be always on.'); 12457}); 12458``` 12459 12460### setKeepScreenOn<sup>(deprecated)</sup> 12461 12462setKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 12463 12464Sets whether to keep the screen always on. This API uses a promise to return the result. 12465 12466> **NOTE** 12467> 12468> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9-1) instead. 12469 12470**System capability**: SystemCapability.WindowManager.WindowManager.Core 12471 12472**Parameters** 12473 12474| Name | Type | Mandatory | Description | 12475| -------------- | ------- | --------- | ------------------------------------------------------------ | 12476| 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. | 12477 12478**Return value** 12479 12480| Type | Description | 12481| ------------------- | ------------------------------ | 12482| Promise<void> | Promise that returns no value. | 12483 12484**Example** 12485 12486```ts 12487import { BusinessError } from '@kit.BasicServicesKit'; 12488 12489let isKeepScreenOn: boolean = true; 12490let promise = windowClass.setKeepScreenOn(isKeepScreenOn); 12491promise.then(() => { 12492 console.info('Succeeded in setting the screen to be always on.'); 12493}).catch((err: BusinessError) => { 12494 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 12495}); 12496``` 12497 12498### setOutsideTouchable<sup>(deprecated)</sup> 12499 12500setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): void 12501 12502Sets whether the area outside the child window is touchable. This API uses an asynchronous callback to return the result. 12503 12504> **NOTE** 12505> 12506> This API is supported since API version 7 and deprecated since API version 9. 12507> 12508> Since API version 9, the area outside the child window is touchable by default. This API is no longer supported and no substitute API is provided. 12509 12510**System capability**: SystemCapability.WindowManager.WindowManager.Core 12511 12512**Parameters** 12513 12514| Name | Type | Mandatory | Description | 12515| --------- | ------------------------- | --------- | ------------------------------------------------------------ | 12516| touchable | boolean | Yes | Whether the area outside the child window is touchable. The value **true** means the area outside the child window is touchable, and **false** means the opposite. | 12517| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12518 12519**Example** 12520 12521```ts 12522import { BusinessError } from '@kit.BasicServicesKit'; 12523 12524windowClass.setOutsideTouchable(true, (err: BusinessError) => { 12525 const errCode: number = err.code; 12526 if (errCode) { 12527 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 12528 return; 12529 } 12530 console.info('Succeeded in setting the area to be touchable.'); 12531}); 12532``` 12533 12534### setOutsideTouchable<sup>(deprecated)</sup> 12535 12536setOutsideTouchable(touchable: boolean): Promise<void> 12537 12538Sets whether the area outside the child window is touchable. This API uses a promise to return the result. 12539 12540> **NOTE** 12541> 12542> This API is supported since API version 7 and deprecated since API version 9. 12543> 12544> Since API version 9, the area outside the child window is touchable by default. This API is no longer supported and no substitute API is provided. 12545 12546**System capability**: SystemCapability.WindowManager.WindowManager.Core 12547 12548**Parameters** 12549 12550| Name | Type | Mandatory | Description | 12551| --------- | ------- | --------- | ------------------------------------------------------------ | 12552| touchable | boolean | Yes | Whether the area outside the child window is touchable. The value **true** means the area outside the child window is touchable, and **false** means the opposite. | 12553 12554**Return value** 12555 12556| Type | Description | 12557| ------------------- | ------------------------------ | 12558| Promise<void> | Promise that returns no value. | 12559 12560**Example** 12561 12562```ts 12563import { BusinessError } from '@kit.BasicServicesKit'; 12564 12565let promise = windowClass.setOutsideTouchable(true); 12566promise.then(() => { 12567 console.info('Succeeded in setting the area to be touchable.'); 12568}).catch((err: BusinessError) => { 12569 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 12570}); 12571``` 12572 12573### setPrivacyMode<sup>(deprecated)</sup> 12574 12575setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 12576 12577Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 12578 12579A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 12580 12581> **NOTE** 12582> 12583> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9) instead. 12584 12585**System capability**: SystemCapability.WindowManager.WindowManager.Core 12586 12587**Parameters** 12588 12589| Name | Type | Mandatory | Description | 12590| ------------- | ------------------------- | --------- | ------------------------------------------------------------ | 12591| 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. | 12592| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12593 12594**Example** 12595 12596```ts 12597import { BusinessError } from '@kit.BasicServicesKit'; 12598 12599let isPrivacyMode: boolean = true; 12600windowClass.setPrivacyMode(isPrivacyMode, (err: BusinessError) => { 12601 const errCode: number = err.code; 12602 if (errCode) { 12603 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 12604 return; 12605 } 12606 console.info('Succeeded in setting the window to privacy mode.'); 12607}); 12608``` 12609 12610### setPrivacyMode<sup>(deprecated)</sup> 12611 12612setPrivacyMode(isPrivacyMode: boolean): Promise<void> 12613 12614Sets whether this window is in privacy mode. This API uses a promise to return the result. 12615 12616A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 12617 12618> **NOTE** 12619> 12620> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9-1) instead. 12621 12622**System capability**: SystemCapability.WindowManager.WindowManager.Core 12623 12624**Parameters** 12625 12626| Name | Type | Mandatory | Description | 12627| ------------- | ------- | --------- | ------------------------------------------------------------ | 12628| 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. | 12629 12630**Return value** 12631 12632| Type | Description | 12633| ------------------- | ------------------------------ | 12634| Promise<void> | Promise that returns no value. | 12635 12636**Example** 12637 12638```ts 12639import { BusinessError } from '@kit.BasicServicesKit'; 12640 12641let isPrivacyMode: boolean = true; 12642let promise = windowClass.setPrivacyMode(isPrivacyMode); 12643promise.then(() => { 12644 console.info('Succeeded in setting the window to privacy mode.'); 12645}).catch((err: BusinessError) => { 12646 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 12647}); 12648``` 12649 12650### setTouchable<sup>(deprecated)</sup> 12651 12652setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 12653 12654Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 12655 12656> **NOTE** 12657> 12658> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9) instead. 12659 12660**System capability**: SystemCapability.WindowManager.WindowManager.Core 12661 12662**Parameters** 12663 12664| Name | Type | Mandatory | Description | 12665| ----------- | ------------------------- | --------- | ------------------------------------------------------------ | 12666| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite. | 12667| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 12668 12669 12670**Example** 12671 12672```ts 12673import { BusinessError } from '@kit.BasicServicesKit'; 12674 12675let isTouchable = true; 12676windowClass.setTouchable(isTouchable, (err: BusinessError) => { 12677 const errCode: number = err.code; 12678 if (errCode) { 12679 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 12680 return; 12681 } 12682 console.info('Succeeded in setting the window to be touchable.'); 12683}); 12684``` 12685 12686### setTouchable<sup>(deprecated)</sup> 12687 12688setTouchable(isTouchable: boolean): Promise<void> 12689 12690Sets whether this window is touchable. This API uses a promise to return the result. 12691 12692> **NOTE** 12693> 12694> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9-1) instead. 12695 12696**System capability**: SystemCapability.WindowManager.WindowManager.Core 12697 12698**Parameters** 12699 12700| Name | Type | Mandatory | Description | 12701| ----------- | ------- | --------- | ------------------------------------------------------------ | 12702| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite. | 12703 12704**Return value** 12705 12706| Type | Description | 12707| ------------------- | ------------------------------ | 12708| Promise<void> | Promise that returns no value. | 12709 12710 12711**Example** 12712 12713```ts 12714import { BusinessError } from '@kit.BasicServicesKit'; 12715 12716let isTouchable = true; 12717let promise = windowClass.setTouchable(isTouchable); 12718promise.then(() => { 12719 console.info('Succeeded in setting the window to be touchable.'); 12720}).catch((err: BusinessError) => { 12721 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 12722}); 12723``` 12724 12725## WindowStageEventType<sup>9+</sup> 12726 12727Enumerates the lifecycle states of a window stage. 12728 12729**Model restriction**: This API can be used only in the stage model. 12730 12731**System capability**: SystemCapability.WindowManager.WindowManager.Core 12732 12733**Atomic service API**: This API can be used in atomic services since API version 11. 12734 12735| Name | Value | Description | 12736| --------------------- | ----- | ------------------------------------------------------------ | 12737| 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. | 12738| 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. | 12739| 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. | 12740| 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. | 12741| RESUMED<sup>11+</sup> | 5 | The window stage is interactive in the foreground, for example, when an application is opened and can interact with the user. | 12742| PAUSED<sup>11+</sup> | 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. | 12743 12744## ModalityType<sup>14+</sup> 12745 12746Enumerates the modality types of the child window. 12747 12748**System capability**: SystemCapability.Window.SessionManager 12749 12750**Atomic service API**: This API can be used in atomic services since API version 14. 12751 12752| Name | Value | Description | 12753| -------------------- | ----- | ------------------------------------------------------------ | 12754| WINDOW_MODALITY | 0 | Window-modal. Select this value when you want the parent window not to respond to user interactions. | 12755| 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.<br> This API can be used only on 2-in-1 devices. | 12756 12757## SubWindowOptions<sup>11+</sup> 12758 12759Describes the parameters used for creating a child window. 12760 12761**System capability**: SystemCapability.Window.SessionManager 12762 12763| Name | Type | Read-Only | Optional | Description | 12764| ------------------------------- | ------------------------------- | --------- | -------- | ------------------------------------------------------------ | 12765| title<sup>11+</sup> | string | No | No | Title of the child window. The title display area should not go past the left side of the three-button area of the system. Any part that goes beyond will show as an ellipsis.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 12766| decorEnabled<sup>11+</sup> | boolean | No | No | Whether decorations are displayed in the child window. The value **true** means that decorations are displayed, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 12767| isModal<sup>12+</sup> | boolean | No | Yes | Whether the modal property is enabled for the child window. The value** true** means that the modal property is enabled for the child window, and **false** means to disable it. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 12768| modalityType<sup>14+</sup> | [ModalityType](#modalitytype14) | No | Yes | Modality type of the child window. This parameter takes effect only when the modal property is enabled for the child window. **WINDOW_MODALITY** means window-modal, and **APPLICATION_MODALITY** means application-modal. The default value is **WINDOW_MODALITY**.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 12769| windowRect<sup>18+</sup> | [Rect](#rect7) | No | Yes | Rectangle of the child window, and the size of the child window is limited. For details, see [resize()](#resize9). If this parameter is not specified, the window is displayed in full screen by default.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 12770| zLevel<sup>18+</sup> | number | No | Yes | Z-level of the child window. This parameter is valid only when the modal property is not enabled for the child window, that is, **isModal** is not set. The value is an integer in the range [-10000, 10000]. Floating-point numbers will be rounded down. The default value is **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 18. | 12771| maximizeSupported<sup>19+</sup> | boolean | No | Yes | Whether the child window supports maximization. <!--RP6-->This API can be used only on 2-in-1 devices. <!--RP6End-->The value **true** means that the child window supports maximization, and **false** means the opposite. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 19. | 12772| outlineEnabled<sup>20+</sup> | boolean | No | Yes | Whether the child window displays an outline. <!--RP6-->This API can be used only on 2-in-1 devices. <!--RP6End-->The value **true** means that the child window displays an outline, and **false** means the opposite. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 20. | 12773 12774## WindowStage<sup>9+</sup> 12775 12776Implements a window manager, which manages each basic window unit, that is, [Window](#window) instance. 12777 12778Before calling any of the following APIs, you must use [onWindowStageCreate()](../apis-ability-kit/js-apis-app-ability-uiAbility.md#onwindowstagecreate) to create a **WindowStage** instance. 12779 12780### getMainWindow<sup>9+</sup> 12781 12782getMainWindow(callback: AsyncCallback<Window>): void 12783 12784Obtains the main window of this window stage. This API uses an asynchronous callback to return the result. 12785 12786**Model restriction**: This API can be used only in the stage model. 12787 12788**System capability**: SystemCapability.WindowManager.WindowManager.Core 12789 12790**Atomic service API**: This API can be used in atomic services since API version 11. 12791 12792**Parameters** 12793 12794| Name | Type | Mandatory | Description | 12795| -------- | -------------------------------------- | --------- | ---------------------------------------- | 12796| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window. | 12797 12798**Error codes** 12799 12800For details about the error codes, see [Window Error Codes](errorcode-window.md). 12801 12802| ID | Error Message | 12803| ------- | ------------------------------ | 12804| 1300002 | This window state is abnormal. | 12805| 1300005 | This window stage is abnormal. | 12806 12807**Example** 12808 12809```ts 12810// EntryAbility.ets 12811import { UIAbility } from '@kit.AbilityKit'; 12812import { BusinessError } from '@kit.BasicServicesKit'; 12813 12814export default class EntryAbility extends UIAbility { 12815 // ... 12816 12817 onWindowStageCreate(windowStage: window.WindowStage) { 12818 console.info('onWindowStageCreate'); 12819 let windowClass: window.Window | undefined = undefined; 12820 windowStage.getMainWindow((err: BusinessError, data) => { 12821 const errCode: number = err.code; 12822 if (errCode) { 12823 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 12824 return; 12825 } 12826 windowClass = data; 12827 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 12828 }); 12829 } 12830}; 12831``` 12832 12833### getMainWindow<sup>9+</sup> 12834 12835getMainWindow(): Promise<Window> 12836 12837Obtains the main window of this window stage. This API uses a promise to return the result. 12838 12839**Model restriction**: This API can be used only in the stage model. 12840 12841**System capability**: SystemCapability.WindowManager.WindowManager.Core 12842 12843**Atomic service API**: This API can be used in atomic services since API version 11. 12844 12845**Return value** 12846 12847| Type | Description | 12848| -------------------------------- | --------------------------------------- | 12849| Promise<[Window](#window)> | Promise used to return the main window. | 12850 12851**Error codes** 12852 12853For details about the error codes, see [Window Error Codes](errorcode-window.md). 12854 12855| ID | Error Message | 12856| ------- | ------------------------------ | 12857| 1300002 | This window state is abnormal. | 12858| 1300005 | This window stage is abnormal. | 12859 12860**Example** 12861 12862```ts 12863// EntryAbility.ets 12864import { UIAbility } from '@kit.AbilityKit'; 12865import { BusinessError } from '@kit.BasicServicesKit'; 12866 12867export default class EntryAbility extends UIAbility { 12868 // ... 12869 12870 onWindowStageCreate(windowStage: window.WindowStage) { 12871 console.info('onWindowStageCreate'); 12872 let windowClass: window.Window | undefined = undefined; 12873 let promise = windowStage.getMainWindow(); 12874 promise.then((data) => { 12875 windowClass = data; 12876 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 12877 }).catch((err: BusinessError) => { 12878 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 12879 }); 12880 } 12881}; 12882``` 12883 12884### getMainWindowSync<sup>9+</sup> 12885 12886getMainWindowSync(): Window 12887 12888Obtains the main window of this window stage. 12889 12890**Model restriction**: This API can be used only in the stage model. 12891 12892**System capability**: SystemCapability.WindowManager.WindowManager.Core 12893 12894**Atomic service API**: This API can be used in atomic services since API version 11. 12895 12896**Return value** 12897 12898| Type | Description | 12899| ----------------- | ------------ | 12900| [Window](#window) | Main window. | 12901 12902**Error codes** 12903 12904For details about the error codes, see [Window Error Codes](errorcode-window.md). 12905 12906| ID | Error Message | 12907| ------- | ------------------------------ | 12908| 1300002 | This window state is abnormal. | 12909| 1300005 | This window stage is abnormal. | 12910 12911**Example** 12912<!--code_no_check--> 12913```ts 12914// EntryAbility.ets 12915import { UIAbility } from '@kit.AbilityKit'; 12916 12917export default class EntryAbility extends UIAbility { 12918 // ... 12919 12920 onWindowStageCreate(windowStage: window.WindowStage) { 12921 console.info('onWindowStageCreate'); 12922 try { 12923 let windowClass = windowStage.getMainWindowSync(); 12924 } catch (exception) { 12925 console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`); 12926 } 12927 } 12928}; 12929``` 12930 12931### createSubWindow<sup>9+</sup> 12932 12933createSubWindow(name: string, callback: AsyncCallback<Window>): void 12934 12935Creates a child window for this window stage. This API uses an asynchronous callback to return the result. 12936 12937**Model restriction**: This API can be used only in the stage model. 12938 12939**System capability**: SystemCapability.WindowManager.WindowManager.Core 12940 12941**Atomic service API**: This API can be used in atomic services since API version 11. 12942 12943**Parameters** 12944 12945| Name | Type | Mandatory | Description | 12946| -------- | -------------------------------------- | --------- | ----------------------------------------- | 12947| name | string | Yes | Name of the child window. | 12948| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the child window. | 12949 12950**Error codes** 12951 12952For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 12953 12954| ID | Error Message | 12955| ------- | ----------------------------------------------------------- | 12956| 401 | Parameter error. Possible cause: Incorrect parameter types. | 12957| 1300002 | This window state is abnormal. | 12958 12959**Example** 12960 12961```ts 12962// EntryAbility.ets 12963import { UIAbility } from '@kit.AbilityKit'; 12964import { BusinessError } from '@kit.BasicServicesKit'; 12965 12966export default class EntryAbility extends UIAbility { 12967 // ... 12968 12969 onWindowStageCreate(windowStage: window.WindowStage) { 12970 console.info('onWindowStageCreate'); 12971 let windowClass: window.Window | undefined = undefined; 12972 try { 12973 windowStage.createSubWindow('mySubWindow', (err: BusinessError, data) => { 12974 const errCode: number = err.code; 12975 if (errCode) { 12976 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 12977 return; 12978 } 12979 windowClass = data; 12980 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 12981 if (!windowClass) { 12982 console.info('Failed to load the content. Cause: windowClass is null'); 12983 } 12984 else { 12985 (windowClass as window.Window).resize(500, 1000); 12986 } 12987 }); 12988 } catch (exception) { 12989 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 12990 } 12991 } 12992}; 12993``` 12994 12995### createSubWindow<sup>9+</sup> 12996 12997createSubWindow(name: string): Promise<Window> 12998 12999Creates a child window for this window stage. This API uses a promise to return the result. 13000 13001**Model restriction**: This API can be used only in the stage model. 13002 13003**System capability**: SystemCapability.WindowManager.WindowManager.Core 13004 13005**Atomic service API**: This API can be used in atomic services since API version 11. 13006 13007**Parameters** 13008 13009| Name | Type | Mandatory | Description | 13010| ---- | ------ | --------- | ------------------------- | 13011| name | string | Yes | Name of the child window. | 13012 13013**Return value** 13014 13015| Type | Description | 13016| -------------------------------- | ---------------------------------------- | 13017| Promise<[Window](#window)> | Promise used to return the child window. | 13018 13019**Error codes** 13020 13021For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13022 13023| ID | Error Message | 13024| ------- | ----------------------------------------------------------- | 13025| 401 | Parameter error. Possible cause: Incorrect parameter types. | 13026| 1300002 | This window state is abnormal. | 13027 13028**Example** 13029 13030```ts 13031// EntryAbility.ets 13032import { UIAbility } from '@kit.AbilityKit'; 13033import { BusinessError } from '@kit.BasicServicesKit'; 13034 13035export default class EntryAbility extends UIAbility { 13036 // ... 13037 13038 onWindowStageCreate(windowStage: window.WindowStage) { 13039 console.info('onWindowStageCreate'); 13040 let windowClass: window.Window | undefined = undefined; 13041 try { 13042 let promise = windowStage.createSubWindow('mySubWindow'); 13043 promise.then((data) => { 13044 windowClass = data; 13045 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 13046 }).catch((err: BusinessError) => { 13047 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 13048 }); 13049 } catch (exception) { 13050 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 13051 } 13052 } 13053}; 13054``` 13055 13056### createSubWindowWithOptions<sup>11+</sup> 13057 13058createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 13059 13060Creates a child window for this window stage. This API uses a promise to return the result. 13061 13062**Model restriction**: This API can be used only in the stage model. 13063 13064**Atomic service API**: This API can be used in atomic services since API version 12. 13065 13066**System capability**: SystemCapability.Window.SessionManager 13067 13068**Parameters** 13069 13070| Name | Type | Mandatory | Description | 13071| ------- | --------------------------------------- | --------- | ---------------------------------------------- | 13072| name | string | Yes | Name of the child window. | 13073| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the child window. | 13074 13075**Return value** 13076 13077| Type | Description | 13078| -------------------------------- | ------------------------------------------------ | 13079| Promise<[Window](#window)> | Promise used to return the child window created. | 13080 13081**Error codes** 13082 13083For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13084 13085| ID | Error Message | 13086| ------- | ------------------------------------------------------------ | 13087| 401 | Parameter error. Possible cause: Incorrect parameter types. | 13088| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 13089| 1300002 | This window state is abnormal. | 13090| 1300005 | This window stage is abnormal. | 13091 13092**Example** 13093 13094```ts 13095// EntryAbility.ets 13096import { UIAbility } from '@kit.AbilityKit'; 13097import { BusinessError } from '@kit.BasicServicesKit'; 13098 13099export default class EntryAbility extends UIAbility { 13100 // ... 13101 13102 onWindowStageCreate(windowStage: window.WindowStage) { 13103 console.info('onWindowStageCreate'); 13104 let windowClass: window.Window | undefined = undefined; 13105 try { 13106 let options : window.SubWindowOptions = { 13107 title: 'title', 13108 decorEnabled: true 13109 }; 13110 let promise = windowStage.createSubWindowWithOptions('mySubWindow', options); 13111 promise.then((data) => { 13112 windowClass = data; 13113 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 13114 }).catch((err: BusinessError) => { 13115 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 13116 }); 13117 } catch (exception) { 13118 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 13119 } 13120 } 13121}; 13122``` 13123 13124### getSubWindow<sup>9+</sup> 13125 13126getSubWindow(callback: AsyncCallback<Array<Window>>): void 13127 13128Obtains all the child windows of this window stage. This API uses an asynchronous callback to return the result. 13129 13130**Model restriction**: This API can be used only in the stage model. 13131 13132**System capability**: SystemCapability.WindowManager.WindowManager.Core 13133 13134**Atomic service API**: This API can be used in atomic services since API version 11. 13135 13136**Parameters** 13137 13138| Name | Type | Mandatory | Description | 13139| -------- | --------------------------------------------------- | --------- | ---------------------------------------------- | 13140| callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the child windows. | 13141 13142**Error codes** 13143 13144For details about the error codes, see [Window Error Codes](errorcode-window.md). 13145 13146| ID | Error Message | 13147| ------- | ------------------------------ | 13148| 1300002 | This window state is abnormal. | 13149 13150**Example** 13151<!--code_no_check--> 13152```ts 13153// EntryAbility.ets 13154import { UIAbility } from '@kit.AbilityKit'; 13155import { BusinessError } from '@kit.BasicServicesKit'; 13156 13157export default class EntryAbility extends UIAbility { 13158 // ... 13159 13160 onWindowStageCreate(windowStage: window.WindowStage) { 13161 console.info('onWindowStageCreate'); 13162 let windowClass: window.Window[] = []; 13163 windowStage.getSubWindow((err: BusinessError, data) => { 13164 const errCode: number = err.code; 13165 if (errCode) { 13166 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 13167 return; 13168 } 13169 windowClass = data; 13170 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 13171 }); 13172 } 13173}; 13174``` 13175 13176### getSubWindow<sup>9+</sup> 13177 13178getSubWindow(): Promise<Array<Window>> 13179 13180Obtains all the child windows of this window stage. This API uses a promise to return the result. 13181 13182**Model restriction**: This API can be used only in the stage model. 13183 13184**System capability**: SystemCapability.WindowManager.WindowManager.Core 13185 13186**Atomic service API**: This API can be used in atomic services since API version 11. 13187 13188**Return value** 13189 13190| Type | Description | 13191| --------------------------------------------- | --------------------------------------------- | 13192| Promise<Array<[Window](#window)>> | Promise used to return all the child windows. | 13193 13194**Error codes** 13195 13196For details about the error codes, see [Window Error Codes](errorcode-window.md). 13197 13198| ID | Error Message | 13199| ------- | ------------------------------ | 13200| 1300002 | This window state is abnormal. | 13201 13202**Example** 13203<!--code_no_check--> 13204```ts 13205// EntryAbility.ets 13206import { UIAbility } from '@kit.AbilityKit'; 13207import { BusinessError } from '@kit.BasicServicesKit'; 13208 13209export default class EntryAbility extends UIAbility { 13210 // ... 13211 13212 onWindowStageCreate(windowStage: window.WindowStage) { 13213 console.info('onWindowStageCreate'); 13214 let windowClass: window.Window[] = []; 13215 let promise = windowStage.getSubWindow(); 13216 promise.then((data) => { 13217 windowClass = data; 13218 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 13219 }).catch((err: BusinessError) => { 13220 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 13221 }); 13222 } 13223}; 13224``` 13225 13226### loadContent<sup>9+</sup> 13227 13228loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 13229 13230Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 13231 13232**Model restriction**: This API can be used only in the stage model. 13233 13234**System capability**: SystemCapability.WindowManager.WindowManager.Core 13235 13236**Atomic service API**: This API can be used in atomic services since API version 11. 13237 13238**Parameters** 13239 13240| Name | Type | Mandatory | Description | 13241| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 13242| 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. | 13243| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page. | 13244| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 13245 13246**Error codes** 13247 13248For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13249 13250| ID | Error Message | 13251| ------- | ------------------------------------------------------------ | 13252| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter. | 13253| 1300002 | This window state is abnormal. | 13254 13255**Example** 13256 13257```ts 13258// EntryAbility.ets 13259import { UIAbility } from '@kit.AbilityKit'; 13260import { BusinessError } from '@kit.BasicServicesKit'; 13261 13262export default class EntryAbility extends UIAbility { 13263 // ... 13264 13265 storage: LocalStorage = new LocalStorage(); 13266 13267 onWindowStageCreate(windowStage: window.WindowStage) { 13268 this.storage.setOrCreate('storageSimpleProp', 121); 13269 console.info('onWindowStageCreate'); 13270 try { 13271 windowStage.loadContent('pages/page2', this.storage, (err: BusinessError) => { 13272 const errCode: number = err.code; 13273 if (errCode) { 13274 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 13275 return; 13276 } 13277 console.info('Succeeded in loading the content.'); 13278 }); 13279 } catch (exception) { 13280 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 13281 } 13282 } 13283}; 13284``` 13285 13286### loadContent<sup>9+</sup> 13287 13288loadContent(path: string, storage?: LocalStorage): Promise<void> 13289 13290Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 13291 13292**Model restriction**: This API can be used only in the stage model. 13293 13294**System capability**: SystemCapability.WindowManager.WindowManager.Core 13295 13296**Atomic service API**: This API can be used in atomic services since API version 11. 13297 13298**Parameters** 13299 13300| Name | Type | Mandatory | Description | 13301| ------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 13302| 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. | 13303| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page. | 13304 13305**Return value** 13306 13307| Type | Description | 13308| ------------------- | ------------------------------ | 13309| Promise<void> | Promise that returns no value. | 13310 13311**Error codes** 13312 13313For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13314 13315| ID | Error Message | 13316| ------- | ------------------------------------------------------------ | 13317| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter. | 13318| 1300002 | This window state is abnormal. | 13319 13320**Example** 13321 13322```ts 13323// EntryAbility.ets 13324import { UIAbility } from '@kit.AbilityKit'; 13325import { BusinessError } from '@kit.BasicServicesKit'; 13326 13327export default class EntryAbility extends UIAbility { 13328 // ... 13329 13330 storage: LocalStorage = new LocalStorage(); 13331 13332 onWindowStageCreate(windowStage: window.WindowStage) { 13333 this.storage.setOrCreate('storageSimpleProp', 121); 13334 console.info('onWindowStageCreate'); 13335 try { 13336 let promise = windowStage.loadContent('pages/page2', this.storage); 13337 promise.then(() => { 13338 console.info('Succeeded in loading the content.'); 13339 }).catch((err: BusinessError) => { 13340 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 13341 }); 13342 } catch (exception) { 13343 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 13344 } 13345 ; 13346 } 13347}; 13348``` 13349 13350### loadContent<sup>9+</sup> 13351 13352loadContent(path: string, callback: AsyncCallback<void>): void 13353 13354Loads the content of a page, with its path in the current project specified, to the main window of this window stage. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 13355 13356**Model restriction**: This API can be used only in the stage model. 13357 13358**System capability**: SystemCapability.WindowManager.WindowManager.Core 13359 13360**Atomic service API**: This API can be used in atomic services since API version 11. 13361 13362**Parameters** 13363 13364| Name | Type | Mandatory | Description | 13365| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 13366| 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. | 13367| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 13368 13369**Error codes** 13370 13371For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13372 13373| ID | Error Message | 13374| ------- | ------------------------------------------------------------ | 13375| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter. | 13376| 1300002 | This window state is abnormal. | 13377 13378**Example** 13379 13380```ts 13381// EntryAbility.ets 13382import { UIAbility } from '@kit.AbilityKit'; 13383import { BusinessError } from '@kit.BasicServicesKit'; 13384 13385export default class EntryAbility extends UIAbility { 13386 // ... 13387 13388 onWindowStageCreate(windowStage: window.WindowStage) { 13389 console.info('onWindowStageCreate'); 13390 try { 13391 windowStage.loadContent('pages/page2', (err: BusinessError) => { 13392 const errCode: number = err.code; 13393 if (errCode) { 13394 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 13395 return; 13396 } 13397 console.info('Succeeded in loading the content.'); 13398 }); 13399 } catch (exception) { 13400 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 13401 } 13402 } 13403}; 13404``` 13405 13406### loadContentByName<sup>11+</sup> 13407 13408loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 13409 13410Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 13411 13412**Model restriction**: This API can be used only in the stage model. 13413 13414**System capability**: SystemCapability.WindowManager.WindowManager.Core 13415 13416**Atomic service API**: This API can be used in atomic services since API version 11. 13417 13418**Parameters** 13419 13420| Name | Type | Mandatory | Description | 13421| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 13422| name | string | Yes | Name of the named route page. | 13423| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page. | 13424| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 13425 13426**Error codes** 13427 13428For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13429 13430| ID | Error Message | 13431| ------- | ------------------------------------------------------------ | 13432| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 13433| 1300002 | This window state is abnormal. | 13434 13435**Example** 13436 13437<!--code_no_check--> 13438```ts 13439// EntryAbility.ets 13440import { UIAbility } from '@kit.AbilityKit'; 13441import { BusinessError } from '@kit.BasicServicesKit'; 13442import * as Index from '../pages/Index'; // Import the named route page. 13443 13444export default class EntryAbility extends UIAbility { 13445 // ... 13446 13447 storage: LocalStorage = new LocalStorage(); 13448 13449 onWindowStageCreate(windowStage: window.WindowStage) { 13450 console.info('onWindowStageCreate'); 13451 this.storage.setOrCreate('storageSimpleProp', 121); 13452 try { 13453 windowStage.loadContentByName(Index.entryName, this.storage, (err: BusinessError) => { 13454 const errCode: number = err.code; 13455 if (errCode) { 13456 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 13457 return; 13458 } 13459 console.info('Succeeded in loading the content.'); 13460 }); 13461 } catch (exception) { 13462 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 13463 } 13464 } 13465}; 13466``` 13467<!--code_no_check--> 13468```ts 13469// ets/pages/Index.ets 13470export const entryName : string = 'Index'; 13471@Entry({routeName: entryName, useSharedStorage: true}) 13472@Component 13473export struct Index { 13474 @State message: string = 'Hello World' 13475 @LocalStorageLink('storageSimpleProp') storageSimpleProp: number = 1; 13476 build() { 13477 Row() { 13478 Column() { 13479 Text(this.message) 13480 .fontSize(50) 13481 .fontWeight(FontWeight.Bold) 13482 } 13483 .width('100%') 13484 } 13485 .height('100%') 13486 } 13487} 13488``` 13489 13490### loadContentByName<sup>11+</sup> 13491 13492loadContentByName(name: string, callback: AsyncCallback<void>): void 13493 13494Loads 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. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 13495 13496**Model restriction**: This API can be used only in the stage model. 13497 13498**System capability**: SystemCapability.WindowManager.WindowManager.Core 13499 13500**Atomic service API**: This API can be used in atomic services since API version 11. 13501 13502**Parameters** 13503 13504| Name | Type | Mandatory | Description | 13505| -------- | ------------------------- | --------- | ----------------------------------- | 13506| name | string | Yes | Name of the named route page. | 13507| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 13508 13509**Error codes** 13510 13511For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13512 13513| ID | Error Message | 13514| ------- | ------------------------------------------------------------ | 13515| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 13516| 1300002 | This window state is abnormal. | 13517 13518**Example** 13519 13520<!--code_no_check--> 13521```ts 13522// EntryAbility.ets 13523import { UIAbility } from '@kit.AbilityKit'; 13524import { BusinessError } from '@kit.BasicServicesKit'; 13525import * as Index from '../pages/Index'; // Import the named route page. 13526 13527export default class EntryAbility extends UIAbility { 13528 // ... 13529 13530 onWindowStageCreate(windowStage: window.WindowStage) { 13531 console.info('onWindowStageCreate'); 13532 try { 13533 windowStage.loadContentByName(Index.entryName, (err: BusinessError) => { 13534 const errCode: number = err.code; 13535 if (errCode) { 13536 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 13537 return; 13538 } 13539 console.info('Succeeded in loading the content.'); 13540 }); 13541 } catch (exception) { 13542 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 13543 } 13544 } 13545}; 13546``` 13547<!--code_no_check--> 13548```ts 13549// ets/pages/Index.ets 13550export const entryName : string = 'Index'; 13551@Entry({routeName: entryName}) 13552@Component 13553export struct Index { 13554 @State message: string = 'Hello World' 13555 build() { 13556 Row() { 13557 Column() { 13558 Text(this.message) 13559 .fontSize(50) 13560 .fontWeight(FontWeight.Bold) 13561 } 13562 .width('100%') 13563 } 13564 .height('100%') 13565 } 13566} 13567``` 13568 13569### loadContentByName<sup>11+</sup> 13570 13571loadContentByName(name: string, storage?: LocalStorage): Promise<void>; 13572 13573Loads 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 a promise to return the result. You are advised to call this API during UIAbility startup. If called repeatedly, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 13574 13575**Model restriction**: This API can be used only in the stage model. 13576 13577**System capability**: SystemCapability.WindowManager.WindowManager.Core 13578 13579**Atomic service API**: This API can be used in atomic services since API version 11. 13580 13581**Parameters** 13582 13583| Name | Type | Mandatory | Description | 13584| ------- | ------------ | --------- | ------------------------------------------------------------ | 13585| name | string | Yes | Name of the named route page. | 13586| storage | LocalStorage | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page. | 13587 13588**Error codes** 13589 13590For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13591 13592| ID | Error Message | 13593| ------- | ------------------------------------------------------------ | 13594| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 13595| 1300002 | This window state is abnormal. | 13596 13597**Example** 13598 13599<!--code_no_check--> 13600```ts 13601// EntryAbility.ets 13602import { UIAbility } from '@kit.AbilityKit'; 13603import { BusinessError } from '@kit.BasicServicesKit'; 13604import * as Index from '../pages/Index'; // Import the named route page. 13605 13606export default class EntryAbility extends UIAbility { 13607 // ... 13608 13609 storage: LocalStorage = new LocalStorage(); 13610 13611 onWindowStageCreate(windowStage: window.WindowStage) { 13612 console.info('onWindowStageCreate'); 13613 this.storage.setOrCreate('storageSimpleProp', 121); 13614 try { 13615 let promise = windowStage.loadContentByName(Index.entryName, this.storage); 13616 promise.then(() => { 13617 console.info('Succeeded in loading the content.'); 13618 }).catch((err: BusinessError) => { 13619 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 13620 }); 13621 } catch (exception) { 13622 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 13623 } 13624 } 13625}; 13626``` 13627<!--code_no_check--> 13628```ts 13629// ets/pages/Index.ets 13630export const entryName : string = 'Index'; 13631@Entry({routeName: entryName, useSharedStorage: true}) 13632@Component 13633export struct Index { 13634 @State message: string = 'Hello World' 13635 @LocalStorageLink('storageSimpleProp') storageSimpleProp: number = 1; 13636 build() { 13637 Row() { 13638 Column() { 13639 Text(this.message) 13640 .fontSize(50) 13641 .fontWeight(FontWeight.Bold) 13642 } 13643 .width('100%') 13644 } 13645 .height('100%') 13646 } 13647} 13648``` 13649 13650### on('windowStageEvent')<sup>9+</sup> 13651 13652on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void 13653 13654Subscribes to the window stage lifecycle change event. 13655 13656**Model restriction**: This API can be used only in the stage model. 13657 13658**System capability**: SystemCapability.WindowManager.WindowManager.Core 13659 13660**Atomic service API**: This API can be used in atomic services since API version 11. 13661 13662**Parameters** 13663 13664| Name | Type | Mandatory | Description | 13665| --------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 13666| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. | 13667| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the window stage lifecycle state. | 13668 13669**Error codes** 13670 13671For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13672 13673| ID | Error Message | 13674| ------- | ------------------------------------------------------------ | 13675| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 13676| 1300002 | This window state is abnormal. | 13677| 1300005 | This window stage is abnormal. | 13678 13679**Example** 13680 13681```ts 13682// EntryAbility.ets 13683import { UIAbility } from '@kit.AbilityKit'; 13684 13685export default class EntryAbility extends UIAbility { 13686 // ... 13687 13688 onWindowStageCreate(windowStage: window.WindowStage) { 13689 console.info('onWindowStageCreate'); 13690 try { 13691 windowStage.on('windowStageEvent', (data) => { 13692 console.info('Succeeded in enabling the listener for window stage event changes. Data: ' + 13693 JSON.stringify(data)); 13694 }); 13695 } catch (exception) { 13696 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 13697 } 13698 } 13699}; 13700``` 13701 13702### off('windowStageEvent')<sup>9+</sup> 13703 13704off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType>): void 13705 13706Unsubscribes from the window stage lifecycle change event. 13707 13708**Model restriction**: This API can be used only in the stage model. 13709 13710**System capability**: SystemCapability.WindowManager.WindowManager.Core 13711 13712**Atomic service API**: This API can be used in atomic services since API version 11. 13713 13714**Parameters** 13715 13716| Name | Type | Mandatory | Description | 13717| --------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 13718| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. | 13719| 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. | 13720 13721**Error codes** 13722 13723For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13724 13725| ID | Error Message | 13726| ------- | ------------------------------------------------------------ | 13727| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 13728| 1300002 | This window state is abnormal. | 13729| 1300005 | This window stage is abnormal. | 13730 13731**Example** 13732 13733```ts 13734// EntryAbility.ets 13735import { UIAbility } from '@kit.AbilityKit'; 13736 13737export default class EntryAbility extends UIAbility { 13738 // ... 13739 13740 onWindowStageCreate(windowStage: window.WindowStage) { 13741 console.info('onWindowStageCreate'); 13742 const callback = (windowStageEventType: window.WindowStageEventType) => { 13743 // ... 13744 } 13745 try { 13746 windowStage.on('windowStageEvent', callback); 13747 } catch (exception) { 13748 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 13749 } 13750 try { 13751 windowStage.off('windowStageEvent', callback); 13752 // Unregister all the callbacks that have been registered through on(). 13753 windowStage.off('windowStageEvent'); 13754 } catch (exception) { 13755 console.error(`Failed to disable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 13756 } 13757 } 13758}; 13759``` 13760 13761### on('windowStageClose')<sup>14+</sup> 13762 13763on(eventType: 'windowStageClose', callback: Callback<void>): void 13764 13765Subscribes to the click event on the close button in the three-button navigation bar of the main window. 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#onpreparetoterminate10) is not executed. 13766 13767If the event is subscribed to multiple times, only the most recently subscribed-to event takes effect. 13768 13769The callback function in this API is executed synchronously. For asynchronous close events of the main window, refer to [on('windowWillClose')](#onwindowwillclose15). 13770 13771If there is an existing event subscribed to by calling [on('windowWillClose')](#onwindowwillclose15), only the [on('windowWillClose')](#onwindowwillclose15) API will be responded to. 13772 13773<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 13774 13775**Model restriction**: This API can be used only in the stage model. 13776 13777**System capability**: SystemCapability.Window.SessionManager 13778 13779**Atomic service API**: This API can be used in atomic services since API version 14. 13780 13781**Parameters** 13782 13783| Name | Type | Mandatory | Description | 13784| --------- | -------------------- | --------- | ------------------------------------------------------------ | 13785| 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 | 13786| 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. | 13787 13788**Error codes** 13789 13790For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13791 13792| ID | Error Message | 13793| ------- | ------------------------------------------------------------ | 13794| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 13795| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 13796| 1300002 | This window state is abnormal. | 13797 13798**Example** 13799 13800```ts 13801// EntryAbility.ets 13802import { UIAbility } from '@kit.AbilityKit'; 13803import { window } from '@kit.ArkUI'; 13804 13805export default class EntryAbility extends UIAbility { 13806 // ... 13807 13808 onWindowStageCreate(windowStage: window.WindowStage) { 13809 console.info('onWindowStageCreate'); 13810 try { 13811 windowStage.on('windowStageClose', () => { 13812 console.info('Succeeded in enabling the listener for window stage close event.'); 13813 return false; 13814 }); 13815 } catch (exception) { 13816 console.error(`Failed to enable the listener for window stage close event. Cause code: ${exception.code}, message: ${exception.message}`); 13817 } 13818 } 13819}; 13820``` 13821 13822### off('windowStageClose')<sup>14+</sup> 13823 13824off(eventType: 'windowStageClose', callback?: Callback<void>): void 13825 13826Unsubscribes from the event indicating that the main window is closed. 13827 13828<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 13829 13830**Model restriction**: This API can be used only in the stage model. 13831 13832**System capability**: SystemCapability.Window.SessionManager 13833 13834**Atomic service API**: This API can be used in atomic services since API version 14. 13835 13836**Parameters** 13837 13838| Name | Type | Mandatory | Description | 13839| --------- | -------------------- | --------- | ------------------------------------------------------------ | 13840| 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. | 13841| 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. | 13842 13843**Error codes** 13844 13845For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13846 13847| ID | Error Message | 13848| ------- | ------------------------------------------------------------ | 13849| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 13850| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 13851| 1300002 | This window state is abnormal. | 13852 13853**Example** 13854 13855```ts 13856// EntryAbility.ets 13857import { UIAbility } from '@kit.AbilityKit'; 13858import { window } from '@kit.ArkUI'; 13859 13860export default class EntryAbility extends UIAbility { 13861 // ... 13862 13863 onWindowStageCreate(windowStage: window.WindowStage) { 13864 console.info('onWindowStageCreate'); 13865 const callback = () => { 13866 // ... 13867 return false; 13868 } 13869 try { 13870 windowStage.on('windowStageClose', callback); 13871 windowStage.off('windowStageClose', callback); 13872 windowStage.off('windowStageClose'); 13873 } catch (exception) { 13874 console.error(`Failed to disable the listener for window stage close changes. Cause code: ${exception.code}, message: ${exception.message}`); 13875 } 13876 } 13877}; 13878``` 13879 13880### setDefaultDensityEnabled<sup>12+</sup> 13881 13882setDefaultDensityEnabled(enabled: boolean): void 13883 13884Sets whether the main window of the application uses the system's default density. Child windows and system windows will follow the main window's setting. Before calling this API, call [WindowStage.loadContent()](#loadcontent9-2) to initialize the layout to ensure the correct call sequence. 13885 13886By default, the system's default density is not used, and the window layout changes with the system display size. 13887 13888**Model restriction**: This API can be used only in the stage model. 13889 13890**Atomic service API**: This API can be used in atomic services since API version 12. 13891 13892**System capability**: SystemCapability.Window.SessionManager 13893 13894**Parameters** 13895 13896| Name | Type | Mandatory | Description | 13897| ------- | ------- | --------- | ------------------------------------------------------------ | 13898| 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. | 13899 13900**Error codes** 13901 13902For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13903 13904| ID | Error Message | 13905| ------- | ------------------------------------------------------------ | 13906| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 13907| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 13908| 1300002 | This window state is abnormal. | 13909| 1300005 | This window stage is abnormal. | 13910 13911**Example** 13912 13913```ts 13914// EntryAbility.ets 13915import { UIAbility } from '@kit.AbilityKit'; 13916import { window } from '@kit.ArkUI'; 13917import { BusinessError } from '@kit.BasicServicesKit' 13918 13919export default class EntryAbility extends UIAbility { 13920 // ... 13921 13922 onWindowStageCreate(windowStage: window.WindowStage) { 13923 windowStage.loadContent("pages/page2", (err: BusinessError) => { 13924 let errCode: number = err.code; 13925 if (errCode) { 13926 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 13927 return; 13928 } 13929 console.info('onWindowStageCreate'); 13930 try { 13931 windowStage.setDefaultDensityEnabled(true); 13932 console.info('Succeeded in loading the content.'); 13933 } catch (exception) { 13934 console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`); 13935 } 13936 }); 13937 } 13938}; 13939``` 13940 13941### setCustomDensity<sup>15+</sup> 13942 13943setCustomDensity(density: number): void 13944 13945Allows the main window of the application to customize its display size scale factor. Child windows and system windows will follow the main window's setting. If both this API and [setDefaultDensityEnabled(true)](#setdefaultdensityenabled12) are called to set a display size scale factor, the setting from the last called API will be applied. 13946 13947**Model restriction**: This API can be used only in the stage model. 13948 13949**Atomic service API**: This API can be used in atomic services since API version 15. 13950 13951**System capability**: SystemCapability.Window.SessionManager 13952 13953**Parameters** 13954 13955| Name | Type | Mandatory | Description | 13956| ------- | ------ | --------- | ------------------------------------------------------------ | 13957| density | number | Yes | Custom display size scale factor. The value is a floating point number in the range [0.5, 4.0] or is set to **-1.0**. The value **4.0** indicates the largest permissible display size scale factor for the window, and **-1.0** means that the window uses the system's default display size scale factor. | 13958 13959**Error codes** 13960 13961For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 13962 13963| ID | Error Message | 13964| ------- | ------------------------------------------------------------ | 13965| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 13966| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 13967| 1300002 | This window state is abnormal. | 13968| 1300005 | This window stage is abnormal. | 13969 13970**Example** 13971 13972```ts 13973// EntryAbility.ets 13974import { UIAbility } from '@kit.AbilityKit'; 13975 13976export default class EntryAbility extends UIAbility { 13977 // ... 13978 13979 onWindowStageCreate(windowStage: window.WindowStage) { 13980 console.info('onWindowStageCreate'); 13981 try { 13982 windowStage.setCustomDensity(-1.0); 13983 } catch (exception) { 13984 console.error(`Failed to set custom density. Cause code: ${exception.code}, message: ${exception.message}`); 13985 } 13986 } 13987}; 13988``` 13989 13990### setWindowModal<sup>14+</sup> 13991 13992setWindowModal(isModal: boolean): Promise<void> 13993 13994Enables the modal property of the main window. This API uses a promise to return the result. 13995 13996This 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 child windows do not respond to user interactions until the main window is closed or the main window's modal property is disabled. 13997 13998<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 13999 14000**Model restriction**: This API can be used only in the stage model. 14001 14002**Atomic service API**: This API can be used in atomic services since API version 14. 14003 14004**System capability**: SystemCapability.Window.SessionManager 14005 14006**Parameters** 14007 14008| Name | Type | Mandatory | Description | 14009| ------- | ------- | --------- | ------------------------------------------------------------ | 14010| 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. | 14011 14012 14013**Return value** 14014 14015| Type | Description | 14016| ------------------- | ------------------------------ | 14017| Promise<void> | Promise that returns no value. | 14018 14019**Error codes** 14020 14021For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 14022 14023| ID | Error Message | 14024| ------- | ------------------------------------------------------------ | 14025| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 14026| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 14027| 1300002 | This window state is abnormal. | 14028| 1300003 | This window manager service works abnormally. | 14029| 1300005 | This window stage is abnormal. | 14030 14031**Example** 14032 14033```ts 14034// EntryAbility.ets 14035import { UIAbility } from '@kit.AbilityKit'; 14036import { BusinessError } from '@kit.BasicServicesKit'; 14037 14038export default class EntryAbility extends UIAbility { 14039 // ... 14040 onWindowStageCreate(windowStage: window.WindowStage): void { 14041 console.info('onWindowStageCreate'); 14042 try { 14043 let promise = windowStage.setWindowModal(true); 14044 promise.then(() => { 14045 console.info('Succeeded in setting window modal'); 14046 }).catch((err: BusinessError) => { 14047 console.error(`Failed to set window modal. Cause code: ${err.code}, message: ${err.message}`); 14048 }); 14049 } catch (exception) { 14050 console.error(`Failed to set window modal. Cause code: ${exception.code}, message: ${exception.message}`); 14051 } 14052 } 14053} 14054``` 14055 14056### removeStartingWindow<sup>14+</sup> 14057 14058removeStartingWindow(): Promise<void> 14059 14060Allows the application to control the time when the launch page disappears. 14061 14062This 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**. 14063 14064If 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. 14065 14066If 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. 14067 14068**Model restriction**: This API can be used only in the stage model. 14069 14070**Atomic service API**: This API can be used in atomic services since API version 14. 14071 14072**System capability**: SystemCapability.Window.SessionManager 14073 14074**Return value** 14075 14076| Type | Description | 14077| ------------------- | ------------------------------ | 14078| Promise<void> | Promise that returns no value. | 14079 14080**Error codes** 14081 14082For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 14083 14084| ID | Error Message | 14085| ------- | ------------------------------------------------------------ | 14086| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 14087| 1300002 | This window state is abnormal. | 14088| 1300003 | This window manager service works abnormally. | 14089 14090**Example** 14091 14092```ts 14093// EntryAbility.ets 14094import { UIAbility } from '@kit.AbilityKit'; 14095import { BusinessError } from '@kit.BasicServicesKit'; 14096 14097export default class EntryAbility extends UIAbility { 14098 // ... 14099 14100 onWindowStageCreate(windowStage: window.WindowStage) { 14101 console.info('onWindowStageCreate'); 14102 windowStage.removeStartingWindow().then(() => { 14103 console.info('Succeeded in removing starting window.'); 14104 }).catch((err: BusinessError) => { 14105 console.error(`Failed to remove starting window. Cause code: ${err.code}, message: ${err.message}`); 14106 }); 14107 } 14108}; 14109``` 14110 14111### setWindowRectAutoSave<sup>14+</sup> 14112 14113setWindowRectAutoSave(enabled: boolean): Promise<void> 14114 14115Enables or disables the auto-save feature for the size of the last closed main window. This API uses a promise to return the result. It takes effect only on 2-in-1 devices. 14116 14117When the auto-save feature is enabled, within the same UIAbility, the size of the last closed main window is remembered. When this main window is restarted, it will open at the remembered size according to the rules. 14118 14119The following rules apply in stacking scenarios: 14120 141211. If the current instance is a free-form window, the next opened window will adopt the same size when stacked. 141222. If the current instance is maximized or in full-screen mode, the next opened window will maintain the maximized state when stacked. 14123 14124The following table describes the memory rules: 14125 14126| Last Window State | Memorizing Rule | 14127| ------------------- | ------------------------------------------------------------ | 14128| Free-form window | Retains the size/position of the free-form window, rebound if exceeding the workspace. | 14129| Split-screen window | Retains the size and position of the free-form window before screen splitting. | 14130| Maximized window | Retains the maximized state. | 14131| Immersive window | Retains the size and position of the free-form window before immersive mode. | 14132| Minimized window | Retains the size and position of the free-form window before minimization. | 14133 14134**Model restriction**: This API can be used only in the stage model. 14135 14136**Atomic service API**: This API can be used in atomic services since API version 14. 14137 14138**System capability**: SystemCapability.Window.SessionManager 14139 14140**Parameters** 14141 14142| Name | Type | Mandatory | Description | 14143| ------- | ------- | --------- | ------------------------------------------------------------ | 14144| enabled | boolean | Yes | Whether to enable the auto-save feature. The value **true** means to enable it, and **false** means to disable it. | 14145 14146 14147**Return value** 14148 14149| Type | Description | 14150| ------------------- | ------------------------------ | 14151| Promise<void> | Promise that returns no value. | 14152 14153**Error codes** 14154 14155For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 14156 14157| ID | Error Message | 14158| ------- | ------------------------------------------------------------ | 14159| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 14160| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 14161| 1300002 | This window state is abnormal. | 14162| 1300003 | This window manager service works abnormally. | 14163 14164**Example** 14165 14166```ts 14167// EntryAbility.ets 14168import { UIAbility } from '@kit.AbilityKit'; 14169import { BusinessError } from '@kit.BasicServicesKit'; 14170 14171export default class EntryAbility extends UIAbility { 14172 // ... 14173 onWindowStageCreate(windowStage: window.WindowStage): void { 14174 console.info('onWindowStageCreate'); 14175 try { 14176 let promise = windowStage.setWindowRectAutoSave(true); 14177 promise.then(() => { 14178 console.info('Succeeded in setting window rect auto-save'); 14179 }).catch((err: BusinessError) => { 14180 console.error(`Failed to set window rect auto-save. Cause code: ${err.code}, message: ${err.message}`); 14181 }); 14182 } catch (exception) { 14183 console.error(`Failed to set window rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`); 14184 } 14185 } 14186} 14187``` 14188 14189### setWindowRectAutoSave<sup>17+</sup> 14190 14191setWindowRectAutoSave(enabled: boolean, isSaveBySpecifiedFlag: boolean): Promise<void> 14192 14193Enables or disables 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. 14194 14195Within the same UIAbility, you can remember the size of the last closed main window, or you can remember the size of each main window individually. The individual auto-save feature for each main window size is only available when the UIAbility launch mode is set to **specified** and the **isSaveBySpecifiedFlag** parameter is set to **true**. 14196 14197When the auto-save feature is enabled, the size of the main window when it is closed is remembered. When the main window is restarted, it will open at the remembered size according to the rules. 14198 14199The following table describes the memory rules: 14200 14201| Last Window State | Memorizing Rule | 14202| ------------------- | ------------------------------------------------------------ | 14203| Free-form window | Retains the size/position of the free-form window, rebound if exceeding the workspace. | 14204| Split-screen window | Retains the size and position of the free-form window before screen splitting. | 14205| Maximized window | Retains the maximized state. | 14206| Immersive window | Retains the size and position of the free-form window before immersive mode. | 14207| Minimized window | Retains the size and position of the free-form window before minimization. | 14208 14209**Model restriction**: This API can be used only in the stage model. 14210 14211**Atomic service API**: This API can be used in atomic services since API version 17. 14212 14213**System capability**: SystemCapability.Window.SessionManager 14214 14215**Parameters** 14216 14217| Name | Type | Mandatory | Description | 14218| --------------------- | ------- | --------- | ------------------------------------------------------------ | 14219| enabled | boolean | Yes | Whether to enable the auto-save feature. The value **true** means to enable it, and **false** means to disable it. | 14220| isSaveBySpecifiedFlag | boolean | Yes | Whether to enable the individual auto-save feature when the UIAbility launch mode is set to **specified**. The value **true** means to enable it, and **false** means to disable it. | 14221 14222 14223**Return value** 14224 14225| Type | Description | 14226| ------------------- | ------------------------------ | 14227| Promise<void> | Promise that returns no value. | 14228 14229**Error codes** 14230 14231For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 14232 14233| ID | Error Message | 14234| ------- | ------------------------------------------------------------ | 14235| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 14236| 801 | Capability not supported. Function setWindowRectAutoSave can not work correctly due to limited device capabilities. | 14237| 1300002 | This window state is abnormal. | 14238| 1300003 | This window manager service works abnormally. | 14239 14240**Example** 14241 14242```ts 14243// EntryAbility.ets 14244import { UIAbility } from '@kit.AbilityKit'; 14245import { BusinessError } from '@kit.BasicServicesKit'; 14246 14247export default class EntryAbility extends UIAbility { 14248 // ... 14249 onWindowStageCreate(windowStage: window.WindowStage): void { 14250 console.info('onWindowStageCreate'); 14251 try { 14252 let promise = windowStage.setWindowRectAutoSave(true, true); 14253 promise.then(() => { 14254 console.info('Succeeded in setting window rect auto-save'); 14255 }).catch((err: BusinessError) => { 14256 console.error(`Failed to set window rect auto-save. Cause code: ${err.code}, message: ${err.message}`); 14257 }); 14258 } catch (exception) { 14259 console.error(`Failed to set window rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`); 14260 } 14261 } 14262} 14263``` 14264 14265### isWindowRectAutoSave<sup>14+</sup> 14266 14267isWindowRectAutoSave(): Promise<boolean> 14268 14269Checks 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. 14270 14271**Model restriction**: This API can be used only in the stage model. 14272 14273**Atomic service API**: This API can be used in atomic services since API version 14. 14274 14275**System capability**: SystemCapability.Window.SessionManager 14276 14277**Return value** 14278 14279| Type | Description | 14280| ---------------------- | ------------------------------------------------------------ | 14281| Promise<boolean> | Promise used to return the result. The value **true** means that the auto-save feature is enabled, and **false** means the opposite. | 14282 14283**Error codes** 14284 14285For details about the error codes, see [Window Error Codes](errorcode-window.md). 14286 14287| ID | Error Message | 14288| ------- | ------------------------------------------------------------ | 14289| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 14290| 1300002 | This window state is abnormal. | 14291| 1300003 | This window manager services works abnormally. | 14292 14293**Example** 14294 14295```ts 14296// EntryAbility.ets 14297import { UIAbility } from '@kit.AbilityKit'; 14298import { BusinessError } from '@kit.BasicServicesKit'; 14299 14300export default class EntryAbility extends UIAbility { 14301 // ... 14302 onWindowStageCreate(windowStage: window.WindowStage): void { 14303 console.info('onWindowStageCreate'); 14304 try { 14305 let promise = windowStage.isWindowRectAutoSave(); 14306 promise.then((data) => { 14307 console.info(`Succeeded in checking whether the window support the rect auto-save. Data: ${data}`); 14308 }).catch((err: BusinessError) => { 14309 console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${err.code}, message: ${err.message}`); 14310 }); 14311 } catch (exception) { 14312 console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`); 14313 } 14314 } 14315} 14316``` 14317 14318### setSupportedWindowModes<sup>15+</sup> 14319 14320setSupportedWindowModes(supportedWindowModes: Array<bundleManager.SupportWindowMode>): Promise<void> 14321 14322Sets the supported window modes of the main window. This API uses a promise to return the result. 14323 14324<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 14325 14326**Model restriction**: This API can be used only in the stage model. 14327 14328**Atomic service API**: This API can be used in atomic services since API version 15. 14329 14330**System capability**: SystemCapability.Window.SessionManager 14331 14332**Parameters** 14333 14334| Name | Type | Mandatory | Description | 14335| -------------------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 14336| supportedWindowModes | Array<[bundleManager.SupportWindowMode](../apis-ability-kit/js-apis-bundleManager.md#supportwindowmode)> | Yes | Supported window modes.<br>- **FULL_SCREEN**: full-screen mode.<br>- **FLOATING**: floating window mode.<br>- **SPLIT**: split-screen mode. **FULL_SCREEN** or **FLOATING** must be used together. Configuring only **SPLIT** is not supported.<br>Note: The values of the **SupportWindowMode** field in the array should not conflict with the values of the **supportWindowMode** field under [abilities](../../quick-start/module-configuration-file.md#abilities) of the [module.json5 file](../../quick-start/module-configuration-file.md) corresponding to this UIAbility, or with the values of the **supportWindowModes** field in [StartOptions](../apis-ability-kit/js-apis-app-ability-startOptions.md#startoptions). In case of a conflict, the window support mode set by this parameter will take precedence. | 14337 14338**Return value** 14339 14340| Type | Description | 14341| ------------------- | ------------------------------ | 14342| Promise<void> | Promise that returns no value. | 14343 14344**Error codes** 14345 14346For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 14347 14348| ID | Error Message | 14349| ------- | ------------------------------------------------------------ | 14350| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 14351| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 14352| 1300002 | This window state is abnormal. | 14353| 1300003 | This window manager service works abnormally. | 14354 14355**Example** 14356 14357```ts 14358// EntryAbility.ets 14359import { UIAbility, bundleManager } from '@kit.AbilityKit'; 14360import { BusinessError } from '@kit.BasicServicesKit'; 14361 14362export default class EntryAbility extends UIAbility { 14363 // ... 14364 onWindowStageCreate(windowStage: window.WindowStage): void { 14365 console.info('onWindowStageCreate'); 14366 try { 14367 let promise = windowStage.setSupportedWindowModes([ 14368 bundleManager.SupportWindowMode.FULL_SCREEN, 14369 bundleManager.SupportWindowMode.SPLIT, 14370 bundleManager.SupportWindowMode.FLOATING 14371 ]); 14372 promise.then(() => { 14373 console.info('Succeeded in setting window support modes'); 14374 }).catch((err: BusinessError) => { 14375 console.error(`Failed to set window support modes. Cause code: ${err.code}, message: ${err.message}`); 14376 }); 14377 } catch (exception) { 14378 console.error(`Failed to set window support modes. Cause code: ${exception.code}, message: ${exception.message}`); 14379 } 14380 } 14381} 14382```