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 | Application subwindow.<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 33## Configuration<sup>9+</sup> 34 35Defines the parameters for creating a subwindow or system window. 36 37**Atomic service API**: This API can be used in atomic services since API version 12. 38 39**System capability**: SystemCapability.WindowManager.WindowManager.Core 40 41| Name| Type| Mandatory| Description | 42| ---------- | -------------------------- | -- |-----------------------------------------------------------------------------| 43| name | string | Yes| Name of the window. | 44| windowType | [WindowType](#windowtype7) | Yes| Window type. | 45| 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 subwindow. 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.| 46| 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. | 47| 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. | 48| 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| 49| title<sup>12+</sup> | string| No| Title of the window when **decorEnabled** is set to **true**. If this parameter is not set, an empty string is used by default.<br>**System capability**: SystemCapability.Window.SessionManager| 50 51## AvoidAreaType<sup>7+</sup> 52 53Enumerates the types of the area where the window cannot be displayed. 54 55**System capability**: SystemCapability.WindowManager.WindowManager.Core 56 57**Atomic service API**: This API can be used in atomic services since API version 11. 58 59| Name | Value | Description | 60| -------------------------------- | ---- | ------------------------------------------------------------ | 61| TYPE_SYSTEM | 0 | Default area of the system. Generally, the status bar and navigation bar are included. The default area may vary according to the device in use.| 62| TYPE_CUTOUT | 1 | Notch. | 63| TYPE_SYSTEM_GESTURE<sup>9+</sup> | 2 | Gesture area. | 64| TYPE_KEYBOARD<sup>9+</sup> | 3 | Soft keyboard area. | 65| TYPE_NAVIGATION_INDICATOR<sup>11+</sup> | 4 | Navigation bar area. | 66 67 68## SystemBarProperties 69 70Describes the properties of the status bar and navigation bar. These properties are valid for the window-level status bar and navigation bar. 71 72**Atomic service API**: This API can be used in atomic services since API version 12. 73 74| Name | Type| Mandatory| Description | 75| -------------------------------------- | -------- | ---- | ------------------------------------------------------------ | 76| statusBarColor | string | No | Background color of the status bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**. The default value is **'#0x66000000'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 77| 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| 78| 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 **'#0xE5FFFFFF'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 79| navigationBarColor | string | No | Background color of the navigation bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**. The default value is **'#0x66000000'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 80| isNavigationBarLightIcon<sup>7+</sup> | boolean | No | Whether any icon on the navigation bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 81| navigationBarContentColor<sup>8+</sup> | string | No | Color of the text on the navigation bar. After this property is set, the setting of **isNavigationBarLightIcon** is invalid. The default value is **'#0xE5FFFFFF'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 82| 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| 83| enableNavigationBarAnimation<sup>12+</sup> | boolean | No | Whether to enable animation for a navigation bar property change. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.<br>**System capability**: SystemCapability.Window.SessionManager| 84 85## SystemBarStyle<sup>12+</sup> 86 87Describes the properties of the status bar. These properties are valid for the page-level status bar. 88 89**Atomic service API**: This API can be used in atomic services since API version 12. 90 91**System capability**: SystemCapability.WindowManager.WindowManager.Core 92 93| Name | Type| Read-Only| Optional| Description | 94| ------ | -------- | ---- | ---- | ------------------ | 95| statusBarContentColor | string | Yes | Yes | Color of the text on the status bar. The default value is **'#0xE5FFFFFF'**.| 96 97## Orientation<sup>9+</sup> 98 99Enumerates the window orientations. 100 101| Name | Value | Description | 102| ------------------------------------- | ---- | ----------------------------- | 103| 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| 104| 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.| 105| 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| 106| 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.| 107| 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.| 108| 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.| 109| 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| 110| 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.| 111| 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.| 112| 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| 113| 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| 114| 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| 115| 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| 116| 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| 117| 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| 118| 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| 119| 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| 120| 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| 121 122## Rect<sup>7+</sup> 123 124Describes the rectangular area of the window. 125 126**System capability**: SystemCapability.WindowManager.WindowManager.Core 127 128**Atomic service API**: This API can be used in atomic services since API version 11. 129 130| Name | Type| Readable| Writable| Description | 131| ------ | -------- | ---- | ---- | ------------------ | 132| left | number | Yes | Yes | Left boundary of the rectangle, in px. The value must be an integer.| 133| top | number | Yes | Yes | Top boundary of the rectangle, in px. The value must be an integer.| 134| width | number | Yes | Yes | Width of the rectangle, in px. The value must be an integer.| 135| height | number | Yes | Yes | Height of the rectangle, in px. The value must be an integer.| 136 137## AvoidArea<sup>7+</sup> 138 139Describes 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. 140 141Pay attention to the following restrictions on this area: 142 143- The non-navigation bar area in the gesture area at the bottom supports transparent transmission of touch events, touch and hold events, but not drag events. 144 145- 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. 146 147- The navigation bar area supports responding to touch events, touch and hold events, and drag events. However, it does not support transparent transmission of events. 148 149**System capability**: SystemCapability.WindowManager.WindowManager.Core 150 151**Atomic service API**: This API can be used in atomic services since API version 11. 152 153| Name | Type | Readable| Writable| Description | 154| ---------- | ------------- | ---- | ---- | ------------------ | 155| 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.| 156| leftRect | [Rect](#rect7) | Yes | Yes | Rectangle on the left of the screen.| 157| topRect | [Rect](#rect7) | Yes | Yes | Rectangle at the top of the screen.| 158| rightRect | [Rect](#rect7) | Yes | Yes | Rectangle on the right of the screen.| 159| bottomRect | [Rect](#rect7) | Yes | Yes | Rectangle at the bottom of the screen.| 160 161## Size<sup>7+</sup> 162 163Describes the window size. 164 165**System capability**: SystemCapability.WindowManager.WindowManager.Core 166 167**Atomic service API**: This API can be used in atomic services since API version 11. 168 169| Name | Type| Readable| Writable| Description | 170| ------ | -------- | ---- | ---- | ---------- | 171| width | number | Yes | Yes | Window width, in px. The value must be an integer.| 172| height | number | Yes | Yes | Window height, in px. The value must be an integer.| 173 174## RectChangeReason<sup>12+</sup> 175 176Enumerates the reasons for window rectangle (position and size) changes. 177 178**System capability**: SystemCapability.Window.SessionManager 179 180**Atomic service API**: This API can be used in atomic services since API version 12. 181 182| Name | Value | Description | 183| --------------------- | ---- | ------------------------------------------------------------ | 184| UNDEFINED | 0 | Default value. | 185| MAXIMIZE | 1 | The window is maximized. | 186| RECOVER | 2 | The window is restored to the previous state. | 187| MOVE | 3 | The window is moved.| 188| DRAG | 4 | The window is zoomed in or out by dragging.| 189| DRAG_START | 5 | The window starts zooming in or out.| 190| DRAG_END | 6 | The window finishes zooming in or out.| 191 192## RectChangeOptions<sup>12+</sup> 193 194Describes the value and reason returned upon a window rectangle (position and size) change. 195 196**System capability**: SystemCapability.Window.SessionManager 197 198**Atomic service API**: This API can be used in atomic services since API version 12. 199 200| Name | Type | Readable| Writable| Description | 201| ---------- | ------------- | ---- | ---- | ------------------ | 202| rect | [Rect](#rect7) | Yes | Yes | New value of the window rectangle.| 203| reason | [RectChangeReason](#rectchangereason12) | Yes | Yes | Reason for the window rectangle change.| 204 205## AvoidAreaOptions<sup>12+</sup> 206 207Describes the new area where the window cannot be displayed. The new area is returned when the corresponding event is triggered. 208 209**System capability**: SystemCapability.WindowManager.WindowManager.Core 210 211**Atomic service API**: This API can be used in atomic services since API version 12. 212 213| Name | Type | Readable| Writable| Description | 214| ---------- | ------------- | ---- | ---- | ------------------ | 215| type | [AvoidAreaType](#avoidareatype7) | Yes | Yes | Type of the new area returned.| 216| area | [AvoidArea](#avoidarea7) | Yes | Yes | New area returned.| 217 218## WindowProperties 219 220Describes the window properties. 221 222**System capability**: SystemCapability.WindowManager.WindowManager.Core 223 224| Name | Type | Read-Only| Optional| Description | 225| ------------------------------------- | ------------------------- | ---- | ---- |--------------------------------------------------------------------------------------------------------| 226| 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#uiabilityonforeground).<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 227| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 228| 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. | 229| 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. | 230| isLayoutFullScreen<sup>7+</sup> | boolean | No | No | Whether the window layout is in full-screen mode (whether the window is immersive). The default value is **false**. The value **true** means that the window is immersive, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 231| 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. | 232| 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. | 233| 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. | 234| 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. | 235| 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. | 236| 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. | 237| 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. | 238| isTransparent<sup>7+</sup> | boolean | No | No | Whether the window is transparent. The default value is **false**. The value **true** means that the window is transparent, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 239| 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. | 240| 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.| 241 242## DecorButtonStyle<sup>14+</sup> 243 244Describes the button style of the system decoration bar. 245 246**System capability**: SystemCapability.Window.SessionManager 247 248**Atomic service API**: This API can be used in atomic services since API version 14. 249 250| Name | Type | Readable| Writable| Description | 251| ---------- | ------------- | ---- | ---- | ------------------ | 252| 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.| 253| 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.| 254| spacingBetweenButtons | number | Yes | Yes | Spacing between buttons. The value ranges from 12 vp to 24 vp. The default value is 12 vp.| 255| closeButtonRightMargin | number | Yes | Yes | Margin between the rightmost edge of the close button and the window. The value ranges from 8 vp to 22 vp. The default value is 20 vp.| 256 257## ColorSpace<sup>8+</sup> 258 259Enumerates the color spaces. 260 261**Atomic service API**: This API can be used in atomic services since API version 12. 262 263**System capability**: SystemCapability.WindowManager.WindowManager.Core 264 265| Name | Value| Description | 266| ---------- | ------ | -------------- | 267| DEFAULT | 0 | Default SRGB gamut.| 268| WIDE_GAMUT | 1 | Wide-gamut. | 269 270## WindowEventType<sup>10+</sup> 271 272Enumerates the window lifecycle states. 273 274**Atomic service API**: This API can be used in atomic services since API version 11. 275 276| Name | Value| Description | 277| ---------- | ------ | ---------- | 278| WINDOW_SHOWN | 1 | The window is running in the foreground.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 279| WINDOW_ACTIVE | 2 | The window gains focus.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 280| WINDOW_INACTIVE | 3 | The window loses focus.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 281| WINDOW_HIDDEN | 4 | The window is running in the background.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 282| WINDOW_DESTROYED<sup>11+</sup> | 7 | The window is destroyed.<br>**System capability**: SystemCapability.Window.SessionManager| 283 284## WindowLimits<sup>11+</sup> 285 286Defines 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. 287 288**Atomic service API**: This API can be used in atomic services since API version 12. 289 290**System capability**: SystemCapability.Window.SessionManager 291 292| Name | Type | Readable| Writable| Description | 293| :-------- | :----- | :--- | :--- | :----------------------------------------------------------- | 294| 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. | 295| 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. | 296| 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. | 297| 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. | 298 299## WindowStatusType<sup>11+</sup> 300 301Enumerates the window modes. 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 | Value | Description | 308| ---------- | ---- | ----------------------------- | 309| UNDEFINED | 0 | The window mode is not defined by the application. | 310| FULL_SCREEN | 1 | The application is displayed in full screen. | 311| MAXIMIZE | 2 | The application window is maximized. | 312| MINIMIZE | 3 | The application window is minimized. | 313| FLOATING | 4 | The application is displayed in a floating window. | 314| SPLIT_SCREEN | 5 | The application is displayed in split-screen mode. | 315 316## TitleButtonRect<sup>11+</sup> 317 318Defines 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. 319 320**Atomic service API**: This API can be used in atomic services since API version 12. 321 322**System capability**: SystemCapability.Window.SessionManager 323 324| Name | Type | Readable| Writable| Description | 325| ------ | ------ | ---- | ---- | ------------------------------------------ | 326| right | number | Yes | Yes | Right boundary of the rectangle, in vp. The value must be an integer.| 327| top | number | Yes | Yes | Top boundary of the rectangle, in vp. The value must be an integer.| 328| width | number | Yes | Yes | Width of the rectangle, in vp. The value must be an integer. | 329| height | number | Yes | Yes | Height of the rectangle, in vp. The value must be an integer. | 330 331## MaximizePresentation<sup>12+</sup> 332 333Enumerates the layout when the window is maximized. 334 335**System capability**: SystemCapability.Window.SessionManager 336 337| Name | Value | Description | 338| ---------- | ---- | ----------------------------- | 339| 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. | 340| 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. | 341| 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. | 342| 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 you hover the cursor over the hot zone.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 343 344## window.createWindow<sup>9+</sup> 345 346createWindow(config: Configuration, callback: AsyncCallback<Window>): void 347 348Creates a subwindow or system window. This API uses an asynchronous callback to return the result. 349 350**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**) 351 352**Atomic service API**: This API can be used in atomic services since API version 12. 353 354**System capability**: SystemCapability.WindowManager.WindowManager.Core 355 356**Parameters** 357 358| Name| Type| Mandatory| Description| 359| -------- | -------------------------------------- | -- | --------------------------------- | 360| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window. | 361| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the window created.| 362 363**Error codes** 364 365For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 366 367| ID| Error Message| 368| ------- | -------------------------------- | 369| 201 | Permission verification failed. The application does not have the permission required to call the API. | 370| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 371| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 372| 1300001 | Repeated operation. | 373| 1300002 | This window state is abnormal. | 374| 1300004 | Unauthorized operation. | 375| 1300006 | This window context is abnormal. | 376| 1300008 | The display device is abnormal. | 377| 1300009 | The parent window is invalid. | 378 379**Example** 380 381```ts 382import { BusinessError } from '@kit.BasicServicesKit'; 383 384let windowClass: window.Window | undefined = undefined; 385let config: window.Configuration = { 386 name: "test", 387 windowType: window.WindowType.TYPE_DIALOG, 388 ctx: this.context 389}; 390try { 391 window.createWindow(config, (err: BusinessError, data) => { 392 const errCode: number = err.code; 393 if (errCode) { 394 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 395 return; 396 } 397 windowClass = data; 398 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 399 windowClass.resize(500, 1000); 400 }); 401} catch (exception) { 402 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 403} 404``` 405 406## window.createWindow<sup>9+</sup> 407 408createWindow(config: Configuration): Promise<Window> 409 410Creates a subwindow or system window. This API uses a promise to return the result. 411 412**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**) 413 414**Atomic service API**: This API can be used in atomic services since API version 12. 415 416**System capability**: SystemCapability.WindowManager.WindowManager.Core 417 418**Parameters** 419 420| Name| Type| Mandatory| Description| 421| ------ | -------------------------------- | -- | ------------------ | 422| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window.| 423 424**Return value** 425 426| Type| Description| 427| -------------------------------- | ------------------------------------ | 428| Promise<[Window](#window)> | Promise used to return the window created.| 429 430**Error codes** 431 432For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 433 434| ID| Error Message| 435| ------- | -------------------------------- | 436| 201 | Permission verification failed. The application does not have the permission required to call the API. | 437| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 438| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 439| 1300001 | Repeated operation. | 440| 1300002 | This window state is abnormal. | 441| 1300004 | Unauthorized operation. | 442| 1300006 | This window context is abnormal. | 443| 1300008 | The display device is abnormal. | 444| 1300009 | The parent window is invalid. | 445 446**Example** 447 448```ts 449import { BusinessError } from '@kit.BasicServicesKit'; 450 451let windowClass: window.Window | undefined = undefined; 452let config: window.Configuration = { 453 name: "test", 454 windowType: window.WindowType.TYPE_DIALOG, 455 ctx: this.context 456}; 457try { 458 let promise = window.createWindow(config); 459 promise.then((data) => { 460 windowClass = data; 461 console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); 462 }).catch((err: BusinessError) => { 463 console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`); 464 }); 465} catch (exception) { 466 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 467} 468``` 469 470## window.findWindow<sup>9+</sup> 471 472findWindow(name: string): Window 473 474Finds a window based on the name. 475 476**System capability**: SystemCapability.WindowManager.WindowManager.Core 477 478**Atomic service API**: This API can be used in atomic services since API version 11. 479 480**Parameters** 481 482| Name| Type | Mandatory| Description | 483| ------ | ------ | ---- | -------- | 484| name | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 485 486**Return value** 487 488| Type| Description| 489| ----------------- | ------------------- | 490| [Window](#window) | Window found.| 491 492**Error codes** 493 494For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 495 496| ID| Error Message| 497| ------- | -------------------------------- | 498| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 499| 1300002 | This window state is abnormal. | 500 501**Example** 502 503```ts 504let windowClass: window.Window | undefined = undefined; 505try { 506 windowClass = window.findWindow('test'); 507} catch (exception) { 508 console.error(`Failed to find the Window. Cause code: ${exception.code}, message: ${exception.message}`); 509} 510``` 511 512## window.getLastWindow<sup>9+</sup> 513 514getLastWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 515 516Obtains the top window of the current application. This API uses an asynchronous callback to return the result. If no subwindow is available, the main window of the application is returned. 517 518**Atomic service API**: This API can be used in atomic services since API version 12. 519 520**System capability**: SystemCapability.WindowManager.WindowManager.Core 521 522**Parameters** 523 524| Name| Type| Mandatory| Description| 525| -------- | -------------------------------------- | -- | ---------------------------------------- | 526| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Current application context.| 527| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the top window obtained.| 528 529**Error codes** 530 531For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 532 533| ID| Error Message| 534| ------- | -------------------------------- | 535| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 536| 1300002 | This window state is abnormal. | 537| 1300006 | This window context is abnormal. | 538 539**Example** 540 541```ts 542// EntryAbility.ets 543import { UIAbility } from '@kit.AbilityKit'; 544import { BusinessError } from '@kit.BasicServicesKit'; 545 546export default class EntryAbility extends UIAbility { 547 // ... 548 onWindowStageCreate(windowStage: window.WindowStage) { 549 console.info('onWindowStageCreate'); 550 let windowClass: window.Window | undefined = undefined; 551 try { 552 window.getLastWindow(this.context, (err: BusinessError, data) => { 553 const errCode: number = err.code; 554 if (errCode) { 555 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 556 return; 557 } 558 windowClass = data; 559 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 560 }); 561 } catch (exception) { 562 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 563 } 564 } 565} 566``` 567 568## window.getLastWindow<sup>9+</sup> 569 570getLastWindow(ctx: BaseContext): Promise<Window> 571 572Obtains the top window of the current application. This API uses a promise to return the result. If no subwindow is available, the main window of the application is returned. 573 574**Atomic service API**: This API can be used in atomic services since API version 12. 575 576**System capability**: SystemCapability.WindowManager.WindowManager.Core 577 578**Parameters** 579 580| Name| Type| Mandatory| Description| 581| ------ | ----------- | ---- | ------------------------------------------------------------ | 582| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 583 584**Return value** 585 586| Type| Description| 587| -------------------------------- | ------------------------------------------- | 588| Promise<[Window](#window)> | Promise used to return the top window obtained.| 589 590**Error codes** 591 592For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 593 594| ID| Error Message| 595| ------- | -------------------------------- | 596| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 597| 1300002 | This window state is abnormal. | 598| 1300006 | This window context is abnormal. | 599 600**Example** 601 602```ts 603// EntryAbility.ets 604import { UIAbility } from '@kit.AbilityKit'; 605import { BusinessError } from '@kit.BasicServicesKit'; 606 607export default class EntryAbility extends UIAbility { 608 // ... 609 onWindowStageCreate(windowStage: window.WindowStage) { 610 console.info('onWindowStageCreate'); 611 let windowClass: window.Window | undefined = undefined; 612 try { 613 let promise = window.getLastWindow(this.context); 614 promise.then((data) => { 615 windowClass = data; 616 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 617 }).catch((err: BusinessError) => { 618 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 619 }); 620 } catch (exception) { 621 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 622 } 623 } 624} 625``` 626 627## window.shiftAppWindowFocus<sup>11+</sup> 628shiftAppWindowFocus(sourceWindowId: number, targetWindowId: number): Promise<void> 629 630Shifts the window focus from the source window to the target window in the same application. The window focus can be shifted between the main window and a subwindow. 631 632**Atomic service API**: This API can be used in atomic services since API version 12. 633 634**System capability**: SystemCapability.Window.SessionManager 635 636**Parameters** 637 638| Name | Type | Mandatory | Description | 639| -------------- | ------ | ----- | ----------------------- | 640| sourceWindowId | number | Yes | ID of the source window, which is having the focus.| 641| targetWindowId | number | Yes | ID of the target window. | 642 643**Return value** 644 645| Type | Description | 646| ------------------- | ------------------------- | 647| Promise<void> | Promise that returns no value.| 648 649**Error codes** 650 651For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 652 653| ID| Error Message | 654| ------- | --------------------------------------------- | 655| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 656| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 657| 1300002 | This window state is abnormal. | 658| 1300003 | This window manager service works abnormally. | 659| 1300004 | Unauthorized operation. | 660 661**Example** 662 663```ts 664// EntryAbility.ets 665import { UIAbility } from '@kit.AbilityKit'; 666import { BusinessError } from '@kit.BasicServicesKit'; 667 668export default class EntryAbility extends UIAbility { 669 onWindowStageCreate(windowStage: window.WindowStage) { 670 // ... 671 console.info('onWindowStageCreate'); 672 let windowClass: window.Window | undefined = undefined; 673 let subWindowClass: window.Window | undefined = undefined; 674 let windowClassId: number = -1; 675 let subWindowClassId: number = -1; 676 677 try { 678 // Obtain the main window and ID of the application. 679 let promise = windowStage.getMainWindow(); 680 promise.then((data) => { 681 if (data == null) { 682 console.error("Failed to obtaining the window. Cause: The data is empty"); 683 return; 684 } 685 windowClass = data; 686 windowClass.setUIContent("pages/Index"); 687 windowClassId = windowClass.getWindowProperties().id; 688 console.info('Succeeded in obtaining the window') 689 }).catch((err: BusinessError) => { 690 console.error(`Failed to obtaining the window. Cause code: ${err.code}, message: ${err.message}`); 691 }); 692 693 // Create or obtain a subwindow and its ID. In this case, the subwindow has focus. 694 let promiseSub = windowStage.createSubWindow("testSubWindow"); 695 promiseSub.then((data) => { 696 if (data == null) { 697 console.error("Failed to obtaining the window. Cause: The data is empty"); 698 return; 699 } 700 subWindowClass = data; 701 subWindowClassId = subWindowClass.getWindowProperties().id; 702 subWindowClass.resize(500, 500); 703 subWindowClass.setUIContent("pages/Index2"); 704 subWindowClass.showWindow(); 705 706 // Listen for the window status and ensure that the window is ready. 707 subWindowClass.on("windowEvent", (windowEvent) => { 708 if (windowEvent == window.WindowEventType.WINDOW_ACTIVE) { 709 // Switch the focus. 710 let promise = window.shiftAppWindowFocus(subWindowClassId, windowClassId); 711 promise.then(() => { 712 console.info('Succeeded in shifting app window focus'); 713 }).catch((err: BusinessError) => { 714 console.error(`Failed to shift app window focus. Cause code: ${err.code}, message: ${err.message}`); 715 }); 716 } 717 }); 718 }); 719 } catch (exception) { 720 console.error(`Failed to shift app focus. Cause code: ${exception.code}, message: ${exception.message}`); 721 } 722 } 723} 724``` 725 726## window.getWindowsByCoordinate<sup>14+</sup> 727 728getWindowsByCoordinate(displayId: number, windowNumber?: number, x?: number, y?: number): Promise<Array<Window>> 729 730Obtains visible windows at the specified coordinates of the application. This API uses a promise to return the result. 731 732**Atomic service API**: This API can be used in atomic services since API version 14. 733 734**System capability**: SystemCapability.Window.SessionManager 735 736**Parameters** 737 738| Name| Type | Mandatory| Description | 739| ------ | ---------- |----|---------------------------------------------------------------------------| 740| 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).| 741| 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. | 742| 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. | 743| 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. | 744 745**Return value** 746 747| Type | Description | 748| -------------------------------- |-------------------------| 749| Promise<Array<[Window](#window)>> | Promise used to return an array of window objects.| 750 751**Error codes** 752 753For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 754 755| ID | Error Message| 756|----------| ------------------------------ | 757| 401 | Parameter error. Possible cause: Incorrect parameter types. | 758| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 759| 1300003 | This window manager service works abnormally. | 760 761```ts 762import { window } from '@kit.ArkUI'; 763import { BusinessError } from '@kit.BasicServicesKit'; 764 765try { 766 let properties = windowClass.getWindowProperties(); 767 window.getWindowsByCoordinate(properties.displayId).then((data) => { 768 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 769 for (let window of data) { 770 // do something with window 771 } 772 }).catch((err: BusinessError) => { 773 console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`); 774 }); 775 776 window.getWindowsByCoordinate(properties.displayId, 2, 500, 500).then((data) => { 777 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 778 for (let window of data) { 779 // do something with window 780 } 781 }).catch((err: BusinessError) => { 782 console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`); 783 }); 784} catch (exception) { 785 console.error(`Failed to get window from point. Cause code: ${exception.code}, message: ${exception.message}`); 786} 787``` 788 789## window.create<sup>(deprecated)</sup> 790 791create(id: string, type: WindowType, callback: AsyncCallback<Window>): void 792 793Creates a subwindow. This API uses an asynchronous callback to return the result. 794 795> **NOTE** 796> 797> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 798 799**Model restriction**: This API can be used only in the FA model. 800 801**System capability**: SystemCapability.WindowManager.WindowManager.Core 802 803**Parameters** 804 805| Name | Type | Mandatory| Description | 806| -------- | -------------------------------------- | ---- | ------------------------------------ | 807| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 808| type | [WindowType](#windowtype7) | Yes | Window type. | 809| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created.| 810 811 812**Example** 813 814```ts 815import { BusinessError } from '@kit.BasicServicesKit'; 816 817let windowClass: window.Window | undefined = undefined; 818window.create('test', window.WindowType.TYPE_APP, (err: BusinessError, data) => { 819 const errCode: number = err.code; 820 if (errCode) { 821 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 822 return; 823 } 824 windowClass = data; 825 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 826}); 827``` 828 829## window.create<sup>(deprecated)</sup> 830 831create(id: string, type: WindowType): Promise<Window> 832 833Creates a subwindow. This API uses a promise to return the result. 834 835> **NOTE** 836> 837> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 838 839**Model restriction**: This API can be used only in the FA model. 840 841**System capability**: SystemCapability.WindowManager.WindowManager.Core 842 843**Parameters** 844 845| Name| Type | Mandatory| Description | 846| ------ | ------------------------- | ---- | ---------- | 847| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 848| type | [WindowType](#windowtype7) | Yes | Window type.| 849 850**Return value** 851 852| Type | Description | 853| -------------------------------- | --------------------------------------- | 854| Promise<[Window](#window)> | Promise used to return the subwindow created.| 855 856 857**Example** 858 859```ts 860import { BusinessError } from '@kit.BasicServicesKit'; 861 862let windowClass: window.Window | undefined = undefined; 863let promise = window.create('test', window.WindowType.TYPE_APP); 864promise.then((data) => { 865 windowClass = data; 866 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 867}).catch((err: BusinessError) => { 868 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 869}); 870``` 871 872## window.create<sup>(deprecated)</sup> 873 874create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void 875 876Creates a system window. This API uses an asynchronous callback to return the result. 877 878> **NOTE** 879> 880> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 881 882**System capability**: SystemCapability.WindowManager.WindowManager.Core 883 884**Parameters** 885 886| Name | Type | Mandatory| Description | 887| -------- | ------------------------------------------------------- | ---- | ------------------------------------ | 888| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context. | 889| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 890| type | [WindowType](#windowtype7) | Yes | Window type. | 891| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created.| 892 893 894**Example** 895 896```ts 897import { BusinessError } from '@kit.BasicServicesKit'; 898 899let windowClass: window.Window | undefined = undefined; 900window.create('test', window.WindowType.TYPE_SYSTEM_ALERT, (err: BusinessError, data) => { 901 const errCode: number = err.code; 902 if (errCode) { 903 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 904 return; 905 } 906 windowClass = data; 907 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 908 windowClass.resetSize(500, 1000); 909}); 910``` 911 912## window.create<sup>(deprecated)</sup> 913 914create(ctx: BaseContext, id: string, type: WindowType): Promise<Window> 915 916Creates a system window. This API uses a promise to return the result. 917 918> **NOTE** 919> 920> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 921 922**System capability**: SystemCapability.WindowManager.WindowManager.Core 923 924**Parameters** 925 926| Name| Type | Mandatory| Description | 927| ------ | ------------------------- | ---- | ------------------------------------------------------------ | 928| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 929| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 930| type | [WindowType](#windowtype7) | Yes | Window type. | 931 932**Return value** 933 934| Type | Description | 935| -------------------------------- | --------------------------------------- | 936| Promise<[Window](#window)> | Promise used to return the subwindow created.| 937 938 939**Example** 940 941```ts 942import { BusinessError } from '@kit.BasicServicesKit'; 943 944let windowClass: window.Window | undefined = undefined; 945let promise = window.create('test', window.WindowType.TYPE_SYSTEM_ALERT); 946promise.then((data) => { 947 windowClass = data; 948 console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); 949}).catch((err: BusinessError) => { 950 console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`); 951}); 952``` 953 954## window.find<sup>(deprecated)</sup> 955 956find(id: string, callback: AsyncCallback<Window>): void 957 958Finds a window based on the ID. This API uses an asynchronous callback to return the result. 959 960> **NOTE** 961> 962> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 963 964**System capability**: SystemCapability.WindowManager.WindowManager.Core 965 966**Parameters** 967 968| Name | Type | Mandatory| Description | 969| -------- | -------------------------------------- | ---- | ------------------------------------ | 970| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 971| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window found.| 972 973**Example** 974 975```ts 976import { BusinessError } from '@kit.BasicServicesKit'; 977 978let windowClass: window.Window | undefined = undefined; 979window.find('test', (err: BusinessError, data) => { 980 const errCode: number = err.code; 981 if (errCode) { 982 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 983 return; 984 } 985 windowClass = data; 986 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 987}); 988``` 989 990## window.find<sup>(deprecated)</sup> 991 992find(id: string): Promise<Window> 993 994Finds a window based on the ID. This API uses a promise to return the result. 995 996> **NOTE** 997> 998> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 999 1000**System capability**: SystemCapability.WindowManager.WindowManager.Core 1001 1002**Parameters** 1003 1004| Name| Type | Mandatory| Description | 1005| ------ | ------ | ---- | -------- | 1006| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1007 1008**Return value** 1009 1010| Type | Description | 1011| -------------------------------- | ------------------------------------- | 1012| Promise<[Window](#window)> | Promise used to return the window found.| 1013 1014**Example** 1015 1016```ts 1017import { BusinessError } from '@kit.BasicServicesKit'; 1018 1019let windowClass: window.Window | undefined = undefined; 1020let promise = window.find('test'); 1021promise.then((data) => { 1022 windowClass = data; 1023 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 1024}).catch((err: BusinessError) => { 1025 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 1026}); 1027``` 1028 1029## window.getTopWindow<sup>(deprecated)</sup> 1030 1031getTopWindow(callback: AsyncCallback<Window>): void 1032 1033Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 1034 1035> **NOTE** 1036> 1037> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 1038 1039**Model restriction**: This API can be used only in the FA model. 1040 1041**System capability**: SystemCapability.WindowManager.WindowManager.Core 1042 1043**Parameters** 1044 1045| Name | Type | Mandatory| Description | 1046| -------- | -------------------------------------- | ---- | -------------------------------------------- | 1047| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained.| 1048 1049**Example** 1050 1051```ts 1052import { BusinessError } from '@kit.BasicServicesKit'; 1053 1054let windowClass: window.Window | undefined = undefined; 1055window.getTopWindow((err: BusinessError, data) => { 1056 const errCode: number = err.code; 1057 if (errCode) { 1058 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1059 return; 1060 } 1061 windowClass = data; 1062 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1063}); 1064``` 1065 1066## window.getTopWindow<sup>(deprecated)</sup> 1067 1068getTopWindow(): Promise<Window> 1069 1070Obtains the top window of the current application. This API uses a promise to return the result. 1071 1072> **NOTE** 1073> 1074> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 1075 1076**Model restriction**: This API can be used only in the FA model. 1077 1078**System capability**: SystemCapability.WindowManager.WindowManager.Core 1079 1080**Return value** 1081 1082| Type | Description | 1083| -------------------------------- | ----------------------------------------------- | 1084| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1085 1086**Example** 1087 1088```ts 1089import { BusinessError } from '@kit.BasicServicesKit'; 1090 1091let windowClass: window.Window | undefined = undefined; 1092let promise = window.getTopWindow(); 1093promise.then((data)=> { 1094 windowClass = data; 1095 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1096}).catch((err: BusinessError)=>{ 1097 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1098}); 1099``` 1100 1101## window.getTopWindow<sup>(deprecated)</sup> 1102 1103getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 1104 1105Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 1106 1107> **NOTE** 1108> 1109> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 1110 1111**System capability**: SystemCapability.WindowManager.WindowManager.Core 1112 1113**Parameters** 1114 1115| Name | Type | Mandatory| Description | 1116| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1117| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1118| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. | 1119 1120**Example** 1121 1122```ts 1123// EntryAbility.ets 1124import { UIAbility } from '@kit.AbilityKit'; 1125import { BusinessError } from '@kit.BasicServicesKit'; 1126 1127export default class EntryAbility extends UIAbility { 1128 onWindowStageCreate(windowStage:window.WindowStage){ 1129 console.info('onWindowStageCreate'); 1130 let windowClass: window.Window | undefined = undefined; 1131 try { 1132 window.getTopWindow(this.context, (err: BusinessError, data) => { 1133 const errCode: number = err.code; 1134 if(errCode){ 1135 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1136 return ; 1137 } 1138 windowClass = data; 1139 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1140 }); 1141 } catch(error){ 1142 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1143 } 1144 } 1145} 1146``` 1147 1148## window.getTopWindow<sup>(deprecated)</sup> 1149 1150getTopWindow(ctx: BaseContext): Promise<Window> 1151 1152Obtains the top window of the current application. This API uses a promise to return the result. 1153 1154> **NOTE** 1155> 1156> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 1157 1158**System capability**: SystemCapability.WindowManager.WindowManager.Core 1159 1160**Parameters** 1161 1162| Name| Type | Mandatory| Description | 1163| ------ | ----------- | ---- | ------------------------------------------------------------ | 1164| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1165 1166**Return value** 1167 1168| Type | Description | 1169| -------------------------------- | ----------------------------------------------- | 1170| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1171 1172**Example** 1173 1174```ts 1175// EntryAbility.ets 1176import { UIAbility } from '@kit.AbilityKit'; 1177import { BusinessError } from '@kit.BasicServicesKit'; 1178 1179export default class EntryAbility extends UIAbility { 1180 onWindowStageCreate(windowStage:window.WindowStage) { 1181 console.info('onWindowStageCreate'); 1182 let windowClass: window.Window | undefined = undefined; 1183 let promise = window.getTopWindow(this.context); 1184 promise.then((data) => { 1185 windowClass = data; 1186 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1187 }).catch((error: BusinessError) => { 1188 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1189 }); 1190 } 1191} 1192``` 1193 1194## SpecificSystemBar<sup>11+</sup> 1195 1196type SpecificSystemBar = 'status' \| 'navigation' \| 'navigationIndicator' 1197 1198Enumerates the types of system bars that can be displayed or hidden. 1199 1200**System capability**: SystemCapability.Window.SessionManager 1201 1202**Atomic service API**: This API can be used in atomic services since API version 11. 1203 1204| Type | Description | 1205|------------|--------| 1206| 'status' | Status bar. | 1207| 'navigation' | Three-button navigation bar. | 1208| 'navigationIndicator' | Bottom navigation bar.| 1209 1210## Window 1211 1212Represents a window instance, which is the basic unit managed by the window manager. 1213 1214In 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. 1215 1216### showWindow<sup>9+</sup> 1217 1218showWindow(callback: AsyncCallback<void>): void 1219 1220Shows this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application subwindow. For the main window of an application, this API moves it at the top when the main window is already displayed. 1221 1222**System capability**: SystemCapability.WindowManager.WindowManager.Core 1223 1224**Atomic service API**: This API can be used in atomic services since API version 11. 1225 1226**Parameters** 1227 1228| Name| Type| Mandatory| Description| 1229| -------- | ------------------------- | -- | --------- | 1230| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1231 1232**Error codes** 1233 1234For details about the error codes, see [Window Error Codes](errorcode-window.md). 1235 1236| ID| Error Message| 1237| ------- | ------------------------------ | 1238| 1300002 | This window state is abnormal. | 1239 1240**Example** 1241 1242```ts 1243import { BusinessError } from '@kit.BasicServicesKit'; 1244 1245windowClass.showWindow((err: BusinessError) => { 1246 const errCode: number = err.code; 1247 if (errCode) { 1248 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1249 return; 1250 } 1251 console.info('Succeeded in showing the window.'); 1252}); 1253``` 1254 1255### showWindow<sup>9+</sup> 1256 1257showWindow(): Promise<void> 1258 1259Shows this window. This API uses a promise to return the result. This API takes effect only for a system window or an application subwindow. For the main window of an application, this API moves it at the top when the main window is already displayed. 1260 1261**System capability**: SystemCapability.WindowManager.WindowManager.Core 1262 1263**Atomic service API**: This API can be used in atomic services since API version 11. 1264 1265**Return value** 1266 1267| Type| Description| 1268| ------------------- | ----------------------- | 1269| Promise<void> | Promise that returns no value.| 1270 1271**Error codes** 1272 1273For details about the error codes, see [Window Error Codes](errorcode-window.md). 1274 1275| ID| Error Message| 1276| ------- | ------------------------------ | 1277| 1300002 | This window state is abnormal. | 1278 1279**Example** 1280 1281```ts 1282import { BusinessError } from '@kit.BasicServicesKit'; 1283 1284let promise = windowClass.showWindow(); 1285promise.then(() => { 1286 console.info('Succeeded in showing the window.'); 1287}).catch((err: BusinessError) => { 1288 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1289}); 1290``` 1291 1292### destroyWindow<sup>9+</sup> 1293 1294destroyWindow(callback: AsyncCallback<void>): void 1295 1296Destroys this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application subwindow. 1297 1298**System capability**: SystemCapability.WindowManager.WindowManager.Core 1299 1300**Atomic service API**: This API can be used in atomic services since API version 11. 1301 1302**Parameters** 1303 1304| Name| Type| Mandatory| Description| 1305| -------- | ------------------------- | -- | --------- | 1306| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1307 1308**Error codes** 1309 1310For details about the error codes, see [Window Error Codes](errorcode-window.md). 1311 1312| ID| Error Message| 1313| ------- | -------------------------------------------- | 1314| 1300002 | This window state is abnormal. | 1315| 1300003 | This window manager service works abnormally. | 1316 1317**Example** 1318 1319```ts 1320import { BusinessError } from '@kit.BasicServicesKit'; 1321 1322windowClass.destroyWindow((err) => { 1323 const errCode: number = err.code; 1324 if (errCode) { 1325 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 1326 return; 1327 } 1328 console.info('Succeeded in destroying the window.'); 1329}); 1330``` 1331 1332### destroyWindow<sup>9+</sup> 1333 1334destroyWindow(): Promise<void> 1335 1336Destroys this window. This API uses a promise to return the result. This API takes effect only for a system window or an application subwindow. 1337 1338**System capability**: SystemCapability.WindowManager.WindowManager.Core 1339 1340**Atomic service API**: This API can be used in atomic services since API version 11. 1341 1342**Return value** 1343 1344| Type| Description| 1345| ------------------- | ------------------------ | 1346| Promise<void> | Promise that returns no value.| 1347 1348**Error codes** 1349 1350For details about the error codes, see [Window Error Codes](errorcode-window.md). 1351 1352| ID| Error Message| 1353| ------- | -------------------------------------------- | 1354| 1300002 | This window state is abnormal. | 1355| 1300003 | This window manager service works abnormally. | 1356 1357**Example** 1358 1359```ts 1360import { BusinessError } from '@kit.BasicServicesKit'; 1361 1362let promise = windowClass.destroyWindow(); 1363promise.then(() => { 1364 console.info('Succeeded in destroying the window.'); 1365}).catch((err: BusinessError) => { 1366 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 1367}); 1368``` 1369 1370### moveWindowTo<sup>9+</sup> 1371 1372moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void 1373 1374Moves this window. This API uses an asynchronous callback to return the result. 1375 1376<!--RP4--> 1377In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 1378 1379On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 1380 1381**System capability**: SystemCapability.WindowManager.WindowManager.Core 1382 1383**Atomic service API**: This API can be used in atomic services since API version 11. 1384 1385**Parameters** 1386 1387| Name| Type| Mandatory| Description| 1388| -------- | ------------------------- | -- | --------------------------------------------- | 1389| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1390| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1391| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 1392 1393**Error codes** 1394 1395For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1396 1397| ID| Error Message| 1398| ------- | -------------------------------------------- | 1399| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1400| 1300002 | This window state is abnormal. | 1401| 1300003 | This window manager service works abnormally. | 1402 1403**Example** 1404 1405```ts 1406import { BusinessError } from '@kit.BasicServicesKit'; 1407 1408try { 1409 windowClass.moveWindowTo(300, 300, (err: BusinessError) => { 1410 const errCode: number = err.code; 1411 if (errCode) { 1412 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1413 return; 1414 } 1415 console.info('Succeeded in moving the window.'); 1416 }); 1417} catch (exception) { 1418 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1419} 1420``` 1421 1422### moveWindowTo<sup>9+</sup> 1423 1424moveWindowTo(x: number, y: number): Promise<void> 1425 1426Moves 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). 1427 1428<!--RP4--> 1429In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 1430 1431On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 1432 1433**System capability**: SystemCapability.WindowManager.WindowManager.Core 1434 1435**Atomic service API**: This API can be used in atomic services since API version 11. 1436 1437**Parameters** 1438 1439| Name| Type| Mandatory| Description| 1440| -- | ----- | -- | --------------------------------------------- | 1441| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1442| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1443 1444**Return value** 1445 1446| Type| Description| 1447| ------------------- | ------------------------ | 1448| Promise<void> | Promise that returns no value.| 1449 1450**Error codes** 1451 1452For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1453 1454| ID| Error Message| 1455| ------- | -------------------------------------------- | 1456| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1457| 1300002 | This window state is abnormal. | 1458| 1300003 | This window manager service works abnormally. | 1459 1460**Example** 1461 1462```ts 1463import { BusinessError } from '@kit.BasicServicesKit'; 1464 1465try { 1466 let promise = windowClass.moveWindowTo(300, 300); 1467 promise.then(() => { 1468 console.info('Succeeded in moving the window.'); 1469 }).catch((err: BusinessError) => { 1470 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1471 }); 1472} catch (exception) { 1473 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1474} 1475``` 1476 1477### moveWindowToAsync<sup>12+</sup> 1478 1479moveWindowToAsync(x: number, y: number): Promise<void> 1480 1481Moves this window. This API uses a promise to return the result. 1482 1483A value is returned once the call takes effect. You can use **getWindowProperties** in the callback (see the code snippet below) to obtain the final effect immediately. 1484 1485This API takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). 1486 1487On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 1488 1489**System capability**: SystemCapability.Window.SessionManager 1490 1491**Atomic service API**: This API can be used in atomic services since API version 12. 1492 1493**Parameters** 1494 1495| Name| Type| Mandatory| Description| 1496| -- | ----- | -- | --------------------------------------------- | 1497| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1498| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1499 1500**Return value** 1501 1502| Type| Description| 1503| ------------------- | ------------------------ | 1504| Promise<void> | Promise that returns no value.| 1505 1506**Error codes** 1507 1508For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1509 1510| ID| Error Message| 1511| ------- | -------------------------------------------- | 1512| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1513| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1514| 1300002 | This window state is abnormal. | 1515| 1300003 | This window manager service works abnormally. | 1516| 1300010 | The operation in the current window status is invalid. | 1517 1518**Example** 1519 1520```ts 1521import { BusinessError } from '@kit.BasicServicesKit'; 1522 1523try { 1524 let promise = windowClass.moveWindowToAsync(300, 300); 1525 promise.then(() => { 1526 console.info('Succeeded in moving the window.'); 1527 let rect = windowClass?.getWindowProperties().windowRect; 1528 console.info(`Get window rect: ` + JSON.stringify(rect)); 1529 }).catch((err: BusinessError) => { 1530 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1531 }); 1532} catch (exception) { 1533 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1534} 1535``` 1536 1537### moveWindowToGlobal<sup>13+</sup> 1538 1539moveWindowToGlobal(x: number, y: number): Promise<void> 1540 1541Moves this window based on the coordinates. This API uses a promise to return the result. A value is returned once the call takes effect. 1542 1543This operation is not supported in a window in full-screen mode. 1544 1545On non-2-in-1 devices, the subwindow moves along with the main window. 1546 1547**System capability**: SystemCapability.Window.SessionManager 1548 1549**Atomic service API**: This API can be used in atomic services since API version 13. 1550 1551**Parameters** 1552 1553| Name| Type| Mandatory| Description| 1554| -- | ----- | -- | --------------------------------------------- | 1555| 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.| 1556| 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.| 1557 1558**Return value** 1559 1560| Type| Description| 1561| ------------------- | ------------------------ | 1562| Promise<void> | Promise that returns no value.| 1563 1564**Error codes** 1565 1566For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1567 1568| ID| Error Message| 1569| ------- | -------------------------------------------- | 1570| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1571| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1572| 1300002 | This window state is abnormal. | 1573| 1300003 | This window manager service works abnormally. | 1574| 1300010 | The operation in the current window status is invalid. | 1575 1576**Example** 1577 1578```ts 1579import { BusinessError } from '@kit.BasicServicesKit'; 1580 1581try { 1582 let promise = windowClass.moveWindowToGlobal(300, 300); 1583 promise.then(() => { 1584 console.info('Succeeded in moving the window.'); 1585 }).catch((err: BusinessError) => { 1586 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1587 }); 1588} catch (exception) { 1589 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1590} 1591``` 1592 1593### resize<sup>9+</sup> 1594 1595resize(width: number, height: number, callback: AsyncCallback<void>): void 1596 1597Changes the size of this window. This API uses an asynchronous callback to return the result. 1598 1599The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1600 1601The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1602 1603The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 1604 1605The window width and height you set must meet the limits. The rules are as follows: 1606- 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. 1607- 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. 1608 1609This operation is not supported in a window in full-screen mode. 1610 1611**System capability**: SystemCapability.WindowManager.WindowManager.Core 1612 1613**Atomic service API**: This API can be used in atomic services since API version 11. 1614 1615**Parameters** 1616 1617| Name| Type| Mandatory| Description| 1618| -------- | ------------------------- | -- | ------------------------ | 1619| 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.| 1620| 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.| 1621| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 1622 1623**Error codes** 1624 1625For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1626 1627| ID| Error Message| 1628| ------- | -------------------------------------------- | 1629| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1630| 1300002 | This window state is abnormal. | 1631| 1300003 | This window manager service works abnormally. | 1632 1633**Example** 1634 1635```ts 1636import { BusinessError } from '@kit.BasicServicesKit'; 1637 1638try { 1639 windowClass.resize(500, 1000, (err: BusinessError) => { 1640 const errCode: number = err.code; 1641 if (errCode) { 1642 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 1643 return; 1644 } 1645 console.info('Succeeded in changing the window size.'); 1646 }); 1647} catch (exception) { 1648 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 1649} 1650``` 1651 1652### resize<sup>9+</sup> 1653 1654resize(width: number, height: number): Promise<void> 1655 1656Changes the size of this window. This API uses a promise to return the result. 1657 1658A 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). 1659 1660The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1661 1662The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1663 1664The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 1665 1666The window width and height you set must meet the limits. The rules are as follows: 1667- 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. 1668- 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. 1669 1670This operation is not supported in a window in full-screen mode. 1671 1672**System capability**: SystemCapability.WindowManager.WindowManager.Core 1673 1674**Atomic service API**: This API can be used in atomic services since API version 11. 1675 1676**Parameters** 1677 1678| Name| Type| Mandatory| Description| 1679| ------ | ------ | -- | ------------------------ | 1680| 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.| 1681| 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.| 1682 1683**Return value** 1684 1685| Type| Description| 1686| ------------------- | ------------------------ | 1687| Promise<void> | Promise that returns no value.| 1688 1689**Error codes** 1690 1691For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1692 1693| ID| Error Message| 1694| ------- | -------------------------------------------- | 1695| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1696| 1300002 | This window state is abnormal. | 1697| 1300003 | This window manager service works abnormally. | 1698 1699**Example** 1700 1701```ts 1702import { BusinessError } from '@kit.BasicServicesKit'; 1703 1704try { 1705 let promise = windowClass.resize(500, 1000); 1706 promise.then(() => { 1707 console.info('Succeeded in changing the window size.'); 1708 }).catch((err: BusinessError) => { 1709 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 1710 }); 1711} catch (exception) { 1712 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 1713} 1714``` 1715 1716### resizeAsync<sup>12+</sup> 1717 1718resizeAsync(width: number, height: number): Promise<void> 1719 1720Changes the size of this window. This API uses a promise to return the result. 1721 1722A value is returned once the call takes effect. You can use **getWindowProperties** in the callback (see the code snippet below) to obtain the final effect immediately. 1723 1724The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1725 1726The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1727 1728The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 1729 1730The window width and height you set must meet the limits. The rules are as follows: 1731 1732- 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. 1733- 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. 1734 1735This operation is not supported in a window in full-screen mode. 1736 1737**System capability**: SystemCapability.Window.SessionManager 1738 1739**Atomic service API**: This API can be used in atomic services since API version 12. 1740 1741**Parameters** 1742 1743| Name| Type| Mandatory| Description| 1744| ------ | ------ | -- | ------------------------ | 1745| 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.| 1746| 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.| 1747 1748**Return value** 1749 1750| Type| Description| 1751| ------------------- | ------------------------ | 1752| Promise<void> | Promise that returns no value.| 1753 1754**Error codes** 1755 1756For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1757 1758| ID| Error Message| 1759| ------- | -------------------------------------------- | 1760| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1761| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1762| 1300002 | This window state is abnormal. | 1763| 1300003 | This window manager service works abnormally. | 1764| 1300010 | The operation in the current window status is invalid. | 1765 1766**Example** 1767 1768```ts 1769import { BusinessError } from '@kit.BasicServicesKit'; 1770 1771try { 1772 let promise = windowClass.resizeAsync(500, 1000); 1773 promise.then(() => { 1774 console.info('Succeeded in changing the window size.'); 1775 let rect = windowClass?.getWindowProperties().windowRect; 1776 console.info(`Get window rect: ` + JSON.stringify(rect)); 1777 }).catch((err: BusinessError) => { 1778 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 1779 }); 1780} catch (exception) { 1781 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 1782} 1783``` 1784 1785### getWindowProperties<sup>9+</sup> 1786 1787getWindowProperties(): WindowProperties 1788 1789Obtains the properties of this window. 1790 1791**System capability**: SystemCapability.WindowManager.WindowManager.Core 1792 1793**Atomic service API**: This API can be used in atomic services since API version 11. 1794 1795**Return value** 1796 1797| Type| Description| 1798| ------------------------------------- | ------------- | 1799| [WindowProperties](#windowproperties) | Window properties obtained.| 1800 1801**Error codes** 1802 1803For details about the error codes, see [Window Error Codes](errorcode-window.md). 1804 1805| ID| Error Message| 1806| ------- | ------------------------------ | 1807| 1300002 | This window state is abnormal. | 1808 1809**Example** 1810 1811```ts 1812try { 1813 let properties = windowClass.getWindowProperties(); 1814} catch (exception) { 1815 console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`); 1816} 1817``` 1818 1819### getGlobalRect<sup>13+</sup> 1820 1821getGlobalRect(): Rect 1822 1823Obtains the actual display area of this window on the screen. This API returns the result synchronously. 1824 1825This API can determine the actual on-screen location and size of a window that has been resized on certain devices. 1826 1827**System capability**: SystemCapability.Window.SessionManager 1828 1829**Atomic service API**: This API can be used in atomic services since API version 13. 1830 1831**Return value** 1832 1833| Type| Description| 1834| ------------------- | ------------------------ | 1835| [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.| 1836 1837**Error codes** 1838 1839For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1840 1841| ID| Error Message| 1842| ------- | -------------------------------------------- | 1843| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1844| 1300002 | This window state is abnormal. | 1845| 1300003 | This window manager service works abnormally. | 1846 1847**Example** 1848 1849```ts 1850try { 1851 let rect = windowClass.getGlobalRect(); 1852 console.info(`Succeeded in getting window rect: ` + JSON.stringify(rect)); 1853} catch (exception) { 1854 console.error(`Failed to get window rect. Cause code: ${exception.code}, message: ${exception.message}`); 1855} 1856``` 1857 1858### getWindowAvoidArea<sup>9+</sup> 1859 1860getWindowAvoidArea(type: AvoidAreaType): AvoidArea 1861 1862Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. 1863 1864This API can be used in the **onWindowStageCreate** callback to obtain the avoid area in the initial layout during application startup. It can also be used when a subwindow requires temporary display, necessitating the avoidance of the layout for the existing content. 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| type | [AvoidAreaType](#avoidareatype7) | Yes| Type of the area.| 1875 1876**Return value** 1877 1878| Type| Description| 1879|--------------------------| ----------------- | 1880| [AvoidArea](#avoidarea7) | Area where the window cannot be displayed.| 1881 1882**Error codes** 1883 1884For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1885 1886| ID| Error Message| 1887| ------- | ------------------------------ | 1888| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1889| 1300002 | This window state is abnormal. | 1890 1891**Example** 1892 1893```ts 1894let type = window.AvoidAreaType.TYPE_SYSTEM; 1895try { 1896 let avoidArea = windowClass.getWindowAvoidArea(type); 1897} catch (exception) { 1898 console.error(`Failed to obtain the area. Cause code: ${exception.code}, message: ${exception.message}`); 1899} 1900``` 1901 1902### setTitleAndDockHoverShown<sup>14+</sup> 1903 1904setTitleAndDockHoverShown(isTitleHoverShown?: boolean, isDockHoverShown?: boolean): Promise<void> 1905 1906Sets 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. 1907 1908**System capability**: SystemCapability.Window.SessionManager 1909 1910**Atomic service API**: This API can be used in atomic services since API version 14. 1911 1912**Parameters** 1913 1914| Name | Type | Mandatory| Description | 1915| ---------- | ------- | ---- | ------------------------------------------------------------ | 1916| 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**.| 1917| 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**.| 1918 1919**Error codes** 1920 1921For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1922 1923| ID| Error Message| 1924| ------- | -------------------------------------------- | 1925| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1926| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1927| 1300002 | This window state is abnormal. | 1928| 1300004 | Unauthorized operation. | 1929 1930**Example** 1931 1932```ts 1933// EntryAbility.ets 1934import { UIAbility } from '@kit.AbilityKit'; 1935import { BusinessError } from '@kit.BasicServicesKit'; 1936import { window } from '@kit.ArkUI'; 1937 1938export default class EntryAbility extends UIAbility { 1939 // ... 1940 onWindowStageCreate(windowStage: window.WindowStage): void { 1941 // Load the page corresponding to the main window. 1942 windowStage.loadContent('pages/Index', (err) => { 1943 let mainWindow: window.Window | undefined = undefined; 1944 // Obtain the main window. 1945 windowStage.getMainWindow().then( 1946 data => { 1947 mainWindow = data; 1948 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 1949 // Call maximize to enable the full-screen mode for the window. 1950 mainWindow.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 1951 // Call setTitleAndDockHoverShown to hide the window title bar and dock bar. 1952 mainWindow.setTitleAndDockHoverShown(false, false); 1953 } 1954 ).catch((err: BusinessError) => { 1955 if(err.code){ 1956 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1957 } 1958 }); 1959 }); 1960 } 1961} 1962``` 1963 1964### setWindowLayoutFullScreen<sup>9+</sup> 1965 1966setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 1967 1968Sets whether the main window layout or the subwindow 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--> 1969- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 1970- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 1971 1972**System capability**: SystemCapability.WindowManager.WindowManager.Core 1973 1974**Atomic service API**: This API can be used in atomic services since API version 12. 1975 1976**Parameters** 1977 1978| Name| Type| Mandatory| Description| 1979| ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ | 1980| isLayoutFullScreen | boolean | Yes| Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window layout is immersive, and **false** means the opposite.| 1981 1982**Return value** 1983 1984| Type| Description| 1985| ------------------- | ------------------------ | 1986| Promise<void> | Promise that returns no value.| 1987 1988**Error codes** 1989 1990For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1991 1992| ID| Error Message| 1993| ------- | -------------------------------------------- | 1994| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1995| 1300002 | This window state is abnormal. | 1996| 1300003 | This window manager service works abnormally. | 1997 1998**Example** 1999 2000```ts 2001// EntryAbility.ets 2002import { UIAbility } from '@kit.AbilityKit'; 2003import { BusinessError } from '@kit.BasicServicesKit'; 2004 2005export default class EntryAbility extends UIAbility { 2006 // ... 2007 onWindowStageCreate(windowStage: window.WindowStage): void { 2008 console.info('onWindowStageCreate'); 2009 let windowClass: window.Window | undefined = undefined; 2010 windowStage.getMainWindow((err: BusinessError, data) => { 2011 const errCode: number = err.code; 2012 if (errCode) { 2013 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2014 return; 2015 } 2016 windowClass = data; 2017 let isLayoutFullScreen = true; 2018 try { 2019 let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen); 2020 promise.then(() => { 2021 console.info('Succeeded in setting the window layout to full-screen mode.'); 2022 }).catch((err: BusinessError) => { 2023 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 2024 }); 2025 } catch (exception) { 2026 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 2027 } 2028 }); 2029 } 2030} 2031``` 2032 2033### setImmersiveModeEnabledState<sup>12+</sup> 2034 2035setImmersiveModeEnabledState(enabled: boolean): void 2036 2037Sets 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--> 2038 2039**System capability**: SystemCapability.WindowManager.WindowManager.Core 2040 2041**Atomic service API**: This API can be used in atomic services since API version 12. 2042 2043**Parameters** 2044 2045| Name | Type | Mandatory| Description | 2046| ---------- | ------- | ---- | ------------------------------------------------------------ | 2047| enabled | boolean | Yes | Whether to enable the immersive layout.<br>The value **true** means to enable the immersive layout, and **false** means the opposite.| 2048 2049**Error codes** 2050 2051For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2052 2053| ID| Error Message| 2054| ------- | -------------------------------------------- | 2055| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2056| 1300002 | This window state is abnormal. | 2057| 1300003 | This window manager service works abnormally. | 2058| 1300004 | Unauthorized operation. | 2059 2060**Example** 2061 2062```ts 2063try { 2064 let enabled = false; 2065 windowClass.setImmersiveModeEnabledState(enabled); 2066} catch (exception) { 2067 console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 2068} 2069``` 2070 2071### getImmersiveModeEnabledState<sup>12+</sup> 2072 2073getImmersiveModeEnabledState(): boolean 2074 2075Checks whether the immersive layout is enabled for this window. 2076 2077**System capability**: SystemCapability.WindowManager.WindowManager.Core 2078 2079**Atomic service API**: This API can be used in atomic services since API version 12. 2080 2081**Return value** 2082| Type | Description | 2083| ------- | ------------------------------------------------------------------------------------ | 2084| 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.| 2085 2086**Error codes** 2087 2088For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2089 2090| ID| Error Message| 2091| -------- | -------------------------------------------- | 2092| 1300002 | This window state is abnormal. | 2093| 1300003 | This window manager service works abnormally. | 2094| 1300004 | Unauthorized operation. | 2095 2096**Example** 2097 2098```ts 2099try { 2100 let isEnabled = windowClass.getImmersiveModeEnabledState(); 2101} catch (exception) { 2102 console.error(`Failed to get the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 2103} 2104``` 2105 2106### setWindowSystemBarEnable<sup>9+</sup> 2107 2108setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 2109 2110Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses a promise to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 2111 2112The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow. 2113 2114**Atomic service API**: This API can be used in atomic services since API version 12. 2115 2116**System capability**: SystemCapability.WindowManager.WindowManager.Core 2117 2118**Parameters** 2119 2120| Name| Type | Mandatory| Description| 2121| ----- | ---------------------------- | -- | --------------------------------- | 2122| names | Array<'status'\|'navigation'> | Yes| Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.<br>For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.| 2123 2124**Return value** 2125 2126| Type| Description| 2127| ------------------- | ------------------------ | 2128| Promise<void> | Promise that returns no value.| 2129 2130**Error codes** 2131 2132For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2133 2134| ID| Error Message| 2135| ------- | -------------------------------------------- | 2136| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2137| 1300002 | This window state is abnormal. | 2138| 1300003 | This window manager service works abnormally. | 2139 2140**Example** 2141 2142```ts 2143// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 2144// EntryAbility.ets 2145import { UIAbility } from '@kit.AbilityKit'; 2146import { BusinessError } from '@kit.BasicServicesKit'; 2147 2148export default class EntryAbility extends UIAbility { 2149 // ... 2150 onWindowStageCreate(windowStage: window.WindowStage): void { 2151 console.info('onWindowStageCreate'); 2152 let windowClass: window.Window | undefined = undefined; 2153 windowStage.getMainWindow((err: BusinessError, data) => { 2154 const errCode: number = err.code; 2155 if (errCode) { 2156 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2157 return; 2158 } 2159 windowClass = data; 2160 let names: Array<'status' | 'navigation'> = []; 2161 try { 2162 let promise = windowClass.setWindowSystemBarEnable(names); 2163 promise.then(() => { 2164 console.info('Succeeded in setting the system bar to be invisible.'); 2165 }).catch((err: BusinessError) => { 2166 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 2167 }); 2168 } catch (exception) { 2169 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 2170 } 2171 }); 2172 } 2173} 2174``` 2175 2176### setSpecificSystemBarEnabled<sup>11+</sup> 2177 2178setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void> 2179 2180Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses a promise to return the result. From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 2181 2182The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow. 2183 2184**System capability**: SystemCapability.Window.SessionManager 2185 2186**Atomic service API**: This API can be used in atomic services since API version 11. 2187 2188**Parameters** 2189 2190| Name| Type | Mandatory| Description| 2191| ----- | ---------------------------- | -- | --------------------------------- | 2192| name | [SpecificSystemBar](#specificsystembar11) | Yes| Type of the system bar to be shown or hidden.| 2193| enable | boolean | Yes| Whether to show the three-button navigation bar, status bar, and bottom navigation bar. The value **true** means to show them, and **false** means to hide them.| 2194| enableAnimation<sup>12+</sup> | boolean | No| Whether to enable animation when the three-button navigation bar, status bar, and bottom navigation bar status changes. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.| 2195 2196**Return value** 2197 2198| Type| Description| 2199| ------------------- | ------------------------ | 2200| Promise<void> | Promise that returns no value.| 2201 2202**Error codes** 2203 2204For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2205 2206| ID| Error Message| 2207| ------- | -------------------------------------------- | 2208| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2209| 1300002 | This window state is abnormal. | 2210| 1300003 | This window manager service works abnormally. | 2211 2212**Example** 2213 2214```ts 2215// Hide the bottom navigation bar. 2216// EntryAbility.ets 2217import { UIAbility } from '@kit.AbilityKit'; 2218import { BusinessError } from '@kit.BasicServicesKit'; 2219 2220export default class EntryAbility extends UIAbility { 2221 // ... 2222 onWindowStageCreate(windowStage: window.WindowStage): void { 2223 console.info('onWindowStageCreate'); 2224 let windowClass: window.Window | undefined = undefined; 2225 windowStage.getMainWindow((err: BusinessError, data) => { 2226 const errCode: number = err.code; 2227 if (errCode) { 2228 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2229 return; 2230 } 2231 windowClass = data; 2232 try { 2233 let promise = windowClass.setSpecificSystemBarEnabled('navigationIndicator', false); 2234 promise.then(() => { 2235 console.info('Succeeded in setting the system bar to be invisible.'); 2236 }).catch((err: BusinessError) => { 2237 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 2238 }); 2239 } catch (exception) { 2240 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 2241 } 2242 }); 2243 } 2244} 2245``` 2246 2247### setWindowSystemBarProperties<sup>9+</sup> 2248 2249setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 2250 2251Sets the properties of the three-button navigation bar and 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--> 2252 2253This API does not take effect when it is called by a subwindow. 2254 2255**System capability**: SystemCapability.WindowManager.WindowManager.Core 2256 2257**Atomic service API**: This API can be used in atomic services since API version 12. 2258 2259**Parameters** 2260 2261| Name | Type | Mandatory| Description | 2262| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2263| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.| 2264 2265**Return value** 2266 2267| Type | Description | 2268| ------------------- | ------------------------- | 2269| Promise<void> | Promise that returns no value.| 2270 2271**Error codes** 2272 2273For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2274 2275| ID| Error Message| 2276| ------- | -------------------------------------------- | 2277| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2278| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2279| 1300002 | This window state is abnormal. | 2280| 1300003 | This window manager service works abnormally. | 2281 2282**Example** 2283 2284```ts 2285// EntryAbility.ets 2286import { UIAbility } from '@kit.AbilityKit'; 2287import { BusinessError } from '@kit.BasicServicesKit'; 2288 2289export default class EntryAbility extends UIAbility { 2290 // ... 2291 onWindowStageCreate(windowStage: window.WindowStage): void { 2292 console.info('onWindowStageCreate'); 2293 let windowClass: window.Window | undefined = undefined; 2294 windowStage.getMainWindow((err: BusinessError, data) => { 2295 const errCode: number = err.code; 2296 if (errCode) { 2297 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2298 return; 2299 } 2300 windowClass = data; 2301 let SystemBarProperties: window.SystemBarProperties = { 2302 statusBarColor: '#ff00ff', 2303 navigationBarColor: '#00ff00', 2304 // The following properties are supported since API version 8. 2305 statusBarContentColor: '#ffffff', 2306 navigationBarContentColor: '#00ffff' 2307 }; 2308 try { 2309 let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties); 2310 promise.then(() => { 2311 console.info('Succeeded in setting the system bar properties.'); 2312 }).catch((err: BusinessError) => { 2313 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 2314 }); 2315 } catch (exception) { 2316 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 2317 } 2318 }); 2319 } 2320} 2321``` 2322 2323### getWindowSystemBarProperties<sup>12+</sup> 2324 2325getWindowSystemBarProperties(): SystemBarProperties 2326 2327Obtains the properties of the three-button navigation bar and status bar of the main window. 2328 2329**System capability**: SystemCapability.WindowManager.WindowManager.Core 2330 2331**Atomic service API**: This API can be used in atomic services since API version 12. 2332 2333**Return value** 2334 2335| Type| Description| 2336| ------------------------------------- | ------------- | 2337| [SystemBarProperties](#systembarproperties) | Properties of the three-button navigation bar and status bar.| 2338 2339**Error codes** 2340 2341For details about the error codes, see [Window Error Codes](errorcode-window.md). 2342 2343| ID| Error Message| 2344| ------- | ------------------------------ | 2345| 1300002 | This window state is abnormal. | 2346| 1300003 | This window manager service works abnormally. | 2347| 1300004 | Unauthorized operation. | 2348 2349 2350**Example** 2351 2352```ts 2353// EntryAbility.ets 2354import { UIAbility } from '@kit.AbilityKit'; 2355import { BusinessError } from '@kit.BasicServicesKit'; 2356 2357export default class EntryAbility extends UIAbility { 2358 // ... 2359 2360 onWindowStageCreate(windowStage: window.WindowStage) { 2361 let windowClass: window.Window | undefined = undefined; 2362 windowStage.getMainWindow((err: BusinessError, data) => { 2363 const errCode: number = err.code; 2364 if (errCode) { 2365 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2366 return; 2367 } 2368 windowClass = data; 2369 try { 2370 let systemBarProperty = windowClass.getWindowSystemBarProperties(); 2371 console.info('Success in obtaining system bar properties. Property: ' + JSON.stringify(systemBarProperty)); 2372 } catch (err) { 2373 console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`); 2374 } 2375 }); 2376 } 2377}; 2378``` 2379 2380### setPreferredOrientation<sup>9+</sup> 2381 2382setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 2383 2384Sets 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 subwindow mode.<!--RP9End--> 2385 2386**System capability**: SystemCapability.WindowManager.WindowManager.Core 2387 2388**Atomic service API**: This API can be used in atomic services since API version 11. 2389 2390**Parameters** 2391 2392| Name | Type | Mandatory| Description | 2393| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2394| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 2395| 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.| 2396 2397**Error codes** 2398 2399For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2400 2401| ID| Error Message| 2402| ------- | ------------------------------ | 2403| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2404| 1300002 | This window state is abnormal. | 2405 2406**Example** 2407 2408```ts 2409// EntryAbility.ets 2410import { UIAbility } from '@kit.AbilityKit'; 2411import { BusinessError } from '@kit.BasicServicesKit'; 2412 2413export default class EntryAbility extends UIAbility { 2414 // ... 2415 onWindowStageCreate(windowStage: window.WindowStage): void { 2416 console.info('onWindowStageCreate'); 2417 let windowClass: window.Window | undefined = undefined; 2418 windowStage.getMainWindow((err: BusinessError, data) => { 2419 const errCode: number = err.code; 2420 if (errCode) { 2421 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2422 return; 2423 } 2424 windowClass = data; 2425 let orientation = window.Orientation.AUTO_ROTATION; 2426 try { 2427 windowClass.setPreferredOrientation(orientation, (err: BusinessError) => { 2428 const errCode: number = err.code; 2429 if (errCode) { 2430 console.error(`Failed to set window orientation. Cause code: ${err.code}, message: ${err.message}`); 2431 return; 2432 } 2433 console.info('Succeeded in setting window orientation.'); 2434 }); 2435 } catch (exception) { 2436 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2437 } 2438 }); 2439 } 2440} 2441``` 2442 2443### setPreferredOrientation<sup>9+</sup> 2444 2445setPreferredOrientation(orientation: Orientation): Promise<void> 2446 2447Sets 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 subwindow mode.<!--RP9End--> 2448 2449**System capability**: SystemCapability.WindowManager.WindowManager.Core 2450 2451**Atomic service API**: This API can be used in atomic services since API version 11. 2452 2453**Parameters** 2454 2455| Name | Type | Mandatory| Description | 2456| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2457| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 2458 2459**Return value** 2460 2461| Type | Description | 2462| ------------------- | ------------------------- | 2463| Promise<void> | Promise that returns no value.| 2464 2465**Error codes** 2466 2467For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2468 2469| ID| Error Message| 2470| ------- | ------------------------------ | 2471| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2472| 1300002 | This window state is abnormal. | 2473 2474**Example** 2475 2476```ts 2477// EntryAbility.ets 2478import { UIAbility } from '@kit.AbilityKit'; 2479import { BusinessError } from '@kit.BasicServicesKit'; 2480 2481export default class EntryAbility extends UIAbility { 2482 // ... 2483 onWindowStageCreate(windowStage: window.WindowStage): void { 2484 console.info('onWindowStageCreate'); 2485 let windowClass: window.Window | undefined = undefined; 2486 windowStage.getMainWindow((err: BusinessError, data) => { 2487 const errCode: number = err.code; 2488 if (errCode) { 2489 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2490 return; 2491 } 2492 windowClass = data; 2493 let orientation = window.Orientation.AUTO_ROTATION; 2494 try { 2495 let promise = windowClass.setPreferredOrientation(orientation); 2496 promise.then(() => { 2497 console.info('Succeeded in setting the window orientation.'); 2498 }).catch((err: BusinessError) => { 2499 console.error(`Failed to set the window orientation. Cause code: ${err.code}, message: ${err.message}`); 2500 }); 2501 } catch (exception) { 2502 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2503 } 2504 }); 2505 } 2506} 2507``` 2508 2509### getPreferredOrientation<sup>12+</sup> 2510 2511getPreferredOrientation(): Orientation 2512 2513Obtains the orientation of the main window. This API can be called only by the main window. 2514 2515**System capability**: SystemCapability.WindowManager.WindowManager.Core 2516 2517**Atomic service API**: This API can be used in atomic services since API version 12. 2518 2519**Return value** 2520 2521| Type| Description| 2522|------------------------------| ------------------ | 2523| [Orientation](#orientation9) | Orientation.| 2524 2525**Error codes** 2526 2527For details about the error codes, see [Window Error Codes](errorcode-window.md). 2528 2529| ID| Error Message| 2530| ------- | ------------------------------ | 2531| 1300002 | This window state is abnormal. | 2532 2533**Example** 2534 2535```ts 2536// EntryAbility.ets 2537import { UIAbility } from '@kit.AbilityKit'; 2538import { BusinessError } from '@kit.BasicServicesKit'; 2539export default class EntryAbility extends UIAbility { 2540 // ... 2541 2542 onWindowStageCreate(windowStage: window.WindowStage) { 2543 console.info('onWindowStageCreate'); 2544 let windowClass: window.Window | undefined = undefined; 2545 windowStage.getMainWindow((err: BusinessError, data) => { 2546 const errCode: number = err.code; 2547 if (errCode) { 2548 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2549 return; 2550 } 2551 windowClass = data; 2552 try { 2553 let orientation = windowClass.getPreferredOrientation(); 2554 } catch (exception) { 2555 console.error(`Failed to get window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2556 } 2557 }); 2558 } 2559}; 2560``` 2561 2562### getUIContext<sup>10+</sup> 2563 2564getUIContext(): UIContext 2565 2566Obtain a **UIContext** instance. 2567 2568**Model restriction**: This API can be used only in the stage model. 2569 2570**System capability**: SystemCapability.WindowManager.WindowManager.Core 2571 2572**Atomic service API**: This API can be used in atomic services since API version 11. 2573 2574**Return value** 2575 2576| Type | Description | 2577| ---------- | ---------------------- | 2578| [UIContext](js-apis-arkui-UIContext.md#uicontext) | **UIContext** instance obtained.| 2579 2580**Error codes** 2581 2582For details about the error codes, see [Window Error Codes](errorcode-window.md). 2583 2584| ID| Error Message| 2585| ------- | ------------------------------ | 2586| 1300002 | This window state is abnormal. | 2587 2588**Example** 2589 2590```ts 2591// EntryAbility.ets 2592import { UIAbility } from '@kit.AbilityKit'; 2593import { window, UIContext } from '@kit.ArkUI'; 2594import { BusinessError } from '@kit.BasicServicesKit'; 2595 2596export default class EntryAbility extends UIAbility { 2597 onWindowStageCreate(windowStage: window.WindowStage) { 2598 // Load content for the main window. 2599 windowStage.loadContent("pages/page2", (err: BusinessError) => { 2600 let errCode: number = err.code; 2601 if (errCode) { 2602 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2603 return; 2604 } 2605 console.info('Succeeded in loading the content.'); 2606 // Obtain the main window. 2607 let windowClass: window.Window | undefined = undefined; 2608 windowStage.getMainWindow((err: BusinessError, data) => { 2609 let errCode: number = err.code; 2610 if (errCode) { 2611 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2612 return; 2613 } 2614 windowClass = data; 2615 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 2616 // Obtain a UIContext instance. 2617 let uiContext: UIContext | null = null; 2618 uiContext = windowClass.getUIContext(); 2619 }); 2620 }); 2621 } 2622}; 2623``` 2624 2625### setUIContent<sup>9+</sup> 2626 2627setUIContent(path: string, callback: AsyncCallback<void>): void 2628 2629Loads 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. 2630 2631**System capability**: SystemCapability.WindowManager.WindowManager.Core 2632 2633**Atomic service API**: This API can be used in atomic services since API version 11. 2634 2635**Parameters** 2636 2637| Name| Type| Mandatory| Description| 2638| -------- | ------------------------- | -- | -------------------- | 2639| 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.| 2640| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 2641 2642**Error codes** 2643 2644For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2645 2646| ID| Error Message| 2647| ------- | -------------------------------------------- | 2648| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2649| 1300002 | This window state is abnormal. | 2650| 1300003 | This window manager service works abnormally. | 2651 2652**Example** 2653 2654```ts 2655import { BusinessError } from '@kit.BasicServicesKit'; 2656 2657try { 2658 windowClass.setUIContent('pages/page2/page3', (err: BusinessError) => { 2659 const errCode: number = err.code; 2660 if (errCode) { 2661 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2662 return; 2663 } 2664 console.info('Succeeded in loading the content.'); 2665 }); 2666} catch (exception) { 2667 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2668} 2669``` 2670 2671### setUIContent<sup>9+</sup> 2672 2673setUIContent(path: string): Promise<void> 2674 2675Loads 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. 2676 2677**System capability**: SystemCapability.WindowManager.WindowManager.Core 2678 2679**Atomic service API**: This API can be used in atomic services since API version 11. 2680 2681**Parameters** 2682 2683| Name| Type| Mandatory| Description| 2684| ---- | ------ | -- | ------------------ | 2685| 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.| 2686 2687**Return value** 2688 2689| Type| Description| 2690| ------------------- | ------------------------ | 2691| Promise<void> | Promise that returns no value.| 2692 2693**Error codes** 2694 2695For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2696 2697| ID| Error Message| 2698| ------- | -------------------------------------------- | 2699| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2700| 1300002 | This window state is abnormal. | 2701| 1300003 | This window manager service works abnormally. | 2702 2703**Example** 2704 2705```ts 2706import { BusinessError } from '@kit.BasicServicesKit'; 2707 2708try { 2709 let promise = windowClass.setUIContent('pages/page2/page3'); 2710 promise.then(() => { 2711 console.info('Succeeded in loading the content.'); 2712 }).catch((err: BusinessError) => { 2713 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2714 }); 2715} catch (exception) { 2716 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2717} 2718``` 2719 2720### loadContent<sup>9+</sup> 2721 2722loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 2723 2724Loads 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. 2725 2726**Model restriction**: This API can be used only in the stage model. 2727 2728**System capability**: SystemCapability.WindowManager.WindowManager.Core 2729 2730**Atomic service API**: This API can be used in atomic services since API version 11. 2731 2732**Parameters** 2733 2734| Name | Type | Mandatory| Description | 2735| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 2736| 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.| 2737| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 2738| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 2739 2740**Error codes** 2741 2742For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2743 2744| ID| Error Message| 2745| ------- | -------------------------------------------- | 2746| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2747| 1300002 | This window state is abnormal. | 2748| 1300003 | This window manager service works abnormally. | 2749 2750**Example** 2751 2752```ts 2753import { BusinessError } from '@kit.BasicServicesKit'; 2754 2755let storage: LocalStorage = new LocalStorage(); 2756storage.setOrCreate('storageSimpleProp', 121); 2757windowClass.loadContent('pages/page2', storage, (err: BusinessError) => { 2758 const errCode: number = err.code; 2759 if (errCode) { 2760 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2761 return; 2762 } 2763 console.info('Succeeded in loading the content.'); 2764}); 2765``` 2766 2767### loadContent<sup>9+</sup> 2768 2769loadContent(path: string, storage: LocalStorage): Promise<void> 2770 2771Loads 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. 2772 2773**Model restriction**: This API can be used only in the stage model. 2774 2775**System capability**: SystemCapability.WindowManager.WindowManager.Core 2776 2777**Atomic service API**: This API can be used in atomic services since API version 11. 2778 2779**Parameters** 2780 2781| Name | Type | Mandatory| Description | 2782| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 2783| 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.| 2784| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 2785 2786**Return value** 2787 2788| Type | Description | 2789| ------------------- | ------------------------- | 2790| Promise<void> | Promise that returns no value.| 2791 2792**Error codes** 2793 2794For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2795 2796| ID| Error Message| 2797| ------- | -------------------------------------------- | 2798| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2799| 1300002 | This window state is abnormal. | 2800| 1300003 | This window manager service works abnormally. | 2801 2802**Example** 2803 2804```ts 2805import { BusinessError } from '@kit.BasicServicesKit'; 2806 2807let storage: LocalStorage = new LocalStorage(); 2808storage.setOrCreate('storageSimpleProp', 121); 2809let promise = windowClass.loadContent('pages/page2', storage); 2810promise.then(() => { 2811 console.info('Succeeded in loading the content.'); 2812}).catch((err: BusinessError) => { 2813 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2814}); 2815``` 2816 2817### loadContentByName<sup>11+</sup> 2818 2819loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 2820 2821Loads 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. 2822 2823**Model restriction**: This API can be used only in the stage model. 2824 2825**System capability**: SystemCapability.WindowManager.WindowManager.Core 2826 2827**Atomic service API**: This API can be used in atomic services since API version 11. 2828 2829**Parameters** 2830 2831| Name | Type | Mandatory| Description | 2832| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 2833| name | string | Yes | Name of the named route page. | 2834| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 2835| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 2836 2837**Error codes** 2838 2839For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2840 2841| ID| Error Message | 2842| -------- | --------------------------------------------- | 2843| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2844| 1300002 | This window state is abnormal. | 2845| 1300003 | This window manager service works abnormally. | 2846 2847**Example** 2848<!--code_no_check--> 2849```ts 2850import { BusinessError } from '@kit.BasicServicesKit'; 2851import * as Index from '../pages/Index'; // Import the named route page. 2852 2853console.info('onWindowStageCreate'); 2854let storage: LocalStorage = new LocalStorage(); 2855storage.setOrCreate('storageSimpleProp', 121); 2856try { 2857 (windowClass as window.Window).loadContentByName(Index.entryName, storage, (err: BusinessError) => { 2858 const errCode: number = err.code; 2859 if (errCode) { 2860 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2861 return; 2862 } 2863 console.info('Succeeded in loading the content.'); 2864 }); 2865} catch (exception) { 2866 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2867} 2868``` 2869<!--code_no_check--> 2870```ts 2871// ets/pages/Index.ets 2872export const entryName : string = 'Index'; 2873@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 2874@Component 2875export struct Index { 2876 @State message: string = 'Hello World' 2877 build() { 2878 Row() { 2879 Column() { 2880 Text(this.message) 2881 .fontSize(50) 2882 .fontWeight(FontWeight.Bold) 2883 } 2884 .width('100%') 2885 } 2886 .height('100%') 2887 } 2888} 2889``` 2890 2891### loadContentByName<sup>11+</sup> 2892 2893loadContentByName(name: string, callback: AsyncCallback<void>): void 2894 2895Loads 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. 2896 2897**Model restriction**: This API can be used only in the stage model. 2898 2899**System capability**: SystemCapability.WindowManager.WindowManager.Core 2900 2901**Atomic service API**: This API can be used in atomic services since API version 11. 2902 2903**Parameters** 2904 2905| Name | Type | Mandatory| Description | 2906| -------- | ------------------------- | ---- | ---------------- | 2907| name | string | Yes | Name of the named route page.| 2908| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 2909 2910**Error codes** 2911 2912For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2913 2914| ID| Error Message | 2915| -------- | --------------------------------------------- | 2916| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2917| 1300002 | This window state is abnormal. | 2918| 1300003 | This window manager service works abnormally. | 2919 2920**Example** 2921<!--code_no_check--> 2922```ts 2923import { BusinessError } from '@kit.BasicServicesKit'; 2924import * as Index from '../pages/Index'; // Import the named route page. 2925 2926try { 2927 (windowClass as window.Window).loadContentByName(Index.entryName, (err: BusinessError) => { 2928 const errCode: number = err.code; 2929 if (errCode) { 2930 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2931 return; 2932 } 2933 console.info('Succeeded in loading the content.'); 2934 }); 2935} catch (exception) { 2936 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2937} 2938``` 2939<!--code_no_check--> 2940```ts 2941// ets/pages/Index.ets 2942export const entryName : string = 'Index'; 2943@Entry({routeName: entryName}) 2944@Component 2945export struct Index { 2946 @State message: string = 'Hello World' 2947 build() { 2948 Row() { 2949 Column() { 2950 Text(this.message) 2951 .fontSize(50) 2952 .fontWeight(FontWeight.Bold) 2953 } 2954 .width('100%') 2955 } 2956 .height('100%') 2957 } 2958} 2959``` 2960 2961### loadContentByName<sup>11+</sup> 2962 2963loadContentByName(name: string, storage?: LocalStorage): Promise<void> 2964 2965Loads 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. 2966 2967**Model restriction**: This API can be used only in the stage model. 2968 2969**System capability**: SystemCapability.WindowManager.WindowManager.Core 2970 2971**Atomic service API**: This API can be used in atomic services since API version 11. 2972 2973**Parameters** 2974 2975| Name | Type | Mandatory| Description | 2976| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 2977| name | string | Yes | Name of the named route page. | 2978| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 2979 2980**Return value** 2981 2982| Type | Description | 2983| ------------------- | ------------------------- | 2984| Promise<void> | Promise that returns no value.| 2985 2986**Error codes** 2987 2988For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2989 2990| ID| Error Message | 2991| -------- | --------------------------------------------- | 2992| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2993| 1300002 | This window state is abnormal. | 2994| 1300003 | This window manager service works abnormally. | 2995 2996**Example** 2997<!--code_no_check--> 2998```ts 2999import { BusinessError } from '@kit.BasicServicesKit'; 3000import * as Index from '../pages/Index'; // Import the named route page. 3001 3002let storage: LocalStorage = new LocalStorage(); 3003storage.setOrCreate('storageSimpleProp', 121); 3004try { 3005 let promise = (windowClass as window.Window).loadContentByName(Index.entryName, storage); 3006 promise.then(() => { 3007 console.info('Succeeded in loading the content.'); 3008 }).catch((err: BusinessError) => { 3009 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3010 }); 3011} catch (exception) { 3012 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 3013} 3014``` 3015<!--code_no_check--> 3016```ts 3017// ets/pages/Index.ets 3018export const entryName : string = 'Index'; 3019@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 3020@Component 3021export struct Index { 3022 @State message: string = 'Hello World' 3023 build() { 3024 Row() { 3025 Column() { 3026 Text(this.message) 3027 .fontSize(50) 3028 .fontWeight(FontWeight.Bold) 3029 } 3030 .width('100%') 3031 } 3032 .height('100%') 3033 } 3034} 3035``` 3036 3037### isWindowShowing<sup>9+</sup> 3038 3039isWindowShowing(): boolean 3040 3041Checks whether this window is displayed. 3042 3043**System capability**: SystemCapability.WindowManager.WindowManager.Core 3044 3045**Atomic service API**: This API can be used in atomic services since API version 11. 3046 3047**Return value** 3048 3049| Type| Description| 3050| ------- | ------------------------------------------------------------------ | 3051| boolean | Whether the window is displayed. The value **true** means that the window is displayed, and **false** means the opposite.| 3052 3053**Error codes** 3054 3055For details about the error codes, see [Window Error Codes](errorcode-window.md). 3056 3057| ID| Error Message| 3058| ------- | ------------------------------ | 3059| 1300002 | This window state is abnormal. | 3060 3061**Example** 3062 3063```ts 3064try { 3065 let data = windowClass.isWindowShowing(); 3066 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 3067} catch (exception) { 3068 console.error(`Failed to check whether the window is showing. Cause code: ${exception.code}, message: ${exception.message}`); 3069} 3070``` 3071 3072### on('windowSizeChange')<sup>7+</sup> 3073 3074on(type: 'windowSizeChange', callback: Callback<Size>): void 3075 3076Subscribes to the window size change event. 3077 3078**System capability**: SystemCapability.WindowManager.WindowManager.Core 3079 3080**Atomic service API**: This API can be used in atomic services since API version 11. 3081 3082**Parameters** 3083 3084| Name | Type | Mandatory| Description | 3085| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 3086| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 3087| callback | Callback<[Size](#size7)> | Yes | Callback used to return the window size. | 3088 3089**Error codes** 3090 3091For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3092 3093| ID| Error Message| 3094| ------- | -------------------------------------------- | 3095| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3096 3097**Example** 3098 3099```ts 3100try { 3101 windowClass.on('windowSizeChange', (data) => { 3102 console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data)); 3103 }); 3104} catch (exception) { 3105 console.error(`Failed to enable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 3106} 3107``` 3108 3109### off('windowSizeChange')<sup>7+</sup> 3110 3111off(type: 'windowSizeChange', callback?: Callback<Size>): void 3112 3113Unsubscribes from the window size change event. 3114 3115**System capability**: SystemCapability.WindowManager.WindowManager.Core 3116 3117**Atomic service API**: This API can be used in atomic services since API version 11. 3118 3119**Parameters** 3120 3121| Name | Type | Mandatory| Description | 3122| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 3123| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 3124| 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. | 3125 3126**Error codes** 3127 3128For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3129 3130| ID| Error Message| 3131| ------- | -------------------------------------------- | 3132| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3133 3134**Example** 3135 3136```ts 3137const callback = (size: window.Size) => { 3138 // ... 3139} 3140try { 3141 // Enable listening through the on API. 3142 windowClass.on('windowSizeChange', callback); 3143 // Disable the listening of a specified callback. 3144 windowClass.off('windowSizeChange', callback); 3145 // Unregister all the callbacks that have been registered through on(). 3146 windowClass.off('windowSizeChange'); 3147} catch (exception) { 3148 console.error(`Failed to disable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 3149} 3150``` 3151 3152### on('avoidAreaChange')<sup>9+</sup> 3153 3154on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void 3155 3156Subscribes to the event indicating changes to the area where this window cannot be displayed. 3157<!--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--> 3158 3159**System capability**: SystemCapability.WindowManager.WindowManager.Core 3160 3161**Atomic service API**: This API can be used in atomic services since API version 11. 3162 3163**Parameters** 3164 3165| Name | Type | Mandatory| Description | 3166| -------- |----------------------------------| ---- |--------------------------------------| 3167| 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.| 3168| callback | Callback<[AvoidAreaOptions](#avoidareaoptions12)> | Yes | Callback used to return the area and area type.| 3169 3170**Error codes** 3171 3172For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3173 3174| ID| Error Message| 3175| ------- | -------------------------------------------- | 3176| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3177 3178**Example** 3179 3180```ts 3181try { 3182 windowClass.on('avoidAreaChange', (data) => { 3183 console.info('Succeeded in enabling the listener for system avoid area changes. type:' + 3184 JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area)); 3185 }); 3186} catch (exception) { 3187 console.error(`Failed to enable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 3188} 3189``` 3190 3191### off('avoidAreaChange')<sup>9+</sup> 3192 3193off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaOptions>): void 3194 3195Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 3196 3197**System capability**: SystemCapability.WindowManager.WindowManager.Core 3198 3199**Atomic service API**: This API can be used in atomic services since API version 11. 3200 3201**Parameters** 3202 3203| Name | Type | Mandatory| Description | 3204| -------- |----------------------------------|------|------------------------------------| 3205| 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.| 3206| 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.| 3207 3208**Error codes** 3209 3210For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3211 3212| ID| Error Message| 3213| ------- | -------------------------------------------- | 3214| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 3215 3216**Example** 3217 3218```ts 3219interface Param { 3220 type: window.AvoidAreaType, 3221 area: window.AvoidArea 3222} 3223const callback = (data: Param) => { 3224 // ... 3225} 3226try { 3227 windowClass.on('avoidAreaChange', callback); 3228 3229 windowClass.off('avoidAreaChange', callback); 3230 // Unregister all the callbacks that have been registered through on(). 3231 windowClass.off('avoidAreaChange'); 3232} catch (exception) { 3233 console.error(`Failed to enable or disable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 3234} 3235``` 3236 3237### on('keyboardHeightChange')<sup>7+</sup> 3238 3239on(type: 'keyboardHeightChange', callback: Callback<number>): void 3240 3241Subscribes to the event indicating soft keyboard height changes in fixed state. 3242 3243The system notifies the keyboard height change when the soft keyboard is invoked by the window and overlaps with the window. 3244 3245Since 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). 3246 3247**Atomic service API**: This API can be used in atomic services since API version 12. 3248 3249**System capability**: SystemCapability.WindowManager.WindowManager.Core 3250 3251**Parameters** 3252 3253| Name | Type | Mandatory| Description | 3254| -------- | ------------------- | ---- |-------------------------------------------| 3255| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 3256| callback | Callback<number> | Yes | Callback used to return the current keyboard height, which is an integer, in px. | 3257 3258**Error codes** 3259 3260For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3261 3262| ID| Error Message| 3263| ------- | -------------------------------------------- | 3264| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3265 3266**Example** 3267 3268```ts 3269import { BusinessError } from '@kit.BasicServicesKit'; 3270 3271try { 3272 windowClass.on('keyboardHeightChange', (data) => { 3273 console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data)); 3274 }); 3275} catch (exception) { 3276 console.error(`Failed to enable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 3277} 3278``` 3279 3280### off('keyboardHeightChange')<sup>7+</sup> 3281 3282off(type: 'keyboardHeightChange', callback?: Callback<number>): void 3283 3284Unsubscribes from the event indicating soft keyboard height changes in fixed state. 3285 3286Since 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). 3287 3288**Atomic service API**: This API can be used in atomic services since API version 12. 3289 3290**System capability**: SystemCapability.WindowManager.WindowManager.Core 3291 3292**Parameters** 3293 3294| Name | Type | Mandatory| Description | 3295| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3296| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 3297| 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. | 3298 3299**Error codes** 3300 3301For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3302 3303| ID| Error Message| 3304| ------- | -------------------------------------------- | 3305| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3306 3307**Example** 3308 3309```ts 3310import { BusinessError } from '@kit.BasicServicesKit'; 3311 3312const callback = (height: number) => { 3313 // ... 3314} 3315try { 3316 windowClass.on('keyboardHeightChange', callback); 3317 3318 windowClass.off('keyboardHeightChange', callback); 3319 // Unregister all the callbacks that have been registered through on(). 3320 windowClass.off('keyboardHeightChange'); 3321} catch (exception) { 3322 console.error(`Failed to disable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 3323} 3324``` 3325 3326### on('touchOutside')<sup>11+</sup> 3327 3328on(type: 'touchOutside', callback: Callback<void>): void 3329 3330Subscribes to the touch event outside this window. 3331 3332**System capability**: SystemCapability.WindowManager.WindowManager.Core 3333 3334**Atomic service API**: This API can be used in atomic services since API version 11. 3335 3336**Parameters** 3337 3338| Name | Type | Mandatory| Description | 3339| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3340| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 3341| callback | Callback<void> | Yes | Callback used to return the touch event outside this window. | 3342 3343**Error codes** 3344 3345For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3346 3347| ID| Error Message| 3348| ------- | -------------------------------------------- | 3349| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3350 3351**Example** 3352 3353```ts 3354try { 3355 windowClass.on('touchOutside', () => { 3356 console.info('touch outside'); 3357 }); 3358} catch (exception) { 3359 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3360} 3361``` 3362 3363### off('touchOutside')<sup>11+</sup> 3364 3365off(type: 'touchOutside', callback?: Callback<void>): void 3366 3367Unsubscribes from the touch event outside this window. 3368 3369**System capability**: SystemCapability.WindowManager.WindowManager.Core 3370 3371**Atomic service API**: This API can be used in atomic services since API version 11. 3372 3373**Parameters** 3374 3375| Name | Type | Mandatory| Description | 3376| -------- |----------------------| ---- |--------------------------------------| 3377| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 3378| 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. | 3379 3380**Error codes** 3381 3382For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3383 3384| ID| Error Message| 3385| ------- | -------------------------------------------- | 3386| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3387 3388**Example** 3389 3390```ts 3391const callback = () => { 3392 // ... 3393} 3394try { 3395 windowClass.on('touchOutside', callback); 3396 windowClass.off('touchOutside', callback); 3397 // Unregister all the callbacks that have been registered through on(). 3398 windowClass.off('touchOutside'); 3399} catch (exception) { 3400 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3401} 3402``` 3403 3404### on('screenshot')<sup>9+</sup> 3405 3406on(type: 'screenshot', callback: Callback<void>): void 3407 3408Subscribes to the screenshot event. 3409 3410**Atomic service API**: This API can be used in atomic services since API version 12. 3411 3412**System capability**: SystemCapability.WindowManager.WindowManager.Core 3413 3414**Parameters** 3415 3416| Name | Type | Mandatory| Description | 3417| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3418| 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.| 3419| callback | Callback<void> | Yes | Callback invoked when a screenshot event occurs. | 3420 3421**Error codes** 3422 3423For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3424 3425| ID| Error Message| 3426| ------- | -------------------------------------------- | 3427| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3428 3429**Example** 3430 3431```ts 3432try { 3433 windowClass.on('screenshot', () => { 3434 console.info('screenshot happened'); 3435 }); 3436} catch (exception) { 3437 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3438} 3439``` 3440 3441### off('screenshot')<sup>9+</sup> 3442 3443off(type: 'screenshot', callback?: Callback<void>): void 3444 3445Unsubscribes from the screenshot event. 3446 3447**Atomic service API**: This API can be used in atomic services since API version 12. 3448 3449**System capability**: SystemCapability.WindowManager.WindowManager.Core 3450 3451**Parameters** 3452 3453| Name | Type | Mandatory| Description | 3454| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3455| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event.| 3456| 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.| 3457 3458**Error codes** 3459 3460For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3461 3462| ID| Error Message| 3463| ------- | -------------------------------------------- | 3464| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3465 3466**Example** 3467 3468```ts 3469let callback = () => { 3470 console.info('screenshot happened'); 3471}; 3472try { 3473 windowClass.on('screenshot', callback); 3474 windowClass.off('screenshot', callback); 3475 // Unregister all the callbacks that have been registered through on(). 3476 windowClass.off('screenshot'); 3477} catch (exception) { 3478 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3479} 3480``` 3481 3482### on('dialogTargetTouch')<sup>10+</sup> 3483 3484on(type: 'dialogTargetTouch', callback: Callback<void>): void 3485 3486Subscribes 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. 3487 3488**Atomic service API**: This API can be used in atomic services since API version 12. 3489 3490**System capability**: SystemCapability.WindowManager.WindowManager.Core 3491 3492**Parameters** 3493 3494| Name | Type | Mandatory| Description | 3495| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3496| 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.| 3497| callback | Callback<void>| Yes | Callback invoked when a click or touch event occurs in the window covered by the modal window.| 3498 3499**Error codes** 3500 3501For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3502 3503| ID| Error Message| 3504| ------- | -------------------------------------------- | 3505| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3506 3507**Example** 3508 3509```ts 3510try { 3511 windowClass.on('dialogTargetTouch', () => { 3512 console.info('touch dialog target'); 3513 }); 3514} catch (exception) { 3515 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3516} 3517``` 3518 3519### off('dialogTargetTouch')<sup>10+</sup> 3520 3521off(type: 'dialogTargetTouch', callback?: Callback<void>): void 3522 3523Unsubscribes from the touch event of the target window in the modal window mode. 3524 3525**Atomic service API**: This API can be used in atomic services since API version 12. 3526 3527**System capability**: SystemCapability.WindowManager.WindowManager.Core 3528 3529**Parameters** 3530 3531| Name | Type | Mandatory| Description | 3532| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3533| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the touch event of the target window in the modal window mode.| 3534| 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.| 3535 3536**Error codes** 3537 3538For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3539 3540| ID| Error Message| 3541| ------- | -------------------------------------------- | 3542| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3543 3544**Example** 3545 3546```ts 3547const callback = () => { 3548 // ... 3549} 3550try { 3551 windowClass.on('dialogTargetTouch', callback); 3552 windowClass.off('dialogTargetTouch', callback); 3553 // Unregister all the callbacks that have been registered through on(). 3554 windowClass.off('dialogTargetTouch'); 3555} catch (exception) { 3556 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3557} 3558``` 3559 3560### on('windowEvent')<sup>10+</sup> 3561 3562on(type: 'windowEvent', callback: Callback<WindowEventType>): void 3563 3564Subscribes to the window lifecycle change event. 3565 3566**System capability**: SystemCapability.WindowManager.WindowManager.Core 3567 3568**Atomic service API**: This API can be used in atomic services since API version 11. 3569 3570**Parameters** 3571 3572| Name | Type | Mandatory| Description | 3573| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3574| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 3575| callback | Callback<[WindowEventType](#windoweventtype10)> | Yes | Callback used to return the window lifecycle state. | 3576 3577**Error codes** 3578 3579For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3580 3581| ID| Error Message| 3582| ------- | -------------------------------------------- | 3583| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3584 3585**Example** 3586 3587```ts 3588try { 3589 windowClass.on('windowEvent', (data) => { 3590 console.info('Window event happened. Event:' + JSON.stringify(data)); 3591 }); 3592} catch (exception) { 3593 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3594} 3595``` 3596 3597### off('windowEvent')<sup>10+</sup> 3598 3599off(type: 'windowEvent', callback?: Callback<WindowEventType>): void 3600 3601Unsubscribes from the window lifecycle change event. 3602 3603**System capability**: SystemCapability.WindowManager.WindowManager.Core 3604 3605**Atomic service API**: This API can be used in atomic services since API version 11. 3606 3607**Parameters** 3608 3609| Name | Type | Mandatory| Description | 3610| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3611| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 3612| 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. | 3613 3614**Error codes** 3615 3616For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3617 3618| ID| Error Message| 3619| ------- | -------------------------------------------- | 3620| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3621 3622**Example** 3623 3624```ts 3625const callback = (windowEventType: window.WindowEventType) => { 3626 // ... 3627} 3628try { 3629 // Enable listening through the on API. 3630 windowClass.on('windowEvent', callback); 3631 // Disable the listening of a specified callback. 3632 windowClass.off('windowEvent', callback); 3633 // Unregister all the callbacks that have been registered through on(). 3634 windowClass.off('windowEvent'); 3635} catch (exception) { 3636 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3637} 3638``` 3639 3640### on('displayIdChange')<sup>14+</sup> 3641 3642on(type: 'displayIdChange', callback: Callback<number>): void 3643 3644Subscribes to the display change event of this window. For example, this event is triggered when the window is moved to a different display. 3645 3646**Atomic service API**: This API can be used in atomic services since API version 14. 3647 3648**System capability**: SystemCapability.Window.SessionManager 3649 3650**Parameters** 3651 3652| Name | Type | Mandatory| Description | 3653| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3654| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.| 3655| 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. | 3656 3657**Error codes** 3658 3659For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3660 3661| ID| Error Message| 3662| ------- | ------------------------------ | 3663| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3664| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3665| 1300002 | This window state is abnormal. | 3666 3667**Example** 3668 3669```ts 3670try { 3671 windowClass.on('displayIdChange', (data) => { 3672 console.info('Window displayId changed, displayId=' + JSON.stringify(data)); 3673 }); 3674} catch (exception) { 3675 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3676} 3677``` 3678### off('displayIdChange')<sup>14+</sup> 3679 3680off(type: 'displayIdChange', callback?: Callback<number>): void 3681 3682Unsubscribes from the display change event of this window. 3683 3684**Atomic service API**: This API can be used in atomic services since API version 14. 3685 3686**System capability**: SystemCapability.Window.SessionManager 3687 3688**Parameters** 3689 3690| Name | Type | Mandatory| Description | 3691| -------- |----------------------------| ---- |--------------------------------------| 3692| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.| 3693| 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. | 3694 3695**Error codes** 3696 3697For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3698 3699| ID| Error Message| 3700| ------- | ------------------------------ | 3701| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3702| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3703| 1300002 | This window state is abnormal. | 3704 3705**Example** 3706 3707```ts 3708const callback = (displayId: number) => { 3709 // ... 3710} 3711try { 3712 // Enable listening through the on API. 3713 windowClass.on('displayIdChange', callback); 3714 // Disable the listening of a specified callback. 3715 windowClass.off('displayIdChange', callback); 3716 // Unregister all the callbacks that have been registered through on(). 3717 windowClass.off('displayIdChange'); 3718} catch (exception) { 3719 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3720} 3721``` 3722 3723### on('windowVisibilityChange')<sup>11+</sup> 3724 3725on(type: 'windowVisibilityChange', callback: Callback<boolean>): void 3726 3727Subscribes to the visibility status change event of this window. 3728 3729**Atomic service API**: This API can be used in atomic services since API version 12. 3730 3731**System capability**: SystemCapability.Window.SessionManager 3732 3733**Parameters** 3734 3735| Name | Type | Mandatory| Description | 3736| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3737| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 3738| 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. | 3739 3740**Error codes** 3741 3742For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3743 3744| ID| Error Message| 3745| ------- | ------------------------------ | 3746| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3747| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3748| 1300002 | This window state is abnormal. | 3749| 1300003 | This window manager service works abnormally. | 3750 3751**Example** 3752 3753```ts 3754try { 3755 windowClass.on('windowVisibilityChange', (boolean) => { 3756 console.info('Window visibility changed, isVisible=' + boolean); 3757 }); 3758} catch (exception) { 3759 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3760} 3761``` 3762 3763### off('windowVisibilityChange')<sup>11+</sup> 3764 3765off(type: 'windowVisibilityChange', callback?: Callback<boolean>): void 3766 3767Unsubscribes from the visibility status change event of this window. 3768 3769**Atomic service API**: This API can be used in atomic services since API version 12. 3770 3771**System capability**: SystemCapability.Window.SessionManager 3772 3773**Parameters** 3774 3775| Name | Type | Mandatory| Description | 3776| -------- |----------------------------| ---- |--------------------------------------| 3777| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 3778| 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. | 3779 3780**Error codes** 3781 3782For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3783 3784| ID| Error Message| 3785| ------- | ------------------------------ | 3786| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3787| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3788| 1300002 | This window state is abnormal. | 3789| 1300003 | This window manager service works abnormally. | 3790 3791**Example** 3792 3793```ts 3794const callback = (bool: boolean) => { 3795 // ... 3796} 3797try { 3798 // Enable listening through the on API. 3799 windowClass.on('windowVisibilityChange', callback); 3800 // Disable the listening of a specified callback. 3801 windowClass.off('windowVisibilityChange', callback); 3802 // Unregister all the callbacks that have been registered through on(). 3803 windowClass.off('windowVisibilityChange'); 3804} catch (exception) { 3805 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3806} 3807``` 3808 3809### on('noInteractionDetected')<sup>12+</sup> 3810 3811on(type: 'noInteractionDetected', timeout: number, callback: Callback<void>): void 3812 3813Subscribes to non-interaction events in a window within the specified period. 3814 3815Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 3816 3817**Atomic service API**: This API can be used in atomic services since API version 12. 3818 3819**System capability**: SystemCapability.Window.SessionManager 3820 3821**Parameters** 3822 3823| Name | Type | Mandatory| Description | 3824| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3825| 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.| 3826| timeout | number | Yes | Period during which no interaction is performed, in seconds. The value must be an integer. Negative numbers and decimals are invalid.| 3827| callback | Callback<void> | Yes | Callback invoked when there is no interaction event in the current window within the specified period. | 3828 3829**Error codes** 3830 3831For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3832 3833| ID| Error Message| 3834| ------- | ------------------------------ | 3835| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3836| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3837| 1300002 | This window state is abnormal. | 3838| 1300003 | This window manager service works abnormally. | 3839 3840**Example** 3841 3842```ts 3843try { 3844 windowClass.on('noInteractionDetected', 60, () => { 3845 console.info('no interaction in 60s'); 3846 }); 3847} catch (exception) { 3848 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3849} 3850``` 3851 3852### off('noInteractionDetected')<sup>12+</sup> 3853 3854off(type: 'noInteractionDetected', callback?: Callback<void>): void 3855 3856Unsubscribes from non-interaction events in a window within the specified period. 3857 3858Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 3859 3860**Atomic service API**: This API can be used in atomic services since API version 12. 3861 3862**System capability**: SystemCapability.Window.SessionManager 3863 3864**Parameters** 3865 3866| Name | Type | Mandatory| Description | 3867| -------- |----------------------------| ---- |--------------------------------------| 3868| 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.| 3869| 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.| 3870 3871**Error codes** 3872 3873For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3874 3875| ID| Error Message| 3876| ------- | ------------------------------ | 3877| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3878| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3879| 1300002 | This window state is abnormal. | 3880| 1300003 | This window manager service works abnormally. | 3881 3882**Example** 3883 3884```ts 3885const callback = () => { 3886 // ... 3887} 3888try { 3889 windowClass.on('noInteractionDetected', 60, callback); 3890 windowClass.off('noInteractionDetected', callback); 3891 // Unregister all the callbacks that have been registered through on(). 3892 windowClass.off('noInteractionDetected'); 3893} catch (exception) { 3894 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3895} 3896``` 3897 3898### on('windowStatusChange')<sup>11+</sup> 3899 3900on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void 3901 3902Subscribes to the window status change event. A notification is sent when the window status changes (the window properties may not be updated). 3903 3904> **NOTE** 3905> 3906> When this API is called on 2-in-1 devices, the return value is **WindowStatusType::FULL_SCREEN** when the window is maximized. 3907> 3908> Upon the return value **WindowStatusType::FULL_SCREEN**, you can call [getImmersiveModeEnabledState()](#getimmersivemodeenabledstate12) to determine whether the window is in full-screen or maximized mode on 2-in-1 devices. The return value **true** means that the window is in full-screen mode, and **false** means that the window is maximized. 3909 3910**Atomic service API**: This API can be used in atomic services since API version 12. 3911 3912**System capability**: SystemCapability.Window.SessionManager 3913 3914**Parameters** 3915 3916| Name | Type | Mandatory| Description | 3917| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 3918| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 3919| callback | Callback<[WindowStatusType](#windowstatustype11)> | Yes | Callback used to return the window status. | 3920 3921**Error codes** 3922 3923For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3924 3925| ID| Error Message| 3926| ------- | ------------------------------ | 3927| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3928| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3929 3930**Example** 3931 3932```ts 3933try { 3934 windowClass.on('windowStatusChange', (WindowStatusType) => { 3935 console.info('Succeeded in enabling the listener for window status changes. Data: ' + JSON.stringify(WindowStatusType)); 3936 }); 3937} catch (exception) { 3938 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3939} 3940``` 3941 3942### off('windowStatusChange')<sup>11+</sup> 3943 3944off(type: 'windowStatusChange', callback?: Callback<WindowStatusType>): void 3945 3946Unsubscribes from the window status change event. 3947 3948**Atomic service API**: This API can be used in atomic services since API version 12. 3949 3950**System capability**: SystemCapability.Window.SessionManager 3951 3952**Parameters** 3953 3954| Name | Type | Mandatory| Description | 3955| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 3956| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 3957| 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. | 3958 3959**Error codes** 3960 3961For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3962 3963| ID| Error Message| 3964| ------- | ------------------------------ | 3965| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3966| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3967 3968**Example** 3969 3970```ts 3971const callback = (windowStatusType: window.WindowStatusType) => { 3972 // ... 3973} 3974try { 3975 windowClass.on('windowStatusChange', callback); 3976 windowClass.off('windowStatusChange', callback); 3977 // Unregister all the callbacks that have been registered through on(). 3978 windowClass.off('windowStatusChange'); 3979} catch (exception) { 3980 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3981} 3982``` 3983 3984### setWindowGrayScale<sup>12+</sup> 3985 3986setWindowGrayScale(grayScale: number): Promise<void> 3987 3988Sets 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. 3989 3990**Atomic service API**: This API can be used in atomic services since API version 12. 3991 3992**System capability**: SystemCapability.Window.SessionManager 3993 3994**Parameters** 3995 3996| Name| Type| Mandatory| Description | 3997| --------- | ------ | -- | ---------------------------------------- | 3998| 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.| 3999 4000**Return value** 4001 4002| Type| Description| 4003| ------------------- | ------------------------ | 4004| Promise<void> | Promise that returns no value.| 4005 4006**Error codes** 4007 4008For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4009 4010| ID| Error Message| 4011| ------- | --------------------------------------------- | 4012| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4013| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4014| 1300002 | This window state is abnormal. | 4015| 1300003 | This window manager service works abnormally. | 4016 4017**Example** 4018 4019```ts 4020import { BusinessError } from '@kit.BasicServicesKit'; 4021 4022windowClass?.setUIContent('pages/Index', (error: BusinessError) => { 4023 if (error.code) { 4024 console.error(`Failed to set the content. Cause code: ${error.code}`); 4025 return; 4026 } 4027 console.info('Succeeded in setting the content.'); 4028 let grayScale: number = 0.5; 4029 try { 4030 if (canIUse("SystemCapability.Window.SessionManager")) { 4031 let promise = windowClass?.setWindowGrayScale(grayScale); 4032 promise?.then(() => { 4033 console.info('Succeeded in setting the grayScale.'); 4034 }).catch((err: BusinessError) => { 4035 console.error(`Failed to set the grayScale. Cause code: ${err.code}, message: ${err.message}`); 4036 }); 4037 } 4038 } catch (exception) { 4039 console.error(`Failed to set the grayScale. Cause code: ${exception.code}, message: ${exception.message}`); 4040 } 4041}); 4042``` 4043 4044### on('windowTitleButtonRectChange')<sup>11+</sup> 4045 4046on(type: 'windowTitleButtonRectChange', callback: Callback<TitleButtonRect>): void 4047 4048Subscribes to the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 4049 4050**Atomic service API**: This API can be used in atomic services since API version 12. 4051 4052**System capability**: SystemCapability.Window.SessionManager 4053 4054**Parameters** 4055 4056| Name | Type | Mandatory| Description | 4057| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 4058| 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.| 4059| callback | Callback<[TitleButtonRect](#titlebuttonrect11)> | Yes | Callback used to return the new rectangle.| 4060 4061**Error codes** 4062 4063For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4064 4065| ID| Error Message | 4066| -------- | ------------------------------ | 4067| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4068| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4069| 1300002 | This window state is abnormal. | 4070 4071**Example** 4072 4073```ts 4074windowClass.setUIContent('pages/WindowPage').then(() => { 4075 try { 4076 windowClass?.on('windowTitleButtonRectChange', (titleButtonRect) => { 4077 console.info('Succeeded in enabling the listener for window title buttons area changes. Data: ' + JSON.stringify(titleButtonRect)); 4078 }); 4079 } catch (exception) { 4080 console.error(`Failed to enable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4081 } 4082}) 4083``` 4084 4085### off('windowTitleButtonRectChange')<sup>11+</sup> 4086 4087off(type: 'windowTitleButtonRectChange', callback?: Callback<TitleButtonRect>): void 4088 4089Unsubscribes from the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 4090 4091**Atomic service API**: This API can be used in atomic services since API version 12. 4092 4093**System capability**: SystemCapability.Window.SessionManager 4094 4095**Parameters** 4096 4097| Name | Type | Mandatory| Description | 4098| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 4099| 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.| 4100| 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.| 4101 4102**Error codes** 4103 4104For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4105 4106| ID| Error Message | 4107| -------- | ------------------------------ | 4108| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4109| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4110| 1300002 | This window state is abnormal. | 4111 4112**Example** 4113 4114```ts 4115windowClass.setUIContent('pages/WindowPage').then(() => { 4116 const callback = (titleButtonRect: window.TitleButtonRect) => { 4117 // ... 4118 } 4119 try { 4120 // Enable listening through the on API. 4121 windowClass?.on('windowTitleButtonRectChange', callback); 4122 // Disable the listening of a specified callback. 4123 windowClass?.off('windowTitleButtonRectChange', callback); 4124 // Unregister all the callbacks that have been registered through on(). 4125 windowClass?.off('windowTitleButtonRectChange'); 4126 } catch (exception) { 4127 console.error(`Failed to disable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4128 } 4129}) 4130``` 4131 4132### on('windowRectChange')<sup>12+</sup> 4133 4134on(type: 'windowRectChange', callback: Callback<RectChangeOptions>): void 4135 4136Subscribes to window rectangle (position and size) change events. 4137 4138**System capability**: SystemCapability.Window.SessionManager 4139 4140**Atomic service API**: This API can be used in atomic services since API version 12. 4141 4142**Parameters** 4143 4144| Name | Type | Mandatory| Description | 4145| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4146| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event.| 4147| callback | Callback<[RectChangeOptions](#rectchangeoptions12)> | Yes | Callback used to return the value and reason of the window rectangle change. | 4148 4149**Error codes** 4150 4151For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4152 4153| ID| Error Message| 4154| ------- | -------------------------------------------- | 4155| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4156| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4157| 1300002 | This window state is abnormal. | 4158| 1300003 | This window manager service works abnormally. | 4159 4160**Example** 4161 4162```ts 4163windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 4164 console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data)); 4165}); 4166``` 4167 4168### off('windowRectChange')<sup>12+</sup> 4169 4170off(type: 'windowRectChange', callback?: Callback<RectChangeOptions>): void 4171 4172Unsubscribes from window rectangle (position and size) change events. 4173 4174**System capability**: SystemCapability.Window.SessionManager 4175 4176**Atomic service API**: This API can be used in atomic services since API version 12. 4177 4178**Parameters** 4179 4180| Name | Type | Mandatory| Description | 4181| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4182| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event. | 4183| 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.| 4184 4185**Error codes** 4186 4187For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4188 4189| ID| Error Message| 4190| ------- | -------------------------------------------- | 4191| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4192| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4193| 1300002 | This window state is abnormal. | 4194| 1300003 | This window manager service works abnormally. | 4195 4196**Example** 4197 4198```ts 4199const callback = (rectChangeOptions: window.RectChangeOptions) => { 4200 // ... 4201} 4202windowClass.on('windowRectChange', callback); 4203windowClass.off('windowRectChange', callback); 4204// Unregister all the callbacks that have been registered through on(). 4205windowClass.off('windowRectChange'); 4206``` 4207 4208### on('subWindowClose')<sup>12+</sup> 4209 4210on(type: 'subWindowClose', callback: Callback<void>): void 4211 4212Subscribes to the event indicating that the subwindow is closed. This event is triggered only when the user clicks the close button in the upper right corner provided by the system to close the subwindow. It is not triggered when the subwindow is closed in other ways. 4213 4214**Atomic service API**: This API can be used in atomic services since API version 12. 4215 4216**System capability**: SystemCapability.Window.SessionManager 4217 4218**Parameters** 4219 4220| Name | Type | Mandatory| Description | 4221| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4222| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the subwindow close event.| 4223| callback | Callback<void> | Yes | Callback invoked when the close button in the upper right corner of the subwindow is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the subwindow. The value **true** means not to close the subwindow, and **false** means to continue to close the subwindow. | 4224 4225**Error codes** 4226 4227For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4228 4229| ID| Error Message| 4230| ------- | -------------------------------------------- | 4231| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4232| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4233| 1300002 | This window state is abnormal. | 4234| 1300004 | Unauthorized operation. | 4235 4236**Example** 4237 4238```ts 4239const callback = () => { 4240 // ... 4241 return true; 4242} 4243try { 4244 windowClass.on('subWindowClose', callback); 4245} catch (exception) { 4246 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4247} 4248``` 4249 4250### off('subWindowClose')<sup>12+</sup> 4251 4252off(type: 'subWindowClose', callback?: Callback<void>): void 4253 4254Unsubscribes from the event indicating that the subwindow is closed. 4255 4256**Atomic service API**: This API can be used in atomic services since API version 12. 4257 4258**System capability**: SystemCapability.Window.SessionManager 4259 4260**Parameters** 4261 4262| Name | Type | Mandatory| Description | 4263| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4264| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the subwindow close event. | 4265| callback | Callback<void> | No | Callback invoked when the close button in the upper right corner of the subwindow is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the subwindow. The value **true** means not to close the subwindow, and **false** means to continue to close the subwindow. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.| 4266 4267**Error codes** 4268 4269For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4270 4271| ID| Error Message| 4272| ------- | -------------------------------------------- | 4273| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4274| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4275| 1300002 | This window state is abnormal. | 4276| 1300004 | Unauthorized operation. | 4277 4278**Example** 4279 4280```ts 4281const callback = () => { 4282 // ... 4283 return true; 4284} 4285try { 4286 windowClass.on('subWindowClose', callback); 4287 windowClass.off('subWindowClose', callback); 4288 // Unregister all the callbacks that have been registered through on(). 4289 windowClass.off('subWindowClose'); 4290} catch (exception) { 4291 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4292} 4293``` 4294 4295### isWindowSupportWideGamut<sup>9+</sup> 4296 4297isWindowSupportWideGamut(callback: AsyncCallback<boolean>): void 4298 4299Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 4300 4301**Atomic service API**: This API can be used in atomic services since API version 12. 4302 4303**System capability**: SystemCapability.WindowManager.WindowManager.Core 4304 4305**Parameters** 4306 4307| Name| Type| Mandatory| Description| 4308| -------- | ---------------------------- | -- | -------------------------------------------------------------------------------- | 4309| 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.| 4310 4311**Error codes** 4312 4313For details about the error codes, see [Window Error Codes](errorcode-window.md). 4314 4315| ID| Error Message| 4316| ------- | ------------------------------ | 4317| 1300002 | This window state is abnormal. | 4318 4319**Example** 4320 4321```ts 4322import { BusinessError } from '@kit.BasicServicesKit'; 4323 4324windowClass.isWindowSupportWideGamut((err: BusinessError, data) => { 4325 const errCode: number = err.code; 4326 if (errCode) { 4327 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 4328 return; 4329 } 4330 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 4331}); 4332``` 4333 4334### isWindowSupportWideGamut<sup>9+</sup> 4335 4336isWindowSupportWideGamut(): Promise<boolean> 4337 4338Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 4339 4340**Atomic service API**: This API can be used in atomic services since API version 12. 4341 4342**System capability**: SystemCapability.WindowManager.WindowManager.Core 4343 4344**Return value** 4345 4346| Type| Description| 4347| ---------------------- | ------------------------------------------------------------------------------------ | 4348| 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.| 4349 4350**Error codes** 4351 4352For details about the error codes, see [Window Error Codes](errorcode-window.md). 4353 4354| ID| Error Message| 4355| ------- | ------------------------------ | 4356| 1300002 | This window state is abnormal. | 4357 4358**Example** 4359 4360```ts 4361import { BusinessError } from '@kit.BasicServicesKit'; 4362 4363let promise = windowClass.isWindowSupportWideGamut(); 4364promise.then((data) => { 4365 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 4366}).catch((err: BusinessError) => { 4367 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 4368}); 4369``` 4370 4371### setWindowColorSpace<sup>9+</sup> 4372 4373setWindowColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 4374 4375Sets a color space for this window. This API uses an asynchronous callback to return the result. 4376 4377**Atomic service API**: This API can be used in atomic services since API version 12. 4378 4379**System capability**: SystemCapability.WindowManager.WindowManager.Core 4380 4381**Parameters** 4382 4383| Name| Type| Mandatory| Description| 4384| ---------- | ------------------------- | -- | ----------- | 4385| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 4386| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4387 4388**Error codes** 4389 4390For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4391 4392| ID| Error Message| 4393| ------- | ------------------------------ | 4394| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4395| 1300002 | This window state is abnormal. | 4396 4397**Example** 4398 4399```ts 4400import { BusinessError } from '@kit.BasicServicesKit'; 4401 4402try { 4403 windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 4404 const errCode: number = err.code; 4405 if (errCode) { 4406 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 4407 return; 4408 } 4409 console.info('Succeeded in setting window colorspace.'); 4410 }); 4411} catch (exception) { 4412 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 4413} 4414``` 4415 4416### setWindowColorSpace<sup>9+</sup> 4417 4418setWindowColorSpace(colorSpace:ColorSpace): Promise<void> 4419 4420Sets a color space for this window. This API uses a promise to return the result. 4421 4422**Atomic service API**: This API can be used in atomic services since API version 12. 4423 4424**System capability**: SystemCapability.WindowManager.WindowManager.Core 4425 4426**Parameters** 4427 4428| Name| Type| Mandatory| Description| 4429| ---------- | ------------------------- | -- | ------------- | 4430| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 4431 4432**Return value** 4433 4434| Type| Description| 4435| ------------------- | ------------------------ | 4436| Promise<void> | Promise that returns no value.| 4437 4438**Error codes** 4439 4440For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4441 4442| ID| Error Message| 4443| ------- | ------------------------------ | 4444| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4445| 1300002 | This window state is abnormal. | 4446 4447**Example** 4448 4449```ts 4450import { BusinessError } from '@kit.BasicServicesKit'; 4451 4452try { 4453 let promise = windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT); 4454 promise.then(() => { 4455 console.info('Succeeded in setting window colorspace.'); 4456 }).catch((err: BusinessError) => { 4457 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 4458 }); 4459} catch (exception) { 4460 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 4461} 4462``` 4463 4464### getWindowColorSpace<sup>9+</sup> 4465 4466getWindowColorSpace(): ColorSpace 4467 4468Obtains the color space of this window. 4469 4470**Atomic service API**: This API can be used in atomic services since API version 12. 4471 4472**System capability**: SystemCapability.WindowManager.WindowManager.Core 4473 4474**Return value** 4475 4476| Type| Description| 4477| ------------------------- | ------------- | 4478| [ColorSpace](#colorspace8) | Color space obtained.| 4479 4480**Error codes** 4481 4482For details about the error codes, see [Window Error Codes](errorcode-window.md). 4483 4484| ID| Error Message| 4485| ------- | ------------------------------ | 4486| 1300002 | This window state is abnormal. | 4487 4488**Example** 4489 4490```ts 4491let colorSpace = windowClass.getWindowColorSpace(); 4492``` 4493 4494### setWindowBackgroundColor<sup>9+</sup> 4495 4496setWindowBackgroundColor(color: string): void 4497 4498Sets 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. 4499 4500**System capability**: SystemCapability.WindowManager.WindowManager.Core 4501 4502**Atomic service API**: This API can be used in atomic services since API version 11. 4503 4504**Parameters** 4505 4506| Name| Type| Mandatory| Description| 4507| ----- | ------ | -- | ----------------------------------------------------------------------- | 4508| 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'**.| 4509 4510**Error codes** 4511 4512For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4513 4514| ID| Error Message| 4515| ------- | ------------------------------ | 4516| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4517| 1300002 | This window state is abnormal. | 4518 4519**Example** 4520 4521```ts 4522import { BusinessError } from '@kit.BasicServicesKit'; 4523 4524let storage: LocalStorage = new LocalStorage(); 4525storage.setOrCreate('storageSimpleProp', 121); 4526windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 4527 let errCode: number = err.code; 4528 if (errCode) { 4529 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 4530 return; 4531 } 4532 console.info('Succeeded in loading the content.'); 4533 let color: string = '#00ff33'; 4534 try { 4535 windowClass?.setWindowBackgroundColor(color); 4536 } catch (exception) { 4537 console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`); 4538 }; 4539}); 4540``` 4541 4542### setWindowBrightness<sup>9+</sup> 4543 4544setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void 4545 4546Sets the screen brightness for the main window. This API uses an asynchronous callback to return the result. 4547 4548When 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. 4549 4550**System capability**: SystemCapability.WindowManager.WindowManager.Core 4551 4552**Atomic service API**: This API can be used in atomic services since API version 11. 4553 4554**Parameters** 4555 4556| Name| Type| Mandatory| Description | 4557| ---------- | ------------------------- | -- |-------------------------------------------| 4558| brightness | number | Yes| Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.| 4559| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4560 4561**Error codes** 4562 4563For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4564 4565| ID| Error Message| 4566| ------- | -------------------------------------------- | 4567| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4568| 1300002 | This window state is abnormal. | 4569| 1300003 | This window manager service works abnormally. | 4570 4571**Example** 4572 4573```ts 4574// EntryAbility.ets 4575import { UIAbility } from '@kit.AbilityKit'; 4576import { BusinessError } from '@kit.BasicServicesKit'; 4577 4578export default class EntryAbility extends UIAbility { 4579 // ... 4580 onWindowStageCreate(windowStage: window.WindowStage): void { 4581 console.info('onWindowStageCreate'); 4582 let windowClass: window.Window | undefined = undefined; 4583 windowStage.getMainWindow((err: BusinessError, data) => { 4584 const errCode: number = err.code; 4585 if (errCode) { 4586 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 4587 return; 4588 } 4589 windowClass = data; 4590 let brightness: number = 1; 4591 try { 4592 windowClass.setWindowBrightness(brightness, (err: BusinessError) => { 4593 const errCode: number = err.code; 4594 if (errCode) { 4595 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 4596 return; 4597 } 4598 console.info('Succeeded in setting the brightness.'); 4599 }); 4600 } catch (exception) { 4601 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 4602 } 4603 }); 4604 } 4605} 4606``` 4607 4608### setWindowBrightness<sup>9+</sup> 4609 4610setWindowBrightness(brightness: number): Promise<void> 4611 4612Sets the screen brightness for the main window. This API uses a promise to return the result. 4613 4614When 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. 4615 4616**System capability**: SystemCapability.WindowManager.WindowManager.Core 4617 4618**Atomic service API**: This API can be used in atomic services since API version 11. 4619 4620**Parameters** 4621 4622| Name| Type| Mandatory| Description | 4623| ---------- | ------ | -- |----------------------------------------| 4624| brightness | number | Yes| Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.| 4625 4626**Return value** 4627 4628| Type| Description| 4629| ------------------- | ------------------------ | 4630| Promise<void> | Promise that returns no value.| 4631 4632**Error codes** 4633 4634For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4635 4636| ID| Error Message| 4637| ------- | -------------------------------------------- | 4638| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4639| 1300002 | This window state is abnormal. | 4640| 1300003 | This window manager service works abnormally. | 4641 4642**Example** 4643 4644```ts 4645// EntryAbility.ets 4646import { UIAbility } from '@kit.AbilityKit'; 4647import { BusinessError } from '@kit.BasicServicesKit'; 4648 4649export default class EntryAbility extends UIAbility { 4650 // ... 4651 onWindowStageCreate(windowStage: window.WindowStage): void { 4652 console.info('onWindowStageCreate'); 4653 let windowClass: window.Window | undefined = undefined; 4654 windowStage.getMainWindow((err: BusinessError, data) => { 4655 const errCode: number = err.code; 4656 if (errCode) { 4657 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 4658 return; 4659 } 4660 windowClass = data; 4661 let brightness: number = 1; 4662 try { 4663 let promise = windowClass.setWindowBrightness(brightness); 4664 promise.then(() => { 4665 console.info('Succeeded in setting the brightness.'); 4666 }).catch((err: BusinessError) => { 4667 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 4668 }); 4669 } catch (exception) { 4670 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 4671 } 4672 }); 4673 } 4674} 4675``` 4676 4677### setWindowFocusable<sup>9+</sup> 4678 4679setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 4680 4681Sets whether this window is focusable, that is, whether the window can gain focus after it is being clicked or using other methods. This API uses an asynchronous callback to return the result. 4682 4683**Atomic service API**: This API can be used in atomic services since API version 12. 4684 4685**System capability**: SystemCapability.WindowManager.WindowManager.Core 4686 4687**Parameters** 4688 4689| Name| Type| Mandatory| Description| 4690| ----------- | ------------------------- | -- | ------------------------------------------------------- | 4691| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.| 4692| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4693 4694**Error codes** 4695 4696For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4697 4698| ID| Error Message| 4699| ------- | -------------------------------------------- | 4700| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4701| 1300002 | This window state is abnormal. | 4702| 1300003 | This window manager service works abnormally. | 4703 4704**Example** 4705 4706```ts 4707import { BusinessError } from '@kit.BasicServicesKit'; 4708 4709let isFocusable: boolean = true; 4710try { 4711 windowClass.setWindowFocusable(isFocusable, (err: BusinessError) => { 4712 const errCode: number = err.code; 4713 if (errCode) { 4714 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 4715 return; 4716 } 4717 console.info('Succeeded in setting the window to be focusable.'); 4718 }); 4719} catch (exception) { 4720 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 4721} 4722``` 4723 4724### setWindowFocusable<sup>9+</sup> 4725 4726setWindowFocusable(isFocusable: boolean): Promise<void> 4727 4728Sets 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. 4729 4730**Atomic service API**: This API can be used in atomic services since API version 12. 4731 4732**System capability**: SystemCapability.WindowManager.WindowManager.Core 4733 4734**Parameters** 4735 4736| Name| Type| Mandatory| Description| 4737| ----------- | ------- | -- | -------------------------------------------------------- | 4738| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 4739 4740**Return value** 4741 4742| Type| Description| 4743| ------------------- | ------------------------ | 4744| Promise<void> | Promise that returns no value.| 4745 4746**Error codes** 4747 4748For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4749 4750| ID| Error Message| 4751| ------- | -------------------------------------------- | 4752| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4753| 1300002 | This window state is abnormal. | 4754| 1300003 | This window manager service works abnormally. | 4755 4756**Example** 4757 4758```ts 4759import { BusinessError } from '@kit.BasicServicesKit'; 4760 4761let isFocusable: boolean = true; 4762try { 4763 let promise = windowClass.setWindowFocusable(isFocusable); 4764 promise.then(() => { 4765 console.info('Succeeded in setting the window to be focusable.'); 4766 }).catch((err: BusinessError) => { 4767 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 4768 }); 4769} catch (exception) { 4770 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 4771} 4772``` 4773 4774### setWindowKeepScreenOn<sup>9+</sup> 4775 4776setWindowKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 4777 4778Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 4779 4780Set **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. 4781 4782**System capability**: SystemCapability.WindowManager.WindowManager.Core 4783 4784**Atomic service API**: This API can be used in atomic services since API version 11. 4785 4786**Parameters** 4787 4788| Name| Type| Mandatory| Description| 4789| -------------- | ------------------------- | -- | ---------------------------------------------------- | 4790| 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. | 4791| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4792 4793**Error codes** 4794 4795For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4796 4797| ID| Error Message| 4798| ------- | -------------------------------------------- | 4799| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4800| 1300002 | This window state is abnormal. | 4801| 1300003 | This window manager service works abnormally. | 4802 4803**Example** 4804 4805```ts 4806import { BusinessError } from '@kit.BasicServicesKit'; 4807 4808let isKeepScreenOn: boolean = true; 4809try { 4810 windowClass.setWindowKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 4811 const errCode: number = err.code; 4812 if (errCode) { 4813 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 4814 return; 4815 } 4816 console.info('Succeeded in setting the screen to be always on.'); 4817 }); 4818} catch (exception) { 4819 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 4820} 4821``` 4822 4823### setWindowKeepScreenOn<sup>9+</sup> 4824 4825setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 4826 4827Sets whether to keep the screen always on. This API uses a promise to return the result. 4828 4829Set **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. 4830 4831**System capability**: SystemCapability.WindowManager.WindowManager.Core 4832 4833**Atomic service API**: This API can be used in atomic services since API version 11. 4834 4835**Parameters** 4836 4837| Name| Type| Mandatory| Description| 4838| -------------- | ------- | -- | --------------------------------------------------- | 4839| 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.| 4840 4841**Return value** 4842 4843| Type| Description| 4844| ------------------- | ------------------------ | 4845| Promise<void> | Promise that returns no value.| 4846 4847**Error codes** 4848 4849For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4850 4851| ID| Error Message| 4852| ------- | -------------------------------------------- | 4853| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4854| 1300002 | This window state is abnormal. | 4855| 1300003 | This window manager service works abnormally. | 4856 4857**Example** 4858 4859```ts 4860import { BusinessError } from '@kit.BasicServicesKit'; 4861 4862let isKeepScreenOn: boolean = true; 4863try { 4864 let promise = windowClass.setWindowKeepScreenOn(isKeepScreenOn); 4865 promise.then(() => { 4866 console.info('Succeeded in setting the screen to be always on.'); 4867 }).catch((err: BusinessError) => { 4868 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 4869 }); 4870} catch (exception) { 4871 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 4872} 4873``` 4874 4875### setWindowPrivacyMode<sup>9+</sup> 4876 4877setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 4878 4879Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 4880 4881A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 4882 4883**System capability**: SystemCapability.WindowManager.WindowManager.Core 4884 4885**Atomic service API**: This API can be used in atomic services since API version 12. 4886 4887**Required permissions**: ohos.permission.PRIVACY_WINDOW 4888 4889**Parameters** 4890 4891| Name| Type| Mandatory| Description| 4892| ------------- | ------------------------- | -- | ------------------------------------------------------ | 4893| 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. | 4894| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4895 4896**Error codes** 4897 4898For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4899 4900| ID| Error Message| 4901| ------- | ------------------------------ | 4902| 201 | Permission verification failed. The application does not have the permission required to call the API. | 4903| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4904| 1300002 | This window state is abnormal. | 4905 4906**Example** 4907 4908```ts 4909import { BusinessError } from '@kit.BasicServicesKit'; 4910 4911let isPrivacyMode: boolean = true; 4912try { 4913 windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => { 4914 const errCode: number = err.code; 4915 if (errCode) { 4916 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 4917 return; 4918 } 4919 console.info('Succeeded in setting the window to privacy mode.'); 4920 }); 4921} catch (exception) { 4922 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 4923} 4924``` 4925 4926### setWindowPrivacyMode<sup>9+</sup> 4927 4928setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 4929 4930Sets whether this window is in privacy mode. This API uses a promise to return the result. 4931 4932A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 4933 4934**System capability**: SystemCapability.WindowManager.WindowManager.Core 4935 4936**Atomic service API**: This API can be used in atomic services since API version 12. 4937 4938**Required permissions**: ohos.permission.PRIVACY_WINDOW 4939 4940**Parameters** 4941 4942| Name| Type| Mandatory| Description| 4943| ------------- | ------- | -- | ----------------------------------------------------- | 4944| 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.| 4945 4946**Return value** 4947 4948| Type| Description| 4949| ------------------- | ------------------------ | 4950| Promise<void> | Promise that returns no value.| 4951 4952**Error codes** 4953 4954For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4955 4956| ID| Error Message| 4957| ------- | ------------------------------ | 4958| 201 | Permission verification failed. The application does not have the permission required to call the API. | 4959| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4960| 1300002 | This window state is abnormal. | 4961 4962**Example** 4963 4964```ts 4965import { BusinessError } from '@kit.BasicServicesKit'; 4966 4967let isPrivacyMode: boolean = true; 4968try { 4969 let promise = windowClass.setWindowPrivacyMode(isPrivacyMode); 4970 promise.then(() => { 4971 console.info('Succeeded in setting the window to privacy mode.'); 4972 }).catch((err: BusinessError) => { 4973 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 4974 }); 4975} catch (exception) { 4976 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 4977} 4978``` 4979 4980### setWindowTouchable<sup>9+</sup> 4981 4982setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 4983 4984Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 4985 4986**Atomic service API**: This API can be used in atomic services since API version 12. 4987 4988**System capability**: SystemCapability.WindowManager.WindowManager.Core 4989 4990**Parameters** 4991 4992| Name| Type| Mandatory| Description| 4993| ----------- | ------------------------- | -- | ----------------------------------------------- | 4994| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 4995| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4996 4997**Error codes** 4998 4999For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5000 5001| ID| Error Message| 5002| ------- | -------------------------------------------- | 5003| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5004| 1300002 | This window state is abnormal. | 5005| 1300003 | This window manager service works abnormally. | 5006 5007**Example** 5008 5009```ts 5010import { BusinessError } from '@kit.BasicServicesKit'; 5011 5012let isTouchable = true; 5013try { 5014 windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => { 5015 const errCode: number = err.code; 5016 if (errCode) { 5017 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 5018 return; 5019 } 5020 console.info('Succeeded in setting the window to be touchable.'); 5021 }); 5022} catch (exception) { 5023 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 5024} 5025``` 5026 5027### setWindowTouchable<sup>9+</sup> 5028 5029setWindowTouchable(isTouchable: boolean): Promise<void> 5030 5031Sets whether this window is touchable. This API uses a promise to return the result. 5032 5033**Atomic service API**: This API can be used in atomic services since API version 12. 5034 5035**System capability**: SystemCapability.WindowManager.WindowManager.Core 5036 5037**Parameters** 5038 5039| Name| Type| Mandatory| Description| 5040| ----------- | ------- | -- | ----------------------------------------------- | 5041| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 5042 5043**Return value** 5044 5045| Type| Description| 5046| ------------------- | ------------------------- | 5047| Promise<void> | Promise that returns no value.| 5048 5049**Error codes** 5050 5051For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5052 5053| ID| Error Message| 5054| ------- | -------------------------------------------- | 5055| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5056| 1300002 | This window state is abnormal. | 5057| 1300003 | This window manager service works abnormally. | 5058 5059**Example** 5060 5061```ts 5062import { BusinessError } from '@kit.BasicServicesKit'; 5063 5064let isTouchable: boolean = true; 5065try { 5066 let promise = windowClass.setWindowTouchable(isTouchable); 5067 promise.then(() => { 5068 console.info('Succeeded in setting the window to be touchable.'); 5069 }).catch((err: BusinessError) => { 5070 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 5071 }); 5072} catch (exception) { 5073 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 5074} 5075``` 5076 5077### snapshot<sup>9+</sup> 5078 5079snapshot(callback: AsyncCallback<image.PixelMap>): void 5080 5081Captures this window. This API uses an asynchronous callback to return the result. 5082 5083**Atomic service API**: This API can be used in atomic services since API version 12. 5084 5085**System capability**: SystemCapability.WindowManager.WindowManager.Core 5086 5087**Parameters** 5088 5089| Name | Type | Mandatory| Description | 5090| ----------- | ------------------------- | ---- | -------------------- | 5091| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. | 5092 5093**Error codes** 5094 5095For details about the error codes, see [Window Error Codes](errorcode-window.md). 5096 5097| ID| Error Message| 5098| ------- | ------------------------------ | 5099| 1300002 | This window state is abnormal. | 5100 5101**Example** 5102 5103```ts 5104import { BusinessError } from '@kit.BasicServicesKit'; 5105import { image } from '@kit.ImageKit'; 5106 5107windowClass.snapshot((err: BusinessError, pixelMap: image.PixelMap) => { 5108 const errCode: number = err.code; 5109 if (errCode) { 5110 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 5111 return; 5112 } 5113 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 5114 pixelMap.release(); // Release the memory in time after the PixelMap is used. 5115}); 5116``` 5117 5118### snapshot<sup>9+</sup> 5119 5120snapshot(): Promise<image.PixelMap> 5121 5122Captures this window. This API uses a promise to return the result. 5123 5124**Atomic service API**: This API can be used in atomic services since API version 12. 5125 5126**System capability**: SystemCapability.WindowManager.WindowManager.Core 5127 5128**Return value** 5129 5130| Type | Description | 5131| ------------------- | ------------------------- | 5132| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot.| 5133 5134**Error codes** 5135 5136For details about the error codes, see [Window Error Codes](errorcode-window.md). 5137 5138| ID| Error Message| 5139| ------- | ------------------------------ | 5140| 1300002 | This window state is abnormal. | 5141 5142**Example** 5143 5144```ts 5145import { BusinessError } from '@kit.BasicServicesKit'; 5146import { image } from '@kit.ImageKit'; 5147 5148let promise = windowClass.snapshot(); 5149promise.then((pixelMap: image.PixelMap) => { 5150 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 5151 pixelMap.release(); // Release the memory in time after the PixelMap is used. 5152}).catch((err: BusinessError) => { 5153 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 5154}); 5155``` 5156 5157### setAspectRatio<sup>10+</sup> 5158 5159setAspectRatio(ratio: number): Promise<void> 5160 5161Sets the aspect ratio of the window content layout. This API uses a promise to return the result. 5162 5163When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**. 5164 5165This 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. 5166 5167**Atomic service API**: This API can be used in atomic services since API version 12. 5168 5169**System capability**: SystemCapability.WindowManager.WindowManager.Core 5170 5171**Parameters** 5172 5173| Name | Type | Mandatory| Description | 5174| ------------------ | ------- | ---- |-------------------------------------------| 5175| 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**.| 5176 5177**Return value** 5178 5179| Type | Description | 5180| ------------------- | ------------------------- | 5181| Promise<void> | Promise that returns no value.| 5182 5183**Error codes** 5184 5185For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5186 5187| ID| Error Message| 5188| ------- | -------------------------------------------- | 5189| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5190| 1300002 | This window state is abnormal. | 5191| 1300004 | Unauthorized operation. | 5192 5193**Example** 5194<!--code_no_check--> 5195```ts 5196// EntryAbility.ets 5197import { UIAbility } from '@kit.AbilityKit'; 5198import { BusinessError } from '@kit.BasicServicesKit'; 5199 5200export default class EntryAbility extends UIAbility { 5201 5202 // ... 5203 onWindowStageCreate(windowStage: window.WindowStage) { 5204 console.info('onWindowStageCreate'); 5205 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5206 if (!windowClass) { 5207 console.info('windowClass is null'); 5208 } 5209 try { 5210 let ratio = 1.0; 5211 let promise = windowClass.setAspectRatio(ratio); 5212 promise.then(() => { 5213 console.info('Succeeded in setting aspect ratio of window.'); 5214 }).catch((err: BusinessError) => { 5215 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5216 }); 5217 } catch (exception) { 5218 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5219 } 5220 } 5221} 5222``` 5223 5224### setAspectRatio<sup>10+</sup> 5225 5226setAspectRatio(ratio: number, callback: AsyncCallback<void>): void 5227 5228Sets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 5229 5230When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**. 5231 5232This 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. 5233 5234**Atomic service API**: This API can be used in atomic services since API version 12. 5235 5236**System capability**: SystemCapability.WindowManager.WindowManager.Core 5237 5238**Parameters** 5239 5240| Name | Type | Mandatory| Description | 5241| ------------------ | ------- | ---- |--------------------------------------------| 5242| 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**.| 5243| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 5244 5245**Error codes** 5246 5247For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5248 5249| ID| Error Message| 5250| ------- | -------------------------------------------- | 5251| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5252| 1300002 | This window state is abnormal. | 5253| 1300004 | Unauthorized operation. | 5254 5255**Example** 5256<!--code_no_check--> 5257```ts 5258// EntryAbility.ets 5259import { UIAbility } from '@kit.AbilityKit'; 5260import { BusinessError } from '@kit.BasicServicesKit'; 5261 5262export default class EntryAbility extends UIAbility { 5263 5264 // ... 5265 onWindowStageCreate(windowStage: window.WindowStage) { 5266 console.info('onWindowStageCreate'); 5267 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5268 if (!windowClass) { 5269 console.info('Failed to load the content. Cause: windowClass is null'); 5270 } 5271 try { 5272 let ratio = 1.0; 5273 windowClass.setAspectRatio(ratio, (err: BusinessError) => { 5274 const errCode: number = err.code; 5275 if (errCode) { 5276 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5277 return; 5278 } 5279 console.info('Succeeded in setting the aspect ratio of window.'); 5280 }); 5281 } catch (exception) { 5282 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5283 } 5284 } 5285} 5286 5287``` 5288 5289### resetAspectRatio<sup>10+</sup> 5290 5291resetAspectRatio(): Promise<void> 5292 5293Resets the aspect ratio of the window content layout. This API uses a promise to return the result. 5294 5295This 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. 5296 5297**Atomic service API**: This API can be used in atomic services since API version 12. 5298 5299**System capability**: SystemCapability.WindowManager.WindowManager.Core 5300 5301**Return value** 5302 5303| Type | Description | 5304| ------------------- | ------------------------- | 5305| Promise<void> | Promise that returns no value.| 5306 5307**Error codes** 5308 5309For details about the error codes, see [Window Error Codes](errorcode-window.md). 5310 5311| ID| Error Message| 5312| ------- | -------------------------------------------- | 5313| 1300002 | This window state is abnormal. | 5314| 1300004 | Unauthorized operation. | 5315 5316**Example** 5317<!--code_no_check--> 5318```ts 5319// EntryAbility.ets 5320import { UIAbility } from '@kit.AbilityKit'; 5321import { BusinessError } from '@kit.BasicServicesKit'; 5322 5323export default class EntryAbility extends UIAbility { 5324 5325 // ... 5326 onWindowStageCreate(windowStage: window.WindowStage) { 5327 console.info('onWindowStageCreate'); 5328 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5329 if (!windowClass) { 5330 console.info('Failed to load the content. Cause: windowClass is null'); 5331 } 5332 try { 5333 let promise = windowClass.resetAspectRatio(); 5334 promise.then(() => { 5335 console.info('Succeeded in resetting aspect ratio of window.'); 5336 }).catch((err: BusinessError) => { 5337 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5338 }); 5339 } catch (exception) { 5340 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5341 } 5342 } 5343} 5344``` 5345 5346### resetAspectRatio<sup>10+</sup> 5347 5348resetAspectRatio(callback: AsyncCallback<void>): void 5349 5350Resets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 5351 5352This 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. 5353 5354**Atomic service API**: This API can be used in atomic services since API version 12. 5355 5356**System capability**: SystemCapability.WindowManager.WindowManager.Core 5357 5358**Parameters** 5359 5360| Name | Type | Mandatory| Description | 5361| ------------------ | ------- | ---- | ------------------------------------------------------------ | 5362| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 5363 5364**Error codes** 5365 5366For details about the error codes, see [Window Error Codes](errorcode-window.md). 5367 5368| ID| Error Message| 5369| ------- | -------------------------------------------- | 5370| 1300002 | This window state is abnormal. | 5371| 1300004 | Unauthorized operation. | 5372 5373**Example** 5374<!--code_no_check--> 5375```ts 5376// EntryAbility.ets 5377import { UIAbility } from '@kit.AbilityKit'; 5378import { BusinessError } from '@kit.BasicServicesKit'; 5379 5380export default class EntryAbility extends UIAbility { 5381 5382 // ... 5383 onWindowStageCreate(windowStage: window.WindowStage) { 5384 console.info('onWindowStageCreate'); 5385 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5386 if (!windowClass) { 5387 console.info('Failed to load the content. Cause: windowClass is null'); 5388 } 5389 try { 5390 windowClass.resetAspectRatio((err: BusinessError) => { 5391 const errCode: number = err.code; 5392 if (errCode) { 5393 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5394 return; 5395 } 5396 console.info('Succeeded in resetting aspect ratio of window.'); 5397 }); 5398 } catch (exception) { 5399 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5400 } 5401 } 5402} 5403``` 5404 5405### minimize<sup>11+</sup> 5406 5407minimize(callback: AsyncCallback<void>): void 5408 5409The behavior of this API varies based on the caller: 5410 5411- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. 5412 5413- Hides the subwindow if the caller is a subwindow. The subwindow cannot be restored in the dock bar. 5414 5415This API uses an asynchronous callback to return the result. 5416 5417**Atomic service API**: This API can be used in atomic services since API version 12. 5418 5419**System capability**: SystemCapability.Window.SessionManager 5420 5421**Parameters** 5422 5423| Name | Type | Mandatory| Description | 5424| -------- | ------------------------- | ---- | ---------- | 5425| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 5426 5427**Error codes** 5428 5429For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5430 5431| ID| Error Message| 5432| ------- | ------------------------------ | 5433| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5434| 1300002 | This window state is abnormal. | 5435| 1300003 | This window manager service works abnormally. | 5436 5437**Example** 5438 5439```ts 5440import { BusinessError } from '@kit.BasicServicesKit'; 5441 5442windowClass.minimize((err: BusinessError) => { 5443 const errCode: number = err.code; 5444 if (errCode) { 5445 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 5446 return; 5447 } 5448 console.info('Succeeded in minimizing the window.'); 5449}); 5450``` 5451 5452### minimize<sup>11+</sup> 5453 5454minimize(): Promise<void> 5455 5456The behavior of this API varies based on the caller: 5457 5458- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. 5459 5460- Hides the subwindow if the caller is a subwindow. The subwindow cannot be restored in the dock bar. 5461 5462This API uses a promise to return the result. 5463 5464**Atomic service API**: This API can be used in atomic services since API version 12. 5465 5466**System capability**: SystemCapability.Window.SessionManager 5467 5468**Return value** 5469 5470| Type | Description | 5471| ------------------- | ------------------------- | 5472| Promise<void> | Promise that returns no value.| 5473 5474**Error codes** 5475 5476For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5477 5478| ID| Error Message| 5479| ------- | ------------------------------ | 5480| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5481| 1300002 | This window state is abnormal. | 5482| 1300003 | This window manager service works abnormally. | 5483 5484**Example** 5485 5486```ts 5487import { BusinessError } from '@kit.BasicServicesKit'; 5488 5489let promise = windowClass.minimize(); 5490promise.then(() => { 5491 console.info('Succeeded in minimizing the window.'); 5492}).catch((err: BusinessError) => { 5493 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 5494}); 5495``` 5496 5497### maximize<sup>12+</sup> 5498maximize(presentation?: MaximizePresentation): Promise<void> 5499 5500Maximizes the main window. This API uses a promise to return the result. 5501 5502<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 5503 5504**Atomic service API**: This API can be used in atomic services since API version 12. 5505 5506**System capability**: SystemCapability.Window.SessionManager 5507 5508**Parameters** 5509 5510| Name| Type | Mandatory| Description| 5511| ----- | ---------------------------- | -- | --------------------------------- | 5512| presentation | [MaximizePresentation](#maximizepresentation12) | No| Layout when the window is maximized. The default value is **window.MaximizePresentation.ENTER_IMMERSIVE**, indicating that the window enters the immersive layout when maximized.| 5513 5514**Return value** 5515 5516| Type | Description | 5517| ------------------- | ------------------------- | 5518| Promise<void> | Promise that returns no value.| 5519 5520**Error codes** 5521 5522For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5523 5524| ID| Error Message| 5525| ------- | ------------------------------ | 5526| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5527| 1300002 | This window state is abnormal. | 5528| 1300003 | This window manager service works abnormally. | 5529| 1300004 | Unauthorized operation. | 5530| 1300005 | This window stage is abnormal. | 5531 5532**Example** 5533 5534```ts 5535// EntryAbility.ets 5536import { UIAbility } from '@kit.AbilityKit'; 5537import { BusinessError } from '@kit.BasicServicesKit'; 5538export default class EntryAbility extends UIAbility { 5539 // ... 5540 5541 onWindowStageCreate(windowStage: window.WindowStage) { 5542 console.info('onWindowStageCreate'); 5543 let windowClass: window.Window | undefined = undefined; 5544 windowStage.getMainWindow((err: BusinessError, data) => { 5545 const errCode: number = err.code; 5546 if (errCode) { 5547 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5548 return; 5549 } 5550 windowClass = data; 5551 let promise = windowClass.maximize(); 5552 // let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 5553 promise.then(() => { 5554 console.info('Succeeded in maximizing the window.'); 5555 }).catch((err: BusinessError) => { 5556 console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`); 5557 }); 5558 }); 5559 } 5560}; 5561``` 5562 5563### setResizeByDragEnabled<sup>14+</sup> 5564setResizeByDragEnabled(enable: boolean, callback: AsyncCallback<void>): void 5565 5566Sets whether to enable the main window or subwindow with decorations to resize itself by dragging. This API uses an asynchronous callback to return the result. 5567 5568**Atomic service API**: This API can be used in atomic services since API version 14. 5569 5570**System capability**: SystemCapability.Window.SessionManager 5571 5572**Parameters** 5573 5574| Name| Type | Mandatory| Description| 5575| ----- | ---------------------------- | -- | --------------------------------- | 5576| 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.| 5577| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 5578 5579**Error codes** 5580 5581For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5582 5583| ID| Error Message| 5584| ------- | ------------------------------ | 5585| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5586| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5587| 1300002 | This window state is abnormal. | 5588| 1300003 | This window manager service works abnormally. | 5589 5590**Example** 5591 5592```ts 5593import { BusinessError } from '@kit.BasicServicesKit'; 5594 5595let enabled = false; 5596windowClass.setResizeByDragEnabled(enabled, (err) => { 5597 if (err.code) { 5598 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 5599 return; 5600 } 5601 console.info('Succeeded in setting the function of disabling the resize by drag window.'); 5602}); 5603``` 5604 5605### setResizeByDragEnabled<sup>14+</sup> 5606setResizeByDragEnabled(enable: boolean): Promise<void> 5607 5608Sets whether to enable the main window or subwindow with decorations to resize itself by dragging. This API uses a promise to return the result. 5609 5610**Atomic service API**: This API can be used in atomic services since API version 14. 5611 5612**System capability**: SystemCapability.Window.SessionManager 5613 5614**Parameters** 5615 5616| Name| Type | Mandatory| Description| 5617| ----- | ---------------------------- | -- | --------------------------------- | 5618| 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.| 5619 5620**Return value** 5621 5622| Type| Description| 5623| ------------------- | ------------------------ | 5624| Promise<void> | Promise that returns no value.| 5625 5626**Error codes** 5627 5628For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5629 5630| ID| Error Message| 5631| ------- | ------------------------------ | 5632| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5633| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5634| 1300002 | This window state is abnormal. | 5635| 1300003 | This window manager service works abnormally. | 5636 5637**Example** 5638 5639```ts 5640import { BusinessError } from '@kit.BasicServicesKit'; 5641 5642let enabled = false; 5643let promise = windowClass.setResizeByDragEnabled(enabled); 5644promise.then(() => { 5645 console.info('Succeeded in setting the function of disabling the resize by drag window.'); 5646}).catch((err: BusinessError) => { 5647 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 5648}); 5649``` 5650 5651### recover<sup>11+</sup> 5652 5653recover(): Promise<void> 5654 5655Restores the main window from the full-screen, maximized, or split-screen mode to a floating window, and restores the window size and position to those before the full-screen, maximized, or split-screen mode is entered. If the main window is already in the floating window mode, nothing will happen. This API uses a promise to return the result. It takes effect only in the multi-window stack layout on 2-in-1 devices. 5656 5657**Atomic service API**: This API can be used in atomic services since API version 12. 5658 5659**System capability**: SystemCapability.Window.SessionManager 5660 5661**Return value** 5662 5663| Type | Description | 5664| ------------------- | ------------------------- | 5665| Promise<void> | Promise that returns no value.| 5666 5667**Error codes** 5668 5669For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5670 5671| ID| Error Message| 5672| ------- | ------------------------------ | 5673| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5674| 1300001 | Repeated operation. | 5675| 1300002 | This window state is abnormal. | 5676 5677**Example** 5678 5679```ts 5680// EntryAbility.ets 5681import { UIAbility } from '@kit.AbilityKit'; 5682import { BusinessError } from '@kit.BasicServicesKit'; 5683 5684export default class EntryAbility extends UIAbility { 5685 // ... 5686 onWindowStageCreate(windowStage: window.WindowStage): void { 5687 console.info('onWindowStageCreate'); 5688 let windowClass: window.Window | undefined = undefined; 5689 windowStage.getMainWindow((err: BusinessError, data) => { 5690 const errCode: number = err.code; 5691 if (errCode) { 5692 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5693 return; 5694 } 5695 windowClass = data; 5696 let promise = windowClass.recover(); 5697 promise.then(() => { 5698 console.info('Succeeded in recovering the window.'); 5699 }).catch((err: BusinessError) => { 5700 console.error(`Failed to recover the window. Cause code: ${err.code}, message: ${err.message}`); 5701 }); 5702 }); 5703 } 5704} 5705``` 5706 5707### restore<sup>14+</sup> 5708 5709restore(): Promise<void> 5710 5711Restores 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. 5712 5713This API takes effect only in the multi-window stack layout when the main window is minimized and the UIAbility is in the **onForeground** state. It can be used only on 2-in-1 devices. 5714 5715**Atomic service API**: This API can be used in atomic services since API version 14. 5716 5717**System capability**: SystemCapability.Window.SessionManager 5718 5719**Return value** 5720 5721| Type | Description | 5722| ------------------- | ------------------------- | 5723| Promise<void> | Promise that returns no value.| 5724 5725**Error codes** 5726 5727For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5728 5729| **ID**| **Error Message** | 5730| ------------ | ------------------------------------------------------------ | 5731| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5732| 1300002 | This window state is abnormal. | 5733| 1300003 | This window manager service works abnormally. | 5734| 1300004 | Unauthorized operation. | 5735 5736**Example** 5737 5738```ts 5739// EntryAbility.ets 5740import { UIAbility } from '@kit.AbilityKit'; 5741import { BusinessError } from '@kit.BasicServicesKit'; 5742import { window } from '@kit.ArkUI'; 5743import { BusinessError } from '@kit.BasicServicesKit'; 5744 5745export default class EntryAbility extends UIAbility { 5746 onWindowStageCreate(windowStage: window.WindowStage): void { 5747 // Load the page corresponding to the main window. 5748 windowStage.loadContent('pages/Index', (err) => { 5749 let mainWindow: window.Window | undefined = undefined; 5750 // Obtain the main window. 5751 windowStage.getMainWindow().then( 5752 data => { 5753 mainWindow = data; 5754 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 5755 // Call minimize() to minimize the main window. 5756 mainWindow.minimize(); 5757 // Set the delay function to restore the main window after a delay of 5 seconds. 5758 setTimeout(()=>{ 5759 // Call restore() to restore the main window. 5760 let promise = mainWindow.restore(); 5761 promise.then(() => { 5762 console.info('Succeeded in restoring the window.'); 5763 }).catch((err: BusinessError) => { 5764 console.error(`Failed to restore the window. Cause code: ${err.code}, 5765 message: ${err.message}`); 5766 }); 5767 },5000); 5768 } 5769 ).catch((err: BusinessError) => { 5770 if(err.code){ 5771 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5772 } 5773 }); 5774 }); 5775 } 5776} 5777``` 5778 5779### getWindowLimits<sup>11+</sup> 5780 5781getWindowLimits(): WindowLimits 5782 5783Obtains the size limits of this application window. 5784 5785**Atomic service API**: This API can be used in atomic services since API version 12. 5786 5787**System capability**: SystemCapability.Window.SessionManager 5788 5789**Return value** 5790 5791| Type | Description | 5792| ----------------------------- | ------------------ | 5793| [WindowLimits](#windowlimits11) | Window size limits.| 5794 5795**Error codes** 5796 5797For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5798 5799| ID| Error Message | 5800| :------- | :----------------------------- | 5801| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5802| 1300002 | This window state is abnormal. | 5803 5804**Example** 5805 5806```ts 5807try { 5808 let windowLimits = windowClass.getWindowLimits(); 5809} catch (exception) { 5810 console.error(`Failed to obtain the window limits of window. Cause code: ${exception.code}, message: ${exception.message}`); 5811} 5812``` 5813 5814### setWindowLimits<sup>11+</sup> 5815 5816setWindowLimits(windowLimits: WindowLimits): Promise<WindowLimits> 5817 5818Sets the size limits for this application window. This API uses a promise to return the result. 5819By 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. 5820 5821**Atomic service API**: This API can be used in atomic services since API version 12. 5822 5823**System capability**: SystemCapability.Window.SessionManager 5824 5825**Parameters** 5826 5827| Name | Type | Mandatory| Description | 5828| :----------- | :---------------------------- | :--- | :----------------------------- | 5829| windowLimits | [WindowLimits](#windowlimits11) | Yes | Target size limits, in px.| 5830 5831**Return value** 5832 5833| Type | Description | 5834| :------------------------------------------- | :---------------------------------- | 5835| 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.| 5836 5837**Error codes** 5838 5839For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5840 5841| ID| Error Message | 5842| :------- | :-------------------------------------------- | 5843| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5844| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5845| 1300002 | This window state is abnormal. | 5846| 1300003 | This window manager service works abnormally. | 5847| 1300004 | Unauthorized operation. | 5848 5849**Example** 5850 5851```ts 5852import { BusinessError } from '@kit.BasicServicesKit'; 5853try { 5854 let windowLimits: window.WindowLimits = { 5855 maxWidth: 1500, 5856 maxHeight: 1000, 5857 minWidth: 500, 5858 minHeight: 400 5859 }; 5860 let promise = windowClass.setWindowLimits(windowLimits); 5861 promise.then((data) => { 5862 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 5863 }).catch((err: BusinessError) => { 5864 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 5865 }); 5866} catch (exception) { 5867 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 5868} 5869``` 5870 5871### setWindowMask<sup>12+</sup> 5872 5873setWindowMask(windowMask: Array<Array<number>>): Promise<void>; 5874 5875Sets a mask for this window to get an irregularly shaped window. This API uses a promise to return the result. 5876 5877The mask is used to describe the shape of the irregularly shaped window. 5878 5879This API is available only for subwindows and global floating windows on 2-in-1 devices. 5880 5881When the size of an irregularly shaped window changes, the actual display content is the intersection of the mask size and the window size. 5882 5883**Atomic service API**: This API can be used in atomic services since API version 12. 5884 5885**System capability**: SystemCapability.Window.SessionManager 5886 5887**Parameters** 5888 5889| Name | Type | Mandatory| Description | 5890| :----------- | :---------------------------- | :--- | :----------------------------- | 5891| 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.| 5892 5893**Return value** 5894 5895| Type | Description | 5896| :------------------------------------------- | :---------------------------------- | 5897| Promise<void> | Promise that returns no value.| 5898 5899**Error codes** 5900 5901For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5902 5903| ID| Error Message | 5904| :------- | :-------------------------------------------- | 5905| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5906| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5907| 1300002 | This window state is abnormal. | 5908| 1300003 | This window manager service works abnormally. | 5909| 1300004 | Unauthorized operation. | 5910 5911**Example** 5912 5913```ts 5914import { BusinessError } from '@kit.BasicServicesKit'; 5915try { 5916 let windowMask: Array<Array<number>> = [ 5917 [0, 0, 0, 1, 0, 0, 0], 5918 [0, 0, 1, 1, 1, 0, 0], 5919 [0, 1, 1, 0, 1, 1, 0], 5920 [1, 1, 0, 0, 0, 1, 1] 5921 ]; 5922 let promise = windowClass.setWindowMask(windowMask); 5923 promise.then(() => { 5924 console.info('Succeeded in setting the window mask.'); 5925 }).catch((err: BusinessError) => { 5926 console.error(`Failed to set the window mask. Cause code: ${err.code}, message: ${err.message}`); 5927 }); 5928} catch (exception) { 5929 console.error(`Failed to set the window mask. Cause code: ${exception.code}, message: ${exception.message}`); 5930} 5931``` 5932 5933### keepKeyboardOnFocus<sup>11+</sup> 5934 5935keepKeyboardOnFocus(keepKeyboardFlag: boolean): void 5936 5937Sets whether to keep the soft keyboard created by others when a window has focus. This API can be called only by a system window or an application subwindow. 5938 5939**Atomic service API**: This API can be used in atomic services since API version 12. 5940 5941**System capability**: SystemCapability.Window.SessionManager 5942 5943**Parameters** 5944 5945| Name | Type | Mandatory| Description | 5946| ---------------- | ------- | ---- | ------------------------------------------------------------ | 5947| 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.| 5948 5949**Error codes** 5950 5951For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5952 5953| ID| Error Message| 5954| ------- | ---------------------------------------- | 5955| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5956| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5957| 1300002 | This window state is abnormal. | 5958| 1300004 | Unauthorized operation. | 5959 5960**Example** 5961 5962```ts 5963try { 5964 windowClass.keepKeyboardOnFocus(true); 5965} catch (exception) { 5966 console.error(`Failed to keep keyboard onFocus. Cause code: ${exception.code}, message: ${exception.message}`); 5967} 5968``` 5969 5970### setWindowDecorVisible<sup>11+</sup> 5971 5972setWindowDecorVisible(isVisible: boolean): void 5973 5974Sets 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. 5975 5976When 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). 5977 5978**Atomic service API**: This API can be used in atomic services since API version 12. 5979 5980**System capability**: SystemCapability.Window.SessionManager 5981 5982**Parameters** 5983 5984| Name | Type | Mandatory| Description | 5985| --------- | ------- | ---- | --------------------------------------------- | 5986| isVisible | boolean | Yes | Whether the title bar is visible. The value **true** means that the title bar is visible and **false** means the opposite.| 5987 5988**Error codes** 5989 5990For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5991 5992| ID| Error Message | 5993| -------- | ------------------------------ | 5994| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5995| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5996| 1300002 | This window state is abnormal. | 5997| 1300004 | Unauthorized operation. | 5998 5999**Example** 6000 6001```ts 6002import { BusinessError } from '@kit.BasicServicesKit'; 6003let storage: LocalStorage = new LocalStorage(); 6004storage.setOrCreate('storageSimpleProp', 121); 6005windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 6006 let errCode: number = err.code; 6007 if (errCode) { 6008 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 6009 return; 6010 } 6011 console.info('Succeeded in loading the content.'); 6012 let isVisible = false; 6013 // Call setWindowDecorVisible. 6014 try { 6015 windowClass?.setWindowDecorVisible(isVisible); 6016 } catch (exception) { 6017 console.error(`Failed to set the visibility of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 6018 } 6019}); 6020``` 6021 6022### setWindowTitleMoveEnabled<sup>14+</sup> 6023 6024setWindowTitleMoveEnabled(enabled: boolean): void 6025 6026Enables or disables the capability to move the window (either main window or subwindow) by dragging its title bar and to maximize the window with a double-click. This API can be used only on 2-in-1 devices. When this capability is disabled, you can use [startMoving()](#startmoving14) to move the window by dragging in the application's hot zone and use [maximize()](#maximize12) to maximize the window. 6027 6028**Atomic service API**: This API can be used in atomic services since API version 14. 6029 6030**System capability**: SystemCapability.Window.SessionManager 6031 6032**Parameters** 6033 6034| Name | Type | Mandatory| Description | 6035| --------- | ------- | ---- | --------------------------------------------- | 6036| enabled | boolean | Yes | Whether to enable the capability to move the window by dragging the title bar and to maximize the window with a double-click. The value **true** means to enable the capability, and **false** means to disable it.| 6037 6038**Error codes** 6039 6040For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6041 6042| ID| Error Message | 6043| -------- | ------------------------------ | 6044| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6045| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6046| 1300002 | This window state is abnormal. | 6047| 1300004 | Unauthorized operation. | 6048 6049**Example** 6050 6051```ts 6052try { 6053 let enabled = false; 6054 windowClass.setWindowTitleMoveEnabled(enabled); 6055} catch (exception) { 6056 console.error(`Failed to set the window title move enabled. Cause code: ${exception.code}, message: ${exception.message}`); 6057} 6058``` 6059 6060### setSubWindowModal<sup>12+</sup> 6061 6062setSubWindowModal(isModal: boolean): Promise<void> 6063 6064Enables the modal property of the subwindow. This API uses a promise to return the result. 6065 6066This API must be called by a subwindow and the setting takes effect for the subwindow. 6067 6068After the modal property is enabled, the parent window does not respond to user interactions until the subwindow is closed or the subwindow's modal property is disabled. 6069 6070If this API is called by a main window, an error is reported. 6071 6072**Atomic service API**: This API can be used in atomic services since API version 12. 6073 6074**System capability**: SystemCapability.Window.SessionManager 6075 6076**Parameters** 6077 6078| Name | Type | Mandatory| Description | 6079| --------- | ------- | ---- | --------------------------------------------- | 6080| isModal | boolean | Yes | Whether to enable the modal property of the subwindow. The value **true** means to enable the modal property, and **false** means the opposite.| 6081 6082 6083**Return value** 6084 6085| Type| Description| 6086| ------------------- | ------------------------ | 6087| Promise<void> | Promise that returns no value.| 6088 6089**Error codes** 6090 6091For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6092 6093| ID| Error Message | 6094| -------- | ------------------------------ | 6095| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6096| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6097| 1300002 | This window state is abnormal. | 6098| 1300004 | Unauthorized operation. | 6099 6100**Example** 6101 6102```ts 6103// EntryAbility.ets 6104import { UIAbility } from '@kit.AbilityKit'; 6105import { BusinessError } from '@kit.BasicServicesKit'; 6106 6107export default class EntryAbility extends UIAbility { 6108 // ... 6109 onWindowStageCreate(windowStage: window.WindowStage): void { 6110 console.info('onWindowStageCreate'); 6111 let windowClass: window.Window | undefined = undefined; 6112 // Create a subwindow. 6113 try { 6114 let subWindow = windowStage.createSubWindow("testSubWindow"); 6115 subWindow.then((data) => { 6116 if (data == null) { 6117 console.error("Failed to create the subWindow. Cause: The data is empty"); 6118 return; 6119 } 6120 windowClass = data; 6121 let promise = windowClass.setSubWindowModal(true); 6122 promise.then(() => { 6123 console.info('Succeeded in setting subwindow modal'); 6124 }).catch((err: BusinessError) => { 6125 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 6126 }); 6127 }); 6128 } catch (exception) { 6129 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 6130 } 6131 } 6132} 6133``` 6134 6135### setSubWindowModal<sup>14+</sup> 6136 6137setSubWindowModal(isModal: boolean, modalityType: ModalityType): Promise<void> 6138 6139Sets the modality type of the subwindow. This API uses a promise to return the result. 6140 6141When the subwindow is of the window-modal type, its parent window does not respond to user interactions until the subwindow is closed or the subwindow's modal property is disabled. 6142 6143When the subwindow is of the application-modal type, its parent window and the windows from other instances of the application do not respond to user interactions until the subwindow is closed or the subwindow's modal property is disabled. 6144 6145This API is used to set the modality type. To disable the modal property, you are advised to use [setSubWindowModal<sup>12+</sup>](#setsubwindowmodal12). 6146 6147If this API is called by a main window, an error is reported. 6148 6149**Atomic service API**: This API can be used in atomic services since API version 14. 6150 6151**System capability**: SystemCapability.Window.SessionManager 6152 6153**Parameters** 6154 6155| Name | Type | Mandatory| Description | 6156| --------- | ------- | ---- | --------------------------------------------- | 6157| isModal | boolean | Yes | Whether to enable the modal property of the subwindow. The value **true** means to enable the modal property, and **false** means the opposite. Currently, this parameter can only be set to **true**.| 6158| modalityType | [ModalityType](#modalitytype14) | Yes | Modality type of the subwindow.| 6159 6160**Return value** 6161 6162| Type| Description| 6163| ------------------- | ------------------------ | 6164| Promise<void> | Promise that returns no value.| 6165 6166**Error codes** 6167 6168For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6169 6170| ID| Error Message | 6171| -------- | ------------------------------ | 6172| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6173| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6174| 1300002 | This window state is abnormal. | 6175| 1300004 | Unauthorized operation. | 6176 6177**Example** 6178 6179```ts 6180// EntryAbility.ets 6181import { UIAbility } from '@kit.AbilityKit'; 6182import { BusinessError } from '@kit.BasicServicesKit'; 6183import { window } from '@kit.ArkUI'; 6184 6185export default class EntryAbility extends UIAbility { 6186 // ... 6187 onWindowStageCreate(windowStage: window.WindowStage): void { 6188 console.info('onWindowStageCreate'); 6189 let windowClass: window.Window | undefined = undefined; 6190 // Create a subwindow. 6191 try { 6192 let subWindow = windowStage.createSubWindow("testSubWindow"); 6193 subWindow.then((data) => { 6194 if (data == null) { 6195 console.error("Failed to create the subWindow. Cause: The data is empty"); 6196 return; 6197 } 6198 windowClass = data; 6199 let promise = windowClass.setSubWindowModal(true, window.ModalityType.WINDOW_MODALITY); 6200 promise.then(() => { 6201 console.info('Succeeded in setting subwindow modal'); 6202 }).catch((err: BusinessError) => { 6203 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 6204 }); 6205 }); 6206 } catch (exception) { 6207 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 6208 } 6209 } 6210} 6211``` 6212 6213### setWindowDecorHeight<sup>11+</sup> 6214 6215setWindowDecorHeight(height: number): void 6216 6217<!--RP1--> 6218Sets 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. 6219<!--RP1End--> 6220 6221When 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. 6222 6223**Atomic service API**: This API can be used in atomic services since API version 12. 6224 6225**System capability**: SystemCapability.Window.SessionManager 6226 6227**Parameters** 6228 6229| Name| Type | Mandatory| Description | 6230| ------ | ------ | ---- | ------------------------------------------------------------ | 6231| 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.| 6232 6233**Error codes** 6234 6235For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6236 6237| ID| Error Message | 6238| -------- | ------------------------------ | 6239| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6240| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6241| 1300002 | This window state is abnormal. | 6242 6243**Example** 6244 6245```ts 6246windowClass.setUIContent('pages/WindowPage').then(() => { 6247 let height: number = 50; 6248 try { 6249 windowClass?.setWindowDecorHeight(height); 6250 console.info(`Succeeded in setting the height of window decor: ${height}`); 6251 } catch (exception) { 6252 console.error(`Failed to set the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 6253 } 6254}) 6255``` 6256 6257### setDecorButtonStyle<sup>14+</sup> 6258 6259setDecorButtonStyle(dectorStyle: DecorButtonStyle): void 6260 6261Sets the button style of the decoration bar. The setting takes effect only for the main window on 2-in-1 devices and the subwindow with the window title enabled. 6262 6263**Atomic service API**: This API can be used in atomic services since API version 14. 6264 6265**System capability**: SystemCapability.Window.SessionManager 6266 6267**Parameters** 6268 6269| Name | Type | Mandatory| Description | 6270| --------- | ------- | ---- | --------------------------------------------- | 6271| dectorStyle | [DecorButtonStyle](#decorbuttonstyle14) | Yes | Button style of the decoration bar.| 6272 6273**Error codes** 6274 6275For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6276 6277| ID| Error Message | 6278| -------- | ------------------------------ | 6279| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6280| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6281| 1300002 | This window state is abnormal. | 6282| 1300004 | Unauthorized operation. | 6283 6284**Example** 6285 6286```ts 6287import { ConfigurationConstant } from '@kit.AbilityKit'; 6288 6289try { 6290 let colorMode : ConfigurationConstant.ColorMode = ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT; 6291 let style: window.DecorButtonStyle = { 6292 colorMode: colorMode, 6293 buttonBackgroundSize: 24, 6294 spacingBetweenButtons: 12, 6295 closeButtonRightMargin: 20 6296 }; 6297 windowClass.setDecorButtonStyle(style); 6298 console.info('Succeeded in setting the style of button. Data: ' + JSON.stringify(style)); 6299} catch (exception) { 6300 console.error(`Failed to set the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 6301} 6302``` 6303 6304### getDecorButtonStyle<sup>14+</sup> 6305 6306getDecorButtonStyle(): DecorButtonStyle 6307 6308Obtains the button style of the decoration bar. The setting takes effect only for the main window on 2-in-1 devices and the subwindow with the window title enabled. 6309 6310**Atomic service API**: This API can be used in atomic services since API version 14. 6311 6312**System capability**: SystemCapability.Window.SessionManager 6313 6314**Return value** 6315 6316| Type | Description | 6317| ------------------------------------- | ------------------------------------------------------------ | 6318| [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.| 6319 6320**Error codes** 6321 6322For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6323 6324| ID| Error Message | 6325| -------- | ------------------------------ | 6326| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6327| 1300002 | This window state is abnormal. | 6328| 1300003 | This window manager service works abnormally. | 6329| 1300004 | Unauthorized operation. | 6330 6331**Example** 6332 6333```ts 6334try { 6335 let decorButtonStyle = windowClass.getDecorButtonStyle(); 6336 console.info('Succeeded in getting the style of button. Data: ' + JSON.stringify(decorButtonStyle)); 6337} catch (exception) { 6338 console.error(`Failed to get the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 6339} 6340``` 6341 6342### getWindowDecorHeight<sup>11+</sup> 6343 6344getWindowDecorHeight(): number 6345 6346<!--RP2--> 6347Obtains 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. 6348<!--RP2End--> 6349 6350**Atomic service API**: This API can be used in atomic services since API version 12. 6351 6352**System capability**: SystemCapability.Window.SessionManager 6353 6354**Return value** 6355 6356| Type | Description | 6357| ------ | ------------------------------------------------------------ | 6358| number | Height of the title bar. The value is an integer in the range [37,112]. The unit is vp.| 6359 6360**Error codes** 6361 6362For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6363 6364| ID| Error Message | 6365| -------- | ------------------------------ | 6366| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6367| 1300002 | This window state is abnormal. | 6368 6369**Example** 6370 6371```ts 6372windowClass.setUIContent('pages/WindowPage').then(() => { 6373 try { 6374 let height = windowClass?.getWindowDecorHeight(); 6375 console.info(`Succeeded in getting the height of window decor: ${height}`); 6376 } catch (exception) { 6377 console.error(`Failed to get the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 6378 } 6379}) 6380``` 6381 6382### getTitleButtonRect<sup>11+</sup> 6383 6384getTitleButtonRect(): TitleButtonRect 6385 6386Obtains the rectangle that holds the minimize, maximize, and close buttons on the title bar of the main window or the decorated subwindow. 6387 6388**Atomic service API**: This API can be used in atomic services since API version 12. 6389 6390**System capability**: SystemCapability.Window.SessionManager 6391 6392**Return value** 6393 6394| Type | Description | 6395| ------------------------------------- | ------------------------------------------------------------ | 6396| [TitleButtonRect](#titlebuttonrect11) | Rectangle obtained, which is located in the upper right corner of the window.| 6397 6398**Error codes** 6399 6400For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6401 6402| ID| Error Message | 6403| -------- | ------------------------------ | 6404| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6405| 1300002 | This window state is abnormal. | 6406 6407**Example** 6408 6409```ts 6410// EntryAbility.ets 6411import { UIAbility } from '@kit.AbilityKit'; 6412import { BusinessError } from '@kit.BasicServicesKit'; 6413 6414export default class EntryAbility extends UIAbility { 6415 // ... 6416 onWindowStageCreate(windowStage: window.WindowStage): void { 6417 console.info('onWindowStageCreate'); 6418 let windowClass: window.Window | undefined = undefined; 6419 windowStage.getMainWindow((err: BusinessError, data) => { 6420 const errCode: number = err.code; 6421 if (errCode) { 6422 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6423 return; 6424 } 6425 windowClass = data; 6426 try { 6427 let titleButtonArea = windowClass.getTitleButtonRect(); 6428 console.info('Succeeded in obtaining the area of title buttons. Data: ' + JSON.stringify(titleButtonArea)); 6429 } catch (exception) { 6430 console.error(`Failed to get the area of title buttons. Cause code: ${exception.code}, message: ${exception.message}`); 6431 } 6432 }); 6433 } 6434} 6435``` 6436 6437### getWindowStatus<sup>12+</sup> 6438 6439getWindowStatus(): WindowStatusType 6440 6441Obtains the mode of this window. 6442 6443> **NOTE** 6444> 6445> When this API is called on 2-in-1 devices, the return value is **WindowStatusType::FULL_SCREEN** when the window is maximized. 6446> 6447> Upon the return value **WindowStatusType::FULL_SCREEN**, you can call [getImmersiveModeEnabledState()](#getimmersivemodeenabledstate12) to determine whether the window is in full-screen or maximized mode on 2-in-1 devices. The return value **true** means that the window is in full-screen mode, and **false** means that the window is maximized. 6448 6449**Atomic service API**: This API can be used in atomic services since API version 12. 6450 6451**System capability**: SystemCapability.Window.SessionManager 6452 6453**Parameters** 6454 6455| Type | Description | 6456| ------------------------------ | ----------------------------------------| 6457| [WindowStatusType](#windowstatustype11) | Window mode. | 6458 6459**Error codes** 6460 6461For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6462 6463| ID| Error Message| 6464| ------- | ------------------------------ | 6465| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6466| 1300002 | This window state is abnormal. | 6467 6468**Example** 6469 6470```ts 6471try { 6472 let windowStatusType = windowClass.getWindowStatus(); 6473} catch (exception) { 6474 console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); 6475} 6476``` 6477 6478### isFocused<sup>12+</sup> 6479 6480isFocused(): boolean 6481 6482Checks whether this window is focused. 6483 6484**System capability**: SystemCapability.WindowManager.WindowManager.Core 6485 6486**Atomic service API**: This API can be used in atomic services since API version 12. 6487 6488**Return value** 6489 6490| Type| Description| 6491| ------- | ------------------------------------------------------------------ | 6492| boolean | Result indicating whether the window is focused. The value **true** means that the window is focused, and **false** means the opposite.| 6493 6494**Error codes** 6495 6496For details about the error codes, see [Window Error Codes](errorcode-window.md). 6497 6498| ID| Error Message| 6499| ------- | ------------------------------ | 6500| 1300002 | This window state is abnormal. | 6501 6502**Example** 6503 6504```ts 6505try { 6506 let focus = windowClass.isFocused(); 6507 console.info('Succeeded in checking whether the window is focused. Data: ' + JSON.stringify(focus)); 6508} catch (exception) { 6509 console.error(`Failed to check whether the window is focused. Cause code: ${exception.code}, message: ${exception.message}`); 6510} 6511``` 6512 6513### createSubWindowWithOptions<sup>12+</sup> 6514 6515createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 6516 6517Creates a subwindow under the main window or another subwindow. This API uses a promise to return the result. It takes effect only on 2-in-1 devices. 6518 6519**Model restriction**: This API can be used only in the stage model. 6520 6521**System capability**: SystemCapability.Window.SessionManager 6522 6523**Atomic service API**: This API can be used in atomic services since API version 12. 6524 6525**Parameters** 6526 6527| Name| Type | Mandatory| Description | 6528| ------ | ------ | ---- | -------------- | 6529| name | string | Yes | Name of the subwindow.| 6530| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the subwindow. | 6531 6532**Return value** 6533 6534| Type | Description | 6535| -------------------------------- | ------------------------------------------------ | 6536| Promise<[Window](#window)> | Promise used to used to return the subwindow created.| 6537 6538**Error codes** 6539 6540For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6541 6542| ID| Error Message| 6543| ------- | ------------------------------ | 6544| 401 | Parameter error. Possible cause: Incorrect parameter types. | 6545| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6546| 1300002 | This window state is abnormal. | 6547| 1300003 | This window manager service works abnormally. | 6548| 1300004 | Unauthorized operation. | 6549 6550**Example** 6551 6552```ts 6553import { BusinessError } from '@kit.BasicServicesKit'; 6554 6555try { 6556 let options : window.SubWindowOptions = { 6557 title: 'title', 6558 decorEnabled: true, 6559 isModal: true 6560 }; 6561 let promise = windowClass.createSubWindowWithOptions('mySubWindow', options); 6562 promise.then((data) => { 6563 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 6564 }).catch((err: BusinessError) => { 6565 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 6566 }); 6567} catch (exception) { 6568 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 6569} 6570``` 6571 6572### setWindowTitleButtonVisible<sup>14+</sup> 6573 6574setWindowTitleButtonVisible(isMaximizeButtonVisible: boolean, isMinimizeButtonVisible: boolean, isCloseButtonVisible?: boolean): void 6575 6576Shows or hides the maximize, minimize, and close buttons on the title bar of the main window. 6577 6578This API can be used only on 2-in-1 devices. 6579 6580**Atomic service API**: This API can be used in atomic services since API version 14. 6581 6582**System capability**: SystemCapability.Window.SessionManager 6583 6584**Parameters** 6585 6586| Name | Type | Mandatory| Description | 6587| --------- | ------- | ---- | --------------------------------------------- | 6588| isMaximizeButtonVisible | boolean | Yes | Whether to show the maximize button. The value **true** means to show the button, and **false** means to hide it. If the maximize button is hidden, the corresponding restore button is also hidden in the maximize scenario.| 6589| isMinimizeButtonVisible | boolean | Yes | Whether to show the minimize button. The value **true** means to show the button, and **false** means to hide it.| 6590| isCloseButtonVisible | boolean | No | Whether to show the close button. The value **true** means to show the button, and **false** means to hide it.| 6591 6592**Error codes** 6593 6594For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6595 6596| ID| Error Message | 6597| -------- | ------------------------------ | 6598| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6599| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6600| 1300002 | This window state is abnormal. | 6601| 1300004 | Unauthorized operation. | 6602 6603**Example** 6604 6605```ts 6606// EntryAbility.ets 6607import { UIAbility } from '@kit.AbilityKit'; 6608import { BusinessError } from '@kit.BasicServicesKit'; 6609import { window } from '@kit.ArkUI'; 6610 6611export default class EntryAbility extends UIAbility { 6612 onWindowStageCreate(windowStage: window.WindowStage): void { 6613 // Load the page corresponding to the main window. 6614 windowStage.loadContent('pages/Index', (err) => { 6615 let mainWindow: window.Window | undefined = undefined; 6616 // Obtain the main window. 6617 windowStage.getMainWindow().then( 6618 data => { 6619 mainWindow = data; 6620 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 6621 // Call setWindowTitleButtonVisible to hide the maximize, minimize, and close buttons on the title bar of the main window. 6622 mainWindow.setWindowTitleButtonVisible(false, false, false); 6623 } 6624 ).catch((err: BusinessError) => { 6625 if(err.code){ 6626 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6627 } 6628 }); 6629 }); 6630 } 6631} 6632``` 6633 6634### setWindowTopmost<sup>14+</sup> 6635 6636setWindowTopmost(isWindowTopmost: boolean): Promise<void> 6637 6638Places the main window above all the other windows of the application. This API uses a promise to return the result. 6639 6640Applications use custom shortcut keys to pin or unpin the main window. 6641 6642<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 6643 6644**Atomic service API**: This API can be used in atomic services since API version 14. 6645 6646**System capability**: SystemCapability.Window.SessionManager 6647 6648**Required permissions**: ohos.permission.WINDOW_TOPMOST 6649 6650**Parameters** 6651 6652| Name | Type | Mandatory| Description | 6653| --------- | ------- | ---- | --------------------------------------------- | 6654| 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.| 6655 6656 6657**Error codes** 6658 6659For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6660 6661| ID| Error Message | 6662| -------- | ------------------------------ | 6663| 201 | Permission verification failed. The application does not have the permission required to call the API. | 6664| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6665| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6666| 1300002 | This window state is abnormal. | 6667| 1300004 | Unauthorized operation. | 6668 6669**Example** 6670 6671```ts 6672// ets/pages/Index.ets 6673import { window } from '@kit.ArkUI'; 6674import { common } from '@kit.AbilityKit'; 6675import { BusinessError } from '@kit.BasicServicesKit'; 6676 6677const context = (getContext(this) as common.UIAbilityContext); 6678let windowClass: window.Window | undefined; 6679let keyUpEventAry: string[] = []; 6680 6681@Entry 6682@Component 6683struct Index { 6684 build() { 6685 RelativeContainer() { 6686 Button("Pin") 6687 .onClick(() => { 6688 try { 6689 let promiseCtx = window.getLastWindow(context); 6690 promiseCtx.then((data) => { 6691 windowClass = data; 6692 // The value true means to pin the window on top, and false means to unpin the window. 6693 let isWindowTopmost: boolean = true; 6694 let promiseTopmost = windowClass.setWindowTopmost(isWindowTopmost); 6695 promiseTopmost.then(() => { 6696 console.info('Succeeded in setting the main window to be topmost.'); 6697 }).catch((err: BusinessError) => { 6698 console.error(`Failed to set the main window to be topmost. Cause code: ${err.code}, message: ${err.message}`); 6699 }); 6700 }) 6701 } catch (exception) { 6702 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`) 6703 } 6704 }) 6705 } 6706 .height('100%') 6707 .width('100%') 6708 .onKeyEvent((event) => { 6709 if(event) { 6710 if(event.type === KeyType.Down) { 6711 keyUpEventAry = []; 6712 } 6713 if(event.type === KeyType.Up) { 6714 keyUpEventAry.push(event.keyText); 6715 // Press Ctrl+T to pin or unpin the main window. 6716 if(windowClass && keyUpEventAry.includes('KEYCODE_CTRL_LEFT') && keyUpEventAry.includes('KEYCODE_T')) { 6717 let isWindowTopmost: boolean = false; 6718 windowClass.setWindowTopmost(isWindowTopmost); 6719 } 6720 } 6721 } 6722 }) 6723 } 6724} 6725``` 6726 6727### raiseToAppTop<sup>14+</sup> 6728 6729raiseToAppTop(): Promise<void> 6730 6731Called by a subwindow to elevate the subwindow to the topmost layer. Its effect is limited to subwindows of the same type that share the same parent window of the current application. This API uses a promise to return the result. 6732 6733**System capability**: SystemCapability.WindowManager.WindowManager.Core 6734 6735**Return value** 6736 6737| Type | Description | 6738| ------------------- | ------------------------- | 6739| Promise<void> | Promise that returns no value.| 6740 6741**Error codes** 6742 6743For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6744 6745| ID| Error Message| 6746| ------- | ------------------------------ | 6747| 1300002 | This window state is abnormal. | 6748| 1300003 | This window manager service works abnormally. | 6749| 1300004 | Unauthorized operation. | 6750| 1300009 | The parent window is invalid. | 6751 6752**Example** 6753 6754```ts 6755import { BusinessError } from '@kit.BasicServicesKit'; 6756 6757let promise = windowClass.raiseToAppTop(); 6758promise.then(() => { 6759 console.info('Succeeded in raising the window to app top.'); 6760}).catch((err: BusinessError) => { 6761 console.error(`Failed to raise the window to app top. Cause code: ${err.code}, message: ${err.message}`); 6762}); 6763``` 6764 6765### setRaiseByClickEnabled<sup>14+</sup> 6766 6767setRaiseByClickEnabled(enable: boolean): Promise<void> 6768 6769Sets whether to enable a subwindow to raise itself by click. This API uses a promise to return the result. 6770 6771Generally, when a subwindow is clicked, it is brought to the forefront among sibling subwindows of the same type that share the same parent window within the application. If the **enable** parameter is set to **false**, when the subwindow is clicked, it still stays in its existing position. 6772 6773**System capability**: SystemCapability.Window.SessionManager 6774 6775**Parameters** 6776 6777| Name | Type | Mandatory| Description | 6778| -------- | ------------------------- | ---- | ---------- | 6779| enable | boolean | Yes | Whether a subwindow can be raised by clicking. The value **true** means that the subwindow can be raised by clicking, and **false** means the opposite.| 6780 6781**Return value** 6782 6783| Type | Description | 6784| ------------------- | ------------------------- | 6785| Promise<void> | Promise that returns no value.| 6786 6787**Error codes** 6788 6789For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6790 6791| ID| Error Message| 6792| ------- | ------------------------------ | 6793| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6794| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6795| 1300002 | This window state is abnormal. | 6796| 1300003 | This window manager service works abnormally. | 6797| 1300004 | Unauthorized operation. | 6798| 1300009 | The parent window is invalid. | 6799 6800**Example** 6801 6802```ts 6803// EntryAbility.ets 6804import { UIAbility } from '@kit.AbilityKit'; 6805import { BusinessError } from '@kit.BasicServicesKit'; 6806 6807export default class EntryAbility extends UIAbility { 6808 // ... 6809 onWindowStageCreate(windowStage: window.WindowStage): void { 6810 console.info('onWindowStageCreate'); 6811 let windowClass: window.Window | undefined = undefined; 6812 // Create a subwindow. 6813 try { 6814 let subWindow = windowStage.createSubWindow("testSubWindow"); 6815 subWindow.then((data) => { 6816 if (data == null) { 6817 console.error("Failed to create the subWindow. Cause: The data is empty"); 6818 return; 6819 } 6820 windowClass = data; 6821 let enabled = false; 6822 let promise = windowClass.setRaiseByClickEnabled(enabled); 6823 promise.then(()=> { 6824 console.info('Succeeded in disabling the raise-by-click function.'); 6825 }).catch((err: BusinessError)=>{ 6826 console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`); 6827 }); 6828 }); 6829 } catch (exception) { 6830 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 6831 } 6832 } 6833} 6834``` 6835 6836### enableLandscapeMultiWindow<sup>12+</sup> 6837 6838enableLandscapeMultiWindow(): Promise<void> 6839 6840Enables 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. 6841 6842This 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. 6843 6844**Atomic service API**: This API can be used in atomic services since API version 12. 6845 6846**System capability**: SystemCapability.Window.SessionManager 6847 6848**Return value** 6849 6850| Type | Description | 6851| ------------------- | ------------------------- | 6852| Promise<void> | Promise that returns no value.| 6853 6854**Error codes** 6855 6856For details about the error codes, see [Window Error Codes](errorcode-window.md). 6857 6858| ID| Error Message| 6859| ------- | -------------------------------------------- | 6860| 1300002 | This window state is abnormal. | 6861| 1300003 | This window manager service works abnormally. | 6862 6863**Example** 6864 6865```ts 6866// EntryAbility.ets 6867import { UIAbility } from '@kit.AbilityKit'; 6868import { BusinessError } from '@kit.BasicServicesKit'; 6869import { window } from '@kit.ArkUI'; 6870 6871export default class EntryAbility extends UIAbility { 6872 // ... 6873 onWindowStageCreate(windowStage: window.WindowStage): void { 6874 console.info('onWindowStageCreate'); 6875 let windowClass: window.Window | undefined = undefined; 6876 windowStage.getMainWindow((err: BusinessError, data) => { 6877 const errCode: number = err.code; 6878 if (errCode) { 6879 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6880 return; 6881 } 6882 windowClass = data; 6883 let promise = windowClass.enableLandscapeMultiWindow(); 6884 promise.then(() => { 6885 console.info('Succeeded in making multi-window become landscape.'); 6886 }).catch((err: BusinessError) => { 6887 console.error(`Failed to make multi-window become landscape. Cause code: ${err.code}, message: ${err.message}`); 6888 }); 6889 }); 6890 } 6891} 6892``` 6893 6894### disableLandscapeMultiWindow<sup>12+</sup> 6895 6896disableLandscapeMultiWindow(): Promise<void> 6897 6898Disables the landscape multi-window mode for the UI page that supports the horizontal layout. 6899 6900This 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. 6901 6902**Atomic service API**: This API can be used in atomic services since API version 12. 6903 6904**System capability**: SystemCapability.Window.SessionManager 6905 6906**Return value** 6907 6908| Type | Description | 6909| ------------------- | ------------------------- | 6910| Promise<void> | Promise that returns no value.| 6911 6912**Error codes** 6913 6914For details about the error codes, see [Window Error Codes](errorcode-window.md). 6915 6916| ID| Error Message| 6917| ------- | -------------------------------------------- | 6918| 1300002 | This window state is abnormal. | 6919| 1300003 | This window manager service works abnormally. | 6920 6921**Example** 6922 6923```ts 6924// EntryAbility.ets 6925import { UIAbility } from '@kit.AbilityKit'; 6926import { BusinessError } from '@kit.BasicServicesKit'; 6927import { window } from '@kit.ArkUI'; 6928 6929export default class EntryAbility extends UIAbility { 6930 // ... 6931 onWindowStageCreate(windowStage: window.WindowStage): void { 6932 console.info('onWindowStageCreate'); 6933 let windowClass: window.Window | undefined = undefined; 6934 windowStage.getMainWindow((err: BusinessError, data) => { 6935 const errCode: number = err.code; 6936 if (errCode) { 6937 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6938 return; 6939 } 6940 windowClass = data; 6941 let promise = windowClass.disableLandscapeMultiWindow(); 6942 promise.then(() => { 6943 console.info('Succeeded in making multi-window become not landscape.'); 6944 }).catch((err: BusinessError) => { 6945 console.error(`Failed to make multi-window become not landscape. Cause code: ${err.code}, message: ${err.message}`); 6946 }); 6947 }); 6948 } 6949} 6950``` 6951 6952### setDialogBackGestureEnabled<sup>12+</sup> 6953 6954setDialogBackGestureEnabled(enabled: boolean): Promise<void> 6955 6956Sets 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. 6957 6958**System capability**: SystemCapability.Window.SessionManager 6959 6960**Atomic service API**: This API can be used in atomic services since API version 12. 6961 6962**Parameters** 6963 6964| Name | Type | Mandatory| Description | 6965| ---------- | ------- | ---- | ------------------------------------------------------------ | 6966| 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>| 6967 6968**Return value** 6969 6970| Type | Description | 6971| ------------------- | ------------------------- | 6972| Promise<void> | Promise that returns no value.| 6973 6974**Error codes** 6975 6976For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6977 6978| ID| Error Message| 6979| ------- | -------------------------------------------- | 6980| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6981| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6982| 1300002 | This window state is abnormal. | 6983| 1300003 | This window manager service works abnormally. | 6984| 1300004 | Unauthorized operation. | 6985 6986**Example** 6987 6988```ts 6989// EntryAbility.ets 6990import { UIAbility } from '@kit.AbilityKit'; 6991import { BusinessError } from '@kit.BasicServicesKit'; 6992 6993export default class EntryAbility extends UIAbility { 6994 onWindowStageCreate(windowStage: window.WindowStage): void { 6995 console.info('onWindowStageCreate'); 6996 let windowClass: window.Window | undefined = undefined; 6997 let config: window.Configuration = { 6998 name: "test", 6999 windowType: window.WindowType.TYPE_DIALOG, 7000 ctx: this.context 7001 }; 7002 try { 7003 window.createWindow(config, (err: BusinessError, data) => { 7004 const errCode: number = err.code; 7005 if (errCode) { 7006 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 7007 return; 7008 } 7009 windowClass = data; 7010 windowClass.setUIContent("pages/Index"); 7011 let enabled = true; 7012 let promise = windowClass.setDialogBackGestureEnabled(enabled); 7013 promise.then(() => { 7014 console.info('Succeeded in setting dialog window to respond back gesture.'); 7015 }).catch((err: BusinessError) => { 7016 console.error(`Failed to set dialog window to respond back gesture. Cause code: ${err.code}, message: ${err.message}`); 7017 }); 7018 }); 7019 } catch (exception) { 7020 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 7021 } 7022 } 7023} 7024``` 7025 7026```ts 7027// ets/pages/Index.ets 7028@Entry 7029@Component 7030struct Index { 7031 @State message: string = 'Hello World' 7032 build() { 7033 RelativeContainer() { 7034 Text(this.message) 7035 .id('HelloWorld') 7036 .fontSize(50) 7037 .fontWeight(FontWeight.Bold) 7038 } 7039 .height('100%') 7040 .width('100%') 7041 } 7042 7043 onBackPress(): boolean | void { 7044 console.info('Succeeded in setting dialog window to respond back gesture.'); 7045 return true; 7046 } 7047} 7048``` 7049 7050### startMoving<sup>14+</sup> 7051 7052startMoving(): Promise<void> 7053 7054Starts moving this window. This API uses a promise to return the result. 7055 7056The 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**. 7057 7058This API takes effect only for the main window, subwindow, and system window on 2-in-1 devices. If it is called for other device types or window types, an error is reported. 7059 7060**System capability**: SystemCapability.Window.SessionManager 7061 7062**Atomic service API**: This API can be used in atomic services since API version 14. 7063 7064**Return value** 7065 7066| Type | Description | 7067| ------------------- | ------------------------- | 7068| Promise<void> | Promise that returns no value.| 7069 7070**Error codes** 7071 7072For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7073 7074| ID| Error Message| 7075| -------- | -------------------------------------------- | 7076| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7077| 1300001 | Repeated operation. | 7078| 1300002 | This window state is abnormal. | 7079| 1300003 | This window manager service works abnormally. | 7080| 1300004 | Unauthorized operation. | 7081 7082**Example** 7083 7084```ts 7085// ets/pages/Index.ets 7086import { BusinessError } from '@kit.BasicServicesKit'; 7087 7088@Entry 7089@Component 7090struct Index { 7091 build() { 7092 Row() { 7093 Column() { 7094 Blank('160') 7095 .color(Color.Blue) 7096 .onTouch((event: TouchEvent) => { 7097 if (event.type === TouchType.Down) { 7098 try { 7099 windowClass.startMoving().then(() => { 7100 console.info('Succeeded in starting moving window.') 7101 }).catch((err: BusinessError) => { 7102 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 7103 }); 7104 } catch (exception) { 7105 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 7106 } 7107 } 7108 }) 7109 }.width('100%') 7110 }.height('100%').width('100%') 7111 } 7112} 7113``` 7114 7115### setGestureBackEnabled<sup>13+<sup> 7116 7117setGestureBackEnabled(enabled: boolean): Promise<void> 7118 7119Sets 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. 7120 7121When 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. 7122 7123When 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. 7124 7125**System capability**: SystemCapability.Window.SessionManager 7126 7127**Atomic service API**: This API can be used in atomic services since API version 13. 7128 7129**Parameters** 7130 7131| Name | Type | Mandatory | Description | 7132| ---------- | --------- | -------- | --------------------------------------------- | 7133| enabled | boolean | Yes | Whether to enable the back gesture feature. The value **true** means to enable the feature, and **false** means to disable it.| 7134 7135**Return value** 7136 7137| Type | Description | 7138| ------------------- | ------------------------- | 7139| Promise<void> | Promise that returns no value.| 7140 7141**Error codes** 7142 7143For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7144 7145| ID| Error Message | 7146| -------- | ------------------------------------------------------------------------------------------------------------ | 7147| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7148| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7149| 1300002 | This window state is abnormal. | 7150| 1300003 | This window manager service works abnormally. | 7151| 1300004 | Unauthorized operation. | 7152 7153**Example** 7154 7155```ts 7156// EntryAbility.ets 7157import { UIAbility } from '@kit.AbilityKit'; 7158import { BusinessError } from '@kit.BasicServicesKit'; 7159import { window } from '@kit.ArkUI'; 7160 7161export default class EntryAbility extends UIAbility { 7162 // ... 7163 onWindowStageCreate(windowStage: window.WindowStage): void { 7164 console.info('onWindowStageCreate'); 7165 let windowClass: window.Window | undefined = undefined; 7166 windowStage.getMainWindow((err: BusinessError, data) => { 7167 const errCode: number = err.code; 7168 if (errCode) { 7169 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7170 return; 7171 } 7172 windowClass = data; 7173 7174 // Disable the back gesture feature in the current window. 7175 try { 7176 let gestureBackEnabled: boolean = false; 7177 let promise = windowClass.setGestureBackEnabled(gestureBackEnabled); 7178 promise.then(() => { 7179 console.info(`Succeeded in setting gesture back disabled`); 7180 }).catch((err: BusinessError) => { 7181 console.error(`Failed to set gesture back disabled, Cause code: ${err.code}, message: ${err.message}`); 7182 }); 7183 } catch(exception) { 7184 console.error(`Failed to set gesture back disabled, Cause code: ${exception.code}, message: ${exception.message}`); 7185 } 7186 }); 7187 } 7188} 7189``` 7190 7191### isGestureBackEnabled<sup>13+<sup> 7192 7193isGestureBackEnabled(): boolean 7194 7195Checks 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. 7196 7197**System capability**: SystemCapability.Window.SessionManager 7198 7199**Atomic service API**: This API can be used in atomic services since API version 13. 7200 7201**Return value** 7202 7203| Type | Description | 7204| ------------------- | --------------------------------------------- | 7205| 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.| 7206 7207**Error codes** 7208 7209For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7210 7211| ID| Error Message | 7212| -------- | ------------------------------------------------------------------------------------------------------------ | 7213| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7214| 1300002 | This window state is abnormal. | 7215| 1300003 | This window manager service works abnormally. | 7216| 1300004 | Unauthorized operation. | 7217 7218**Example** 7219 7220```ts 7221// EntryAbility.ets 7222import { UIAbility } from '@kit.AbilityKit'; 7223import { BusinessError } from '@kit.BasicServicesKit'; 7224import { window } from '@kit.ArkUI'; 7225 7226export default class EntryAbility extends UIAbility { 7227 // ... 7228 onWindowStageCreate(windowStage: window.WindowStage): void { 7229 console.info('onWindowStageCreate'); 7230 let windowClass: window.Window | undefined = undefined; 7231 windowStage.getMainWindow((err: BusinessError, data) => { 7232 const errCode: number = err.code; 7233 if (errCode) { 7234 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7235 return; 7236 } 7237 windowClass = data; 7238 7239 // Check whether the back gesture feature is enabled in the current window. 7240 try { 7241 let gestureBackEnabled: boolean = windowClass.isGestureBackEnabled(); 7242 console.info(`Succeeded in obtaining gesture back enabled status: ${gestureBackEnabled}`); 7243 } catch (exception) { 7244 console.error(`Failed to get gesture back enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 7245 } 7246 }); 7247 } 7248} 7249``` 7250 7251### setWindowSystemBarProperties<sup>(deprecated)</sup> 7252 7253setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 7254 7255Sets the properties of the three-button navigation bar and status bar of the main window. This API uses an asynchronous callback to return the result. <!--RP5-->This API does not take effect on 2-in-1 devices.<!--RP5End--> 7256 7257This API does not take effect when it is called by a subwindow. 7258 7259> **NOTE** 7260> 7261> 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. 7262 7263**System capability**: SystemCapability.WindowManager.WindowManager.Core 7264 7265**Atomic service API**: This API can be used in atomic services since API version 12. 7266 7267**Parameters** 7268 7269| Name | Type | Mandatory| Description | 7270| ------------------- | ------------------------------------------- | ---- | ---------------------- | 7271| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.| 7272| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7273 7274**Error codes** 7275 7276For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7277 7278| ID| Error Message | 7279| -------- | ------------------------------------------------------------------------------------------------------------ | 7280| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7281| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7282| 1300002 | This window state is abnormal. | 7283| 1300003 | This window manager service works abnormally. | 7284 7285**Example** 7286 7287```ts 7288// EntryAbility.ets 7289import { UIAbility } from '@kit.AbilityKit'; 7290import { BusinessError } from '@kit.BasicServicesKit'; 7291 7292export default class EntryAbility extends UIAbility { 7293 // ... 7294 onWindowStageCreate(windowStage: window.WindowStage): void { 7295 console.info('onWindowStageCreate'); 7296 let windowClass: window.Window | undefined = undefined; 7297 windowStage.getMainWindow((err: BusinessError, data) => { 7298 const errCode: number = err.code; 7299 if (errCode) { 7300 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7301 return; 7302 } 7303 windowClass = data; 7304 let SystemBarProperties: window.SystemBarProperties = { 7305 statusBarColor: '#ff00ff', 7306 navigationBarColor: '#00ff00', 7307 // The following properties are supported since API version 8. 7308 statusBarContentColor: '#ffffff', 7309 navigationBarContentColor: '#00ffff' 7310 }; 7311 try { 7312 windowClass.setWindowSystemBarProperties(SystemBarProperties, (err: BusinessError) => { 7313 const errCode: number = err.code; 7314 if (errCode) { 7315 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 7316 return; 7317 } 7318 console.info('Succeeded in setting the system bar properties.'); 7319 }); 7320 } catch (exception) { 7321 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 7322 } 7323 }); 7324 } 7325} 7326``` 7327 7328### setWindowSystemBarEnable<sup>(deprecated)</sup> 7329 7330setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 7331 7332Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses an asynchronous callback to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 7333 7334The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow. 7335 7336> **NOTE** 7337> 7338> 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. 7339 7340**Atomic service API**: This API can be used in atomic services since API version 12. 7341 7342**System capability**: SystemCapability.WindowManager.WindowManager.Core 7343 7344**Parameters** 7345 7346| Name | Type | Mandatory| Description | 7347| -------- | ----------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------- | 7348| names | Array<'status'\|'navigation'> | Yes | Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.<br>For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.| 7349| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7350 7351**Error codes** 7352 7353For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7354 7355| ID| Error Message | 7356| -------- | ------------------------------------------------------------------------------------------------------------ | 7357| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7358| 1300002 | This window state is abnormal. | 7359| 1300003 | This window manager service works abnormally. | 7360 7361**Example** 7362 7363```ts 7364// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 7365// EntryAbility.ets 7366import { UIAbility } from '@kit.AbilityKit'; 7367import { BusinessError } from '@kit.BasicServicesKit'; 7368 7369export default class EntryAbility extends UIAbility { 7370 // ... 7371 onWindowStageCreate(windowStage: window.WindowStage): void { 7372 console.info('onWindowStageCreate'); 7373 let windowClass: window.Window | undefined = undefined; 7374 windowStage.getMainWindow((err: BusinessError, data) => { 7375 const errCode: number = err.code; 7376 if (errCode) { 7377 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7378 return; 7379 } 7380 windowClass = data; 7381 let names: Array<'status' | 'navigation'> = []; 7382 try { 7383 windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => { 7384 const errCode: number = err.code; 7385 if (errCode) { 7386 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 7387 return; 7388 } 7389 console.info('Succeeded in setting the system bar to be invisible.'); 7390 }); 7391 } catch (exception) { 7392 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 7393 } 7394 }); 7395 } 7396} 7397``` 7398 7399### setWindowLayoutFullScreen<sup>(deprecated)</sup> 7400 7401setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 7402 7403Sets whether the main window layout or the subwindow layout is immersive. This API uses an asynchronous callback to return the result. 7404- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 7405- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 7406 7407> **NOTE** 7408> 7409> 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. 7410 7411**System capability**: SystemCapability.WindowManager.WindowManager.Core 7412 7413**Atomic service API**: This API can be used in atomic services since API version 12. 7414 7415**Parameters** 7416 7417| Name | Type | Mandatory| Description | 7418| ------------------ | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------- | 7419| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window layout is immersive, and **false** means the opposite.| 7420| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7421 7422**Error codes** 7423 7424For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7425 7426| ID| Error Message | 7427| -------- | ------------------------------------------------------------------------------------------------------------ | 7428| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7429| 1300002 | This window state is abnormal. | 7430| 1300003 | This window manager service works abnormally. | 7431 7432**Example** 7433 7434```ts 7435// EntryAbility.ets 7436import { UIAbility } from '@kit.AbilityKit'; 7437import { BusinessError } from '@kit.BasicServicesKit'; 7438 7439export default class EntryAbility extends UIAbility { 7440 // ... 7441 onWindowStageCreate(windowStage: window.WindowStage): void { 7442 console.info('onWindowStageCreate'); 7443 let windowClass: window.Window | undefined = undefined; 7444 windowStage.getMainWindow((err: BusinessError, data) => { 7445 const errCode: number = err.code; 7446 if (errCode) { 7447 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7448 return; 7449 } 7450 windowClass = data; 7451 let isLayoutFullScreen = true; 7452 try { 7453 windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 7454 const errCode: number = err.code; 7455 if (errCode) { 7456 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 7457 return; 7458 } 7459 console.info('Succeeded in setting the window layout to full-screen mode.'); 7460 }); 7461 } catch (exception) { 7462 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 7463 } 7464 }); 7465 } 7466} 7467``` 7468 7469### show<sup>(deprecated)</sup> 7470 7471show(callback: AsyncCallback<void>): void 7472 7473Shows this window. This API uses an asynchronous callback to return the result. 7474 7475> **NOTE** 7476> 7477> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9) instead. 7478 7479**System capability**: SystemCapability.WindowManager.WindowManager.Core 7480 7481**Parameters** 7482 7483| Name | Type | Mandatory| Description | 7484| -------- | ------------------------- | ---- | ---------- | 7485| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 7486 7487**Example** 7488 7489```ts 7490import { BusinessError } from '@kit.BasicServicesKit'; 7491 7492windowClass.show((err: BusinessError) => { 7493 const errCode: number = err.code; 7494 if (errCode) { 7495 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 7496 return; 7497 } 7498 console.info('Succeeded in showing the window.'); 7499}); 7500``` 7501 7502### show<sup>(deprecated)</sup> 7503 7504show(): Promise<void> 7505 7506Shows this window. This API uses a promise to return the result. 7507 7508> **NOTE** 7509> 7510> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9-1) instead. 7511 7512**System capability**: SystemCapability.WindowManager.WindowManager.Core 7513 7514**Return value** 7515 7516| Type | Description | 7517| ------------------- | ------------------------- | 7518| Promise<void> | Promise that returns no value.| 7519 7520**Example** 7521 7522```ts 7523import { BusinessError } from '@kit.BasicServicesKit'; 7524 7525let promise = windowClass.show(); 7526promise.then(() => { 7527 console.info('Succeeded in showing the window.'); 7528}).catch((err: BusinessError) => { 7529 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 7530}); 7531``` 7532 7533### destroy<sup>(deprecated)</sup> 7534 7535destroy(callback: AsyncCallback<void>): void 7536 7537Destroys this window. This API uses an asynchronous callback to return the result. 7538 7539> **NOTE** 7540> 7541> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9) instead. 7542 7543**System capability**: SystemCapability.WindowManager.WindowManager.Core 7544 7545**Parameters** 7546 7547| Name | Type | Mandatory| Description | 7548| -------- | ------------------------- | ---- | ---------- | 7549| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 7550 7551**Example** 7552 7553```ts 7554import { BusinessError } from '@kit.BasicServicesKit'; 7555 7556windowClass.destroy((err: BusinessError) => { 7557 const errCode: number = err.code; 7558 if (err.code) { 7559 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 7560 return; 7561 } 7562 console.info('Succeeded in destroying the window.'); 7563}); 7564``` 7565 7566### destroy<sup>(deprecated)</sup> 7567 7568destroy(): Promise<void> 7569 7570Destroys this window. This API uses a promise to return the result. 7571 7572> **NOTE** 7573> 7574> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9-1) instead. 7575 7576**System capability**: SystemCapability.WindowManager.WindowManager.Core 7577 7578**Return value** 7579 7580| Type | Description | 7581| ------------------- | ------------------------- | 7582| Promise<void> | Promise that returns no value.| 7583 7584**Example** 7585 7586```ts 7587import { BusinessError } from '@kit.BasicServicesKit'; 7588 7589let promise = windowClass.destroy(); 7590promise.then(() => { 7591 console.info('Succeeded in destroying the window.'); 7592}).catch((err: BusinessError) => { 7593 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 7594}); 7595``` 7596 7597### moveTo<sup>(deprecated)</sup> 7598 7599moveTo(x: number, y: number, callback: AsyncCallback<void>): void 7600 7601Moves this window. This API uses an asynchronous callback to return the result. 7602 7603This operation is not supported in a window in full-screen mode. 7604 7605> **NOTE** 7606> 7607> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9) instead. 7608 7609**System capability**: SystemCapability.WindowManager.WindowManager.Core 7610 7611**Parameters** 7612 7613| Name | Type | Mandatory| Description | 7614| -------- | ------------------------- | ---- | ------------------------------------------------- | 7615| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 7616| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 7617| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7618 7619**Example** 7620 7621```ts 7622import { BusinessError } from '@kit.BasicServicesKit'; 7623 7624windowClass.moveTo(300, 300, (err: BusinessError) => { 7625 const errCode: number = err.code; 7626 if (errCode) { 7627 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 7628 return; 7629 } 7630 console.info('Succeeded in moving the window.'); 7631}); 7632``` 7633 7634### moveTo<sup>(deprecated)</sup> 7635 7636moveTo(x: number, y: number): Promise<void> 7637 7638Moves this window. This API uses a promise to return the result. 7639 7640This operation is not supported in a window in full-screen mode. 7641 7642> **NOTE** 7643> 7644> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9-1) instead. 7645 7646**System capability**: SystemCapability.WindowManager.WindowManager.Core 7647 7648**Parameters** 7649 7650| Name| Type | Mandatory| Description | 7651| ------ | ------ | ---- | ------------------------------------------------- | 7652| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 7653| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 7654 7655**Return value** 7656 7657| Type | Description | 7658| ------------------- | ------------------------- | 7659| Promise<void> | Promise that returns no value.| 7660 7661**Example** 7662 7663```ts 7664import { BusinessError } from '@kit.BasicServicesKit'; 7665 7666let promise = windowClass.moveTo(300, 300); 7667promise.then(() => { 7668 console.info('Succeeded in moving the window.'); 7669}).catch((err: BusinessError) => { 7670 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 7671}); 7672``` 7673 7674### resetSize<sup>(deprecated)</sup> 7675 7676resetSize(width: number, height: number, callback: AsyncCallback<void>): void 7677 7678Changes the size of this window. This API uses an asynchronous callback to return the result. 7679 7680The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 7681The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 7682 7683The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 7684 7685The window width and height you set must meet the limits. The rules are as follows: 7686- 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. 7687- 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. 7688 7689This operation is not supported in a window in full-screen mode. 7690 7691> **NOTE** 7692> 7693> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9) instead. 7694 7695**System capability**: SystemCapability.WindowManager.WindowManager.Core 7696 7697**Parameters** 7698 7699| Name | Type | Mandatory| Description | 7700| -------- | ------------------------- | ---- | -------------------------- | 7701| 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.| 7702| 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.| 7703| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7704 7705**Example** 7706 7707```ts 7708import { BusinessError } from '@kit.BasicServicesKit'; 7709 7710windowClass.resetSize(500, 1000, (err: BusinessError) => { 7711 const errCode: number = err.code; 7712 if (errCode) { 7713 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 7714 return; 7715 } 7716 console.info('Succeeded in changing the window size.'); 7717}); 7718``` 7719 7720### resetSize<sup>(deprecated)</sup> 7721 7722resetSize(width: number, height: number): Promise<void> 7723 7724Changes the size of this window. This API uses a promise to return the result. 7725 7726The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 7727The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 7728 7729The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 7730 7731The window width and height you set must meet the limits. The rules are as follows: 7732- 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. 7733- 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. 7734 7735This operation is not supported in a window in full-screen mode. 7736 7737> **NOTE** 7738> 7739> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9-1) instead. 7740 7741**System capability**: SystemCapability.WindowManager.WindowManager.Core 7742 7743**Parameters** 7744 7745| Name| Type | Mandatory| Description | 7746| ------ | ------ | ---- | -------------------------- | 7747| 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.| 7748| 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.| 7749 7750**Return value** 7751 7752| Type | Description | 7753| ------------------- | ------------------------- | 7754| Promise<void> | Promise that returns no value.| 7755 7756**Example** 7757 7758```ts 7759import { BusinessError } from '@kit.BasicServicesKit'; 7760 7761let promise = windowClass.resetSize(500, 1000); 7762promise.then(() => { 7763 console.info('Succeeded in changing the window size.'); 7764}).catch((err: BusinessError) => { 7765 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 7766}); 7767``` 7768 7769### getProperties<sup>(deprecated)</sup> 7770 7771getProperties(callback: AsyncCallback<WindowProperties>): void 7772 7773Obtains the properties of this window. This API uses an asynchronous callback to return the result. 7774 7775> **NOTE** 7776> 7777> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 7778 7779**System capability**: SystemCapability.WindowManager.WindowManager.Core 7780 7781**Parameters** 7782 7783| Name | Type | Mandatory| Description | 7784| -------- | ---------------------------------------------------------- | ---- | ---------------------------- | 7785| callback | AsyncCallback<[WindowProperties](#windowproperties)> | Yes | Callback used to return the window properties.| 7786 7787**Example** 7788 7789```ts 7790import { BusinessError } from '@kit.BasicServicesKit'; 7791 7792windowClass.getProperties((err: BusinessError, data) => { 7793 const errCode: number = err.code; 7794 if (errCode) { 7795 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 7796 return; 7797 } 7798 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 7799}); 7800``` 7801 7802### getProperties<sup>(deprecated)</sup> 7803 7804getProperties(): Promise<WindowProperties> 7805 7806Obtains the properties of this window. This API uses a promise to return the result. 7807 7808> **NOTE** 7809> 7810> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 7811 7812**System capability**: SystemCapability.WindowManager.WindowManager.Core 7813 7814**Return value** 7815 7816| Type | Description | 7817| ---------------------------------------------------- | ------------------------------- | 7818| Promise<[WindowProperties](#windowproperties)> | Promise used to return the window properties.| 7819 7820**Example** 7821 7822```ts 7823import { BusinessError } from '@kit.BasicServicesKit'; 7824 7825let promise = windowClass.getProperties(); 7826promise.then((data) => { 7827 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 7828}).catch((err: BusinessError) => { 7829 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 7830}); 7831``` 7832 7833### getAvoidArea<sup>(deprecated)</sup> 7834 7835getAvoidArea(type: [AvoidAreaType](#avoidareatype7), callback: AsyncCallback<[AvoidArea](#avoidarea7)>): void 7836 7837Obtains 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. 7838 7839> **NOTE** 7840> 7841> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 7842 7843**System capability**: SystemCapability.WindowManager.WindowManager.Core 7844 7845**Parameters** 7846 7847| Name | Type | Mandatory| Description | 7848| -------- |-----------------------------------------------| ---- | ------------------------------------------------------------ | 7849| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area.| 7850| callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 7851 7852**Example** 7853 7854```ts 7855import { BusinessError } from '@kit.BasicServicesKit'; 7856 7857let type = window.AvoidAreaType.TYPE_SYSTEM; 7858windowClass.getAvoidArea(type, (err: BusinessError, data) => { 7859 const errCode: number = err.code; 7860 if (errCode) { 7861 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 7862 return; 7863 } 7864 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 7865}); 7866``` 7867 7868### getAvoidArea<sup>(deprecated)</sup> 7869 7870getAvoidArea(type: [AvoidAreaType](#avoidareatype7)): Promise<[AvoidArea](#avoidarea7)> 7871 7872Obtains 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. 7873 7874> **NOTE** 7875> 7876> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 7877 7878**System capability**: SystemCapability.WindowManager.WindowManager.Core 7879 7880**Parameters** 7881 7882| Name| Type | Mandatory| Description | 7883| ------ |----------------------------------| ---- | ------------------------------------------------------------ | 7884| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area.| 7885 7886**Return value** 7887 7888| Type | Description | 7889|-----------------------------------------| ----------------------------------- | 7890| Promise<[AvoidArea](#avoidarea7)> | Promise used to return the area.| 7891 7892**Example** 7893 7894```ts 7895import { BusinessError } from '@kit.BasicServicesKit'; 7896 7897let type = window.AvoidAreaType.TYPE_SYSTEM; 7898let promise = windowClass.getAvoidArea(type); 7899promise.then((data) => { 7900 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 7901}).catch((err: BusinessError) => { 7902 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 7903}); 7904``` 7905 7906### setFullScreen<sup>(deprecated)</sup> 7907 7908setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void 7909 7910Sets whether the main window or the subwindow is in full-screen mode. This API uses an asynchronous callback to return the result. 7911- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them. 7912- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them. 7913 7914> **NOTE** 7915> 7916> 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. 7917 7918**System capability**: SystemCapability.WindowManager.WindowManager.Core 7919 7920**Parameters** 7921 7922| Name | Type | Mandatory| Description | 7923| ------------ | ------------------------- | ---- | ---------------------------------------------- | 7924| isFullScreen | boolean | Yes | Whether to set full-screen mode. This setting affects the display of the status bar and navigation bar. The value **true** means to set full-screen mode, and **false** means the opposite.| 7925| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7926 7927**Example** 7928 7929```ts 7930// EntryAbility.ets 7931import { UIAbility } from '@kit.AbilityKit'; 7932import { BusinessError } from '@kit.BasicServicesKit'; 7933 7934export default class EntryAbility extends UIAbility { 7935 // ... 7936 onWindowStageCreate(windowStage: window.WindowStage): void { 7937 console.info('onWindowStageCreate'); 7938 let windowClass: window.Window | undefined = undefined; 7939 windowStage.getMainWindow((err: BusinessError, data) => { 7940 const errCode: number = err.code; 7941 if (errCode) { 7942 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7943 return; 7944 } 7945 windowClass = data; 7946 let isFullScreen: boolean = true; 7947 windowClass.setFullScreen(isFullScreen, (err: BusinessError) => { 7948 const errCode: number = err.code; 7949 if (errCode) { 7950 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 7951 return; 7952 } 7953 console.info('Succeeded in enabling the full-screen mode.'); 7954 }); 7955 }); 7956 } 7957} 7958``` 7959 7960### setFullScreen<sup>(deprecated)</sup> 7961 7962setFullScreen(isFullScreen: boolean): Promise<void> 7963 7964Sets whether the main window or the subwindow is in full-screen mode. This API uses a promise to return the result. 7965- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them. 7966- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them. 7967 7968> **NOTE** 7969> 7970> 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. 7971 7972**System capability**: SystemCapability.WindowManager.WindowManager.Core 7973 7974**Parameters** 7975 7976| Name | Type | Mandatory| Description | 7977| ------------ | ------- | ---- | ---------------------------------------------- | 7978| isFullScreen | boolean | Yes | Whether to set full-screen mode. This setting affects the display of the status bar and navigation bar. The value **true** means to set full-screen mode, and **false** means the opposite.| 7979 7980**Return value** 7981 7982| Type | Description | 7983| ------------------- | ------------------------- | 7984| Promise<void> | Promise that returns no value.| 7985 7986**Example** 7987 7988```ts 7989// EntryAbility.ets 7990import { UIAbility } from '@kit.AbilityKit'; 7991import { BusinessError } from '@kit.BasicServicesKit'; 7992 7993export default class EntryAbility extends UIAbility { 7994 // ... 7995 onWindowStageCreate(windowStage: window.WindowStage): void { 7996 console.info('onWindowStageCreate'); 7997 let windowClass: window.Window | undefined = undefined; 7998 windowStage.getMainWindow((err: BusinessError, data) => { 7999 const errCode: number = err.code; 8000 if (errCode) { 8001 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8002 return; 8003 } 8004 windowClass = data; 8005 let isFullScreen: boolean = true; 8006 let promise = windowClass.setFullScreen(isFullScreen); 8007 promise.then(() => { 8008 console.info('Succeeded in enabling the full-screen mode.'); 8009 }).catch((err: BusinessError) => { 8010 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 8011 }); 8012 }); 8013 } 8014} 8015``` 8016 8017### setLayoutFullScreen<sup>(deprecated)</sup> 8018 8019setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 8020 8021Sets whether the main window layout or the subwindow layout is immersive. This API uses an asynchronous callback to return the result. 8022- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 8023- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 8024 8025> **NOTE** 8026> 8027> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9) instead. 8028 8029**System capability**: SystemCapability.WindowManager.WindowManager.Core 8030 8031**Parameters** 8032 8033| Name | Type | Mandatory| Description | 8034| ------------------ | ------------------------- | ---- | ------------------------------------------------------------ | 8035| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. This setting does not affect the display of the status bar and navigation bar. The value **true** means that the window layout is immersive, and **false** means the opposite.| 8036| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8037 8038**Example** 8039 8040```ts 8041// EntryAbility.ets 8042import { UIAbility } from '@kit.AbilityKit'; 8043import { BusinessError } from '@kit.BasicServicesKit'; 8044 8045export default class EntryAbility extends UIAbility { 8046 // ... 8047 onWindowStageCreate(windowStage: window.WindowStage): void { 8048 console.info('onWindowStageCreate'); 8049 let windowClass: window.Window | undefined = undefined; 8050 windowStage.getMainWindow((err: BusinessError, data) => { 8051 const errCode: number = err.code; 8052 if (errCode) { 8053 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8054 return; 8055 } 8056 windowClass = data; 8057 let isLayoutFullScreen: boolean = true; 8058 windowClass.setLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 8059 const errCode: number = err.code; 8060 if (errCode) { 8061 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 8062 return; 8063 } 8064 console.info('Succeeded in setting the window layout to full-screen mode.'); 8065 }); 8066 }); 8067 } 8068} 8069``` 8070 8071### setLayoutFullScreen<sup>(deprecated)</sup> 8072 8073setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 8074 8075Sets whether the main window layout or the subwindow layout is immersive. This API uses a promise to return the result. 8076- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 8077- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 8078 8079> **NOTE** 8080> 8081> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9-1) instead. 8082 8083**System capability**: SystemCapability.WindowManager.WindowManager.Core 8084 8085**Parameters** 8086 8087| Name | Type | Mandatory| Description | 8088| ------------------ | ------- | ---- | ------------------------------------------------------------ | 8089| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. This setting does not affect the display of the status bar and navigation bar. The value **true** means that the window layout is immersive, and **false** means the opposite.| 8090 8091**Return value** 8092 8093| Type | Description | 8094| ------------------- | ------------------------- | 8095| Promise<void> | Promise that returns no value.| 8096 8097**Example** 8098 8099```ts 8100// EntryAbility.ets 8101import { UIAbility } from '@kit.AbilityKit'; 8102import { BusinessError } from '@kit.BasicServicesKit'; 8103 8104export default class EntryAbility extends UIAbility { 8105 // ... 8106 onWindowStageCreate(windowStage: window.WindowStage): void { 8107 console.info('onWindowStageCreate'); 8108 let windowClass: window.Window | undefined = undefined; 8109 windowStage.getMainWindow((err: BusinessError, data) => { 8110 const errCode: number = err.code; 8111 if (errCode) { 8112 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8113 return; 8114 } 8115 windowClass = data; 8116 let isLayoutFullScreen: boolean = true; 8117 let promise = windowClass.setLayoutFullScreen(isLayoutFullScreen); 8118 promise.then(() => { 8119 console.info('Succeeded in setting the window layout to full-screen mode.'); 8120 }).catch((err: BusinessError) => { 8121 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 8122 }); 8123 }); 8124 } 8125} 8126``` 8127 8128### setSystemBarEnable<sup>(deprecated)</sup> 8129 8130setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 8131 8132Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses an asynchronous callback to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 8133 8134The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow. 8135 8136> **NOTE** 8137> 8138> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) instead. 8139 8140**System capability**: SystemCapability.WindowManager.WindowManager.Core 8141 8142**Parameters** 8143 8144| Name | Type | Mandatory| Description | 8145| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 8146| names | Array<'status'\|'navigation'> | Yes | Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.<br>For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.| 8147| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8148 8149 8150**Example** 8151 8152```ts 8153// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 8154// EntryAbility.ets 8155import { UIAbility } from '@kit.AbilityKit'; 8156import { BusinessError } from '@kit.BasicServicesKit'; 8157 8158export default class EntryAbility extends UIAbility { 8159 // ... 8160 onWindowStageCreate(windowStage: window.WindowStage): void { 8161 console.info('onWindowStageCreate'); 8162 let windowClass: window.Window | undefined = undefined; 8163 windowStage.getMainWindow((err: BusinessError, data) => { 8164 const errCode: number = err.code; 8165 if (errCode) { 8166 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8167 return; 8168 } 8169 windowClass = data; 8170 let names: Array<'status' | 'navigation'> = []; 8171 windowClass.setSystemBarEnable(names, (err: BusinessError) => { 8172 const errCode: number = err.code; 8173 if (errCode) { 8174 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 8175 return; 8176 } 8177 console.info('Succeeded in setting the system bar to be invisible.'); 8178 }); 8179 }); 8180 } 8181} 8182``` 8183 8184### setSystemBarEnable<sup>(deprecated)</sup> 8185 8186setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 8187 8188Sets whether to show the three-button navigation bar, status bar, and bottom navigation bar of the main window. This API uses a promise to return the result. The display of the status bar and bottom navigation bar is controlled by **status**, and that of the three-button navigation bar is controlled by **navigation**. From API version 12, <!--RP5-->this API does not take effect on 2-in-1 devices.<!--RP5End--> 8189 8190The return value does not indicate that the visibility changes of the three-button navigation bar, status bar, and bottom navigation bar have been fully executed. This API does not take effect when it is called by a subwindow. 8191 8192> **NOTE** 8193> 8194> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9-1) instead. 8195 8196**System capability**: SystemCapability.WindowManager.WindowManager.Core 8197 8198**Parameters** 8199 8200| Name| Type | Mandatory| Description | 8201| ------ | ---------------------------- | ---- | ------------------------ | 8202| names | Array<'status'\|'navigation'> | Yes | Whether to show the three-button navigation bar, status bar, and bottom navigation bar of the window in full-screen mode.<br>For example, to display all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.| 8203 8204**Return value** 8205 8206| Type | Description | 8207| ------------------- | ------------------------- | 8208| Promise<void> | Promise that returns no value.| 8209 8210 8211**Example** 8212 8213```ts 8214// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 8215// EntryAbility.ets 8216import { UIAbility } from '@kit.AbilityKit'; 8217import { BusinessError } from '@kit.BasicServicesKit'; 8218 8219export default class EntryAbility extends UIAbility { 8220 // ... 8221 onWindowStageCreate(windowStage: window.WindowStage): void { 8222 console.info('onWindowStageCreate'); 8223 let windowClass: window.Window | undefined = undefined; 8224 windowStage.getMainWindow((err: BusinessError, data) => { 8225 const errCode: number = err.code; 8226 if (errCode) { 8227 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8228 return; 8229 } 8230 windowClass = data; 8231 let names: Array<'status' | 'navigation'> = []; 8232 let promise = windowClass.setSystemBarEnable(names); 8233 promise.then(() => { 8234 console.info('Succeeded in setting the system bar to be invisible.'); 8235 }).catch((err: BusinessError) => { 8236 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 8237 }); 8238 }); 8239 } 8240} 8241``` 8242 8243### setSystemBarProperties<sup>(deprecated)</sup> 8244 8245setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 8246 8247Sets the properties of the three-button navigation bar and status bar of the main window. This API uses an asynchronous callback to return the result. <!--RP5-->This API does not take effect on 2-in-1 devices.<!--RP5End--> 8248 8249This API does not take effect when it is called by a subwindow. 8250 8251> **NOTE** 8252> 8253> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9) instead. 8254 8255**System capability**: SystemCapability.WindowManager.WindowManager.Core 8256 8257**Parameters** 8258 8259| Name | Type | Mandatory| Description | 8260| ------------------- | ------------------------------------------- | ---- | ---------------------- | 8261| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.| 8262| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8263 8264**Example** 8265 8266```ts 8267// EntryAbility.ets 8268import { UIAbility } from '@kit.AbilityKit'; 8269import { BusinessError } from '@kit.BasicServicesKit'; 8270 8271export default class EntryAbility extends UIAbility { 8272 // ... 8273 onWindowStageCreate(windowStage: window.WindowStage): void { 8274 console.info('onWindowStageCreate'); 8275 let windowClass: window.Window | undefined = undefined; 8276 windowStage.getMainWindow((err: BusinessError, data) => { 8277 const errCode: number = err.code; 8278 if (errCode) { 8279 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8280 return; 8281 } 8282 windowClass = data; 8283 let SystemBarProperties: window.SystemBarProperties = { 8284 statusBarColor: '#ff00ff', 8285 navigationBarColor: '#00ff00', 8286 // The following properties are supported since API version 8. 8287 statusBarContentColor: '#ffffff', 8288 navigationBarContentColor: '#00ffff' 8289 }; 8290 windowClass.setSystemBarProperties(SystemBarProperties, (err) => { 8291 const errCode: number = err.code; 8292 if (errCode) { 8293 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 8294 return; 8295 } 8296 console.info('Succeeded in setting the system bar properties.'); 8297 }); 8298 }); 8299 } 8300} 8301``` 8302 8303### setSystemBarProperties<sup>(deprecated)</sup> 8304 8305setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 8306 8307Sets the properties of the three-button navigation bar and 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--> 8308 8309This API does not take effect when it is called by a subwindow. 8310 8311> **NOTE** 8312> 8313> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9-1) instead. 8314 8315**System capability**: SystemCapability.WindowManager.WindowManager.Core 8316 8317**Parameters** 8318 8319| Name | Type | Mandatory| Description | 8320| ------------------- | ------------------------------------------- | ---- | ---------------------- | 8321| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.| 8322 8323**Return value** 8324 8325| Type | Description | 8326| ------------------- | ------------------------- | 8327| Promise<void> | Promise that returns no value.| 8328 8329**Example** 8330 8331```ts 8332// EntryAbility.ets 8333import { UIAbility } from '@kit.AbilityKit'; 8334import { BusinessError } from '@kit.BasicServicesKit'; 8335 8336export default class EntryAbility extends UIAbility { 8337 // ... 8338 onWindowStageCreate(windowStage: window.WindowStage): void { 8339 console.info('onWindowStageCreate'); 8340 let windowClass: window.Window | undefined = undefined; 8341 windowStage.getMainWindow((err: BusinessError, data) => { 8342 const errCode: number = err.code; 8343 if (errCode) { 8344 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8345 return; 8346 } 8347 windowClass = data; 8348 let SystemBarProperties: window.SystemBarProperties = { 8349 statusBarColor: '#ff00ff', 8350 navigationBarColor: '#00ff00', 8351 // The following properties are supported since API version 8. 8352 statusBarContentColor: '#ffffff', 8353 navigationBarContentColor: '#00ffff' 8354 }; 8355 let promise = windowClass.setSystemBarProperties(SystemBarProperties); 8356 promise.then(() => { 8357 console.info('Succeeded in setting the system bar properties.'); 8358 }).catch((err: BusinessError) => { 8359 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 8360 }); 8361 }); 8362 } 8363} 8364``` 8365 8366### loadContent<sup>(deprecated)</sup> 8367 8368loadContent(path: string, callback: AsyncCallback<void>): void 8369 8370Loads content from a page to this window. This API uses an asynchronous callback to return the result. 8371 8372> **NOTE** 8373> 8374> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9) instead. 8375 8376**System capability**: SystemCapability.WindowManager.WindowManager.Core 8377 8378**Parameters** 8379 8380| Name | Type | Mandatory| Description | 8381| -------- | ------------------------- | ---- | -------------------- | 8382| 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.| 8383| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8384 8385**Example** 8386 8387```ts 8388import { BusinessError } from '@kit.BasicServicesKit'; 8389 8390windowClass.loadContent('pages/page2/page3', (err: BusinessError) => { 8391 const errCode: number = err.code; 8392 if (errCode) { 8393 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8394 return; 8395 } 8396 console.info('Succeeded in loading the content.'); 8397}); 8398``` 8399 8400### loadContent<sup>(deprecated)</sup> 8401 8402loadContent(path: string): Promise<void> 8403 8404Loads content from a page to this window. This API uses a promise to return the result. 8405 8406> **NOTE** 8407> 8408> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9-1) instead. 8409 8410**System capability**: SystemCapability.WindowManager.WindowManager.Core 8411 8412**Parameters** 8413 8414| Name| Type | Mandatory| Description | 8415| ------ | ------ | ---- | -------------------- | 8416| 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.| 8417 8418**Return value** 8419 8420| Type | Description | 8421| ------------------- | ------------------------- | 8422| Promise<void> | Promise that returns no value.| 8423 8424**Example** 8425 8426```ts 8427import { BusinessError } from '@kit.BasicServicesKit'; 8428 8429let promise = windowClass.loadContent('pages/page2/page3'); 8430promise.then(() => { 8431 console.info('Succeeded in loading the content.'); 8432}).catch((err: BusinessError) => { 8433 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8434}); 8435``` 8436 8437### isShowing<sup>(deprecated)</sup> 8438 8439isShowing(callback: AsyncCallback<boolean>): void 8440 8441Checks whether this window is displayed. This API uses an asynchronous callback to return the result. 8442 8443> **NOTE** 8444> 8445> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 8446 8447**System capability**: SystemCapability.WindowManager.WindowManager.Core 8448 8449**Parameters** 8450 8451| Name | Type | Mandatory| Description | 8452| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 8453| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the window is displayed, and **false** means the opposite.| 8454 8455**Example** 8456 8457```ts 8458import { BusinessError } from '@kit.BasicServicesKit'; 8459 8460windowClass.isShowing((err: BusinessError, data) => { 8461 const errCode: number = err.code; 8462 if (errCode) { 8463 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 8464 return; 8465 } 8466 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 8467}); 8468``` 8469 8470### isShowing<sup>(deprecated)</sup> 8471 8472isShowing(): Promise<boolean> 8473 8474Checks whether this window is displayed. This API uses a promise to return the result. 8475 8476> **NOTE** 8477> 8478> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 8479 8480**System capability**: SystemCapability.WindowManager.WindowManager.Core 8481 8482**Return value** 8483 8484| Type | Description | 8485| ---------------------- | ------------------------------------------------------------ | 8486| Promise<boolean> | Promise used to return the result. The value **true** means that the window is displayed, and **false** means the opposite.| 8487 8488**Example** 8489 8490```ts 8491import { BusinessError } from '@kit.BasicServicesKit'; 8492 8493let promise = windowClass.isShowing(); 8494promise.then((data) => { 8495 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 8496}).catch((err: BusinessError) => { 8497 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 8498}); 8499``` 8500 8501### on('systemAvoidAreaChange')<sup>(deprecated)</sup> 8502 8503on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void 8504 8505Subscribes to the event indicating changes to the area where this window cannot be displayed. 8506 8507> **NOTE** 8508> 8509> This API is supported since API version 7 and deprecated since API version 9. Use [on('avoidAreaChange')](#onavoidareachange9) instead. 8510 8511**System capability**: SystemCapability.WindowManager.WindowManager.Core 8512 8513**Parameters** 8514 8515| Name | Type | Mandatory| Description | 8516| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 8517| 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.| 8518| callback | Callback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 8519 8520 8521**Example** 8522 8523```ts 8524windowClass.on('systemAvoidAreaChange', (data) => { 8525 console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data)); 8526}); 8527``` 8528 8529### off('systemAvoidAreaChange')<sup>(deprecated)</sup> 8530 8531off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void 8532 8533Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 8534 8535> **NOTE** 8536> 8537> This API is supported since API version 7 and deprecated since API version 9. Use [off('avoidAreaChange')](#offavoidareachange9) instead. 8538 8539**System capability**: SystemCapability.WindowManager.WindowManager.Core 8540 8541**Parameters** 8542 8543| Name | Type | Mandatory| Description | 8544| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 8545| 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.| 8546| 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. | 8547 8548**Example** 8549 8550```ts 8551const callback = (avoidArea: window.AvoidArea) => { 8552 // ... 8553} 8554windowClass.on('systemAvoidAreaChange', callback); 8555windowClass.off('systemAvoidAreaChange', callback); 8556// Unregister all the callbacks that have been registered through on(). 8557windowClass.off('systemAvoidAreaChange'); 8558``` 8559 8560### isSupportWideGamut<sup>(deprecated)</sup> 8561 8562isSupportWideGamut(callback: AsyncCallback<boolean>): void 8563 8564Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 8565 8566> **NOTE** 8567> 8568> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9) instead. 8569 8570**System capability**: SystemCapability.WindowManager.WindowManager.Core 8571 8572**Parameters** 8573 8574| Name | Type | Mandatory| Description | 8575| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 8576| 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.| 8577 8578**Example** 8579 8580```ts 8581import { BusinessError } from '@kit.BasicServicesKit'; 8582 8583windowClass.isSupportWideGamut((err: BusinessError, data) => { 8584 const errCode: number = err.code; 8585 if (errCode) { 8586 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 8587 return; 8588 } 8589 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 8590}); 8591``` 8592 8593### isSupportWideGamut<sup>(deprecated)</sup> 8594 8595isSupportWideGamut(): Promise<boolean> 8596 8597Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 8598 8599> **NOTE** 8600> 8601> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9-1) instead. 8602 8603**System capability**: SystemCapability.WindowManager.WindowManager.Core 8604 8605**Return value** 8606 8607| Type | Description | 8608| ---------------------- | ------------------------------------------------------------ | 8609| 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.| 8610 8611**Example** 8612 8613```ts 8614import { BusinessError } from '@kit.BasicServicesKit'; 8615 8616let promise = windowClass.isSupportWideGamut(); 8617promise.then((data) => { 8618 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 8619}).catch((err: BusinessError) => { 8620 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 8621}); 8622``` 8623 8624### setColorSpace<sup>(deprecated)</sup> 8625 8626setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 8627 8628Sets a color space for this window. This API uses an asynchronous callback to return the result. 8629 8630> **NOTE** 8631> 8632> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9) instead. 8633 8634**System capability**: SystemCapability.WindowManager.WindowManager.Core 8635 8636**Parameters** 8637 8638| Name | Type | Mandatory| Description | 8639| ---------- | ------------------------- | ---- | ------------ | 8640| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set.| 8641| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8642 8643 8644**Example** 8645 8646```ts 8647import { BusinessError } from '@kit.BasicServicesKit'; 8648 8649windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 8650 const errCode: number = err.code; 8651 if (errCode) { 8652 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 8653 return; 8654 } 8655 console.info('Succeeded in setting window colorspace.'); 8656}); 8657``` 8658 8659### setColorSpace<sup>(deprecated)</sup> 8660 8661setColorSpace(colorSpace:ColorSpace): Promise<void> 8662 8663Sets a color space for this window. This API uses a promise to return the result. 8664 8665> **NOTE** 8666> 8667> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9-1) instead. 8668 8669**System capability**: SystemCapability.WindowManager.WindowManager.Core 8670 8671**Parameters** 8672 8673| Name | Type | Mandatory| Description | 8674| ---------- | ------------------------- | ---- | -------------- | 8675| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set.| 8676 8677**Return value** 8678 8679| Type | Description | 8680| ------------------- | ------------------------- | 8681| Promise<void> | Promise that returns no value.| 8682 8683 8684**Example** 8685 8686```ts 8687import { BusinessError } from '@kit.BasicServicesKit'; 8688 8689let promise = windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT); 8690promise.then(() => { 8691 console.info('Succeeded in setting window colorspace.'); 8692}).catch((err: BusinessError) => { 8693 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 8694}); 8695``` 8696 8697### getColorSpace<sup>(deprecated)</sup> 8698 8699getColorSpace(callback: AsyncCallback<ColorSpace>): void 8700 8701Obtains the color space of this window. This API uses an asynchronous callback to return the result. 8702 8703> **NOTE** 8704> 8705> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 8706 8707**System capability**: SystemCapability.WindowManager.WindowManager.Core 8708 8709**Parameters** 8710 8711| Name | Type | Mandatory| Description | 8712| -------- | ---------------------------------------------- | ---- | ---------------------------------------------------------- | 8713| 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.| 8714 8715**Example** 8716 8717```ts 8718import { BusinessError } from '@kit.BasicServicesKit'; 8719 8720windowClass.getColorSpace((err: BusinessError, data) => { 8721 const errCode: number = err.code; 8722 if (errCode) { 8723 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 8724 return; 8725 } 8726 console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data)); 8727}); 8728``` 8729 8730### getColorSpace<sup>(deprecated)</sup> 8731 8732getColorSpace(): Promise<ColorSpace> 8733 8734Obtains the color space of this window. This API uses a promise to return the result. 8735 8736> **NOTE** 8737> 8738> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 8739 8740**System capability**: SystemCapability.WindowManager.WindowManager.Core 8741 8742**Return value** 8743 8744| Type | Description | 8745| ---------------------------------------- | ------------------------------- | 8746| Promise<[ColorSpace](#colorspace8)> | Promise used to return the current color space.| 8747 8748**Example** 8749 8750```ts 8751import { BusinessError } from '@kit.BasicServicesKit'; 8752 8753let promise = windowClass.getColorSpace(); 8754promise.then((data) => { 8755 console.info('Succeeded in getting window color space. Cause:' + JSON.stringify(data)); 8756}).catch((err: BusinessError) => { 8757 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 8758}); 8759``` 8760 8761### setBackgroundColor<sup>(deprecated)</sup> 8762 8763setBackgroundColor(color: string, callback: AsyncCallback<void>): void 8764 8765Sets 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. 8766 8767> **NOTE** 8768> 8769> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 8770 8771**System capability**: SystemCapability.WindowManager.WindowManager.Core 8772 8773**Parameters** 8774 8775| Name | Type | Mandatory| Description | 8776| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 8777| 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'**.| 8778| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8779 8780 8781**Example** 8782 8783```ts 8784import { BusinessError } from '@kit.BasicServicesKit'; 8785 8786let color: string = '#00ff33'; 8787windowClass.setBackgroundColor(color, (err: BusinessError) => { 8788 const errCode: number = err.code; 8789 if (errCode) { 8790 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 8791 return; 8792 } 8793 console.info('Succeeded in setting the background color.'); 8794}); 8795``` 8796 8797### setBackgroundColor<sup>(deprecated)</sup> 8798 8799setBackgroundColor(color: string): Promise<void> 8800 8801Sets 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. 8802 8803> **NOTE** 8804> 8805> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 8806 8807**System capability**: SystemCapability.WindowManager.WindowManager.Core 8808 8809**Parameters** 8810 8811| Name| Type | Mandatory| Description | 8812| ------ | ------ | ---- | ------------------------------------------------------------ | 8813| 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'**.| 8814 8815**Return value** 8816 8817| Type | Description | 8818| ------------------- | ------------------------- | 8819| Promise<void> | Promise that returns no value.| 8820 8821 8822**Example** 8823 8824```ts 8825import { BusinessError } from '@kit.BasicServicesKit'; 8826 8827let color: string = '#00ff33'; 8828let promise = windowClass.setBackgroundColor(color); 8829promise.then(() => { 8830 console.info('Succeeded in setting the background color.'); 8831}).catch((err: BusinessError) => { 8832 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 8833}); 8834``` 8835 8836### setBrightness<sup>(deprecated)</sup> 8837 8838setBrightness(brightness: number, callback: AsyncCallback<void>): void 8839 8840Sets the screen brightness for this window. This API uses an asynchronous callback to return the result. 8841 8842When 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. 8843 8844> **NOTE** 8845> 8846> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9) instead. 8847 8848**System capability**: SystemCapability.WindowManager.WindowManager.Core 8849 8850**Parameters** 8851 8852| Name | Type | Mandatory| Description | 8853| ---------- | ------------------------- | ---- |---------------------------------------| 8854| brightness | number | Yes | Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.| 8855| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8856 8857 8858**Example** 8859 8860```ts 8861import { BusinessError } from '@kit.BasicServicesKit'; 8862 8863let brightness: number = 1; 8864windowClass.setBrightness(brightness, (err: BusinessError) => { 8865 const errCode: number = err.code; 8866 if (errCode) { 8867 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 8868 return; 8869 } 8870 console.info('Succeeded in setting the brightness.'); 8871}); 8872``` 8873 8874### setBrightness<sup>(deprecated)</sup> 8875 8876setBrightness(brightness: number): Promise<void> 8877 8878Sets the screen brightness for this window. This API uses a promise to return the result. 8879 8880When 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. 8881 8882> **NOTE** 8883> 8884> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9-1) instead. 8885 8886**System capability**: SystemCapability.WindowManager.WindowManager.Core 8887 8888**Parameters** 8889 8890| Name | Type | Mandatory| Description | 8891| ---------- | ------ | ---- |------------------------------------------| 8892| brightness | number | Yes | Brightness to set. The value is a floating point number in the range [0.0, 1.0] or **-1.0**. The value **1.0** means the brightest, and **-1.0** means the default brightness.| 8893 8894**Return value** 8895 8896| Type | Description | 8897| ------------------- | ------------------------- | 8898| Promise<void> | Promise that returns no value.| 8899 8900 8901**Example** 8902 8903```ts 8904import { BusinessError } from '@kit.BasicServicesKit'; 8905 8906let brightness: number = 1; 8907let promise = windowClass.setBrightness(brightness); 8908promise.then(() => { 8909 console.info('Succeeded in setting the brightness.'); 8910}).catch((err: BusinessError) => { 8911 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 8912}); 8913``` 8914 8915### setDimBehind<sup>(deprecated)</sup> 8916 8917setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void 8918 8919Sets the dimness of the window that is not on top. This API uses an asynchronous callback to return the result. 8920 8921> **NOTE** 8922> 8923> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 8924 8925**System capability**: SystemCapability.WindowManager.WindowManager.Core 8926 8927**Parameters** 8928 8929| Name | Type | Mandatory| Description | 8930| -------------- | ------------------------- | ---- |----------------------------------------| 8931| 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.| 8932| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8933 8934**Example** 8935 8936```ts 8937import { BusinessError } from '@kit.BasicServicesKit'; 8938 8939windowClass.setDimBehind(0.5, (err: BusinessError) => { 8940 const errCode: number = err.code; 8941 if (errCode) { 8942 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 8943 return; 8944 } 8945 console.info('Succeeded in setting the dimness.'); 8946}); 8947``` 8948 8949### setDimBehind<sup>(deprecated)</sup> 8950 8951setDimBehind(dimBehindValue: number): Promise<void> 8952 8953Sets the dimness of the window that is not on top. This API uses a promise to return the result. 8954 8955> **NOTE** 8956> 8957> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 8958 8959**System capability**: SystemCapability.WindowManager.WindowManager.Core 8960 8961**Parameters** 8962 8963| Name | Type | Mandatory| Description | 8964| -------------- | ------ | ---- | -------------------------------------------------- | 8965| dimBehindValue | number | Yes | Dimness of the window to set. The value ranges from 0 to 1. The value **1** indicates the dimmest.| 8966 8967**Return value** 8968 8969| Type | Description | 8970| ------------------- | ------------------------- | 8971| Promise<void> | Promise that returns no value.| 8972 8973**Example** 8974 8975```ts 8976import { BusinessError } from '@kit.BasicServicesKit'; 8977 8978let promise = windowClass.setDimBehind(0.5); 8979promise.then(() => { 8980 console.info('Succeeded in setting the dimness.'); 8981}).catch((err: BusinessError) => { 8982 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 8983}); 8984``` 8985 8986### setFocusable<sup>(deprecated)</sup> 8987 8988setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 8989 8990Sets 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. 8991 8992> **NOTE** 8993> 8994> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9) instead. 8995 8996**System capability**: SystemCapability.WindowManager.WindowManager.Core 8997 8998**Parameters** 8999 9000| Name | Type | Mandatory| Description | 9001| ----------- | ------------------------- | ---- | ---------------------------- | 9002| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.| 9003| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9004 9005 9006**Example** 9007 9008```ts 9009import { BusinessError } from '@kit.BasicServicesKit'; 9010 9011let isFocusable: boolean = true; 9012windowClass.setFocusable(isFocusable, (err: BusinessError) => { 9013 const errCode: number = err.code; 9014 if (errCode) { 9015 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 9016 return; 9017 } 9018 console.info('Succeeded in setting the window to be focusable.'); 9019}); 9020``` 9021 9022### setFocusable<sup>(deprecated)</sup> 9023 9024setFocusable(isFocusable: boolean): Promise<void> 9025 9026Sets 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. 9027 9028> **NOTE** 9029> 9030> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9-1) instead. 9031 9032**System capability**: SystemCapability.WindowManager.WindowManager.Core 9033 9034**Parameters** 9035 9036| Name | Type | Mandatory| Description | 9037| ----------- | ------- | ---- | ---------------------------- | 9038| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.| 9039 9040**Return value** 9041 9042| Type | Description | 9043| ------------------- | ------------------------- | 9044| Promise<void> | Promise that returns no value.| 9045 9046 9047**Example** 9048 9049```ts 9050import { BusinessError } from '@kit.BasicServicesKit'; 9051 9052let isFocusable: boolean = true; 9053let promise = windowClass.setFocusable(isFocusable); 9054promise.then(() => { 9055 console.info('Succeeded in setting the window to be focusable.'); 9056}).catch((err: BusinessError) => { 9057 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 9058}); 9059``` 9060 9061### setKeepScreenOn<sup>(deprecated)</sup> 9062 9063setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 9064 9065Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 9066 9067> **NOTE** 9068> 9069> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9) instead. 9070 9071**System capability**: SystemCapability.WindowManager.WindowManager.Core 9072 9073**Parameters** 9074 9075| Name | Type | Mandatory| Description | 9076| -------------- | ------------------------- | ---- | ------------------------ | 9077| 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.| 9078| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9079 9080 9081**Example** 9082 9083```ts 9084import { BusinessError } from '@kit.BasicServicesKit'; 9085 9086let isKeepScreenOn: boolean = true; 9087windowClass.setKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 9088 const errCode: number = err.code; 9089 if (errCode) { 9090 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 9091 return; 9092 } 9093 console.info('Succeeded in setting the screen to be always on.'); 9094}); 9095``` 9096 9097### setKeepScreenOn<sup>(deprecated)</sup> 9098 9099setKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 9100 9101Sets whether to keep the screen always on. This API uses a promise to return the result. 9102 9103> **NOTE** 9104> 9105> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9-1) instead. 9106 9107**System capability**: SystemCapability.WindowManager.WindowManager.Core 9108 9109**Parameters** 9110 9111| Name | Type | Mandatory| Description | 9112| -------------- | ------- | ---- | ------------------------ | 9113| 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.| 9114 9115**Return value** 9116 9117| Type | Description | 9118| ------------------- | ------------------------- | 9119| Promise<void> | Promise that returns no value.| 9120 9121**Example** 9122 9123```ts 9124import { BusinessError } from '@kit.BasicServicesKit'; 9125 9126let isKeepScreenOn: boolean = true; 9127let promise = windowClass.setKeepScreenOn(isKeepScreenOn); 9128promise.then(() => { 9129 console.info('Succeeded in setting the screen to be always on.'); 9130}).catch((err: BusinessError) => { 9131 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 9132}); 9133``` 9134 9135### setOutsideTouchable<sup>(deprecated)</sup> 9136 9137setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): void 9138 9139Sets whether the area outside the subwindow is touchable. This API uses an asynchronous callback to return the result. 9140 9141> **NOTE** 9142> 9143> This API is supported since API version 7 and deprecated since API version 9. 9144> 9145> Since API version 9, the area outside the subwindow is touchable by default. This API is no longer supported and no substitute API is provided. 9146 9147**System capability**: SystemCapability.WindowManager.WindowManager.Core 9148 9149**Parameters** 9150 9151| Name | Type | Mandatory| Description | 9152| --------- | ------------------------- | ---- | ---------------- | 9153| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means the area outside the subwindow is touchable, and **false** means the opposite.| 9154| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9155 9156**Example** 9157 9158```ts 9159import { BusinessError } from '@kit.BasicServicesKit'; 9160 9161windowClass.setOutsideTouchable(true, (err: BusinessError) => { 9162 const errCode: number = err.code; 9163 if (errCode) { 9164 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 9165 return; 9166 } 9167 console.info('Succeeded in setting the area to be touchable.'); 9168}); 9169``` 9170 9171### setOutsideTouchable<sup>(deprecated)</sup> 9172 9173setOutsideTouchable(touchable: boolean): Promise<void> 9174 9175Sets whether the area outside the subwindow is touchable. This API uses a promise to return the result. 9176 9177> **NOTE** 9178> 9179> This API is supported since API version 7 and deprecated since API version 9. 9180> 9181> Since API version 9, the area outside the subwindow is touchable by default. This API is no longer supported and no substitute API is provided. 9182 9183**System capability**: SystemCapability.WindowManager.WindowManager.Core 9184 9185**Parameters** 9186 9187| Name | Type | Mandatory| Description | 9188| --------- | ------- | ---- | ---------------- | 9189| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means the area outside the subwindow is touchable, and **false** means the opposite.| 9190 9191**Return value** 9192 9193| Type | Description | 9194| ------------------- | ------------------------- | 9195| Promise<void> | Promise that returns no value.| 9196 9197**Example** 9198 9199```ts 9200import { BusinessError } from '@kit.BasicServicesKit'; 9201 9202let promise = windowClass.setOutsideTouchable(true); 9203promise.then(() => { 9204 console.info('Succeeded in setting the area to be touchable.'); 9205}).catch((err: BusinessError) => { 9206 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 9207}); 9208``` 9209 9210### setPrivacyMode<sup>(deprecated)</sup> 9211 9212setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 9213 9214Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 9215 9216A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 9217 9218> **NOTE** 9219> 9220> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9) instead. 9221 9222**System capability**: SystemCapability.WindowManager.WindowManager.Core 9223 9224**Parameters** 9225 9226| Name | Type | Mandatory| Description | 9227| ------------- | ------------------------- | ---- | -------------------- | 9228| 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.| 9229| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9230 9231**Example** 9232 9233```ts 9234import { BusinessError } from '@kit.BasicServicesKit'; 9235 9236let isPrivacyMode: boolean = true; 9237windowClass.setPrivacyMode(isPrivacyMode, (err: BusinessError) => { 9238 const errCode: number = err.code; 9239 if (errCode) { 9240 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 9241 return; 9242 } 9243 console.info('Succeeded in setting the window to privacy mode.'); 9244}); 9245``` 9246 9247### setPrivacyMode<sup>(deprecated)</sup> 9248 9249setPrivacyMode(isPrivacyMode: boolean): Promise<void> 9250 9251Sets whether this window is in privacy mode. This API uses a promise to return the result. 9252 9253A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 9254 9255> **NOTE** 9256> 9257> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9-1) instead. 9258 9259**System capability**: SystemCapability.WindowManager.WindowManager.Core 9260 9261**Parameters** 9262 9263| Name | Type | Mandatory| Description | 9264| ------------- | ------- | ---- | -------------------- | 9265| 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.| 9266 9267**Return value** 9268 9269| Type | Description | 9270| ------------------- | ------------------------- | 9271| Promise<void> | Promise that returns no value.| 9272 9273**Example** 9274 9275```ts 9276import { BusinessError } from '@kit.BasicServicesKit'; 9277 9278let isPrivacyMode: boolean = true; 9279let promise = windowClass.setPrivacyMode(isPrivacyMode); 9280promise.then(() => { 9281 console.info('Succeeded in setting the window to privacy mode.'); 9282}).catch((err: BusinessError) => { 9283 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 9284}); 9285``` 9286 9287### setTouchable<sup>(deprecated)</sup> 9288 9289setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 9290 9291Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 9292 9293> **NOTE** 9294> 9295> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9) instead. 9296 9297**System capability**: SystemCapability.WindowManager.WindowManager.Core 9298 9299**Parameters** 9300 9301| Name | Type | Mandatory| Description | 9302| ----------- | ------------------------- | ---- | -------------------- | 9303| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 9304| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9305 9306 9307**Example** 9308 9309```ts 9310import { BusinessError } from '@kit.BasicServicesKit'; 9311 9312let isTouchable = true; 9313windowClass.setTouchable(isTouchable, (err: BusinessError) => { 9314 const errCode: number = err.code; 9315 if (errCode) { 9316 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 9317 return; 9318 } 9319 console.info('Succeeded in setting the window to be touchable.'); 9320}); 9321``` 9322 9323### setTouchable<sup>(deprecated)</sup> 9324 9325setTouchable(isTouchable: boolean): Promise<void> 9326 9327Sets whether this window is touchable. This API uses a promise to return the result. 9328 9329> **NOTE** 9330> 9331> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9-1) instead. 9332 9333**System capability**: SystemCapability.WindowManager.WindowManager.Core 9334 9335**Parameters** 9336 9337| Name | Type | Mandatory| Description | 9338| ----------- | ------- | ---- | -------------------- | 9339| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 9340 9341**Return value** 9342 9343| Type | Description | 9344| ------------------- | ------------------------- | 9345| Promise<void> | Promise that returns no value.| 9346 9347 9348**Example** 9349 9350```ts 9351import { BusinessError } from '@kit.BasicServicesKit'; 9352 9353let isTouchable = true; 9354let promise = windowClass.setTouchable(isTouchable); 9355promise.then(() => { 9356 console.info('Succeeded in setting the window to be touchable.'); 9357}).catch((err: BusinessError) => { 9358 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 9359}); 9360``` 9361 9362## WindowStageEventType<sup>9+</sup> 9363 9364Describes the lifecycle of a window stage. 9365 9366**Model restriction**: This API can be used only in the stage model. 9367 9368**System capability**: SystemCapability.WindowManager.WindowManager.Core 9369 9370**Atomic service API**: This API can be used in atomic services since API version 11. 9371 9372| Name | Value| Description | 9373| ---------- | ------ | ---------- | 9374| 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.| 9375| 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.| 9376| 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.| 9377| 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.| 9378| 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.| 9379| 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.| 9380 9381## ModalityType<sup>14+</sup> 9382 9383Enumerates the modality types of the subwindow. 9384 9385**System capability**: SystemCapability.Window.SessionManager 9386 9387**Atomic service API**: This API can be used in atomic services since API version 14. 9388 9389| Name | Value | Description | 9390| -------------------- | ------ | ---------- | 9391| WINDOW_MODALITY | 0 | Window-modal. Select this value when you want the parent window not to respond to user interactions.| 9392| 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.| 9393 9394## SubWindowOptions<sup>11+</sup> 9395 9396Describes the parameters used for creating a subwindow. 9397 9398**System capability**: SystemCapability.Window.SessionManager 9399 9400| Name | Type | Read-Only| Optional| Description | 9401| ---------- | ---- | ---- | ---- | ----------- | 9402| title<sup>11+</sup> | string | No| No| Title of the subwindow.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 9403| decorEnabled<sup>11+</sup> | boolean | No| No| Whether decorations are displayed in the subwindow. The value **true** means decorations are displayed, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 9404| isModal<sup>12+</sup> | boolean | No| Yes| Whether the modal property is enabled for the subwindow. The value** true** means that the modal property is enabled for the subwindow, and **false** means to disable it. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 9405| modalityType<sup>14+</sup> | [ModalityType](#modalitytype14) | No| Yes| Modality type of the subwindow. This parameter takes effect only when the modal property is enabled for the subwindow. **WINDOW_MODALITY** means window-modal, and **APPLICATION_MODALITY** means application-modal. The default value is **WINDOW_MODALITY**.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 9406 9407## WindowStage<sup>9+</sup> 9408 9409Implements a window manager, which manages each basic window unit, that is, [Window](#window) instance. 9410 9411Before calling any of the following APIs, you must use [onWindowStageCreate()](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) to create a **WindowStage** instance. 9412 9413### getMainWindow<sup>9+</sup> 9414 9415getMainWindow(callback: AsyncCallback<Window>): void 9416 9417Obtains the main window of this window stage. This API uses an asynchronous callback to return the result. 9418 9419**Model restriction**: This API can be used only in the stage model. 9420 9421**System capability**: SystemCapability.WindowManager.WindowManager.Core 9422 9423**Atomic service API**: This API can be used in atomic services since API version 11. 9424 9425**Parameters** 9426 9427| Name | Type | Mandatory| Description | 9428| -------- | -------------------------------------- | ---- | --------------------------------------------- | 9429| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window.| 9430 9431**Error codes** 9432 9433For details about the error codes, see [Window Error Codes](errorcode-window.md). 9434 9435| ID| Error Message| 9436| ------- | ------------------------------ | 9437| 1300002 | This window state is abnormal. | 9438| 1300005 | This window stage is abnormal. | 9439 9440**Example** 9441 9442```ts 9443// EntryAbility.ets 9444import { UIAbility } from '@kit.AbilityKit'; 9445import { BusinessError } from '@kit.BasicServicesKit'; 9446 9447export default class EntryAbility extends UIAbility { 9448 // ... 9449 9450 onWindowStageCreate(windowStage: window.WindowStage) { 9451 console.log('onWindowStageCreate'); 9452 let windowClass: window.Window | undefined = undefined; 9453 windowStage.getMainWindow((err: BusinessError, data) => { 9454 const errCode: number = err.code; 9455 if (errCode) { 9456 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9457 return; 9458 } 9459 windowClass = data; 9460 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 9461 }); 9462 } 9463}; 9464``` 9465 9466### getMainWindow<sup>9+</sup> 9467 9468getMainWindow(): Promise<Window> 9469 9470Obtains the main window of this window stage. This API uses a promise to return the result. 9471 9472**Model restriction**: This API can be used only in the stage model. 9473 9474**System capability**: SystemCapability.WindowManager.WindowManager.Core 9475 9476**Atomic service API**: This API can be used in atomic services since API version 11. 9477 9478**Return value** 9479 9480| Type | Description | 9481| -------------------------------- | ------------------------------------------------ | 9482| Promise<[Window](#window)> | Promise used to return the main window.| 9483 9484**Error codes** 9485 9486For details about the error codes, see [Window Error Codes](errorcode-window.md). 9487 9488| ID| Error Message| 9489| ------- | ------------------------------ | 9490| 1300002 | This window state is abnormal. | 9491| 1300005 | This window stage is abnormal. | 9492 9493**Example** 9494 9495```ts 9496// EntryAbility.ets 9497import { UIAbility } from '@kit.AbilityKit'; 9498import { BusinessError } from '@kit.BasicServicesKit'; 9499 9500export default class EntryAbility extends UIAbility { 9501 // ... 9502 9503 onWindowStageCreate(windowStage: window.WindowStage) { 9504 console.log('onWindowStageCreate'); 9505 let windowClass: window.Window | undefined = undefined; 9506 let promise = windowStage.getMainWindow(); 9507 promise.then((data) => { 9508 windowClass = data; 9509 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 9510 }).catch((err: BusinessError) => { 9511 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9512 }); 9513 } 9514}; 9515``` 9516 9517### getMainWindowSync<sup>9+</sup> 9518 9519getMainWindowSync(): Window 9520 9521Obtains the main window of this window stage. 9522 9523**Model restriction**: This API can be used only in the stage model. 9524 9525**System capability**: SystemCapability.WindowManager.WindowManager.Core 9526 9527**Atomic service API**: This API can be used in atomic services since API version 11. 9528 9529**Return value** 9530 9531| Type| Description| 9532| ----------------- | --------------------------------- | 9533| [Window](#window) | Main window.| 9534 9535**Error codes** 9536 9537For details about the error codes, see [Window Error Codes](errorcode-window.md). 9538 9539| ID| Error Message| 9540| ------- | ------------------------------ | 9541| 1300002 | This window state is abnormal. | 9542| 1300005 | This window stage is abnormal. | 9543 9544**Example** 9545<!--code_no_check--> 9546```ts 9547// EntryAbility.ets 9548import { UIAbility } from '@kit.AbilityKit'; 9549 9550export default class EntryAbility extends UIAbility { 9551 // ... 9552 9553 onWindowStageCreate(windowStage: window.WindowStage) { 9554 console.log('onWindowStageCreate'); 9555 try { 9556 let windowClass = windowStage.getMainWindowSync(); 9557 } catch (exception) { 9558 console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`); 9559 } 9560 } 9561}; 9562``` 9563 9564### createSubWindow<sup>9+</sup> 9565 9566createSubWindow(name: string, callback: AsyncCallback<Window>): void 9567 9568Creates a subwindow for this window stage. This API uses an asynchronous callback to return the result. 9569 9570**Model restriction**: This API can be used only in the stage model. 9571 9572**System capability**: SystemCapability.WindowManager.WindowManager.Core 9573 9574**Atomic service API**: This API can be used in atomic services since API version 11. 9575 9576**Parameters** 9577 9578| Name | Type | Mandatory| Description | 9579| -------- | -------------------------------------- | ---- | --------------------------------------------- | 9580| name | string | Yes | Name of the subwindow. | 9581| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow.| 9582 9583**Error codes** 9584 9585For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9586 9587| ID| Error Message| 9588| ------- | ------------------------------ | 9589| 401 | Parameter error. Possible cause: Incorrect parameter types. | 9590| 1300002 | This window state is abnormal. | 9591| 1300005 | This window stage is abnormal. | 9592 9593**Example** 9594 9595```ts 9596// EntryAbility.ets 9597import { UIAbility } from '@kit.AbilityKit'; 9598import { BusinessError } from '@kit.BasicServicesKit'; 9599 9600export default class EntryAbility extends UIAbility { 9601 // ... 9602 9603 onWindowStageCreate(windowStage: window.WindowStage) { 9604 console.log('onWindowStageCreate'); 9605 let windowClass: window.Window | undefined = undefined; 9606 try { 9607 windowStage.createSubWindow('mySubWindow', (err: BusinessError, data) => { 9608 const errCode: number = err.code; 9609 if (errCode) { 9610 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 9611 return; 9612 } 9613 windowClass = data; 9614 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 9615 if (!windowClass) { 9616 console.info('Failed to load the content. Cause: windowClass is null'); 9617 } 9618 else { 9619 (windowClass as window.Window).resize(500, 1000); 9620 } 9621 }); 9622 } catch (exception) { 9623 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 9624 } 9625 } 9626}; 9627``` 9628 9629### createSubWindow<sup>9+</sup> 9630 9631createSubWindow(name: string): Promise<Window> 9632 9633Creates a subwindow for this window stage. This API uses a promise to return the result. 9634 9635**Model restriction**: This API can be used only in the stage model. 9636 9637**System capability**: SystemCapability.WindowManager.WindowManager.Core 9638 9639**Atomic service API**: This API can be used in atomic services since API version 11. 9640 9641**Parameters** 9642 9643| Name| Type | Mandatory| Description | 9644| ------ | ------ | ---- | -------------- | 9645| name | string | Yes | Name of the subwindow.| 9646 9647**Return value** 9648 9649| Type | Description | 9650| -------------------------------- | ------------------------------------------------ | 9651| Promise<[Window](#window)> | Promise used to return the subwindow.| 9652 9653**Error codes** 9654 9655For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9656 9657| ID| Error Message| 9658| ------- | ------------------------------ | 9659| 401 | Parameter error. Possible cause: Incorrect parameter types. | 9660| 1300002 | This window state is abnormal. | 9661| 1300005 | This window stage is abnormal. | 9662 9663**Example** 9664 9665```ts 9666// EntryAbility.ets 9667import { UIAbility } from '@kit.AbilityKit'; 9668import { BusinessError } from '@kit.BasicServicesKit'; 9669 9670export default class EntryAbility extends UIAbility { 9671 // ... 9672 9673 onWindowStageCreate(windowStage: window.WindowStage) { 9674 console.log('onWindowStageCreate'); 9675 let windowClass: window.Window | undefined = undefined; 9676 try { 9677 let promise = windowStage.createSubWindow('mySubWindow'); 9678 promise.then((data) => { 9679 windowClass = data; 9680 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 9681 }).catch((err: BusinessError) => { 9682 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 9683 }); 9684 } catch (exception) { 9685 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 9686 } 9687 } 9688}; 9689``` 9690 9691### createSubWindowWithOptions<sup>11+</sup> 9692 9693createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 9694 9695Creates a subwindow for this window stage. This API uses a promise to return the result. 9696 9697**Model restriction**: This API can be used only in the stage model. 9698 9699**Atomic service API**: This API can be used in atomic services since API version 12. 9700 9701**System capability**: SystemCapability.Window.SessionManager 9702 9703**Parameters** 9704 9705| Name| Type | Mandatory| Description | 9706| ------ | ------ | ---- | -------------- | 9707| name | string | Yes | Name of the subwindow.| 9708| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the subwindow. | 9709 9710**Return value** 9711 9712| Type | Description | 9713| -------------------------------- | ------------------------------------------------ | 9714| Promise<[Window](#window)> | Promise used to return the subwindow created.| 9715 9716**Error codes** 9717 9718For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9719 9720| ID| Error Message| 9721| ------- | ------------------------------ | 9722| 401 | Parameter error. Possible cause: Incorrect parameter types. | 9723| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9724| 1300002 | This window state is abnormal. | 9725| 1300005 | This window stage is abnormal. | 9726 9727**Example** 9728 9729```ts 9730// EntryAbility.ets 9731import { UIAbility } from '@kit.AbilityKit'; 9732import { BusinessError } from '@kit.BasicServicesKit'; 9733 9734export default class EntryAbility extends UIAbility { 9735 // ... 9736 9737 onWindowStageCreate(windowStage: window.WindowStage) { 9738 console.info('onWindowStageCreate'); 9739 let windowClass: window.Window | undefined = undefined; 9740 try { 9741 let options : window.SubWindowOptions = { 9742 title: 'title', 9743 decorEnabled: true 9744 }; 9745 let promise = windowStage.createSubWindowWithOptions('mySubWindow', options); 9746 promise.then((data) => { 9747 windowClass = data; 9748 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 9749 }).catch((err: BusinessError) => { 9750 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 9751 }); 9752 } catch (exception) { 9753 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 9754 } 9755 } 9756}; 9757``` 9758 9759### getSubWindow<sup>9+</sup> 9760 9761getSubWindow(callback: AsyncCallback<Array<Window>>): void 9762 9763Obtains all the subwindows of this window stage. This API uses an asynchronous callback to return the result. 9764 9765**Model restriction**: This API can be used only in the stage model. 9766 9767**System capability**: SystemCapability.WindowManager.WindowManager.Core 9768 9769**Atomic service API**: This API can be used in atomic services since API version 11. 9770 9771**Parameters** 9772 9773| Name | Type | Mandatory| Description | 9774| -------- | --------------------------------------------------- | ---- | ------------------------------------------------- | 9775| callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the subwindows.| 9776 9777**Error codes** 9778 9779For details about the error codes, see [Window Error Codes](errorcode-window.md). 9780 9781| ID| Error Message| 9782| ------- | ------------------------------ | 9783| 1300005 | This window stage is abnormal. | 9784 9785**Example** 9786<!--code_no_check--> 9787```ts 9788// EntryAbility.ets 9789import { UIAbility } from '@kit.AbilityKit'; 9790import { BusinessError } from '@kit.BasicServicesKit'; 9791 9792export default class EntryAbility extends UIAbility { 9793 // ... 9794 9795 onWindowStageCreate(windowStage: window.WindowStage) { 9796 console.log('onWindowStageCreate'); 9797 let windowClass: window.Window[] = []; 9798 windowStage.getSubWindow((err: BusinessError, data) => { 9799 const errCode: number = err.code; 9800 if (errCode) { 9801 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 9802 return; 9803 } 9804 windowClass = data; 9805 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 9806 }); 9807 } 9808}; 9809``` 9810 9811### getSubWindow<sup>9+</sup> 9812 9813getSubWindow(): Promise<Array<Window>> 9814 9815Obtains all the subwindows of this window stage. This API uses a promise to return the result. 9816 9817**Model restriction**: This API can be used only in the stage model. 9818 9819**System capability**: SystemCapability.WindowManager.WindowManager.Core 9820 9821**Atomic service API**: This API can be used in atomic services since API version 11. 9822 9823**Return value** 9824 9825| Type | Description | 9826| --------------------------------------------- | ---------------------------------------------------- | 9827| Promise<Array<[Window](#window)>> | Promise used to return all the subwindows.| 9828 9829**Error codes** 9830 9831For details about the error codes, see [Window Error Codes](errorcode-window.md). 9832 9833| ID| Error Message| 9834| ------- | ------------------------------ | 9835| 1300005 | This window stage is abnormal. | 9836 9837**Example** 9838<!--code_no_check--> 9839```ts 9840// EntryAbility.ets 9841import { UIAbility } from '@kit.AbilityKit'; 9842import { BusinessError } from '@kit.BasicServicesKit'; 9843 9844export default class EntryAbility extends UIAbility { 9845 // ... 9846 9847 onWindowStageCreate(windowStage: window.WindowStage) { 9848 console.log('onWindowStageCreate'); 9849 let windowClass: window.Window[] = []; 9850 let promise = windowStage.getSubWindow(); 9851 promise.then((data) => { 9852 windowClass = data; 9853 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 9854 }).catch((err: BusinessError) => { 9855 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 9856 }); 9857 } 9858}; 9859``` 9860 9861### loadContent<sup>9+</sup> 9862 9863loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 9864 9865Loads 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. 9866 9867**Model restriction**: This API can be used only in the stage model. 9868 9869**System capability**: SystemCapability.WindowManager.WindowManager.Core 9870 9871**Atomic service API**: This API can be used in atomic services since API version 11. 9872 9873**Parameters** 9874 9875| Name | Type | Mandatory| Description | 9876| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 9877| 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. | 9878| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 9879| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9880 9881**Error codes** 9882 9883For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9884 9885| ID| Error Message| 9886| ------- | ------------------------------ | 9887| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9888| 1300002 | This window state is abnormal. | 9889| 1300005 | This window stage is abnormal. | 9890 9891**Example** 9892 9893```ts 9894// EntryAbility.ets 9895import { UIAbility } from '@kit.AbilityKit'; 9896import { BusinessError } from '@kit.BasicServicesKit'; 9897 9898export default class EntryAbility extends UIAbility { 9899 // ... 9900 9901 storage: LocalStorage = new LocalStorage(); 9902 9903 onWindowStageCreate(windowStage: window.WindowStage) { 9904 this.storage.setOrCreate('storageSimpleProp', 121); 9905 console.log('onWindowStageCreate'); 9906 try { 9907 windowStage.loadContent('pages/page2', this.storage, (err: BusinessError) => { 9908 const errCode: number = err.code; 9909 if (errCode) { 9910 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 9911 return; 9912 } 9913 console.info('Succeeded in loading the content.'); 9914 }); 9915 } catch (exception) { 9916 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 9917 } 9918 } 9919}; 9920``` 9921 9922### loadContent<sup>9+</sup> 9923 9924loadContent(path: string, storage?: LocalStorage): Promise<void> 9925 9926Loads 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. 9927 9928**Model restriction**: This API can be used only in the stage model. 9929 9930**System capability**: SystemCapability.WindowManager.WindowManager.Core 9931 9932**Atomic service API**: This API can be used in atomic services since API version 11. 9933 9934**Parameters** 9935 9936| Name | Type | Mandatory| Description | 9937| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 9938| 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.| 9939| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 9940 9941**Return value** 9942 9943| Type | Description | 9944| ------------------- | ------------------------- | 9945| Promise<void> | Promise that returns no value.| 9946 9947**Error codes** 9948 9949For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9950 9951| ID| Error Message| 9952| ------- | ------------------------------ | 9953| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9954| 1300002 | This window state is abnormal. | 9955| 1300005 | This window stage is abnormal. | 9956 9957**Example** 9958 9959```ts 9960// EntryAbility.ets 9961import { UIAbility } from '@kit.AbilityKit'; 9962import { BusinessError } from '@kit.BasicServicesKit'; 9963 9964export default class EntryAbility extends UIAbility { 9965 // ... 9966 9967 storage: LocalStorage = new LocalStorage(); 9968 9969 onWindowStageCreate(windowStage: window.WindowStage) { 9970 this.storage.setOrCreate('storageSimpleProp', 121); 9971 console.log('onWindowStageCreate'); 9972 try { 9973 let promise = windowStage.loadContent('pages/page2', this.storage); 9974 promise.then(() => { 9975 console.info('Succeeded in loading the content.'); 9976 }).catch((err: BusinessError) => { 9977 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 9978 }); 9979 } catch (exception) { 9980 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 9981 } 9982 ; 9983 } 9984}; 9985``` 9986 9987### loadContent<sup>9+</sup> 9988 9989loadContent(path: string, callback: AsyncCallback<void>): void 9990 9991Loads content from a page to this window stage. This API uses an asynchronous callback to return the result. 9992 9993**Model restriction**: This API can be used only in the stage model. 9994 9995**System capability**: SystemCapability.WindowManager.WindowManager.Core 9996 9997**Atomic service API**: This API can be used in atomic services since API version 11. 9998 9999**Parameters** 10000 10001| Name | Type | Mandatory| Description | 10002| -------- | ------------------------- | ---- | -------------------- | 10003| 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.| 10004| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10005 10006**Error codes** 10007 10008For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10009 10010| ID| Error Message| 10011| ------- | ------------------------------ | 10012| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10013| 1300002 | This window state is abnormal. | 10014| 1300005 | This window stage is abnormal. | 10015 10016**Example** 10017 10018```ts 10019// EntryAbility.ets 10020import { UIAbility } from '@kit.AbilityKit'; 10021import { BusinessError } from '@kit.BasicServicesKit'; 10022 10023export default class EntryAbility extends UIAbility { 10024 // ... 10025 10026 onWindowStageCreate(windowStage: window.WindowStage) { 10027 console.log('onWindowStageCreate'); 10028 try { 10029 windowStage.loadContent('pages/page2', (err: BusinessError) => { 10030 const errCode: number = err.code; 10031 if (errCode) { 10032 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10033 return; 10034 } 10035 console.info('Succeeded in loading the content.'); 10036 }); 10037 } catch (exception) { 10038 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 10039 } 10040 } 10041}; 10042``` 10043 10044### loadContentByName<sup>11+</sup> 10045 10046loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 10047 10048Loads 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. 10049 10050**Model restriction**: This API can be used only in the stage model. 10051 10052**System capability**: SystemCapability.WindowManager.WindowManager.Core 10053 10054**Atomic service API**: This API can be used in atomic services since API version 11. 10055 10056**Parameters** 10057 10058| Name | Type | Mandatory| Description | 10059| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 10060| name | string | Yes | Name of the named route page. | 10061| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 10062| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10063 10064**Error codes** 10065 10066For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10067 10068| ID| Error Message | 10069| -------- | --------------------------------------------- | 10070| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10071| 1300002 | This window state is abnormal. | 10072| 1300003 | This window manager service works abnormally. | 10073 10074**Example** 10075 10076<!--code_no_check--> 10077```ts 10078// EntryAbility.ets 10079import { UIAbility } from '@kit.AbilityKit'; 10080import { BusinessError } from '@kit.BasicServicesKit'; 10081import * as Index from '../pages/Index'; // Import the named route page. 10082 10083export default class EntryAbility extends UIAbility { 10084 // ... 10085 10086 storage: LocalStorage = new LocalStorage(); 10087 10088 onWindowStageCreate(windowStage: window.WindowStage) { 10089 console.log('onWindowStageCreate'); 10090 this.storage.setOrCreate('storageSimpleProp', 121); 10091 try { 10092 windowStage.loadContentByName(Index.entryName, this.storage, (err: BusinessError) => { 10093 const errCode: number = err.code; 10094 if (errCode) { 10095 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10096 return; 10097 } 10098 console.info('Succeeded in loading the content.'); 10099 }); 10100 } catch (exception) { 10101 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 10102 } 10103 } 10104}; 10105``` 10106<!--code_no_check--> 10107```ts 10108// ets/pages/Index.ets 10109export const entryName : string = 'Index'; 10110@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 10111@Component 10112export struct Index { 10113 @State message: string = 'Hello World' 10114 build() { 10115 Row() { 10116 Column() { 10117 Text(this.message) 10118 .fontSize(50) 10119 .fontWeight(FontWeight.Bold) 10120 } 10121 .width('100%') 10122 } 10123 .height('100%') 10124 } 10125} 10126``` 10127 10128### loadContentByName<sup>11+</sup> 10129 10130loadContentByName(name: string, callback: AsyncCallback<void>): void 10131 10132Loads 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. 10133 10134**Model restriction**: This API can be used only in the stage model. 10135 10136**System capability**: SystemCapability.WindowManager.WindowManager.Core 10137 10138**Atomic service API**: This API can be used in atomic services since API version 11. 10139 10140**Parameters** 10141 10142| Name | Type | Mandatory| Description | 10143| -------- | ------------------------- | ---- | ---------------- | 10144| name | string | Yes | Name of the named route page.| 10145| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10146 10147**Error codes** 10148 10149For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10150 10151| ID| Error Message | 10152| -------- | --------------------------------------------- | 10153| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10154| 1300002 | This window state is abnormal. | 10155| 1300003 | This window manager service works abnormally. | 10156 10157**Example** 10158 10159<!--code_no_check--> 10160```ts 10161// EntryAbility.ets 10162import { UIAbility } from '@kit.AbilityKit'; 10163import { BusinessError } from '@kit.BasicServicesKit'; 10164import * as Index from '../pages/Index'; // Import the named route page. 10165 10166export default class EntryAbility extends UIAbility { 10167 // ... 10168 10169 onWindowStageCreate(windowStage: window.WindowStage) { 10170 console.log('onWindowStageCreate'); 10171 try { 10172 windowStage.loadContentByName(Index.entryName, (err: BusinessError) => { 10173 const errCode: number = err.code; 10174 if (errCode) { 10175 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10176 return; 10177 } 10178 console.info('Succeeded in loading the content.'); 10179 }); 10180 } catch (exception) { 10181 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 10182 } 10183 } 10184}; 10185``` 10186<!--code_no_check--> 10187```ts 10188// ets/pages/Index.ets 10189export const entryName : string = 'Index'; 10190@Entry({routeName: entryName}) 10191@Component 10192export struct Index { 10193 @State message: string = 'Hello World' 10194 build() { 10195 Row() { 10196 Column() { 10197 Text(this.message) 10198 .fontSize(50) 10199 .fontWeight(FontWeight.Bold) 10200 } 10201 .width('100%') 10202 } 10203 .height('100%') 10204 } 10205} 10206``` 10207 10208### loadContentByName<sup>11+</sup> 10209 10210loadContentByName(name: string, storage?: LocalStorage): Promise<void>; 10211 10212Loads the content a [named route](../../ui/arkts-routing.md#named-route) page to this window stage, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result. 10213 10214**Model restriction**: This API can be used only in the stage model. 10215 10216**System capability**: SystemCapability.WindowManager.WindowManager.Core 10217 10218**Atomic service API**: This API can be used in atomic services since API version 11. 10219 10220**Parameters** 10221 10222| Name | Type | Mandatory| Description | 10223| ------- | ------------ | ---- | ------------------------------------------------------------ | 10224| name | string | Yes | Name of the named route page. | 10225| storage | LocalStorage | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page.| 10226 10227**Error codes** 10228 10229For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10230 10231| ID| Error Message | 10232| -------- | --------------------------------------------- | 10233| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10234| 1300002 | This window state is abnormal. | 10235| 1300003 | This window manager service works abnormally. | 10236 10237**Example** 10238 10239<!--code_no_check--> 10240```ts 10241// EntryAbility.ets 10242import { UIAbility } from '@kit.AbilityKit'; 10243import { BusinessError } from '@kit.BasicServicesKit'; 10244import * as Index from '../pages/Index'; // Import the named route page. 10245 10246export default class EntryAbility extends UIAbility { 10247 // ... 10248 10249 storage: LocalStorage = new LocalStorage(); 10250 10251 onWindowStageCreate(windowStage: window.WindowStage) { 10252 console.log('onWindowStageCreate'); 10253 this.storage.setOrCreate('storageSimpleProp', 121); 10254 try { 10255 let promise = windowStage.loadContentByName(Index.entryName, this.storage); 10256 promise.then(() => { 10257 console.info('Succeeded in loading the content.'); 10258 }).catch((err: BusinessError) => { 10259 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10260 }); 10261 } catch (exception) { 10262 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 10263 } 10264 } 10265}; 10266``` 10267<!--code_no_check--> 10268```ts 10269// ets/pages/Index.ets 10270export const entryName : string = 'Index'; 10271@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 10272@Component 10273export struct Index { 10274 @State message: string = 'Hello World' 10275 build() { 10276 Row() { 10277 Column() { 10278 Text(this.message) 10279 .fontSize(50) 10280 .fontWeight(FontWeight.Bold) 10281 } 10282 .width('100%') 10283 } 10284 .height('100%') 10285 } 10286} 10287``` 10288 10289### on('windowStageEvent')<sup>9+</sup> 10290 10291on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void 10292 10293Subscribes to the window stage lifecycle change event. 10294 10295**Model restriction**: This API can be used only in the stage model. 10296 10297**System capability**: SystemCapability.WindowManager.WindowManager.Core 10298 10299**Atomic service API**: This API can be used in atomic services since API version 11. 10300 10301**Parameters** 10302 10303| Name | Type | Mandatory| Description | 10304| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 10305| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event.| 10306| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the window stage lifecycle state. | 10307 10308**Error codes** 10309 10310For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10311 10312| ID| Error Message| 10313| ------- | ------------------------------ | 10314| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 10315| 1300002 | This window state is abnormal. | 10316| 1300005 | This window stage is abnormal. | 10317 10318**Example** 10319 10320```ts 10321// EntryAbility.ets 10322import { UIAbility } from '@kit.AbilityKit'; 10323 10324export default class EntryAbility extends UIAbility { 10325 // ... 10326 10327 onWindowStageCreate(windowStage: window.WindowStage) { 10328 console.log('onWindowStageCreate'); 10329 try { 10330 windowStage.on('windowStageEvent', (data) => { 10331 console.info('Succeeded in enabling the listener for window stage event changes. Data: ' + 10332 JSON.stringify(data)); 10333 }); 10334 } catch (exception) { 10335 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 10336 } 10337 } 10338}; 10339``` 10340 10341### off('windowStageEvent')<sup>9+</sup> 10342 10343off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType>): void 10344 10345Unsubscribes from the window stage lifecycle change event. 10346 10347**Model restriction**: This API can be used only in the stage model. 10348 10349**System capability**: SystemCapability.WindowManager.WindowManager.Core 10350 10351**Atomic service API**: This API can be used in atomic services since API version 11. 10352 10353**Parameters** 10354 10355| Name | Type | Mandatory| Description | 10356| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 10357| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event.| 10358| 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. | 10359 10360**Error codes** 10361 10362For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10363 10364| ID| Error Message| 10365| ------- | ------------------------------ | 10366| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 10367| 1300002 | This window state is abnormal. | 10368| 1300005 | This window stage is abnormal. | 10369 10370**Example** 10371 10372```ts 10373// EntryAbility.ets 10374import { UIAbility } from '@kit.AbilityKit'; 10375 10376export default class EntryAbility extends UIAbility { 10377 // ... 10378 10379 onWindowStageCreate(windowStage: window.WindowStage) { 10380 console.log('onWindowStageCreate'); 10381 const callback = (windowStageEventType: window.WindowStageEventType) => { 10382 // ... 10383 } 10384 try { 10385 windowStage.on('windowStageEvent', callback); 10386 } catch (exception) { 10387 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 10388 } 10389 try { 10390 windowStage.off('windowStageEvent', callback); 10391 // Unregister all the callbacks that have been registered through on(). 10392 windowStage.off('windowStageEvent'); 10393 } catch (exception) { 10394 console.error(`Failed to disable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 10395 } 10396 } 10397}; 10398``` 10399 10400### on('windowStageClose')<sup>14+</sup> 10401 10402on(eventType: 'windowStageClose', callback: Callback<void>): void 10403 10404Subscribes to the click event on the close button in the three-button navigation bar of the main window. This API can be used only on 2-in-1 devices. This event is triggered when the close button in the three-button navigation bar of the main window is clicked. The registered lifecycle callback function [UIAbility.onPrepareToTerminate](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonpreparetoterminate10) is not executed. 10405 10406**Model restriction**: This API can be used only in the stage model. 10407 10408**System capability**: SystemCapability.Window.SessionManager 10409 10410**Atomic service API**: This API can be used in atomic services since API version 14. 10411 10412**Parameters** 10413 10414| Name | Type | Mandatory| Description | 10415| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 10416| 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| 10417| 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.| 10418 10419**Error codes** 10420 10421For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10422 10423| ID| Error Message| 10424| ------- | ------------------------------ | 10425| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 10426| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10427| 1300002 | This window state is abnormal. | 10428 10429**Example** 10430 10431```ts 10432// EntryAbility.ets 10433import { UIAbility } from '@kit.AbilityKit'; 10434import { window } from '@kit.ArkUI'; 10435 10436export default class EntryAbility extends UIAbility { 10437 // ... 10438 10439 onWindowStageCreate(windowStage: window.WindowStage) { 10440 console.info('onWindowStageCreate'); 10441 try { 10442 windowStage.on('windowStageClose', () => { 10443 console.info('Succeeded in enabling the listener for window stage close event.'); 10444 return false; 10445 }); 10446 } catch (exception) { 10447 console.error(`Failed to enable the listener for window stage close event. Cause code: ${exception.code}, message: ${exception.message}`); 10448 } 10449 } 10450}; 10451``` 10452 10453### off('windowStageClose')<sup>14+</sup> 10454 10455off(eventType: 'windowStageClose', callback?: Callback<void>): void 10456 10457Unsubscribes from the click event on the close button in the three-button navigation bar of the main window. This API can be used only on 2-in-1 devices. 10458 10459**Model restriction**: This API can be used only in the stage model. 10460 10461**System capability**: SystemCapability.Window.SessionManager 10462 10463**Atomic service API**: This API can be used in atomic services since API version 14. 10464 10465**Parameters** 10466 10467| Name | Type | Mandatory| Description | 10468| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 10469| 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.| 10470| 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.| 10471 10472**Error codes** 10473 10474For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10475 10476| ID| Error Message| 10477| ------- | ------------------------------ | 10478| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 10479| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10480| 1300002 | This window state is abnormal. | 10481 10482**Example** 10483 10484```ts 10485// EntryAbility.ets 10486import { UIAbility } from '@kit.AbilityKit'; 10487import { window } from '@kit.ArkUI'; 10488 10489export default class EntryAbility extends UIAbility { 10490 // ... 10491 10492 onWindowStageCreate(windowStage: window.WindowStage) { 10493 console.info('onWindowStageCreate'); 10494 const callback = () => { 10495 // ... 10496 return false; 10497 } 10498 try { 10499 windowStage.on('windowStageClose', callback); 10500 windowStage.off('windowStageClose', callback); 10501 windowStage.off('windowStageClose'); 10502 } catch (exception) { 10503 console.error(`Failed to disable the listener for window stage close changes. Cause code: ${exception.code}, message: ${exception.message}`); 10504 } 10505 } 10506}; 10507``` 10508 10509### setDefaultDensityEnabled<sup>12+</sup> 10510 10511setDefaultDensityEnabled(enabled: boolean): void 10512 10513Enables the system's default density. 10514 10515By default, the system's default density is not used, and the window layout changes with the system display size. 10516 10517**Model restriction**: This API can be used only in the stage model. 10518 10519**Atomic service API**: This API can be used in atomic services since API version 12. 10520 10521**System capability**: SystemCapability.Window.SessionManager 10522 10523**Parameters** 10524 10525| Name | Type | Mandatory| Description | 10526| ---------------- | ------- | ---- | ---------------------------- | 10527| 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.| 10528 10529**Error codes** 10530 10531For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10532 10533| ID| Error Message| 10534| ------- | ------------------------------ | 10535| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10536| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10537| 1300002 | This window state is abnormal. | 10538| 1300005 | This window stage is abnormal. | 10539 10540**Example** 10541 10542```ts 10543// EntryAbility.ets 10544import { UIAbility } from '@kit.AbilityKit'; 10545 10546export default class EntryAbility extends UIAbility { 10547 // ... 10548 10549 onWindowStageCreate(windowStage: window.WindowStage) { 10550 console.log('onWindowStageCreate'); 10551 try { 10552 windowStage.setDefaultDensityEnabled(true); 10553 } catch (exception) { 10554 console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`); 10555 } 10556 } 10557}; 10558``` 10559 10560### setWindowModal<sup>14+</sup> 10561 10562setWindowModal(isModal: boolean): Promise<void> 10563 10564Enables the modal property of the main window. This API uses a promise to return the result. 10565 10566This API must be called by the main window and the setting takes effect for the main window. After the modal property of the main window is enabled, other main windows in the same application process and their subwindows do not respond to user interactions until the main window is closed or the main window's modal property is disabled. 10567 10568This API can be used only on 2-in-1 devices. 10569 10570**Model restriction**: This API can be used only in the stage model. 10571 10572**Atomic service API**: This API can be used in atomic services since API version 14. 10573 10574**System capability**: SystemCapability.Window.SessionManager 10575 10576**Parameters** 10577 10578| Name | Type | Mandatory| Description | 10579| --------- | ------- | ---- | --------------------------------------------- | 10580| 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.| 10581 10582 10583**Return value** 10584 10585| Type| Description| 10586| ------------------- | ------------------------ | 10587| Promise<void> | Promise that returns no value.| 10588 10589**Error codes** 10590 10591For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10592 10593| ID| Error Message | 10594| -------- | ------------------------------ | 10595| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10596| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10597| 1300002 | This window state is abnormal. | 10598| 1300003 | This window manager service works abnormally. | 10599 10600**Example** 10601 10602```ts 10603// EntryAbility.ets 10604import { UIAbility } from '@kit.AbilityKit'; 10605import { BusinessError } from '@kit.BasicServicesKit'; 10606 10607export default class EntryAbility extends UIAbility { 10608 // ... 10609 onWindowStageCreate(windowStage: window.WindowStage): void { 10610 console.info('onWindowStageCreate'); 10611 try { 10612 let promise = windowStage.setWindowModal(true); 10613 promise.then(() => { 10614 console.info('Succeeded in setting window modal'); 10615 }).catch((err: BusinessError) => { 10616 console.error(`Failed to set window modal. Cause code: ${err.code}, message: ${err.message}`); 10617 }); 10618 } catch (exception) { 10619 console.error(`Failed to set window modal. Cause code: ${exception.code}, message: ${exception.message}`); 10620 } 10621 } 10622} 10623``` 10624 10625### removeStartingWindow<sup>14+</sup> 10626 10627removeStartingWindow(): Promise<void> 10628 10629Allows the application to control the time when the launch page disappears. 10630 10631This 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**. 10632 10633If 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. 10634 10635If 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. 10636 10637**Model restriction**: This API can be used only in the stage model. 10638 10639**Atomic service API**: This API can be used in atomic services since API version 14. 10640 10641**System capability**: SystemCapability.Window.SessionManager 10642 10643**Return value** 10644 10645| Type | Description | 10646| ------------------- | ------------------------- | 10647| Promise<void> | Promise that returns no value.| 10648 10649**Error codes** 10650 10651For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10652 10653| ID| Error Message| 10654| ------- | ------------------------------ | 10655| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10656| 1300002 | This window state is abnormal. | 10657| 1300003 | This window manager service works abnormally. | 10658 10659**Example** 10660 10661```ts 10662// EntryAbility.ets 10663import { UIAbility } from '@kit.AbilityKit'; 10664import { BusinessError } from '@kit.BasicServicesKit'; 10665 10666export default class EntryAbility extends UIAbility { 10667 // ... 10668 10669 onWindowStageCreate(windowStage: window.WindowStage) { 10670 console.info('onWindowStageCreate'); 10671 windowStage.removeStartingWindow().then(() => { 10672 console.info('Succeeded in removing starting window.'); 10673 }).catch((err: BusinessError) => { 10674 console.error(`Failed to remove starting window. Cause code: ${err.code}, message: ${err.message}`); 10675 }); 10676 } 10677}; 10678``` 10679 10680### setWindowRectAutoSave<sup>14+</sup> 10681 10682setWindowRectAutoSave(enabled: boolean): Promise<void> 10683 10684Sets whether to enable the auto-save feature for the size of the main window. This API uses a promise to return the result. It takes effect only on 2-in-1 devices. 10685 10686This API must be called by the main window and the setting takes effect for the main window. When the auto-save feature is enabled, the application will remember the size and state of the main window upon its closure under the same UIAbility. 10687 10688Upon relaunch, the window will reopen in accordance with these remembered size and state. 10689 10690The following rules apply in stacking scenarios: 106911. If the current instance is a free-form window, the next opened window will adopt the same size when stacked. 106922. If the current instance is maximized or in full-screen mode, the next opened window will maintain the maximized state when stacked. 10693 10694The following table describes the memory rules: 10695|Last Window State|Memorizing Rule| 10696|-------------|-------| 10697|Free-form window|Retains the size/position of the free-form window, rebound if exceeding the workspace| 10698|Split-screen window|Retains the size and position of the free-form window before screen splitting.| 10699|Maximized window|Retains the maximized state.| 10700|Immersive window|Retains the size and position of the free-form window before immersive mode.| 10701|Minimized window|Retains the size and position of the free-form window before minimization.| 10702 10703**Model restriction**: This API can be used only in the stage model. 10704 10705**Atomic service API**: This API can be used in atomic services since API version 14. 10706 10707**System capability**: SystemCapability.Window.SessionManager 10708 10709**Parameters** 10710 10711| Name | Type | Mandatory| Description | 10712| --------- | ------- | ---- | --------------------------------------------- | 10713| enabled | boolean | Yes | Whether to enable the auto-save feature for the main window's size. The value **true** means to enable the auto-save feature, and **false** means the opposite.| 10714 10715 10716**Return value** 10717 10718| Type| Description| 10719| ------------------- | ------------------------ | 10720| Promise<void> | Promise that returns no value.| 10721 10722**Error codes** 10723 10724For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10725 10726| ID| Error Message | 10727| -------- | ------------------------------ | 10728| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10729| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10730| 1300002 | This window state is abnormal. | 10731| 1300003 | This window manager service works abnormally. | 10732 10733**Example** 10734 10735```ts 10736// EntryAbility.ets 10737import { UIAbility } from '@kit.AbilityKit'; 10738import { BusinessError } from '@kit.BasicServicesKit'; 10739 10740export default class EntryAbility extends UIAbility { 10741 // ... 10742 onWindowStageCreate(windowStage: window.WindowStage): void { 10743 console.info('onWindowStageCreate'); 10744 try { 10745 let promise = windowStage.setWindowRectAutoSave(true); 10746 promise.then(() => { 10747 console.info('Succeeded in setting window rect auto-save'); 10748 }).catch((err: BusinessError) => { 10749 console.error(`Failed to set window rect auto-save. Cause code: ${err.code}, message: ${err.message}`); 10750 }); 10751 } catch (exception) { 10752 console.error(`Failed to set window rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`); 10753 } 10754 } 10755} 10756``` 10757 10758### isWindowRectAutoSave<sup>14+</sup> 10759 10760isWindowRectAutoSave(): Promise<boolean> 10761 10762Checks 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. 10763 10764**Model restriction**: This API can be used only in the stage model. 10765 10766**Atomic service API**: This API can be used in atomic services since API version 14. 10767 10768**System capability**: SystemCapability.Window.SessionManager 10769 10770**Return value** 10771 10772| Type| Description| 10773| ---------------------- | ------------------------------------------------------------------------------------ | 10774| Promise<boolean> | Promise used to return the result. The value **true** means that the auto-save feature is enabled, and **false** means the opposite.| 10775 10776**Error codes** 10777 10778For details about the error codes, see [Window Error Codes](errorcode-window.md). 10779 10780| ID| Error Message| 10781| ------- | ------------------------------ | 10782| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10783| 1300002 | This window state is abnormal. | 10784 10785**Example** 10786 10787```ts 10788// EntryAbility.ets 10789import { UIAbility } from '@kit.AbilityKit'; 10790import { BusinessError } from '@kit.BasicServicesKit'; 10791 10792export default class EntryAbility extends UIAbility { 10793 // ... 10794 onWindowStageCreate(windowStage: window.WindowStage): void { 10795 console.info('onWindowStageCreate'); 10796 try { 10797 let promise = windowStage.isWindowRectAutoSave(); 10798 promise.then((data) => { 10799 console.info('Succeeded in checking whether the window support the rect auto-save. Data: ' + JSON.stringify(data)); 10800 }).catch((err: BusinessError) => { 10801 console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${err.code}, message: ${err.message}`); 10802 }); 10803 } catch (exception) { 10804 console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`); 10805 } 10806 } 10807} 10808``` 10809