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 child window.<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 child window 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 child window. Otherwise, an error is reported.<br>In the stage model, you must pass in this parameter when creating a floating window, modal window, or system window.| 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 **'#66000000'**.<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 **'#E5FFFFFF'**.<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 **'#66000000'**.<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 **'#E5FFFFFF'**.<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 **'#E5FFFFFF'**.| 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## WindowDensityInfo<sup>15+</sup> 345 346Describes the information about the display density of the screen where the window is located and the window's custom display density. It is a scale factor independent of pixel units, that is, a factor for scaling display size. 347 348**Atomic service API**: This API can be used in atomic services since API version 15. 349 350**System capability**: SystemCapability.Window.SessionManager 351 352| Name | Type| Readable| Writable| Description | 353| ------ | -------- | ---- | ---- | ---------- | 354| systemDensity | number | Yes | No | System's display size scale factor for the screen where the window is located. The value ranges from 0.5 to 4.0 and varies according to user settings.| 355| defaultDensity | number | Yes | No | Default display size scale factor for the screen where the window is located. The value ranges from 0.5 to 4.0 and varies with the screen.| 356| customDensity | number | Yes | No | Custom display size scale factor of the window. The value ranges from 0.5 to 4.0. If this parameter is left unspecified, the system's display size scale factor is used.| 357 358## WindowLayoutInfo<sup>15+</sup> 359 360Describes the information about the window layout. 361 362**Atomic service API**: This API can be used in atomic services since API version 15. 363 364**System capability**: SystemCapability.Window.SessionManager 365 366| Name | Type | Mandatory| Description | 367| ------ | ------ | ---- | ------------------------------------------ | 368| windowRect<sup>15+</sup> | [Rect](#rect7) | Yes| Window rectangle, that is, the position and size of the window on the display.| 369 370## MoveConfiguration<sup>15+</sup> 371 372Describes the window movement configuration. 373 374**Atomic service API**: This API can be used in atomic services since API version 15. 375 376**System capability**: SystemCapability.Window.SessionManager 377 378| Name | Type | Mandatory| Description | 379| ------ | ------ | ---- | ------------------------------------------ | 380| displayId | number | No| Target display ID. The value must be an integer. If a non-integer is passed in, the value is rounded down. If this parameter is not set or the target displayed ID does not exist, the current display is used by default.| 381 382## window.createWindow<sup>9+</sup> 383 384createWindow(config: Configuration, callback: AsyncCallback<Window>): void 385 386Creates a child window or system window. This API uses an asynchronous callback to return the result. 387 388**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**) 389 390**Atomic service API**: This API can be used in atomic services since API version 12. 391 392**System capability**: SystemCapability.WindowManager.WindowManager.Core 393 394**Parameters** 395 396| Name| Type| Mandatory| Description| 397| -------- | -------------------------------------- | -- | --------------------------------- | 398| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window. | 399| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the window created.| 400 401**Error codes** 402 403For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 404 405| ID| Error Message| 406| ------- | -------------------------------- | 407| 201 | Permission verification failed. The application does not have the permission required to call the API. | 408| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 409| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 410| 1300001 | Repeated operation. | 411| 1300002 | This window state is abnormal. | 412| 1300004 | Unauthorized operation. | 413| 1300006 | This window context is abnormal. | 414| 1300008 | The display device is abnormal. | 415| 1300009 | The parent window is invalid. | 416 417**Example** 418 419```ts 420import { BusinessError } from '@kit.BasicServicesKit'; 421 422let windowClass: window.Window | undefined = undefined; 423let config: window.Configuration = { 424 name: "test", 425 windowType: window.WindowType.TYPE_DIALOG, 426 ctx: this.context 427}; 428try { 429 window.createWindow(config, (err: BusinessError, data) => { 430 const errCode: number = err.code; 431 if (errCode) { 432 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 433 return; 434 } 435 windowClass = data; 436 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 437 windowClass.resize(500, 1000); 438 }); 439} catch (exception) { 440 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 441} 442``` 443 444## window.createWindow<sup>9+</sup> 445 446createWindow(config: Configuration): Promise<Window> 447 448Creates a child window or system window. This API uses a promise to return the result. 449 450**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**) 451 452**Atomic service API**: This API can be used in atomic services since API version 12. 453 454**System capability**: SystemCapability.WindowManager.WindowManager.Core 455 456**Parameters** 457 458| Name| Type| Mandatory| Description| 459| ------ | -------------------------------- | -- | ------------------ | 460| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window.| 461 462**Return value** 463 464| Type| Description| 465| -------------------------------- | ------------------------------------ | 466| Promise<[Window](#window)> | Promise used to return the window created.| 467 468**Error codes** 469 470For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 471 472| ID| Error Message| 473| ------- | -------------------------------- | 474| 201 | Permission verification failed. The application does not have the permission required to call the API. | 475| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 476| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 477| 1300001 | Repeated operation. | 478| 1300002 | This window state is abnormal. | 479| 1300004 | Unauthorized operation. | 480| 1300006 | This window context is abnormal. | 481| 1300008 | The display device is abnormal. | 482| 1300009 | The parent window is invalid. | 483 484**Example** 485 486```ts 487import { BusinessError } from '@kit.BasicServicesKit'; 488 489let windowClass: window.Window | undefined = undefined; 490let config: window.Configuration = { 491 name: "test", 492 windowType: window.WindowType.TYPE_DIALOG, 493 ctx: this.context 494}; 495try { 496 let promise = window.createWindow(config); 497 promise.then((data) => { 498 windowClass = data; 499 console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); 500 }).catch((err: BusinessError) => { 501 console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`); 502 }); 503} catch (exception) { 504 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 505} 506``` 507 508## window.findWindow<sup>9+</sup> 509 510findWindow(name: string): Window 511 512Finds a window based on the name. 513 514**System capability**: SystemCapability.WindowManager.WindowManager.Core 515 516**Atomic service API**: This API can be used in atomic services since API version 11. 517 518**Parameters** 519 520| Name| Type | Mandatory| Description | 521| ------ | ------ | ---- | -------- | 522| name | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 523 524**Return value** 525 526| Type| Description| 527| ----------------- | ------------------- | 528| [Window](#window) | Window found.| 529 530**Error codes** 531 532For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 533 534| ID| Error Message| 535| ------- | -------------------------------- | 536| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 537| 1300002 | This window state is abnormal. | 538 539**Example** 540 541```ts 542let windowClass: window.Window | undefined = undefined; 543try { 544 windowClass = window.findWindow('test'); 545} catch (exception) { 546 console.error(`Failed to find the Window. Cause code: ${exception.code}, message: ${exception.message}`); 547} 548``` 549 550## window.getLastWindow<sup>9+</sup> 551 552getLastWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 553 554Obtains the top window of the current application. This API uses an asynchronous callback to return the result. If no child window is available, the main window of the application is returned. 555 556**Atomic service API**: This API can be used in atomic services since API version 12. 557 558**System capability**: SystemCapability.WindowManager.WindowManager.Core 559 560**Parameters** 561 562| Name| Type| Mandatory| Description| 563| -------- | -------------------------------------- | -- | ---------------------------------------- | 564| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Current application context.| 565| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the top window obtained.| 566 567**Error codes** 568 569For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 570 571| ID| Error Message| 572| ------- | -------------------------------- | 573| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 574| 1300002 | This window state is abnormal. | 575| 1300006 | This window context is abnormal. | 576 577**Example** 578 579```ts 580// EntryAbility.ets 581import { UIAbility } from '@kit.AbilityKit'; 582import { BusinessError } from '@kit.BasicServicesKit'; 583 584export default class EntryAbility extends UIAbility { 585 // ... 586 onWindowStageCreate(windowStage: window.WindowStage) { 587 console.info('onWindowStageCreate'); 588 let windowClass: window.Window | undefined = undefined; 589 try { 590 window.getLastWindow(this.context, (err: BusinessError, data) => { 591 const errCode: number = err.code; 592 if (errCode) { 593 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 594 return; 595 } 596 windowClass = data; 597 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 598 }); 599 } catch (exception) { 600 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 601 } 602 } 603} 604``` 605 606## window.getLastWindow<sup>9+</sup> 607 608getLastWindow(ctx: BaseContext): Promise<Window> 609 610Obtains the top window of the current application. This API uses a promise to return the result. If no child window is available, the main window of the application is returned. 611 612**Atomic service API**: This API can be used in atomic services since API version 12. 613 614**System capability**: SystemCapability.WindowManager.WindowManager.Core 615 616**Parameters** 617 618| Name| Type| Mandatory| Description| 619| ------ | ----------- | ---- | ------------------------------------------------------------ | 620| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 621 622**Return value** 623 624| Type| Description| 625| -------------------------------- | ------------------------------------------- | 626| Promise<[Window](#window)> | Promise used to return the top window obtained.| 627 628**Error codes** 629 630For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 631 632| ID| Error Message| 633| ------- | -------------------------------- | 634| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 635| 1300002 | This window state is abnormal. | 636| 1300006 | This window context is abnormal. | 637 638**Example** 639 640```ts 641// EntryAbility.ets 642import { UIAbility } from '@kit.AbilityKit'; 643import { BusinessError } from '@kit.BasicServicesKit'; 644 645export default class EntryAbility extends UIAbility { 646 // ... 647 onWindowStageCreate(windowStage: window.WindowStage) { 648 console.info('onWindowStageCreate'); 649 let windowClass: window.Window | undefined = undefined; 650 try { 651 let promise = window.getLastWindow(this.context); 652 promise.then((data) => { 653 windowClass = data; 654 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 655 }).catch((err: BusinessError) => { 656 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 657 }); 658 } catch (exception) { 659 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 660 } 661 } 662} 663``` 664 665## window.shiftAppWindowFocus<sup>11+</sup> 666shiftAppWindowFocus(sourceWindowId: number, targetWindowId: number): Promise<void> 667 668Shifts the window focus from the source window to the target window in the same application. The window focus can be shifted between the main window and a child window. 669 670**Atomic service API**: This API can be used in atomic services since API version 12. 671 672**System capability**: SystemCapability.Window.SessionManager 673 674**Parameters** 675 676| Name | Type | Mandatory | Description | 677| -------------- | ------ | ----- | ----------------------- | 678| sourceWindowId | number | Yes | ID of the source window, which is having the focus.| 679| targetWindowId | number | Yes | ID of the target window. | 680 681**Return value** 682 683| Type | Description | 684| ------------------- | ------------------------- | 685| Promise<void> | Promise that returns no value.| 686 687**Error codes** 688 689For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 690 691| ID| Error Message | 692| ------- | --------------------------------------------- | 693| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 694| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 695| 1300002 | This window state is abnormal. | 696| 1300003 | This window manager service works abnormally. | 697| 1300004 | Unauthorized operation. | 698 699**Example** 700 701```ts 702// EntryAbility.ets 703import { UIAbility } from '@kit.AbilityKit'; 704import { BusinessError } from '@kit.BasicServicesKit'; 705 706export default class EntryAbility extends UIAbility { 707 onWindowStageCreate(windowStage: window.WindowStage) { 708 // ... 709 console.info('onWindowStageCreate'); 710 let windowClass: window.Window | undefined = undefined; 711 let subWindowClass: window.Window | undefined = undefined; 712 let windowClassId: number = -1; 713 let subWindowClassId: number = -1; 714 715 try { 716 // Obtain the main window and ID of the application. 717 let promise = windowStage.getMainWindow(); 718 promise.then((data) => { 719 if (data == null) { 720 console.error("Failed to obtaining the window. Cause: The data is empty"); 721 return; 722 } 723 windowClass = data; 724 windowClass.setUIContent("pages/Index"); 725 windowClassId = windowClass.getWindowProperties().id; 726 console.info('Succeeded in obtaining the window') 727 }).catch((err: BusinessError) => { 728 console.error(`Failed to obtaining the window. Cause code: ${err.code}, message: ${err.message}`); 729 }); 730 731 // Create or obtain a child window and its ID. In this case, the child window has focus. 732 let promiseSub = windowStage.createSubWindow("testSubWindow"); 733 promiseSub.then((data) => { 734 if (data == null) { 735 console.error("Failed to obtaining the window. Cause: The data is empty"); 736 return; 737 } 738 subWindowClass = data; 739 subWindowClassId = subWindowClass.getWindowProperties().id; 740 subWindowClass.resize(500, 500); 741 subWindowClass.setUIContent("pages/Index2"); 742 subWindowClass.showWindow(); 743 744 // Listen for the window status and ensure that the window is ready. 745 subWindowClass.on("windowEvent", (windowEvent) => { 746 if (windowEvent == window.WindowEventType.WINDOW_ACTIVE) { 747 // Switch the focus. 748 let promise = window.shiftAppWindowFocus(subWindowClassId, windowClassId); 749 promise.then(() => { 750 console.info('Succeeded in shifting app window focus'); 751 }).catch((err: BusinessError) => { 752 console.error(`Failed to shift app window focus. Cause code: ${err.code}, message: ${err.message}`); 753 }); 754 } 755 }); 756 }); 757 } catch (exception) { 758 console.error(`Failed to shift app focus. Cause code: ${exception.code}, message: ${exception.message}`); 759 } 760 } 761} 762``` 763 764## window.shiftAppWindowPointerEvent<sup>15+</sup> 765shiftAppWindowPointerEvent(sourceWindowId: number, targetWindowId: number): Promise<void> 766 767Transfers an input event from one window to another within the same application, particularly in split-window scenarios. This API uses a promise to return the result. It takes effect only for the main window and its child windows on 2-in-1 devices. 768 769On 2-in-1 devices, the source window must be in a mouse-down state for this API to work; otherwise, the call does not take effect. After the input event is transferred, a mouse-up event is sent to the source window, and a mouse-down event is sent to the target window. 770 771**Atomic service API**: This API can be used in atomic services since API version 15. 772 773**System capability**: SystemCapability.Window.SessionManager 774 775**Parameters** 776 777| Name | Type | Mandatory | Description | 778| -------------- | ------ | ----- | ----------------------- | 779| sourceWindowId | number | Yes | ID of the source window. You are advised to call [getWindowProperties()](#getwindowproperties9) to obtain the window ID. | 780| targetWindowId | number | Yes | ID of the target window. You are advised to call [getWindowProperties()](#getwindowproperties9) to obtain the window ID. | 781 782**Return value** 783 784| Type | Description | 785| ------------------- | ------------------------- | 786| Promise<void> | Promise that returns no value.| 787 788**Error codes** 789 790For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 791 792| ID| Error Message | 793| ------- | --------------------------------------------- | 794| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 795| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 796| 1300002 | This window state is abnormal. | 797| 1300003 | This window manager service works abnormally. | 798| 1300004 | Unauthorized operation. | 799 800**Example** 801 802```ts 803// ets/pages/Index.ets 804import { window } from '@kit.ArkUI'; 805import { BusinessError } from '@kit.BasicServicesKit'; 806 807@Entry 808struct Index { 809 build() { 810 Row() { 811 Column() { 812 Blank('160') 813 .color(Color.Blue) 814 .onTouch((event: TouchEvent) => { 815 if (event.type === TouchType.Down) { 816 try { 817 let sourceWindowId = 1; 818 let targetWindowId = 2; 819 let promise = window.shiftAppWindowPointerEvent(sourceWindowId, targetWindowId); 820 promise.then(() => { 821 console.info('Succeeded in shifting app window pointer event'); 822 }).catch((err: BusinessError) => { 823 console.error(`Failed to shift app window pointer event. Cause code: ${err.code}, message: ${err.message}`); 824 }); 825 } catch (exception) { 826 console.error(`Failed to shift app pointer event. Cause code: ${exception.code}, message: ${exception.message}`); 827 } 828 } 829 }) 830 }.width('100%') 831 }.height('100%').width('100%') 832 } 833} 834``` 835 836## window.getWindowsByCoordinate<sup>14+</sup> 837 838getWindowsByCoordinate(displayId: number, windowNumber?: number, x?: number, y?: number): Promise<Array<Window>> 839 840Obtains visible windows at the specified coordinates of the application. This API uses a promise to return the result. 841 842**Atomic service API**: This API can be used in atomic services since API version 14. 843 844**System capability**: SystemCapability.Window.SessionManager 845 846**Parameters** 847 848| Name| Type | Mandatory| Description | 849| ------ | ---------- |----|---------------------------------------------------------------------------| 850| 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).| 851| 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. | 852| 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. | 853| 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. | 854 855**Return value** 856 857| Type | Description | 858| -------------------------------- |-------------------------| 859| Promise<Array<[Window](#window)>> | Promise used to return an array of window objects.| 860 861**Error codes** 862 863For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 864 865| ID | Error Message| 866|----------| ------------------------------ | 867| 401 | Parameter error. Possible cause: Incorrect parameter types. | 868| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 869| 1300003 | This window manager service works abnormally. | 870 871```ts 872import { UIAbility } from '@kit.AbilityKit'; 873import { window } from '@kit.ArkUI'; 874import { BusinessError } from '@kit.BasicServicesKit'; 875 876export default class EntryAbility extends UIAbility { 877 878 onWindowStageCreate(windowStage: window.WindowStage): void { 879 let windowClass = windowStage.getMainWindowSync(); 880 try { 881 let properties = windowClass.getWindowProperties(); 882 window.getWindowsByCoordinate(properties.displayId).then((data) => { 883 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 884 for (let window of data) { 885 // do something with window 886 } 887 }).catch((err: BusinessError) => { 888 console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`); 889 }); 890 window.getWindowsByCoordinate(properties.displayId, 2, 500, 500).then((data) => { 891 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 892 for (let window of data) { 893 // do something with window 894 } 895 }).catch((err: BusinessError) => { 896 console.error(`Failed to get window from point. Cause code: ${err.code}, message: ${err.message}`); 897 }); 898 } catch (exception) { 899 console.error(`Failed to get window from point. Cause code: ${exception.code}, message: ${exception.message}`); 900 } 901 } 902} 903``` 904 905## window.getAllWindowLayoutInfo<sup>15+</sup> 906 907getAllWindowLayoutInfo(displayId: number): Promise<Array<WindowLayoutInfo>> 908 909Obtains the layout information array of all windows visible on a display. The layout information is arranged based on the current window stacking order, and the topmost window in the hierarchy is at index 0 of the array. This API uses a promise to return the result. 910 911**Atomic service API**: This API can be used in atomic services since API version 15. 912 913**System capability**: SystemCapability.Window.SessionManager 914 915**Parameters** 916 917| Name| Type | Mandatory| Description | 918| ------ | ---------- |----|---------------------------------------------------------------------------| 919| 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).| 920 921**Return value** 922 923| Type | Description | 924| -------------------------------- |-------------------------| 925| Promise<Array<[WindowLayoutInfo](#windowlayoutinfo15)>> | Promise used to return an array of window layout information objects.| 926 927**Error codes** 928 929For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 930 931| ID | Error Message| 932|----------| ------------------------------ | 933| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 934| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 935| 1300002 | This window state is abnormal. | 936| 1300003 | This window manager service works abnormally. | 937 938```ts 939import { window } from '@kit.ArkUI'; 940import { BusinessError } from '@kit.BasicServicesKit'; 941 942try { 943 let displayId = 0; 944 let promise = window.getAllWindowLayoutInfo(displayId) 945 promise.then((data) => { 946 console.info('Succeeded in obtaining all window layout info. Data: ' + JSON.stringify(data)); 947 }).catch((err: BusinessError) => { 948 console.error(`Failed to obtain all window layout info. Cause code: ${err.code}, message: ${err.message}`); 949 }); 950} catch (exception) { 951 console.error(`Failed to obtain all window layout info. Cause code: ${exception.code}, message: ${exception.message}`); 952} 953``` 954 955## window.create<sup>(deprecated)</sup> 956 957create(id: string, type: WindowType, callback: AsyncCallback<Window>): void 958 959Creates a child window. This API uses an asynchronous callback to return the result. 960 961> **NOTE** 962> 963> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 964 965**Model restriction**: This API can be used only in the FA model. 966 967**System capability**: SystemCapability.WindowManager.WindowManager.Core 968 969**Parameters** 970 971| Name | Type | Mandatory| Description | 972| -------- | -------------------------------------- | ---- | ------------------------------------ | 973| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 974| type | [WindowType](#windowtype7) | Yes | Window type. | 975| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the child window created.| 976 977 978**Example** 979 980```ts 981import { BusinessError } from '@kit.BasicServicesKit'; 982 983let windowClass: window.Window | undefined = undefined; 984window.create('test', window.WindowType.TYPE_APP, (err: BusinessError, data) => { 985 const errCode: number = err.code; 986 if (errCode) { 987 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 988 return; 989 } 990 windowClass = data; 991 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 992}); 993``` 994 995## window.create<sup>(deprecated)</sup> 996 997create(id: string, type: WindowType): Promise<Window> 998 999Creates a child window. This API uses a promise to return the result. 1000 1001> **NOTE** 1002> 1003> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 1004 1005**Model restriction**: This API can be used only in the FA model. 1006 1007**System capability**: SystemCapability.WindowManager.WindowManager.Core 1008 1009**Parameters** 1010 1011| Name| Type | Mandatory| Description | 1012| ------ | ------------------------- | ---- | ---------- | 1013| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 1014| type | [WindowType](#windowtype7) | Yes | Window type.| 1015 1016**Return value** 1017 1018| Type | Description | 1019| -------------------------------- | --------------------------------------- | 1020| Promise<[Window](#window)> | Promise used to return the child window created.| 1021 1022 1023**Example** 1024 1025```ts 1026import { BusinessError } from '@kit.BasicServicesKit'; 1027 1028let windowClass: window.Window | undefined = undefined; 1029let promise = window.create('test', window.WindowType.TYPE_APP); 1030promise.then((data) => { 1031 windowClass = data; 1032 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 1033}).catch((err: BusinessError) => { 1034 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 1035}); 1036``` 1037 1038## window.create<sup>(deprecated)</sup> 1039 1040create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void 1041 1042Creates a system window. This API uses an asynchronous callback to return the result. 1043 1044> **NOTE** 1045> 1046> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 1047 1048**System capability**: SystemCapability.WindowManager.WindowManager.Core 1049 1050**Parameters** 1051 1052| Name | Type | Mandatory| Description | 1053| -------- | ------------------------------------------------------- | ---- | ------------------------------------ | 1054| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context. | 1055| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 1056| type | [WindowType](#windowtype7) | Yes | Window type. | 1057| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the child window created.| 1058 1059 1060**Example** 1061 1062```ts 1063import { BusinessError } from '@kit.BasicServicesKit'; 1064 1065let windowClass: window.Window | undefined = undefined; 1066window.create('test', window.WindowType.TYPE_SYSTEM_ALERT, (err: BusinessError, data) => { 1067 const errCode: number = err.code; 1068 if (errCode) { 1069 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 1070 return; 1071 } 1072 windowClass = data; 1073 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 1074 windowClass.resetSize(500, 1000); 1075}); 1076``` 1077 1078## window.create<sup>(deprecated)</sup> 1079 1080create(ctx: BaseContext, id: string, type: WindowType): Promise<Window> 1081 1082Creates a system window. This API uses a promise to return the result. 1083 1084> **NOTE** 1085> 1086> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 1087 1088**System capability**: SystemCapability.WindowManager.WindowManager.Core 1089 1090**Parameters** 1091 1092| Name| Type | Mandatory| Description | 1093| ------ | ------------------------- | ---- | ------------------------------------------------------------ | 1094| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1095| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1096| type | [WindowType](#windowtype7) | Yes | Window type. | 1097 1098**Return value** 1099 1100| Type | Description | 1101| -------------------------------- | --------------------------------------- | 1102| Promise<[Window](#window)> | Promise used to return the child window created.| 1103 1104 1105**Example** 1106 1107```ts 1108import { BusinessError } from '@kit.BasicServicesKit'; 1109 1110let windowClass: window.Window | undefined = undefined; 1111let promise = window.create('test', window.WindowType.TYPE_SYSTEM_ALERT); 1112promise.then((data) => { 1113 windowClass = data; 1114 console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); 1115}).catch((err: BusinessError) => { 1116 console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`); 1117}); 1118``` 1119 1120## window.find<sup>(deprecated)</sup> 1121 1122find(id: string, callback: AsyncCallback<Window>): void 1123 1124Finds a window based on the ID. This API uses an asynchronous callback to return the result. 1125 1126> **NOTE** 1127> 1128> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 1129 1130**System capability**: SystemCapability.WindowManager.WindowManager.Core 1131 1132**Parameters** 1133 1134| Name | Type | Mandatory| Description | 1135| -------- | -------------------------------------- | ---- | ------------------------------------ | 1136| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1137| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window found.| 1138 1139**Example** 1140 1141```ts 1142import { BusinessError } from '@kit.BasicServicesKit'; 1143 1144let windowClass: window.Window | undefined = undefined; 1145window.find('test', (err: BusinessError, data) => { 1146 const errCode: number = err.code; 1147 if (errCode) { 1148 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 1149 return; 1150 } 1151 windowClass = data; 1152 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 1153}); 1154``` 1155 1156## window.find<sup>(deprecated)</sup> 1157 1158find(id: string): Promise<Window> 1159 1160Finds a window based on the ID. This API uses a promise to return the result. 1161 1162> **NOTE** 1163> 1164> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 1165 1166**System capability**: SystemCapability.WindowManager.WindowManager.Core 1167 1168**Parameters** 1169 1170| Name| Type | Mandatory| Description | 1171| ------ | ------ | ---- | -------- | 1172| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 1173 1174**Return value** 1175 1176| Type | Description | 1177| -------------------------------- | ------------------------------------- | 1178| Promise<[Window](#window)> | Promise used to return the window found.| 1179 1180**Example** 1181 1182```ts 1183import { BusinessError } from '@kit.BasicServicesKit'; 1184 1185let windowClass: window.Window | undefined = undefined; 1186let promise = window.find('test'); 1187promise.then((data) => { 1188 windowClass = data; 1189 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 1190}).catch((err: BusinessError) => { 1191 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 1192}); 1193``` 1194 1195## window.getTopWindow<sup>(deprecated)</sup> 1196 1197getTopWindow(callback: AsyncCallback<Window>): void 1198 1199Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 1200 1201> **NOTE** 1202> 1203> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 1204 1205**Model restriction**: This API can be used only in the FA model. 1206 1207**System capability**: SystemCapability.WindowManager.WindowManager.Core 1208 1209**Parameters** 1210 1211| Name | Type | Mandatory| Description | 1212| -------- | -------------------------------------- | ---- | -------------------------------------------- | 1213| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained.| 1214 1215**Example** 1216 1217```ts 1218import { BusinessError } from '@kit.BasicServicesKit'; 1219 1220let windowClass: window.Window | undefined = undefined; 1221window.getTopWindow((err: BusinessError, data) => { 1222 const errCode: number = err.code; 1223 if (errCode) { 1224 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1225 return; 1226 } 1227 windowClass = data; 1228 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1229}); 1230``` 1231 1232## window.getTopWindow<sup>(deprecated)</sup> 1233 1234getTopWindow(): Promise<Window> 1235 1236Obtains the top window of the current application. This API uses a promise to return the result. 1237 1238> **NOTE** 1239> 1240> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 1241 1242**Model restriction**: This API can be used only in the FA model. 1243 1244**System capability**: SystemCapability.WindowManager.WindowManager.Core 1245 1246**Return value** 1247 1248| Type | Description | 1249| -------------------------------- | ----------------------------------------------- | 1250| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1251 1252**Example** 1253 1254```ts 1255import { BusinessError } from '@kit.BasicServicesKit'; 1256 1257let windowClass: window.Window | undefined = undefined; 1258let promise = window.getTopWindow(); 1259promise.then((data)=> { 1260 windowClass = data; 1261 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1262}).catch((err: BusinessError)=>{ 1263 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1264}); 1265``` 1266 1267## window.getTopWindow<sup>(deprecated)</sup> 1268 1269getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 1270 1271Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 1272 1273> **NOTE** 1274> 1275> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 1276 1277**System capability**: SystemCapability.WindowManager.WindowManager.Core 1278 1279**Parameters** 1280 1281| Name | Type | Mandatory| Description | 1282| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1283| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1284| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. | 1285 1286**Example** 1287 1288```ts 1289// EntryAbility.ets 1290import { UIAbility } from '@kit.AbilityKit'; 1291import { BusinessError } from '@kit.BasicServicesKit'; 1292 1293export default class EntryAbility extends UIAbility { 1294 onWindowStageCreate(windowStage:window.WindowStage){ 1295 console.info('onWindowStageCreate'); 1296 let windowClass: window.Window | undefined = undefined; 1297 try { 1298 window.getTopWindow(this.context, (err: BusinessError, data) => { 1299 const errCode: number = err.code; 1300 if(errCode){ 1301 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1302 return ; 1303 } 1304 windowClass = data; 1305 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1306 }); 1307 } catch(error){ 1308 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1309 } 1310 } 1311} 1312``` 1313 1314## window.getTopWindow<sup>(deprecated)</sup> 1315 1316getTopWindow(ctx: BaseContext): Promise<Window> 1317 1318Obtains the top window of the current application. This API uses a promise to return the result. 1319 1320> **NOTE** 1321> 1322> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 1323 1324**System capability**: SystemCapability.WindowManager.WindowManager.Core 1325 1326**Parameters** 1327 1328| Name| Type | Mandatory| Description | 1329| ------ | ----------- | ---- | ------------------------------------------------------------ | 1330| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1331 1332**Return value** 1333 1334| Type | Description | 1335| -------------------------------- | ----------------------------------------------- | 1336| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1337 1338**Example** 1339 1340```ts 1341// EntryAbility.ets 1342import { UIAbility } from '@kit.AbilityKit'; 1343import { BusinessError } from '@kit.BasicServicesKit'; 1344 1345export default class EntryAbility extends UIAbility { 1346 onWindowStageCreate(windowStage:window.WindowStage) { 1347 console.info('onWindowStageCreate'); 1348 let windowClass: window.Window | undefined = undefined; 1349 let promise = window.getTopWindow(this.context); 1350 promise.then((data) => { 1351 windowClass = data; 1352 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1353 }).catch((error: BusinessError) => { 1354 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1355 }); 1356 } 1357} 1358``` 1359 1360## SpecificSystemBar<sup>11+</sup> 1361 1362type SpecificSystemBar = 'status' \| 'navigation' \| 'navigationIndicator' 1363 1364Enumerates the types of system bars that can be displayed or hidden. 1365 1366**System capability**: SystemCapability.Window.SessionManager 1367 1368**Atomic service API**: This API can be used in atomic services since API version 11. 1369 1370| Type | Description | 1371|------------|--------| 1372| 'status' | Status bar. | 1373| 'navigation' | Three-button navigation bar. | 1374| 'navigationIndicator' | Bottom navigation bar.| 1375 1376## Window 1377 1378Represents a window instance, which is the basic unit managed by the window manager. 1379 1380In 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. 1381 1382### showWindow<sup>9+</sup> 1383 1384showWindow(callback: AsyncCallback<void>): void 1385 1386Shows this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application child window. For the main window of an application, this API moves it at the top when the main window is already displayed. 1387 1388**System capability**: SystemCapability.WindowManager.WindowManager.Core 1389 1390**Atomic service API**: This API can be used in atomic services since API version 11. 1391 1392**Parameters** 1393 1394| Name| Type| Mandatory| Description| 1395| -------- | ------------------------- | -- | --------- | 1396| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1397 1398**Error codes** 1399 1400For details about the error codes, see [Window Error Codes](errorcode-window.md). 1401 1402| ID| Error Message| 1403| ------- | ------------------------------ | 1404| 1300002 | This window state is abnormal. | 1405 1406**Example** 1407 1408```ts 1409import { BusinessError } from '@kit.BasicServicesKit'; 1410 1411windowClass.showWindow((err: BusinessError) => { 1412 const errCode: number = err.code; 1413 if (errCode) { 1414 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1415 return; 1416 } 1417 console.info('Succeeded in showing the window.'); 1418}); 1419``` 1420 1421### showWindow<sup>9+</sup> 1422 1423showWindow(): Promise<void> 1424 1425Shows this window. This API uses a promise to return the result. This API takes effect only for a system window or an application child window. For the main window of an application, this API moves it at the top when the main window is already displayed. 1426 1427**System capability**: SystemCapability.WindowManager.WindowManager.Core 1428 1429**Atomic service API**: This API can be used in atomic services since API version 11. 1430 1431**Return value** 1432 1433| Type| Description| 1434| ------------------- | ----------------------- | 1435| Promise<void> | Promise that returns no value.| 1436 1437**Error codes** 1438 1439For details about the error codes, see [Window Error Codes](errorcode-window.md). 1440 1441| ID| Error Message| 1442| ------- | ------------------------------ | 1443| 1300002 | This window state is abnormal. | 1444 1445**Example** 1446 1447```ts 1448import { BusinessError } from '@kit.BasicServicesKit'; 1449 1450let promise = windowClass.showWindow(); 1451promise.then(() => { 1452 console.info('Succeeded in showing the window.'); 1453}).catch((err: BusinessError) => { 1454 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1455}); 1456``` 1457 1458### destroyWindow<sup>9+</sup> 1459 1460destroyWindow(callback: AsyncCallback<void>): void 1461 1462Destroys this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application child window. 1463 1464**System capability**: SystemCapability.WindowManager.WindowManager.Core 1465 1466**Atomic service API**: This API can be used in atomic services since API version 11. 1467 1468**Parameters** 1469 1470| Name| Type| Mandatory| Description| 1471| -------- | ------------------------- | -- | --------- | 1472| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1473 1474**Error codes** 1475 1476For details about the error codes, see [Window Error Codes](errorcode-window.md). 1477 1478| ID| Error Message| 1479| ------- | -------------------------------------------- | 1480| 1300002 | This window state is abnormal. | 1481| 1300003 | This window manager service works abnormally. | 1482 1483**Example** 1484 1485```ts 1486import { BusinessError } from '@kit.BasicServicesKit'; 1487 1488windowClass.destroyWindow((err) => { 1489 const errCode: number = err.code; 1490 if (errCode) { 1491 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 1492 return; 1493 } 1494 console.info('Succeeded in destroying the window.'); 1495}); 1496``` 1497 1498### destroyWindow<sup>9+</sup> 1499 1500destroyWindow(): Promise<void> 1501 1502Destroys this window. This API uses a promise to return the result. This API takes effect only for a system window or an application child window. 1503 1504**System capability**: SystemCapability.WindowManager.WindowManager.Core 1505 1506**Atomic service API**: This API can be used in atomic services since API version 11. 1507 1508**Return value** 1509 1510| Type| Description| 1511| ------------------- | ------------------------ | 1512| Promise<void> | Promise that returns no value.| 1513 1514**Error codes** 1515 1516For details about the error codes, see [Window Error Codes](errorcode-window.md). 1517 1518| ID| Error Message| 1519| ------- | -------------------------------------------- | 1520| 1300002 | This window state is abnormal. | 1521| 1300003 | This window manager service works abnormally. | 1522 1523**Example** 1524 1525```ts 1526import { BusinessError } from '@kit.BasicServicesKit'; 1527 1528let promise = windowClass.destroyWindow(); 1529promise.then(() => { 1530 console.info('Succeeded in destroying the window.'); 1531}).catch((err: BusinessError) => { 1532 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 1533}); 1534``` 1535 1536### moveWindowTo<sup>9+</sup> 1537 1538moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void 1539 1540Moves this window. This API uses an asynchronous callback to return the result. 1541 1542<!--RP4--> 1543In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 1544 1545On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 1546 1547**System capability**: SystemCapability.WindowManager.WindowManager.Core 1548 1549**Atomic service API**: This API can be used in atomic services since API version 11. 1550 1551**Parameters** 1552 1553| Name| Type| Mandatory| Description| 1554| -------- | ------------------------- | -- | --------------------------------------------- | 1555| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1556| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1557| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 1558 1559**Error codes** 1560 1561For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1562 1563| ID| Error Message| 1564| ------- | -------------------------------------------- | 1565| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1566| 1300002 | This window state is abnormal. | 1567| 1300003 | This window manager service works abnormally. | 1568 1569**Example** 1570 1571```ts 1572import { BusinessError } from '@kit.BasicServicesKit'; 1573 1574try { 1575 windowClass.moveWindowTo(300, 300, (err: BusinessError) => { 1576 const errCode: number = err.code; 1577 if (errCode) { 1578 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1579 return; 1580 } 1581 console.info('Succeeded in moving the window.'); 1582 }); 1583} catch (exception) { 1584 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1585} 1586``` 1587 1588### moveWindowTo<sup>9+</sup> 1589 1590moveWindowTo(x: number, y: number): Promise<void> 1591 1592Moves 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). 1593 1594<!--RP4--> 1595In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 1596 1597On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 1598 1599**System capability**: SystemCapability.WindowManager.WindowManager.Core 1600 1601**Atomic service API**: This API can be used in atomic services since API version 11. 1602 1603**Parameters** 1604 1605| Name| Type| Mandatory| Description| 1606| -- | ----- | -- | --------------------------------------------- | 1607| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1608| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1609 1610**Return value** 1611 1612| Type| Description| 1613| ------------------- | ------------------------ | 1614| Promise<void> | Promise that returns no value.| 1615 1616**Error codes** 1617 1618For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1619 1620| ID| Error Message| 1621| ------- | -------------------------------------------- | 1622| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1623| 1300002 | This window state is abnormal. | 1624| 1300003 | This window manager service works abnormally. | 1625 1626**Example** 1627 1628```ts 1629import { BusinessError } from '@kit.BasicServicesKit'; 1630 1631try { 1632 let promise = windowClass.moveWindowTo(300, 300); 1633 promise.then(() => { 1634 console.info('Succeeded in moving the window.'); 1635 }).catch((err: BusinessError) => { 1636 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1637 }); 1638} catch (exception) { 1639 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1640} 1641``` 1642 1643### moveWindowToAsync<sup>12+</sup> 1644 1645moveWindowToAsync(x: number, y: number): Promise<void> 1646 1647Moves this window. This API uses a promise to return the result. 1648 1649A 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. 1650 1651This API takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). 1652 1653On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 1654 1655**System capability**: SystemCapability.Window.SessionManager 1656 1657**Atomic service API**: This API can be used in atomic services since API version 12. 1658 1659**Parameters** 1660 1661| Name| Type| Mandatory| Description| 1662| -- | ----- | -- | --------------------------------------------- | 1663| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1664| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1665 1666**Return value** 1667 1668| Type| Description| 1669| ------------------- | ------------------------ | 1670| Promise<void> | Promise that returns no value.| 1671 1672**Error codes** 1673 1674For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1675 1676| ID| Error Message| 1677| ------- | -------------------------------------------- | 1678| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1679| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1680| 1300002 | This window state is abnormal. | 1681| 1300003 | This window manager service works abnormally. | 1682| 1300010 | The operation in the current window status is invalid. | 1683 1684**Example** 1685 1686```ts 1687import { BusinessError } from '@kit.BasicServicesKit'; 1688 1689try { 1690 let promise = windowClass.moveWindowToAsync(300, 300); 1691 promise.then(() => { 1692 console.info('Succeeded in moving the window.'); 1693 let rect = windowClass?.getWindowProperties().windowRect; 1694 console.info(`Get window rect: ` + JSON.stringify(rect)); 1695 }).catch((err: BusinessError) => { 1696 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1697 }); 1698} catch (exception) { 1699 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1700} 1701``` 1702 1703### moveWindowToAsync<sup>15+</sup> 1704 1705moveWindowToAsync(x: number, y: number, moveConfiguration?: MoveConfiguration): Promise<void> 1706 1707Moves this window to an existing display (specified by **displayId** in **moveConfiguration**). This API uses a promise to return the result. A value is returned once the call takes effect. You can use **getWindowProperties** in the callback (see the code snippet below) to obtain the final effect immediately. 1708 1709This API takes effect only in floating window mode (**window.WindowStatusType.FLOATING** mode). 1710 1711On 2-in-1 devices, the window moves relative to the display. On other devices, the window moves relative to the parent window. 1712 1713**System capability**: SystemCapability.Window.SessionManager 1714 1715**Atomic service API**: This API can be used in atomic services since API version 15. 1716 1717**Parameters** 1718 1719| Name| Type| Mandatory| Description| 1720| -- | ----- | -- | --------------------------------------------- | 1721| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1722| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1723| moveConfiguration | [MoveConfiguration](#moveconfiguration15) | No| Window movement configuration. If this parameter is not set, the window will stay on the current display.| 1724 1725**Return value** 1726 1727| Type| Description| 1728| ------------------- | ------------------------ | 1729| Promise<void> | Promise that returns no value.| 1730 1731**Error codes** 1732 1733For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1734 1735| ID| Error Message| 1736| ------- | -------------------------------------------- | 1737| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1738| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1739| 1300002 | This window state is abnormal. | 1740| 1300003 | This window manager service works abnormally. | 1741| 1300010 | The operation in the current window status is invalid. | 1742 1743**Example** 1744 1745```ts 1746import { window } from '@kit.ArkUI'; 1747import { BusinessError } from '@kit.BasicServicesKit'; 1748 1749try { 1750 let moveConfiguration: window.MoveConfiguration = { 1751 displayId: 0 1752 }; 1753 let promise = windowClass.moveWindowToAsync(300, 300, moveConfiguration); 1754 promise.then(() => { 1755 console.info('Succeeded in moving the window.'); 1756 let rect = windowClass?.getWindowProperties().windowRect; 1757 console.info(`Get window rect: ` + JSON.stringify(rect)); 1758 }).catch((err: BusinessError) => { 1759 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1760 }); 1761} catch (exception) { 1762 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1763} 1764``` 1765 1766### moveWindowToGlobal<sup>13+</sup> 1767 1768moveWindowToGlobal(x: number, y: number): Promise<void> 1769 1770Moves this window based on the coordinates. This API uses a promise to return the result. A value is returned once the call takes effect. 1771 1772This operation is not supported in a window in full-screen mode. 1773 1774On non-2-in-1 devices, the child window moves along with the main window. 1775 1776**System capability**: SystemCapability.Window.SessionManager 1777 1778**Atomic service API**: This API can be used in atomic services since API version 13. 1779 1780**Parameters** 1781 1782| Name| Type| Mandatory| Description| 1783| -- | ----- | -- | --------------------------------------------- | 1784| x | number | Yes| Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1785| y | number | Yes| Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1786 1787**Return value** 1788 1789| Type| Description| 1790| ------------------- | ------------------------ | 1791| Promise<void> | Promise that returns no value.| 1792 1793**Error codes** 1794 1795For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1796 1797| ID| Error Message| 1798| ------- | -------------------------------------------- | 1799| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1800| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1801| 1300002 | This window state is abnormal. | 1802| 1300003 | This window manager service works abnormally. | 1803| 1300010 | The operation in the current window status is invalid. | 1804 1805**Example** 1806 1807```ts 1808import { BusinessError } from '@kit.BasicServicesKit'; 1809 1810try { 1811 let promise = windowClass.moveWindowToGlobal(300, 300); 1812 promise.then(() => { 1813 console.info('Succeeded in moving the window.'); 1814 }).catch((err: BusinessError) => { 1815 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1816 }); 1817} catch (exception) { 1818 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1819} 1820``` 1821 1822### moveWindowToGlobal<sup>15+</sup> 1823 1824moveWindowToGlobal(x: number, y: number, moveConfiguration?: MoveConfiguration): Promise<void> 1825 1826Moves this window to an existing display (specified by **displayId** in **moveConfiguration**) based on the coordinates. This API uses a promise to return the result. A value is returned once the call takes effect. 1827 1828This operation is not supported in a window in full-screen mode. 1829 1830On non-2-in-1 devices, the child window moves along with the main window. 1831 1832**System capability**: SystemCapability.Window.SessionManager 1833 1834**Atomic service API**: This API can be used in atomic services since API version 15. 1835 1836**Parameters** 1837 1838| Name| Type| Mandatory| Description| 1839| -- | ----- | -- | --------------------------------------------- | 1840| x | number | Yes| Distance that the window moves along the x-axis, in px, with the upper left corner of the target display used as the origin. A positive value indicates that the window moves to the right, and a negative value indicates that the window moves to the left. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1841| y | number | Yes| Distance that the window moves along the y-axis, in px, with the upper left corner of the target display used as the origin. A positive value indicates that the window moves downwards, and a negative value indicates that the window moves upwards. The value must be an integer. If a non-integer is passed in, the value is rounded down.| 1842| moveConfiguration | [MoveConfiguration](#moveconfiguration15) | No| Window movement configuration. If this parameter is not set, the window will stay on the current display.| 1843 1844**Return value** 1845 1846| Type| Description| 1847| ------------------- | ------------------------ | 1848| Promise<void> | Promise that returns no value.| 1849 1850**Error codes** 1851 1852For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1853 1854| ID| Error Message| 1855| ------- | -------------------------------------------- | 1856| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1857| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1858| 1300002 | This window state is abnormal. | 1859| 1300003 | This window manager service works abnormally. | 1860| 1300010 | The operation in the current window status is invalid. | 1861 1862**Example** 1863 1864```ts 1865import { window } from '@kit.ArkUI'; 1866import { BusinessError } from '@kit.BasicServicesKit'; 1867 1868try { 1869 let moveConfiguration: window.MoveConfiguration = { 1870 displayId: 0 1871 }; 1872 let promise = windowClass.moveWindowToGlobal(300, 300, moveConfiguration); 1873 promise.then(() => { 1874 console.info('Succeeded in moving the window.'); 1875 }).catch((err: BusinessError) => { 1876 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1877 }); 1878} catch (exception) { 1879 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1880} 1881``` 1882 1883### resize<sup>9+</sup> 1884 1885resize(width: number, height: number, callback: AsyncCallback<void>): void 1886 1887Changes the size of this window. This API uses an asynchronous callback to return the result. 1888 1889The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1890 1891The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1892 1893The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 1894 1895The window width and height you set must meet the limits. The rules are as follows: 1896- 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. 1897- 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. 1898 1899This operation is not supported in a window in full-screen mode. 1900 1901**System capability**: SystemCapability.WindowManager.WindowManager.Core 1902 1903**Atomic service API**: This API can be used in atomic services since API version 11. 1904 1905**Parameters** 1906 1907| Name| Type| Mandatory| Description| 1908| -------- | ------------------------- | -- | ------------------------ | 1909| 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.| 1910| 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.| 1911| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 1912 1913**Error codes** 1914 1915For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1916 1917| ID| Error Message| 1918| ------- | -------------------------------------------- | 1919| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1920| 1300002 | This window state is abnormal. | 1921| 1300003 | This window manager service works abnormally. | 1922 1923**Example** 1924 1925```ts 1926import { BusinessError } from '@kit.BasicServicesKit'; 1927 1928try { 1929 windowClass.resize(500, 1000, (err: BusinessError) => { 1930 const errCode: number = err.code; 1931 if (errCode) { 1932 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 1933 return; 1934 } 1935 console.info('Succeeded in changing the window size.'); 1936 }); 1937} catch (exception) { 1938 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 1939} 1940``` 1941 1942### resize<sup>9+</sup> 1943 1944resize(width: number, height: number): Promise<void> 1945 1946Changes the size of this window. This API uses a promise to return the result. 1947 1948A 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). 1949 1950The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1951 1952The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1953 1954The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 1955 1956The window width and height you set must meet the limits. The rules are as follows: 1957- 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. 1958- 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. 1959 1960This operation is not supported in a window in full-screen mode. 1961 1962**System capability**: SystemCapability.WindowManager.WindowManager.Core 1963 1964**Atomic service API**: This API can be used in atomic services since API version 11. 1965 1966**Parameters** 1967 1968| Name| Type| Mandatory| Description| 1969| ------ | ------ | -- | ------------------------ | 1970| 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.| 1971| 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.| 1972 1973**Return value** 1974 1975| Type| Description| 1976| ------------------- | ------------------------ | 1977| Promise<void> | Promise that returns no value.| 1978 1979**Error codes** 1980 1981For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1982 1983| ID| Error Message| 1984| ------- | -------------------------------------------- | 1985| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1986| 1300002 | This window state is abnormal. | 1987| 1300003 | This window manager service works abnormally. | 1988 1989**Example** 1990 1991```ts 1992import { BusinessError } from '@kit.BasicServicesKit'; 1993 1994try { 1995 let promise = windowClass.resize(500, 1000); 1996 promise.then(() => { 1997 console.info('Succeeded in changing the window size.'); 1998 }).catch((err: BusinessError) => { 1999 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 2000 }); 2001} catch (exception) { 2002 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 2003} 2004``` 2005 2006### resizeAsync<sup>12+</sup> 2007 2008resizeAsync(width: number, height: number): Promise<void> 2009 2010Changes the size of this window. This API uses a promise to return the result. 2011 2012A 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. 2013 2014The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 2015 2016The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 2017 2018The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 2019 2020The window width and height you set must meet the limits. The rules are as follows: 2021 2022- 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. 2023- 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. 2024 2025This operation is not supported in a window in full-screen mode. 2026 2027**System capability**: SystemCapability.Window.SessionManager 2028 2029**Atomic service API**: This API can be used in atomic services since API version 12. 2030 2031**Parameters** 2032 2033| Name| Type| Mandatory| Description| 2034| ------ | ------ | -- | ------------------------ | 2035| 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.| 2036| 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.| 2037 2038**Return value** 2039 2040| Type| Description| 2041| ------------------- | ------------------------ | 2042| Promise<void> | Promise that returns no value.| 2043 2044**Error codes** 2045 2046For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2047 2048| ID| Error Message| 2049| ------- | -------------------------------------------- | 2050| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2051| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2052| 1300002 | This window state is abnormal. | 2053| 1300003 | This window manager service works abnormally. | 2054| 1300010 | The operation in the current window status is invalid. | 2055 2056**Example** 2057 2058```ts 2059import { BusinessError } from '@kit.BasicServicesKit'; 2060 2061try { 2062 let promise = windowClass.resizeAsync(500, 1000); 2063 promise.then(() => { 2064 console.info('Succeeded in changing the window size.'); 2065 let rect = windowClass?.getWindowProperties().windowRect; 2066 console.info(`Get window rect: ` + JSON.stringify(rect)); 2067 }).catch((err: BusinessError) => { 2068 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 2069 }); 2070} catch (exception) { 2071 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 2072} 2073``` 2074 2075### getWindowProperties<sup>9+</sup> 2076 2077getWindowProperties(): WindowProperties 2078 2079Obtains the properties of this window. 2080 2081**System capability**: SystemCapability.WindowManager.WindowManager.Core 2082 2083**Atomic service API**: This API can be used in atomic services since API version 11. 2084 2085**Return value** 2086 2087| Type| Description| 2088| ------------------------------------- | ------------- | 2089| [WindowProperties](#windowproperties) | Window properties obtained.| 2090 2091**Error codes** 2092 2093For details about the error codes, see [Window Error Codes](errorcode-window.md). 2094 2095| ID| Error Message| 2096| ------- | ------------------------------ | 2097| 1300002 | This window state is abnormal. | 2098 2099**Example** 2100 2101```ts 2102try { 2103 let properties = windowClass.getWindowProperties(); 2104} catch (exception) { 2105 console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`); 2106} 2107``` 2108 2109### getWindowDensityInfo<sup>15+</sup> 2110 2111getWindowDensityInfo(): WindowDensityInfo 2112 2113Obtains the display density information of this window. 2114 2115**System capability**: SystemCapability.Window.SessionManager 2116 2117**Atomic service API**: This API can be used in atomic services since API version 15. 2118 2119**Return value** 2120 2121| Type| Description| 2122| ------------------------------------- | ------------- | 2123| [WindowDensityInfo](#windowdensityinfo15) | Display density information of the window.| 2124 2125**Error codes** 2126 2127For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2128 2129| ID| Error Message| 2130| ------- | ------------------------------ | 2131| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2132| 1300002 | This window state is abnormal. | 2133 2134**Example** 2135 2136```ts 2137try { 2138 let densityInfo = windowClass.getWindowDensityInfo(); 2139} catch (exception) { 2140 console.error(`Failed to obtain the window densityInfo. Cause code: ${exception.code}, message: ${exception.message}`); 2141} 2142``` 2143 2144### getGlobalRect<sup>13+</sup> 2145 2146getGlobalRect(): Rect 2147 2148Obtains the actual display area of this window on the screen. This API returns the result synchronously. 2149 2150This API can determine the actual on-screen location and size of a window that has been resized on certain devices. 2151 2152**System capability**: SystemCapability.Window.SessionManager 2153 2154**Atomic service API**: This API can be used in atomic services since API version 13. 2155 2156**Return value** 2157 2158| Type| Description| 2159| ------------------- | ------------------------ | 2160| [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.| 2161 2162**Error codes** 2163 2164For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2165 2166| ID| Error Message| 2167| ------- | -------------------------------------------- | 2168| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2169| 1300002 | This window state is abnormal. | 2170| 1300003 | This window manager service works abnormally. | 2171 2172**Example** 2173 2174```ts 2175try { 2176 let rect = windowClass.getGlobalRect(); 2177 console.info(`Succeeded in getting window rect: ` + JSON.stringify(rect)); 2178} catch (exception) { 2179 console.error(`Failed to get window rect. Cause code: ${exception.code}, message: ${exception.message}`); 2180} 2181``` 2182 2183### getWindowAvoidArea<sup>9+</sup> 2184 2185getWindowAvoidArea(type: AvoidAreaType): AvoidArea 2186 2187Obtains the avoid area of this application window, for example, the system bar area, notch, gesture area, and soft keyboard area. 2188 2189This 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. 2190 2191**System capability**: SystemCapability.WindowManager.WindowManager.Core 2192 2193**Atomic service API**: This API can be used in atomic services since API version 11. 2194 2195**Parameters** 2196 2197| Name| Type| Mandatory| Description| 2198| ---- |----------------------------------| -- | ------------------------------------------------------------ | 2199| type | [AvoidAreaType](#avoidareatype7) | Yes| Type of the area.| 2200 2201**Return value** 2202 2203| Type| Description| 2204|--------------------------| ----------------- | 2205| [AvoidArea](#avoidarea7) | Area where the window cannot be displayed.| 2206 2207**Error codes** 2208 2209For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2210 2211| ID| Error Message| 2212| ------- | ------------------------------ | 2213| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2214| 1300002 | This window state is abnormal. | 2215 2216**Example** 2217 2218```ts 2219let type = window.AvoidAreaType.TYPE_SYSTEM; 2220try { 2221 let avoidArea = windowClass.getWindowAvoidArea(type); 2222} catch (exception) { 2223 console.error(`Failed to obtain the area. Cause code: ${exception.code}, message: ${exception.message}`); 2224} 2225``` 2226 2227### setTitleAndDockHoverShown<sup>14+</sup> 2228 2229setTitleAndDockHoverShown(isTitleHoverShown?: boolean, isDockHoverShown?: boolean): Promise<void> 2230 2231Sets 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. 2232 2233**System capability**: SystemCapability.Window.SessionManager 2234 2235**Atomic service API**: This API can be used in atomic services since API version 14. 2236 2237**Parameters** 2238 2239| Name | Type | Mandatory| Description | 2240| ---------- | ------- | ---- | ------------------------------------------------------------ | 2241| 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**.| 2242| 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**.| 2243 2244**Error codes** 2245 2246For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2247 2248| ID| Error Message| 2249| ------- | -------------------------------------------- | 2250| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2251| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2252| 1300002 | This window state is abnormal. | 2253| 1300004 | Unauthorized operation. | 2254 2255**Example** 2256 2257```ts 2258// EntryAbility.ets 2259import { UIAbility } from '@kit.AbilityKit'; 2260import { BusinessError } from '@kit.BasicServicesKit'; 2261import { window } from '@kit.ArkUI'; 2262 2263export default class EntryAbility extends UIAbility { 2264 // ... 2265 onWindowStageCreate(windowStage: window.WindowStage): void { 2266 // Load the page corresponding to the main window. 2267 windowStage.loadContent('pages/Index', (err) => { 2268 let mainWindow: window.Window | undefined = undefined; 2269 // Obtain the main window. 2270 windowStage.getMainWindow().then( 2271 data => { 2272 mainWindow = data; 2273 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 2274 // Call maximize to enable the full-screen mode for the window. 2275 mainWindow.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 2276 // Call setTitleAndDockHoverShown to hide the window title bar and dock bar. 2277 mainWindow.setTitleAndDockHoverShown(false, false); 2278 } 2279 ).catch((err: BusinessError) => { 2280 if(err.code){ 2281 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2282 } 2283 }); 2284 }); 2285 } 2286} 2287``` 2288 2289### setWindowLayoutFullScreen<sup>9+</sup> 2290 2291setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 2292 2293Sets whether the main window layout or the child window layout is immersive. This API uses a promise to return the result. <!--RP8-->From API version 14, this API does not take effect on 2-in-1 devices.<!--RP8End--> 2294- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 2295- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 2296 2297**System capability**: SystemCapability.WindowManager.WindowManager.Core 2298 2299**Atomic service API**: This API can be used in atomic services since API version 12. 2300 2301**Parameters** 2302 2303| Name| Type| Mandatory| Description| 2304| ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ | 2305| 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.| 2306 2307**Return value** 2308 2309| Type| Description| 2310| ------------------- | ------------------------ | 2311| Promise<void> | Promise that returns no value.| 2312 2313**Error codes** 2314 2315For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2316 2317| ID| Error Message| 2318| ------- | -------------------------------------------- | 2319| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2320| 1300002 | This window state is abnormal. | 2321| 1300003 | This window manager service works abnormally. | 2322 2323**Example** 2324 2325```ts 2326// EntryAbility.ets 2327import { UIAbility } from '@kit.AbilityKit'; 2328import { BusinessError } from '@kit.BasicServicesKit'; 2329 2330export default class EntryAbility extends UIAbility { 2331 // ... 2332 onWindowStageCreate(windowStage: window.WindowStage): void { 2333 console.info('onWindowStageCreate'); 2334 let windowClass: window.Window | undefined = undefined; 2335 windowStage.getMainWindow((err: BusinessError, data) => { 2336 const errCode: number = err.code; 2337 if (errCode) { 2338 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2339 return; 2340 } 2341 windowClass = data; 2342 let isLayoutFullScreen = true; 2343 try { 2344 let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen); 2345 promise.then(() => { 2346 console.info('Succeeded in setting the window layout to full-screen mode.'); 2347 }).catch((err: BusinessError) => { 2348 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 2349 }); 2350 } catch (exception) { 2351 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 2352 } 2353 }); 2354 } 2355} 2356``` 2357 2358### setImmersiveModeEnabledState<sup>12+</sup> 2359 2360setImmersiveModeEnabledState(enabled: boolean): void 2361 2362Sets 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--> 2363 2364**System capability**: SystemCapability.WindowManager.WindowManager.Core 2365 2366**Atomic service API**: This API can be used in atomic services since API version 12. 2367 2368**Parameters** 2369 2370| Name | Type | Mandatory| Description | 2371| ---------- | ------- | ---- | ------------------------------------------------------------ | 2372| enabled | boolean | Yes | Whether to enable the immersive layout.<br>The value **true** means to enable the immersive layout, and **false** means the opposite.| 2373 2374**Error codes** 2375 2376For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2377 2378| ID| Error Message| 2379| ------- | -------------------------------------------- | 2380| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2381| 1300002 | This window state is abnormal. | 2382| 1300003 | This window manager service works abnormally. | 2383| 1300004 | Unauthorized operation. | 2384 2385**Example** 2386 2387```ts 2388try { 2389 let enabled = false; 2390 windowClass.setImmersiveModeEnabledState(enabled); 2391} catch (exception) { 2392 console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 2393} 2394``` 2395 2396### getImmersiveModeEnabledState<sup>12+</sup> 2397 2398getImmersiveModeEnabledState(): boolean 2399 2400Checks whether the immersive layout is enabled for this window. 2401 2402**System capability**: SystemCapability.WindowManager.WindowManager.Core 2403 2404**Atomic service API**: This API can be used in atomic services since API version 12. 2405 2406**Return value** 2407| Type | Description | 2408| ------- | ------------------------------------------------------------------------------------ | 2409| 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.| 2410 2411**Error codes** 2412 2413For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2414 2415| ID| Error Message| 2416| -------- | -------------------------------------------- | 2417| 1300002 | This window state is abnormal. | 2418| 1300003 | This window manager service works abnormally. | 2419| 1300004 | Unauthorized operation. | 2420 2421**Example** 2422 2423```ts 2424try { 2425 let isEnabled = windowClass.getImmersiveModeEnabledState(); 2426} catch (exception) { 2427 console.error(`Failed to get the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 2428} 2429``` 2430 2431### setWindowSystemBarEnable<sup>9+</sup> 2432 2433setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 2434 2435Sets 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--> 2436 2437The 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 child window. 2438 2439**Atomic service API**: This API can be used in atomic services since API version 12. 2440 2441**System capability**: SystemCapability.WindowManager.WindowManager.Core 2442 2443**Parameters** 2444 2445| Name| Type | Mandatory| Description| 2446| ----- | ---------------------------- | -- | --------------------------------- | 2447| 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.| 2448 2449**Return value** 2450 2451| Type| Description| 2452| ------------------- | ------------------------ | 2453| Promise<void> | Promise that returns no value.| 2454 2455**Error codes** 2456 2457For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2458 2459| ID| Error Message| 2460| ------- | -------------------------------------------- | 2461| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2462| 1300002 | This window state is abnormal. | 2463| 1300003 | This window manager service works abnormally. | 2464 2465**Example** 2466 2467```ts 2468// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 2469// EntryAbility.ets 2470import { UIAbility } from '@kit.AbilityKit'; 2471import { BusinessError } from '@kit.BasicServicesKit'; 2472 2473export default class EntryAbility extends UIAbility { 2474 // ... 2475 onWindowStageCreate(windowStage: window.WindowStage): void { 2476 console.info('onWindowStageCreate'); 2477 let windowClass: window.Window | undefined = undefined; 2478 windowStage.getMainWindow((err: BusinessError, data) => { 2479 const errCode: number = err.code; 2480 if (errCode) { 2481 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2482 return; 2483 } 2484 windowClass = data; 2485 let names: Array<'status' | 'navigation'> = []; 2486 try { 2487 let promise = windowClass.setWindowSystemBarEnable(names); 2488 promise.then(() => { 2489 console.info('Succeeded in setting the system bar to be invisible.'); 2490 }).catch((err: BusinessError) => { 2491 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 2492 }); 2493 } catch (exception) { 2494 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 2495 } 2496 }); 2497 } 2498} 2499``` 2500 2501### setSpecificSystemBarEnabled<sup>11+</sup> 2502 2503setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void> 2504 2505Sets 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--> 2506 2507The 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 child window. 2508 2509**System capability**: SystemCapability.Window.SessionManager 2510 2511**Atomic service API**: This API can be used in atomic services since API version 11. 2512 2513**Parameters** 2514 2515| Name| Type | Mandatory| Description| 2516| ----- | ---------------------------- | -- | --------------------------------- | 2517| name | [SpecificSystemBar](#specificsystembar11) | Yes| Type of the system bar to be shown or hidden.| 2518| 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.| 2519| 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**.| 2520 2521**Return value** 2522 2523| Type| Description| 2524| ------------------- | ------------------------ | 2525| Promise<void> | Promise that returns no value.| 2526 2527**Error codes** 2528 2529For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2530 2531| ID| Error Message| 2532| ------- | -------------------------------------------- | 2533| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2534| 1300002 | This window state is abnormal. | 2535| 1300003 | This window manager service works abnormally. | 2536 2537**Example** 2538 2539```ts 2540// Hide the bottom navigation bar. 2541// EntryAbility.ets 2542import { UIAbility } from '@kit.AbilityKit'; 2543import { BusinessError } from '@kit.BasicServicesKit'; 2544 2545export default class EntryAbility extends UIAbility { 2546 // ... 2547 onWindowStageCreate(windowStage: window.WindowStage): void { 2548 console.info('onWindowStageCreate'); 2549 let windowClass: window.Window | undefined = undefined; 2550 windowStage.getMainWindow((err: BusinessError, data) => { 2551 const errCode: number = err.code; 2552 if (errCode) { 2553 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2554 return; 2555 } 2556 windowClass = data; 2557 try { 2558 let promise = windowClass.setSpecificSystemBarEnabled('navigationIndicator', false); 2559 promise.then(() => { 2560 console.info('Succeeded in setting the system bar to be invisible.'); 2561 }).catch((err: BusinessError) => { 2562 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 2563 }); 2564 } catch (exception) { 2565 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 2566 } 2567 }); 2568 } 2569} 2570``` 2571 2572### setWindowSystemBarProperties<sup>9+</sup> 2573 2574setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 2575 2576Sets 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--> 2577 2578This API does not take effect when it is called by a child window. 2579 2580**System capability**: SystemCapability.WindowManager.WindowManager.Core 2581 2582**Atomic service API**: This API can be used in atomic services since API version 12. 2583 2584**Parameters** 2585 2586| Name | Type | Mandatory| Description | 2587| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2588| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.| 2589 2590**Return value** 2591 2592| Type | Description | 2593| ------------------- | ------------------------- | 2594| Promise<void> | Promise that returns no value.| 2595 2596**Error codes** 2597 2598For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2599 2600| ID| Error Message| 2601| ------- | -------------------------------------------- | 2602| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2603| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2604| 1300002 | This window state is abnormal. | 2605| 1300003 | This window manager service works abnormally. | 2606 2607**Example** 2608 2609```ts 2610// EntryAbility.ets 2611import { UIAbility } from '@kit.AbilityKit'; 2612import { BusinessError } from '@kit.BasicServicesKit'; 2613 2614export default class EntryAbility extends UIAbility { 2615 // ... 2616 onWindowStageCreate(windowStage: window.WindowStage): void { 2617 console.info('onWindowStageCreate'); 2618 let windowClass: window.Window | undefined = undefined; 2619 windowStage.getMainWindow((err: BusinessError, data) => { 2620 const errCode: number = err.code; 2621 if (errCode) { 2622 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2623 return; 2624 } 2625 windowClass = data; 2626 let SystemBarProperties: window.SystemBarProperties = { 2627 statusBarColor: '#ff00ff', 2628 navigationBarColor: '#00ff00', 2629 // The following properties are supported since API version 8. 2630 statusBarContentColor: '#ffffff', 2631 navigationBarContentColor: '#00ffff' 2632 }; 2633 try { 2634 let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties); 2635 promise.then(() => { 2636 console.info('Succeeded in setting the system bar properties.'); 2637 }).catch((err: BusinessError) => { 2638 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 2639 }); 2640 } catch (exception) { 2641 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 2642 } 2643 }); 2644 } 2645} 2646``` 2647 2648### getWindowSystemBarProperties<sup>12+</sup> 2649 2650getWindowSystemBarProperties(): SystemBarProperties 2651 2652Obtains the properties of the three-button navigation bar and status bar of the main window. 2653 2654**System capability**: SystemCapability.WindowManager.WindowManager.Core 2655 2656**Atomic service API**: This API can be used in atomic services since API version 12. 2657 2658**Return value** 2659 2660| Type| Description| 2661| ------------------------------------- | ------------- | 2662| [SystemBarProperties](#systembarproperties) | Properties of the three-button navigation bar and status bar.| 2663 2664**Error codes** 2665 2666For details about the error codes, see [Window Error Codes](errorcode-window.md). 2667 2668| ID| Error Message| 2669| ------- | ------------------------------ | 2670| 1300002 | This window state is abnormal. | 2671| 1300003 | This window manager service works abnormally. | 2672| 1300004 | Unauthorized operation. | 2673 2674 2675**Example** 2676 2677```ts 2678// EntryAbility.ets 2679import { UIAbility } from '@kit.AbilityKit'; 2680import { BusinessError } from '@kit.BasicServicesKit'; 2681 2682export default class EntryAbility extends UIAbility { 2683 // ... 2684 2685 onWindowStageCreate(windowStage: window.WindowStage) { 2686 let windowClass: window.Window | undefined = undefined; 2687 windowStage.getMainWindow((err: BusinessError, data) => { 2688 const errCode: number = err.code; 2689 if (errCode) { 2690 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2691 return; 2692 } 2693 windowClass = data; 2694 try { 2695 let systemBarProperty = windowClass.getWindowSystemBarProperties(); 2696 console.info('Success in obtaining system bar properties. Property: ' + JSON.stringify(systemBarProperty)); 2697 } catch (err) { 2698 console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`); 2699 } 2700 }); 2701 } 2702}; 2703``` 2704 2705### setPreferredOrientation<sup>9+</sup> 2706 2707setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 2708 2709Sets the preferred orientation for the main window. This API uses an asynchronous callback to return the result. <!--RP9-->This API takes effect only on devices that support rotation with the sensor. It does not take effect on 2-in-1 devices or in the child window mode.<!--RP9End--> 2710 2711**System capability**: SystemCapability.WindowManager.WindowManager.Core 2712 2713**Atomic service API**: This API can be used in atomic services since API version 11. 2714 2715**Parameters** 2716 2717| Name | Type | Mandatory| Description | 2718| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2719| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 2720| 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.| 2721 2722**Error codes** 2723 2724For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2725 2726| ID| Error Message| 2727| ------- | ------------------------------ | 2728| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2729| 1300002 | This window state is abnormal. | 2730 2731**Example** 2732 2733```ts 2734// EntryAbility.ets 2735import { UIAbility } from '@kit.AbilityKit'; 2736import { BusinessError } from '@kit.BasicServicesKit'; 2737 2738export default class EntryAbility extends UIAbility { 2739 // ... 2740 onWindowStageCreate(windowStage: window.WindowStage): void { 2741 console.info('onWindowStageCreate'); 2742 let windowClass: window.Window | undefined = undefined; 2743 windowStage.getMainWindow((err: BusinessError, data) => { 2744 const errCode: number = err.code; 2745 if (errCode) { 2746 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2747 return; 2748 } 2749 windowClass = data; 2750 let orientation = window.Orientation.AUTO_ROTATION; 2751 try { 2752 windowClass.setPreferredOrientation(orientation, (err: BusinessError) => { 2753 const errCode: number = err.code; 2754 if (errCode) { 2755 console.error(`Failed to set window orientation. Cause code: ${err.code}, message: ${err.message}`); 2756 return; 2757 } 2758 console.info('Succeeded in setting window orientation.'); 2759 }); 2760 } catch (exception) { 2761 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2762 } 2763 }); 2764 } 2765} 2766``` 2767 2768### setPreferredOrientation<sup>9+</sup> 2769 2770setPreferredOrientation(orientation: Orientation): Promise<void> 2771 2772Sets the preferred orientation for the main window. This API uses a promise to return the result. <!--RP9-->This API takes effect only on devices that support rotation with the sensor. It does not take effect on 2-in-1 devices or in the child window mode.<!--RP9End--> 2773 2774**System capability**: SystemCapability.WindowManager.WindowManager.Core 2775 2776**Atomic service API**: This API can be used in atomic services since API version 11. 2777 2778**Parameters** 2779 2780| Name | Type | Mandatory| Description | 2781| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2782| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 2783 2784**Return value** 2785 2786| Type | Description | 2787| ------------------- | ------------------------- | 2788| Promise<void> | Promise that returns no value.| 2789 2790**Error codes** 2791 2792For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2793 2794| ID| Error Message| 2795| ------- | ------------------------------ | 2796| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2797| 1300002 | This window state is abnormal. | 2798 2799**Example** 2800 2801```ts 2802// EntryAbility.ets 2803import { UIAbility } from '@kit.AbilityKit'; 2804import { BusinessError } from '@kit.BasicServicesKit'; 2805 2806export default class EntryAbility extends UIAbility { 2807 // ... 2808 onWindowStageCreate(windowStage: window.WindowStage): void { 2809 console.info('onWindowStageCreate'); 2810 let windowClass: window.Window | undefined = undefined; 2811 windowStage.getMainWindow((err: BusinessError, data) => { 2812 const errCode: number = err.code; 2813 if (errCode) { 2814 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2815 return; 2816 } 2817 windowClass = data; 2818 let orientation = window.Orientation.AUTO_ROTATION; 2819 try { 2820 let promise = windowClass.setPreferredOrientation(orientation); 2821 promise.then(() => { 2822 console.info('Succeeded in setting the window orientation.'); 2823 }).catch((err: BusinessError) => { 2824 console.error(`Failed to set the window orientation. Cause code: ${err.code}, message: ${err.message}`); 2825 }); 2826 } catch (exception) { 2827 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2828 } 2829 }); 2830 } 2831} 2832``` 2833 2834### getPreferredOrientation<sup>12+</sup> 2835 2836getPreferredOrientation(): Orientation 2837 2838Obtains the orientation of the main window. This API can be called only by the main window. 2839 2840**System capability**: SystemCapability.WindowManager.WindowManager.Core 2841 2842**Atomic service API**: This API can be used in atomic services since API version 12. 2843 2844**Return value** 2845 2846| Type| Description| 2847|------------------------------| ------------------ | 2848| [Orientation](#orientation9) | Orientation.| 2849 2850**Error codes** 2851 2852For details about the error codes, see [Window Error Codes](errorcode-window.md). 2853 2854| ID| Error Message| 2855| ------- | ------------------------------ | 2856| 1300002 | This window state is abnormal. | 2857 2858**Example** 2859 2860```ts 2861// EntryAbility.ets 2862import { UIAbility } from '@kit.AbilityKit'; 2863import { BusinessError } from '@kit.BasicServicesKit'; 2864export default class EntryAbility extends UIAbility { 2865 // ... 2866 2867 onWindowStageCreate(windowStage: window.WindowStage) { 2868 console.info('onWindowStageCreate'); 2869 let windowClass: window.Window | undefined = undefined; 2870 windowStage.getMainWindow((err: BusinessError, data) => { 2871 const errCode: number = err.code; 2872 if (errCode) { 2873 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2874 return; 2875 } 2876 windowClass = data; 2877 try { 2878 let orientation = windowClass.getPreferredOrientation(); 2879 } catch (exception) { 2880 console.error(`Failed to get window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2881 } 2882 }); 2883 } 2884}; 2885``` 2886 2887### getUIContext<sup>10+</sup> 2888 2889getUIContext(): UIContext 2890 2891Obtain a **UIContext** instance. 2892 2893**Model restriction**: This API can be used only in the stage model. 2894 2895**System capability**: SystemCapability.WindowManager.WindowManager.Core 2896 2897**Atomic service API**: This API can be used in atomic services since API version 11. 2898 2899**Return value** 2900 2901| Type | Description | 2902| ---------- | ---------------------- | 2903| [UIContext](js-apis-arkui-UIContext.md#uicontext) | **UIContext** instance obtained.| 2904 2905**Error codes** 2906 2907For details about the error codes, see [Window Error Codes](errorcode-window.md). 2908 2909| ID| Error Message| 2910| ------- | ------------------------------ | 2911| 1300002 | This window state is abnormal. | 2912 2913**Example** 2914 2915```ts 2916// EntryAbility.ets 2917import { UIAbility } from '@kit.AbilityKit'; 2918import { window, UIContext } from '@kit.ArkUI'; 2919import { BusinessError } from '@kit.BasicServicesKit'; 2920 2921export default class EntryAbility extends UIAbility { 2922 onWindowStageCreate(windowStage: window.WindowStage) { 2923 // Load content for the main window. 2924 windowStage.loadContent("pages/page2", (err: BusinessError) => { 2925 let errCode: number = err.code; 2926 if (errCode) { 2927 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2928 return; 2929 } 2930 console.info('Succeeded in loading the content.'); 2931 // Obtain the main window. 2932 let windowClass: window.Window | undefined = undefined; 2933 windowStage.getMainWindow((err: BusinessError, data) => { 2934 let errCode: number = err.code; 2935 if (errCode) { 2936 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2937 return; 2938 } 2939 windowClass = data; 2940 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 2941 // Obtain a UIContext instance. 2942 let uiContext: UIContext | null = null; 2943 uiContext = windowClass.getUIContext(); 2944 }); 2945 }); 2946 } 2947}; 2948``` 2949 2950### setUIContent<sup>9+</sup> 2951 2952setUIContent(path: string, callback: AsyncCallback<void>): void 2953 2954Loads 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. 2955 2956**System capability**: SystemCapability.WindowManager.WindowManager.Core 2957 2958**Atomic service API**: This API can be used in atomic services since API version 11. 2959 2960**Parameters** 2961 2962| Name| Type| Mandatory| Description| 2963| -------- | ------------------------- | -- | -------------------- | 2964| 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.| 2965| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 2966 2967**Error codes** 2968 2969For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2970 2971| ID| Error Message| 2972| ------- | -------------------------------------------- | 2973| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2974| 1300002 | This window state is abnormal. | 2975| 1300003 | This window manager service works abnormally. | 2976 2977**Example** 2978 2979```ts 2980import { BusinessError } from '@kit.BasicServicesKit'; 2981 2982try { 2983 windowClass.setUIContent('pages/page2/page3', (err: BusinessError) => { 2984 const errCode: number = err.code; 2985 if (errCode) { 2986 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2987 return; 2988 } 2989 console.info('Succeeded in loading the content.'); 2990 }); 2991} catch (exception) { 2992 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2993} 2994``` 2995 2996### setUIContent<sup>9+</sup> 2997 2998setUIContent(path: string): Promise<void> 2999 3000Loads 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. 3001 3002**System capability**: SystemCapability.WindowManager.WindowManager.Core 3003 3004**Atomic service API**: This API can be used in atomic services since API version 11. 3005 3006**Parameters** 3007 3008| Name| Type| Mandatory| Description| 3009| ---- | ------ | -- | ------------------ | 3010| 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.| 3011 3012**Return value** 3013 3014| Type| Description| 3015| ------------------- | ------------------------ | 3016| Promise<void> | Promise that returns no value.| 3017 3018**Error codes** 3019 3020For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3021 3022| ID| Error Message| 3023| ------- | -------------------------------------------- | 3024| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3025| 1300002 | This window state is abnormal. | 3026| 1300003 | This window manager service works abnormally. | 3027 3028**Example** 3029 3030```ts 3031import { BusinessError } from '@kit.BasicServicesKit'; 3032 3033try { 3034 let promise = windowClass.setUIContent('pages/page2/page3'); 3035 promise.then(() => { 3036 console.info('Succeeded in loading the content.'); 3037 }).catch((err: BusinessError) => { 3038 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3039 }); 3040} catch (exception) { 3041 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 3042} 3043``` 3044 3045### loadContent<sup>9+</sup> 3046 3047loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 3048 3049Loads the content of a page, with its path in the current project specified, to this window, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3050 3051**Model restriction**: This API can be used only in the stage model. 3052 3053**System capability**: SystemCapability.WindowManager.WindowManager.Core 3054 3055**Atomic service API**: This API can be used in atomic services since API version 11. 3056 3057**Parameters** 3058 3059| Name | Type | Mandatory| Description | 3060| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 3061| 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.| 3062| 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.| 3063| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 3064 3065**Error codes** 3066 3067For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3068 3069| ID| Error Message| 3070| ------- | -------------------------------------------- | 3071| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3072| 1300002 | This window state is abnormal. | 3073| 1300003 | This window manager service works abnormally. | 3074 3075**Example** 3076 3077```ts 3078import { BusinessError } from '@kit.BasicServicesKit'; 3079 3080let storage: LocalStorage = new LocalStorage(); 3081storage.setOrCreate('storageSimpleProp', 121); 3082windowClass.loadContent('pages/page2', storage, (err: BusinessError) => { 3083 const errCode: number = err.code; 3084 if (errCode) { 3085 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3086 return; 3087 } 3088 console.info('Succeeded in loading the content.'); 3089}); 3090``` 3091 3092### loadContent<sup>9+</sup> 3093 3094loadContent(path: string, storage: LocalStorage): Promise<void> 3095 3096Loads the content of a page, with its path in the current project specified, to this window, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3097 3098**Model restriction**: This API can be used only in the stage model. 3099 3100**System capability**: SystemCapability.WindowManager.WindowManager.Core 3101 3102**Atomic service API**: This API can be used in atomic services since API version 11. 3103 3104**Parameters** 3105 3106| Name | Type | Mandatory| Description | 3107| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 3108| 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.| 3109| 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.| 3110 3111**Return value** 3112 3113| Type | Description | 3114| ------------------- | ------------------------- | 3115| Promise<void> | Promise that returns no value.| 3116 3117**Error codes** 3118 3119For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3120 3121| ID| Error Message| 3122| ------- | -------------------------------------------- | 3123| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3124| 1300002 | This window state is abnormal. | 3125| 1300003 | This window manager service works abnormally. | 3126 3127**Example** 3128 3129```ts 3130import { BusinessError } from '@kit.BasicServicesKit'; 3131 3132let storage: LocalStorage = new LocalStorage(); 3133storage.setOrCreate('storageSimpleProp', 121); 3134let promise = windowClass.loadContent('pages/page2', storage); 3135promise.then(() => { 3136 console.info('Succeeded in loading the content.'); 3137}).catch((err: BusinessError) => { 3138 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3139}); 3140``` 3141 3142### loadContentByName<sup>11+</sup> 3143 3144loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 3145 3146Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3147 3148**Model restriction**: This API can be used only in the stage model. 3149 3150**System capability**: SystemCapability.WindowManager.WindowManager.Core 3151 3152**Atomic service API**: This API can be used in atomic services since API version 11. 3153 3154**Parameters** 3155 3156| Name | Type | Mandatory| Description | 3157| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3158| name | string | Yes | Name of the named route page. | 3159| 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.| 3160| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 3161 3162**Error codes** 3163 3164For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3165 3166| ID| Error Message | 3167| -------- | --------------------------------------------- | 3168| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3169| 1300002 | This window state is abnormal. | 3170| 1300003 | This window manager service works abnormally. | 3171 3172**Example** 3173<!--code_no_check--> 3174```ts 3175import { BusinessError } from '@kit.BasicServicesKit'; 3176import * as Index from '../pages/Index'; // Import the named route page. 3177 3178console.info('onWindowStageCreate'); 3179let storage: LocalStorage = new LocalStorage(); 3180storage.setOrCreate('storageSimpleProp', 121); 3181try { 3182 (windowClass as window.Window).loadContentByName(Index.entryName, storage, (err: BusinessError) => { 3183 const errCode: number = err.code; 3184 if (errCode) { 3185 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3186 return; 3187 } 3188 console.info('Succeeded in loading the content.'); 3189 }); 3190} catch (exception) { 3191 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 3192} 3193``` 3194<!--code_no_check--> 3195```ts 3196// ets/pages/Index.ets 3197export const entryName : string = 'Index'; 3198@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 3199@Component 3200export struct Index { 3201 @State message: string = 'Hello World' 3202 build() { 3203 Row() { 3204 Column() { 3205 Text(this.message) 3206 .fontSize(50) 3207 .fontWeight(FontWeight.Bold) 3208 } 3209 .width('100%') 3210 } 3211 .height('100%') 3212 } 3213} 3214``` 3215 3216### loadContentByName<sup>11+</sup> 3217 3218loadContentByName(name: string, callback: AsyncCallback<void>): void 3219 3220Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3221 3222**Model restriction**: This API can be used only in the stage model. 3223 3224**System capability**: SystemCapability.WindowManager.WindowManager.Core 3225 3226**Atomic service API**: This API can be used in atomic services since API version 11. 3227 3228**Parameters** 3229 3230| Name | Type | Mandatory| Description | 3231| -------- | ------------------------- | ---- | ---------------- | 3232| name | string | Yes | Name of the named route page.| 3233| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 3234 3235**Error codes** 3236 3237For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3238 3239| ID| Error Message | 3240| -------- | --------------------------------------------- | 3241| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3242| 1300002 | This window state is abnormal. | 3243| 1300003 | This window manager service works abnormally. | 3244 3245**Example** 3246<!--code_no_check--> 3247```ts 3248import { BusinessError } from '@kit.BasicServicesKit'; 3249import * as Index from '../pages/Index'; // Import the named route page. 3250 3251try { 3252 (windowClass as window.Window).loadContentByName(Index.entryName, (err: BusinessError) => { 3253 const errCode: number = err.code; 3254 if (errCode) { 3255 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3256 return; 3257 } 3258 console.info('Succeeded in loading the content.'); 3259 }); 3260} catch (exception) { 3261 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 3262} 3263``` 3264<!--code_no_check--> 3265```ts 3266// ets/pages/Index.ets 3267export const entryName : string = 'Index'; 3268@Entry({routeName: entryName}) 3269@Component 3270export struct Index { 3271 @State message: string = 'Hello World' 3272 build() { 3273 Row() { 3274 Column() { 3275 Text(this.message) 3276 .fontSize(50) 3277 .fontWeight(FontWeight.Bold) 3278 } 3279 .width('100%') 3280 } 3281 .height('100%') 3282 } 3283} 3284``` 3285 3286### loadContentByName<sup>11+</sup> 3287 3288loadContentByName(name: string, storage?: LocalStorage): Promise<void> 3289 3290Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 3291 3292**Model restriction**: This API can be used only in the stage model. 3293 3294**System capability**: SystemCapability.WindowManager.WindowManager.Core 3295 3296**Atomic service API**: This API can be used in atomic services since API version 11. 3297 3298**Parameters** 3299 3300| Name | Type | Mandatory| Description | 3301| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3302| name | string | Yes | Name of the named route page. | 3303| 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.| 3304 3305**Return value** 3306 3307| Type | Description | 3308| ------------------- | ------------------------- | 3309| Promise<void> | Promise that returns no value.| 3310 3311**Error codes** 3312 3313For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3314 3315| ID| Error Message | 3316| -------- | --------------------------------------------- | 3317| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 3318| 1300002 | This window state is abnormal. | 3319| 1300003 | This window manager service works abnormally. | 3320 3321**Example** 3322<!--code_no_check--> 3323```ts 3324import { BusinessError } from '@kit.BasicServicesKit'; 3325import * as Index from '../pages/Index'; // Import the named route page. 3326 3327let storage: LocalStorage = new LocalStorage(); 3328storage.setOrCreate('storageSimpleProp', 121); 3329try { 3330 let promise = (windowClass as window.Window).loadContentByName(Index.entryName, storage); 3331 promise.then(() => { 3332 console.info('Succeeded in loading the content.'); 3333 }).catch((err: BusinessError) => { 3334 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 3335 }); 3336} catch (exception) { 3337 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 3338} 3339``` 3340<!--code_no_check--> 3341```ts 3342// ets/pages/Index.ets 3343export const entryName : string = 'Index'; 3344@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 3345@Component 3346export struct Index { 3347 @State message: string = 'Hello World' 3348 build() { 3349 Row() { 3350 Column() { 3351 Text(this.message) 3352 .fontSize(50) 3353 .fontWeight(FontWeight.Bold) 3354 } 3355 .width('100%') 3356 } 3357 .height('100%') 3358 } 3359} 3360``` 3361 3362### isWindowShowing<sup>9+</sup> 3363 3364isWindowShowing(): boolean 3365 3366Checks whether this window is displayed. 3367 3368**System capability**: SystemCapability.WindowManager.WindowManager.Core 3369 3370**Atomic service API**: This API can be used in atomic services since API version 11. 3371 3372**Return value** 3373 3374| Type| Description| 3375| ------- | ------------------------------------------------------------------ | 3376| boolean | Whether the window is displayed. The value **true** means that the window is displayed, and **false** means the opposite.| 3377 3378**Error codes** 3379 3380For details about the error codes, see [Window Error Codes](errorcode-window.md). 3381 3382| ID| Error Message| 3383| ------- | ------------------------------ | 3384| 1300002 | This window state is abnormal. | 3385 3386**Example** 3387 3388```ts 3389try { 3390 let data = windowClass.isWindowShowing(); 3391 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 3392} catch (exception) { 3393 console.error(`Failed to check whether the window is showing. Cause code: ${exception.code}, message: ${exception.message}`); 3394} 3395``` 3396 3397### on('windowSizeChange')<sup>7+</sup> 3398 3399on(type: 'windowSizeChange', callback: Callback<Size>): void 3400 3401Subscribes to the window size change event. 3402 3403**System capability**: SystemCapability.WindowManager.WindowManager.Core 3404 3405**Atomic service API**: This API can be used in atomic services since API version 11. 3406 3407**Parameters** 3408 3409| Name | Type | Mandatory| Description | 3410| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 3411| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 3412| callback | Callback<[Size](#size7)> | Yes | Callback used to return the window size. | 3413 3414**Error codes** 3415 3416For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3417 3418| ID| Error Message| 3419| ------- | -------------------------------------------- | 3420| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3421 3422**Example** 3423 3424```ts 3425try { 3426 windowClass.on('windowSizeChange', (data) => { 3427 console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data)); 3428 }); 3429} catch (exception) { 3430 console.error(`Failed to enable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 3431} 3432``` 3433 3434### off('windowSizeChange')<sup>7+</sup> 3435 3436off(type: 'windowSizeChange', callback?: Callback<Size>): void 3437 3438Unsubscribes from the window size change event. 3439 3440**System capability**: SystemCapability.WindowManager.WindowManager.Core 3441 3442**Atomic service API**: This API can be used in atomic services since API version 11. 3443 3444**Parameters** 3445 3446| Name | Type | Mandatory| Description | 3447| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 3448| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 3449| 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. | 3450 3451**Error codes** 3452 3453For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3454 3455| ID| Error Message| 3456| ------- | -------------------------------------------- | 3457| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3458 3459**Example** 3460 3461```ts 3462const callback = (size: window.Size) => { 3463 // ... 3464} 3465try { 3466 // Enable listening through the on API. 3467 windowClass.on('windowSizeChange', callback); 3468 // Disable the listening of a specified callback. 3469 windowClass.off('windowSizeChange', callback); 3470 // Unregister all the callbacks that have been registered through on(). 3471 windowClass.off('windowSizeChange'); 3472} catch (exception) { 3473 console.error(`Failed to disable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 3474} 3475``` 3476 3477### on('avoidAreaChange')<sup>9+</sup> 3478 3479on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void 3480 3481Subscribes to the event indicating changes to the area where this window cannot be displayed. 3482<!--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--> 3483 3484**System capability**: SystemCapability.WindowManager.WindowManager.Core 3485 3486**Atomic service API**: This API can be used in atomic services since API version 11. 3487 3488**Parameters** 3489 3490| Name | Type | Mandatory| Description | 3491| -------- |----------------------------------| ---- |--------------------------------------| 3492| 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.| 3493| callback | Callback<[AvoidAreaOptions](#avoidareaoptions12)> | Yes | Callback used to return the area and area type.| 3494 3495**Error codes** 3496 3497For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3498 3499| ID| Error Message| 3500| ------- | -------------------------------------------- | 3501| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3502 3503**Example** 3504 3505```ts 3506try { 3507 windowClass.on('avoidAreaChange', (data) => { 3508 console.info('Succeeded in enabling the listener for system avoid area changes. type:' + 3509 JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area)); 3510 }); 3511} catch (exception) { 3512 console.error(`Failed to enable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 3513} 3514``` 3515 3516### off('avoidAreaChange')<sup>9+</sup> 3517 3518off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaOptions>): void 3519 3520Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 3521 3522**System capability**: SystemCapability.WindowManager.WindowManager.Core 3523 3524**Atomic service API**: This API can be used in atomic services since API version 11. 3525 3526**Parameters** 3527 3528| Name | Type | Mandatory| Description | 3529| -------- |----------------------------------|------|------------------------------------| 3530| 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.| 3531| 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.| 3532 3533**Error codes** 3534 3535For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3536 3537| ID| Error Message| 3538| ------- | -------------------------------------------- | 3539| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 3540 3541**Example** 3542 3543```ts 3544interface Param { 3545 type: window.AvoidAreaType, 3546 area: window.AvoidArea 3547} 3548const callback = (data: Param) => { 3549 // ... 3550} 3551try { 3552 windowClass.on('avoidAreaChange', callback); 3553 3554 windowClass.off('avoidAreaChange', callback); 3555 // Unregister all the callbacks that have been registered through on(). 3556 windowClass.off('avoidAreaChange'); 3557} catch (exception) { 3558 console.error(`Failed to enable or disable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 3559} 3560``` 3561 3562### on('keyboardHeightChange')<sup>7+</sup> 3563 3564on(type: 'keyboardHeightChange', callback: Callback<number>): void 3565 3566Subscribes to the event indicating soft keyboard height changes in fixed state. 3567 3568The system notifies the keyboard height change when the soft keyboard is invoked by the window and overlaps with the window. 3569 3570Since 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). 3571 3572**Atomic service API**: This API can be used in atomic services since API version 12. 3573 3574**System capability**: SystemCapability.WindowManager.WindowManager.Core 3575 3576**Parameters** 3577 3578| Name | Type | Mandatory| Description | 3579| -------- | ------------------- | ---- |-------------------------------------------| 3580| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 3581| callback | Callback<number> | Yes | Callback used to return the current keyboard height, which is an integer, in px. | 3582 3583**Error codes** 3584 3585For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3586 3587| ID| Error Message| 3588| ------- | -------------------------------------------- | 3589| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3590 3591**Example** 3592 3593```ts 3594import { BusinessError } from '@kit.BasicServicesKit'; 3595 3596try { 3597 windowClass.on('keyboardHeightChange', (data) => { 3598 console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data)); 3599 }); 3600} catch (exception) { 3601 console.error(`Failed to enable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 3602} 3603``` 3604 3605### off('keyboardHeightChange')<sup>7+</sup> 3606 3607off(type: 'keyboardHeightChange', callback?: Callback<number>): void 3608 3609Unsubscribes from the event indicating soft keyboard height changes in fixed state. 3610 3611Since 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). 3612 3613**Atomic service API**: This API can be used in atomic services since API version 12. 3614 3615**System capability**: SystemCapability.WindowManager.WindowManager.Core 3616 3617**Parameters** 3618 3619| Name | Type | Mandatory| Description | 3620| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3621| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 3622| 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. | 3623 3624**Error codes** 3625 3626For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3627 3628| ID| Error Message| 3629| ------- | -------------------------------------------- | 3630| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3631 3632**Example** 3633 3634```ts 3635import { BusinessError } from '@kit.BasicServicesKit'; 3636 3637const callback = (height: number) => { 3638 // ... 3639} 3640try { 3641 windowClass.on('keyboardHeightChange', callback); 3642 3643 windowClass.off('keyboardHeightChange', callback); 3644 // Unregister all the callbacks that have been registered through on(). 3645 windowClass.off('keyboardHeightChange'); 3646} catch (exception) { 3647 console.error(`Failed to disable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 3648} 3649``` 3650 3651### on('touchOutside')<sup>11+</sup> 3652 3653on(type: 'touchOutside', callback: Callback<void>): void 3654 3655Subscribes to the touch event outside this window. 3656 3657**System capability**: SystemCapability.WindowManager.WindowManager.Core 3658 3659**Atomic service API**: This API can be used in atomic services since API version 11. 3660 3661**Parameters** 3662 3663| Name | Type | Mandatory| Description | 3664| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3665| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 3666| callback | Callback<void> | Yes | Callback used to return the touch event outside this window. | 3667 3668**Error codes** 3669 3670For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3671 3672| ID| Error Message| 3673| ------- | -------------------------------------------- | 3674| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3675 3676**Example** 3677 3678```ts 3679try { 3680 windowClass.on('touchOutside', () => { 3681 console.info('touch outside'); 3682 }); 3683} catch (exception) { 3684 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3685} 3686``` 3687 3688### off('touchOutside')<sup>11+</sup> 3689 3690off(type: 'touchOutside', callback?: Callback<void>): void 3691 3692Unsubscribes from the touch event outside this window. 3693 3694**System capability**: SystemCapability.WindowManager.WindowManager.Core 3695 3696**Atomic service API**: This API can be used in atomic services since API version 11. 3697 3698**Parameters** 3699 3700| Name | Type | Mandatory| Description | 3701| -------- |----------------------| ---- |--------------------------------------| 3702| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 3703| 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. | 3704 3705**Error codes** 3706 3707For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3708 3709| ID| Error Message| 3710| ------- | -------------------------------------------- | 3711| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3712 3713**Example** 3714 3715```ts 3716const callback = () => { 3717 // ... 3718} 3719try { 3720 windowClass.on('touchOutside', callback); 3721 windowClass.off('touchOutside', callback); 3722 // Unregister all the callbacks that have been registered through on(). 3723 windowClass.off('touchOutside'); 3724} catch (exception) { 3725 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3726} 3727``` 3728 3729### on('screenshot')<sup>9+</sup> 3730 3731on(type: 'screenshot', callback: Callback<void>): void 3732 3733Subscribes to the screenshot event. 3734 3735**Atomic service API**: This API can be used in atomic services since API version 12. 3736 3737**System capability**: SystemCapability.WindowManager.WindowManager.Core 3738 3739**Parameters** 3740 3741| Name | Type | Mandatory| Description | 3742| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3743| 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.| 3744| callback | Callback<void> | Yes | Callback invoked when a screenshot event occurs. | 3745 3746**Error codes** 3747 3748For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3749 3750| ID| Error Message| 3751| ------- | -------------------------------------------- | 3752| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3753 3754**Example** 3755 3756```ts 3757try { 3758 windowClass.on('screenshot', () => { 3759 console.info('screenshot happened'); 3760 }); 3761} catch (exception) { 3762 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3763} 3764``` 3765 3766### off('screenshot')<sup>9+</sup> 3767 3768off(type: 'screenshot', callback?: Callback<void>): void 3769 3770Unsubscribes from the screenshot event. 3771 3772**Atomic service API**: This API can be used in atomic services since API version 12. 3773 3774**System capability**: SystemCapability.WindowManager.WindowManager.Core 3775 3776**Parameters** 3777 3778| Name | Type | Mandatory| Description | 3779| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3780| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event.| 3781| 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.| 3782 3783**Error codes** 3784 3785For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3786 3787| ID| Error Message| 3788| ------- | -------------------------------------------- | 3789| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3790 3791**Example** 3792 3793```ts 3794let callback = () => { 3795 console.info('screenshot happened'); 3796}; 3797try { 3798 windowClass.on('screenshot', callback); 3799 windowClass.off('screenshot', callback); 3800 // Unregister all the callbacks that have been registered through on(). 3801 windowClass.off('screenshot'); 3802} catch (exception) { 3803 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3804} 3805``` 3806 3807### on('dialogTargetTouch')<sup>10+</sup> 3808 3809on(type: 'dialogTargetTouch', callback: Callback<void>): void 3810 3811Subscribes 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. 3812 3813**Atomic service API**: This API can be used in atomic services since API version 12. 3814 3815**System capability**: SystemCapability.WindowManager.WindowManager.Core 3816 3817**Parameters** 3818 3819| Name | Type | Mandatory| Description | 3820| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3821| 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.| 3822| callback | Callback<void>| Yes | Callback invoked when a click or touch event occurs in the window covered by the modal window.| 3823 3824**Error codes** 3825 3826For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3827 3828| ID| Error Message| 3829| ------- | -------------------------------------------- | 3830| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3831 3832**Example** 3833 3834```ts 3835try { 3836 windowClass.on('dialogTargetTouch', () => { 3837 console.info('touch dialog target'); 3838 }); 3839} catch (exception) { 3840 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3841} 3842``` 3843 3844### off('dialogTargetTouch')<sup>10+</sup> 3845 3846off(type: 'dialogTargetTouch', callback?: Callback<void>): void 3847 3848Unsubscribes from the touch event of the target window in the modal window mode. 3849 3850**Atomic service API**: This API can be used in atomic services since API version 12. 3851 3852**System capability**: SystemCapability.WindowManager.WindowManager.Core 3853 3854**Parameters** 3855 3856| Name | Type | Mandatory| Description | 3857| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3858| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the touch event of the target window in the modal window mode.| 3859| 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.| 3860 3861**Error codes** 3862 3863For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3864 3865| ID| Error Message| 3866| ------- | -------------------------------------------- | 3867| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3868 3869**Example** 3870 3871```ts 3872const callback = () => { 3873 // ... 3874} 3875try { 3876 windowClass.on('dialogTargetTouch', callback); 3877 windowClass.off('dialogTargetTouch', callback); 3878 // Unregister all the callbacks that have been registered through on(). 3879 windowClass.off('dialogTargetTouch'); 3880} catch (exception) { 3881 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3882} 3883``` 3884 3885### on('windowEvent')<sup>10+</sup> 3886 3887on(type: 'windowEvent', callback: Callback<WindowEventType>): void 3888 3889Subscribes to the window lifecycle change event. 3890 3891**System capability**: SystemCapability.WindowManager.WindowManager.Core 3892 3893**Atomic service API**: This API can be used in atomic services since API version 11. 3894 3895**Parameters** 3896 3897| Name | Type | Mandatory| Description | 3898| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3899| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 3900| callback | Callback<[WindowEventType](#windoweventtype10)> | Yes | Callback used to return the window lifecycle state. | 3901 3902**Error codes** 3903 3904For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3905 3906| ID| Error Message| 3907| ------- | -------------------------------------------- | 3908| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3909 3910**Example** 3911 3912```ts 3913try { 3914 windowClass.on('windowEvent', (data) => { 3915 console.info('Window event happened. Event:' + JSON.stringify(data)); 3916 }); 3917} catch (exception) { 3918 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3919} 3920``` 3921 3922### off('windowEvent')<sup>10+</sup> 3923 3924off(type: 'windowEvent', callback?: Callback<WindowEventType>): void 3925 3926Unsubscribes from the window lifecycle change event. 3927 3928**System capability**: SystemCapability.WindowManager.WindowManager.Core 3929 3930**Atomic service API**: This API can be used in atomic services since API version 11. 3931 3932**Parameters** 3933 3934| Name | Type | Mandatory| Description | 3935| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3936| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 3937| 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. | 3938 3939**Error codes** 3940 3941For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3942 3943| ID| Error Message| 3944| ------- | -------------------------------------------- | 3945| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3946 3947**Example** 3948 3949```ts 3950const callback = (windowEventType: window.WindowEventType) => { 3951 // ... 3952} 3953try { 3954 // Enable listening through the on API. 3955 windowClass.on('windowEvent', callback); 3956 // Disable the listening of a specified callback. 3957 windowClass.off('windowEvent', callback); 3958 // Unregister all the callbacks that have been registered through on(). 3959 windowClass.off('windowEvent'); 3960} catch (exception) { 3961 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3962} 3963``` 3964 3965### on('displayIdChange')<sup>14+</sup> 3966 3967on(type: 'displayIdChange', callback: Callback<number>): void 3968 3969Subscribes to the display change event of this window. For example, this event is triggered when the window is moved to a different display. 3970 3971**Atomic service API**: This API can be used in atomic services since API version 14. 3972 3973**System capability**: SystemCapability.Window.SessionManager 3974 3975**Parameters** 3976 3977| Name | Type | Mandatory| Description | 3978| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3979| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.| 3980| 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. | 3981 3982**Error codes** 3983 3984For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3985 3986| ID| Error Message| 3987| ------- | ------------------------------ | 3988| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3989| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3990| 1300002 | This window state is abnormal. | 3991 3992**Example** 3993 3994```ts 3995try { 3996 windowClass.on('displayIdChange', (data) => { 3997 console.info('Window displayId changed, displayId=' + JSON.stringify(data)); 3998 }); 3999} catch (exception) { 4000 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4001} 4002``` 4003### off('displayIdChange')<sup>14+</sup> 4004 4005off(type: 'displayIdChange', callback?: Callback<number>): void 4006 4007Unsubscribes from the display change event of this window. 4008 4009**Atomic service API**: This API can be used in atomic services since API version 14. 4010 4011**System capability**: SystemCapability.Window.SessionManager 4012 4013**Parameters** 4014 4015| Name | Type | Mandatory| Description | 4016| -------- |----------------------------| ---- |--------------------------------------| 4017| type | string | Yes | Event type. The value is fixed at **'displayIdChange'**, indicating the display change event.| 4018| 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. | 4019 4020**Error codes** 4021 4022For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4023 4024| ID| Error Message| 4025| ------- | ------------------------------ | 4026| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4027| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4028| 1300002 | This window state is abnormal. | 4029 4030**Example** 4031 4032```ts 4033const callback = (displayId: number) => { 4034 // ... 4035} 4036try { 4037 // Enable listening through the on API. 4038 windowClass.on('displayIdChange', callback); 4039 // Disable the listening of a specified callback. 4040 windowClass.off('displayIdChange', callback); 4041 // Unregister all the callbacks that have been registered through on(). 4042 windowClass.off('displayIdChange'); 4043} catch (exception) { 4044 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4045} 4046``` 4047 4048### on('windowVisibilityChange')<sup>11+</sup> 4049 4050on(type: 'windowVisibilityChange', callback: Callback<boolean>): void 4051 4052Subscribes to the visibility status change event of this window. 4053 4054**Atomic service API**: This API can be used in atomic services since API version 12. 4055 4056**System capability**: SystemCapability.Window.SessionManager 4057 4058**Parameters** 4059 4060| Name | Type | Mandatory| Description | 4061| -------- | --------------------------| ---- | ------------------------------------------------------------ | 4062| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 4063| 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. | 4064 4065**Error codes** 4066 4067For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4068 4069| ID| Error Message| 4070| ------- | ------------------------------ | 4071| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4072| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4073| 1300002 | This window state is abnormal. | 4074| 1300003 | This window manager service works abnormally. | 4075 4076**Example** 4077 4078```ts 4079try { 4080 windowClass.on('windowVisibilityChange', (boolean) => { 4081 console.info('Window visibility changed, isVisible=' + boolean); 4082 }); 4083} catch (exception) { 4084 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4085} 4086``` 4087 4088### off('windowVisibilityChange')<sup>11+</sup> 4089 4090off(type: 'windowVisibilityChange', callback?: Callback<boolean>): void 4091 4092Unsubscribes from the visibility status change event of this window. 4093 4094**Atomic service API**: This API can be used in atomic services since API version 12. 4095 4096**System capability**: SystemCapability.Window.SessionManager 4097 4098**Parameters** 4099 4100| Name | Type | Mandatory| Description | 4101| -------- |----------------------------| ---- |--------------------------------------| 4102| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 4103| 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. | 4104 4105**Error codes** 4106 4107For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4108 4109| ID| Error Message| 4110| ------- | ------------------------------ | 4111| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4112| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4113| 1300002 | This window state is abnormal. | 4114| 1300003 | This window manager service works abnormally. | 4115 4116**Example** 4117 4118```ts 4119const callback = (bool: boolean) => { 4120 // ... 4121} 4122try { 4123 // Enable listening through the on API. 4124 windowClass.on('windowVisibilityChange', callback); 4125 // Disable the listening of a specified callback. 4126 windowClass.off('windowVisibilityChange', callback); 4127 // Unregister all the callbacks that have been registered through on(). 4128 windowClass.off('windowVisibilityChange'); 4129} catch (exception) { 4130 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4131} 4132``` 4133 4134### on('systemDensityChange')<sup>15+</sup> 4135 4136on(type: 'systemDensityChange', callback: Callback<number>): void 4137 4138Subscribes to the system density change event, which is triggered when the system's display size scale factor changes for the screen where the window is located. 4139 4140**Atomic service API**: This API can be used in atomic services since API version 15. 4141 4142**System capability**: SystemCapability.Window.SessionManager 4143 4144**Parameters** 4145 4146| Name | Type | Mandatory| Description | 4147| -------- | --------------------------| ---- | ------------------------------------------------------------ | 4148| type | string | Yes | Event type. The value is fixed at **'systemDensityChange'**, indicating the system density change event.| 4149| callback | Callback<number> | Yes | Callback invoked when the system's display size scale factor changes. The callback contains a parameter of the number type, indicating the new scale factor. | 4150 4151**Error codes** 4152 4153 4154For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4155 4156| ID| Error Message| 4157| ------- | ------------------------------ | 4158| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4159| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4160| 1300002 | This window state is abnormal. | 4161 4162**Example** 4163 4164```ts 4165const callback = (density: number) => { 4166 console.info('System density changed, density=' + JSON.stringify(density)); 4167} 4168try { 4169 windowClass.on('systemDensityChange', callback); 4170} catch (exception) { 4171 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4172} 4173``` 4174### off('systemDensityChange')<sup>15+</sup> 4175 4176off(type: 'systemDensityChange', callback?: Callback<number>): void 4177 4178Unsubscribes from the system density change event. 4179 4180**Atomic service API**: This API can be used in atomic services since API version 15. 4181 4182**System capability**: SystemCapability.Window.SessionManager 4183 4184**Parameters** 4185 4186| Name | Type | Mandatory| Description | 4187| -------- |----------------------------| ---- |--------------------------------------| 4188| type | string | Yes | Event type. The value is fixed at **'systemDensityChange'**, indicating the system density change event.| 4189| callback | Callback<number> | No | Callback invoked when the system's display size scale factor changes. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled. | 4190 4191**Error codes** 4192 4193For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4194 4195| ID| Error Message| 4196| ------- | ------------------------------ | 4197| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4198| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4199| 1300002 | This window state is abnormal. | 4200 4201**Example** 4202 4203```ts 4204const callback = (density: number) => { 4205 // ... 4206} 4207try { 4208 // Enable listening through the on API. 4209 windowClass.on('systemDensityChange', callback); 4210 // Disable the listening of a specified callback. 4211 windowClass.off('systemDensityChange', callback); 4212 // Unregister all the callbacks that have been registered through on(). 4213 windowClass.off('systemDensityChange'); 4214} catch (exception) { 4215 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4216} 4217``` 4218 4219### on('noInteractionDetected')<sup>12+</sup> 4220 4221on(type: 'noInteractionDetected', timeout: number, callback: Callback<void>): void 4222 4223Subscribes to non-interaction events in a window within the specified period. 4224 4225Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 4226 4227**Atomic service API**: This API can be used in atomic services since API version 12. 4228 4229**System capability**: SystemCapability.Window.SessionManager 4230 4231**Parameters** 4232 4233| Name | Type | Mandatory| Description | 4234| -------- | --------------------------| ---- | ------------------------------------------------------------ | 4235| 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.| 4236| timeout | number | Yes | Period during which no interaction is performed, in seconds. The value must be an integer. Negative numbers and decimals are invalid.| 4237| callback | Callback<void> | Yes | Callback invoked when there is no interaction event in the current window within the specified period. | 4238 4239**Error codes** 4240 4241For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4242 4243| ID| Error Message| 4244| ------- | ------------------------------ | 4245| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4246| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4247| 1300002 | This window state is abnormal. | 4248| 1300003 | This window manager service works abnormally. | 4249 4250**Example** 4251 4252```ts 4253try { 4254 windowClass.on('noInteractionDetected', 60, () => { 4255 console.info('no interaction in 60s'); 4256 }); 4257} catch (exception) { 4258 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4259} 4260``` 4261 4262### off('noInteractionDetected')<sup>12+</sup> 4263 4264off(type: 'noInteractionDetected', callback?: Callback<void>): void 4265 4266Unsubscribes from non-interaction events in a window within the specified period. 4267 4268Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 4269 4270**Atomic service API**: This API can be used in atomic services since API version 12. 4271 4272**System capability**: SystemCapability.Window.SessionManager 4273 4274**Parameters** 4275 4276| Name | Type | Mandatory| Description | 4277| -------- |----------------------------| ---- |--------------------------------------| 4278| 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.| 4279| 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.| 4280 4281**Error codes** 4282 4283For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4284 4285| ID| Error Message| 4286| ------- | ------------------------------ | 4287| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4288| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4289| 1300002 | This window state is abnormal. | 4290| 1300003 | This window manager service works abnormally. | 4291 4292**Example** 4293 4294```ts 4295const callback = () => { 4296 // ... 4297} 4298try { 4299 windowClass.on('noInteractionDetected', 60, callback); 4300 windowClass.off('noInteractionDetected', callback); 4301 // Unregister all the callbacks that have been registered through on(). 4302 windowClass.off('noInteractionDetected'); 4303} catch (exception) { 4304 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4305} 4306``` 4307 4308### on('windowStatusChange')<sup>11+</sup> 4309 4310on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void 4311 4312Subscribes to the window status change event. A notification is sent when the window status changes (the window properties may not be updated). 4313 4314> **NOTE** 4315> 4316> When this API is called on 2-in-1 devices, the return value is **WindowStatusType::FULL_SCREEN** when the window is maximized. 4317> 4318> 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. 4319 4320**Atomic service API**: This API can be used in atomic services since API version 12. 4321 4322**System capability**: SystemCapability.Window.SessionManager 4323 4324**Parameters** 4325 4326| Name | Type | Mandatory| Description | 4327| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4328| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 4329| callback | Callback<[WindowStatusType](#windowstatustype11)> | Yes | Callback used to return the window status. | 4330 4331**Error codes** 4332 4333For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4334 4335| ID| Error Message| 4336| ------- | ------------------------------ | 4337| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4338| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4339 4340**Example** 4341 4342```ts 4343try { 4344 windowClass.on('windowStatusChange', (WindowStatusType) => { 4345 console.info('Succeeded in enabling the listener for window status changes. Data: ' + JSON.stringify(WindowStatusType)); 4346 }); 4347} catch (exception) { 4348 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4349} 4350``` 4351 4352### off('windowStatusChange')<sup>11+</sup> 4353 4354off(type: 'windowStatusChange', callback?: Callback<WindowStatusType>): void 4355 4356Unsubscribes from the window status change event. 4357 4358**Atomic service API**: This API can be used in atomic services since API version 12. 4359 4360**System capability**: SystemCapability.Window.SessionManager 4361 4362**Parameters** 4363 4364| Name | Type | Mandatory| Description | 4365| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 4366| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 4367| 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. | 4368 4369**Error codes** 4370 4371For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 4372 4373| ID| Error Message| 4374| ------- | ------------------------------ | 4375| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4376| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4377 4378**Example** 4379 4380```ts 4381const callback = (windowStatusType: window.WindowStatusType) => { 4382 // ... 4383} 4384try { 4385 windowClass.on('windowStatusChange', callback); 4386 windowClass.off('windowStatusChange', callback); 4387 // Unregister all the callbacks that have been registered through on(). 4388 windowClass.off('windowStatusChange'); 4389} catch (exception) { 4390 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4391} 4392``` 4393 4394### setWindowGrayScale<sup>12+</sup> 4395 4396setWindowGrayScale(grayScale: number): Promise<void> 4397 4398Sets 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. 4399 4400**Atomic service API**: This API can be used in atomic services since API version 12. 4401 4402**System capability**: SystemCapability.Window.SessionManager 4403 4404**Parameters** 4405 4406| Name| Type| Mandatory| Description | 4407| --------- | ------ | -- | ---------------------------------------- | 4408| 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.| 4409 4410**Return value** 4411 4412| Type| Description| 4413| ------------------- | ------------------------ | 4414| Promise<void> | Promise that returns no value.| 4415 4416**Error codes** 4417 4418For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4419 4420| ID| Error Message| 4421| ------- | --------------------------------------------- | 4422| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4423| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4424| 1300002 | This window state is abnormal. | 4425| 1300003 | This window manager service works abnormally. | 4426 4427**Example** 4428 4429```ts 4430import { BusinessError } from '@kit.BasicServicesKit'; 4431 4432windowClass?.setUIContent('pages/Index', (error: BusinessError) => { 4433 if (error.code) { 4434 console.error(`Failed to set the content. Cause code: ${error.code}`); 4435 return; 4436 } 4437 console.info('Succeeded in setting the content.'); 4438 let grayScale: number = 0.5; 4439 try { 4440 if (canIUse("SystemCapability.Window.SessionManager")) { 4441 let promise = windowClass?.setWindowGrayScale(grayScale); 4442 promise?.then(() => { 4443 console.info('Succeeded in setting the grayScale.'); 4444 }).catch((err: BusinessError) => { 4445 console.error(`Failed to set the grayScale. Cause code: ${err.code}, message: ${err.message}`); 4446 }); 4447 } 4448 } catch (exception) { 4449 console.error(`Failed to set the grayScale. Cause code: ${exception.code}, message: ${exception.message}`); 4450 } 4451}); 4452``` 4453 4454### on('windowTitleButtonRectChange')<sup>11+</sup> 4455 4456on(type: 'windowTitleButtonRectChange', callback: Callback<TitleButtonRect>): void 4457 4458Subscribes to the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 4459 4460<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 4461 4462**Atomic service API**: This API can be used in atomic services since API version 12. 4463 4464**System capability**: SystemCapability.Window.SessionManager 4465 4466**Parameters** 4467 4468| Name | Type | Mandatory| Description | 4469| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 4470| 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.| 4471| callback | Callback<[TitleButtonRect](#titlebuttonrect11)> | Yes | Callback used to return the new rectangle.| 4472 4473**Error codes** 4474 4475For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4476 4477| ID| Error Message | 4478| -------- | ------------------------------ | 4479| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4480| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4481| 1300002 | This window state is abnormal. | 4482 4483**Example** 4484 4485```ts 4486windowClass.setUIContent('pages/WindowPage').then(() => { 4487 try { 4488 windowClass?.on('windowTitleButtonRectChange', (titleButtonRect) => { 4489 console.info('Succeeded in enabling the listener for window title buttons area changes. Data: ' + JSON.stringify(titleButtonRect)); 4490 }); 4491 } catch (exception) { 4492 console.error(`Failed to enable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4493 } 4494}) 4495``` 4496 4497### off('windowTitleButtonRectChange')<sup>11+</sup> 4498 4499off(type: 'windowTitleButtonRectChange', callback?: Callback<TitleButtonRect>): void 4500 4501Unsubscribes from the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 4502 4503<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 4504 4505**Atomic service API**: This API can be used in atomic services since API version 12. 4506 4507**System capability**: SystemCapability.Window.SessionManager 4508 4509**Parameters** 4510 4511| Name | Type | Mandatory| Description | 4512| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 4513| 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.| 4514| 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.| 4515 4516**Error codes** 4517 4518For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4519 4520| ID| Error Message | 4521| -------- | ------------------------------ | 4522| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4523| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4524| 1300002 | This window state is abnormal. | 4525 4526**Example** 4527 4528```ts 4529windowClass.setUIContent('pages/WindowPage').then(() => { 4530 const callback = (titleButtonRect: window.TitleButtonRect) => { 4531 // ... 4532 } 4533 try { 4534 // Enable listening through the on API. 4535 windowClass?.on('windowTitleButtonRectChange', callback); 4536 // Disable the listening of a specified callback. 4537 windowClass?.off('windowTitleButtonRectChange', callback); 4538 // Unregister all the callbacks that have been registered through on(). 4539 windowClass?.off('windowTitleButtonRectChange'); 4540 } catch (exception) { 4541 console.error(`Failed to disable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4542 } 4543}) 4544``` 4545 4546### on('windowRectChange')<sup>12+</sup> 4547 4548on(type: 'windowRectChange', callback: Callback<RectChangeOptions>): void 4549 4550Subscribes to window rectangle (position and size) change events. 4551 4552**System capability**: SystemCapability.Window.SessionManager 4553 4554**Atomic service API**: This API can be used in atomic services since API version 12. 4555 4556**Parameters** 4557 4558| Name | Type | Mandatory| Description | 4559| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4560| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event.| 4561| callback | Callback<[RectChangeOptions](#rectchangeoptions12)> | Yes | Callback used to return the value and reason of the window rectangle change. | 4562 4563**Error codes** 4564 4565For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4566 4567| ID| Error Message| 4568| ------- | -------------------------------------------- | 4569| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4570| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4571| 1300002 | This window state is abnormal. | 4572| 1300003 | This window manager service works abnormally. | 4573 4574**Example** 4575 4576```ts 4577windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 4578 console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data)); 4579}); 4580``` 4581 4582### off('windowRectChange')<sup>12+</sup> 4583 4584off(type: 'windowRectChange', callback?: Callback<RectChangeOptions>): void 4585 4586Unsubscribes from window rectangle (position and size) change events. 4587 4588**System capability**: SystemCapability.Window.SessionManager 4589 4590**Atomic service API**: This API can be used in atomic services since API version 12. 4591 4592**Parameters** 4593 4594| Name | Type | Mandatory| Description | 4595| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4596| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event. | 4597| 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.| 4598 4599**Error codes** 4600 4601For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4602 4603| ID| Error Message| 4604| ------- | -------------------------------------------- | 4605| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4606| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4607| 1300002 | This window state is abnormal. | 4608| 1300003 | This window manager service works abnormally. | 4609 4610**Example** 4611 4612```ts 4613const callback = (rectChangeOptions: window.RectChangeOptions) => { 4614 // ... 4615} 4616windowClass.on('windowRectChange', callback); 4617windowClass.off('windowRectChange', callback); 4618// Unregister all the callbacks that have been registered through on(). 4619windowClass.off('windowRectChange'); 4620``` 4621 4622### on('subWindowClose')<sup>12+</sup> 4623 4624on(type: 'subWindowClose', callback: Callback<void>): void 4625 4626Subscribes to the event indicating that the child window is closed. This event is triggered only when the user clicks the system-provided close button in the upper right corner to close the child window. It is not triggered when the child window is closed in other ways. 4627 4628If the event is subscribed to multiple times, only the most recently subscribed-to event takes effect. 4629 4630The callback function in this API is executed synchronously. For asynchronous close events of child windows, refer to [on('windowWillClose')](#onwindowwillclose15). 4631 4632If there is an existing event subscribed to by calling [on('windowWillClose')](#onwindowwillclose15), only the [on('windowWillClose')](#onwindowwillclose15) API will be responded to. 4633 4634**Atomic service API**: This API can be used in atomic services since API version 12. 4635 4636**System capability**: SystemCapability.Window.SessionManager 4637 4638**Parameters** 4639 4640| Name | Type | Mandatory| Description | 4641| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4642| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the child window close event.| 4643| callback | Callback<void> | Yes | Callback invoked when the close button in the upper right corner of the child window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the child window. The value **true** means not to close the child window, and **false** means to continue to close the child window. | 4644 4645**Error codes** 4646 4647For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4648 4649| ID| Error Message| 4650| ------- | -------------------------------------------- | 4651| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4652| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4653| 1300002 | This window state is abnormal. | 4654| 1300004 | Unauthorized operation. | 4655 4656**Example** 4657 4658```ts 4659const callback = () => { 4660 // ... 4661 return true; 4662} 4663try { 4664 windowClass.on('subWindowClose', callback); 4665} catch (exception) { 4666 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4667} 4668``` 4669 4670### off('subWindowClose')<sup>12+</sup> 4671 4672off(type: 'subWindowClose', callback?: Callback<void>): void 4673 4674Unsubscribes from the event indicating that the child window is closed. 4675 4676**Atomic service API**: This API can be used in atomic services since API version 12. 4677 4678**System capability**: SystemCapability.Window.SessionManager 4679 4680**Parameters** 4681 4682| Name | Type | Mandatory| Description | 4683| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4684| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the child window close event. | 4685| callback | Callback<void> | No | Callback invoked when the close button in the upper right corner of the child window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the child window. The value **true** means not to close the child window, and **false** means to continue to close the child 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.| 4686 4687**Error codes** 4688 4689For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4690 4691| ID| Error Message| 4692| ------- | -------------------------------------------- | 4693| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4694| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4695| 1300002 | This window state is abnormal. | 4696| 1300004 | Unauthorized operation. | 4697 4698**Example** 4699 4700```ts 4701const callback = () => { 4702 // ... 4703 return true; 4704} 4705try { 4706 windowClass.on('subWindowClose', callback); 4707 windowClass.off('subWindowClose', callback); 4708 // Unregister all the callbacks that have been registered through on(). 4709 windowClass.off('subWindowClose'); 4710} catch (exception) { 4711 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4712} 4713``` 4714 4715### on('windowWillClose')<sup>15+</sup> 4716 4717on(type: 'windowWillClose', callback: Callback<void, Promise<boolean>>): void 4718 4719Subscribes to the event indicating that the main window or child window will be closed. This event is triggered only when the user clicks the close button in the system-provided title bar to close the window. It is not triggered when the window is closed in other ways. 4720 4721The callback function in this API is executed synchronously. For synchronous close events of child windows, refer to [on('subWindowClose')](#onsubwindowclose12). For synchronous close events of the main window, refer to [on('windowStageClose')](#onwindowstageclose14). 4722 4723<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> <br> 4724 4725**Atomic service API**: This API can be used in atomic services since API version 15. 4726 4727**System capability**: SystemCapability.Window.SessionManager 4728 4729**Parameters** 4730 4731| Name | Type | Mandatory| Description | 4732| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4733| type | string | Yes | Event type. The value is fixed at **'windowWillClose'**, indicating the window close event.| 4734| callback | Callback<void, Promise<boolean>> | Yes | Callback used to when the close button in the upper right corner of the window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Promise<boolean> type. In the returned Promise function, **resolve(true)** means not to close the window, and **resolve(false)** or **reject** means to continue to close the window.| 4735 4736**Error codes** 4737 4738For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4739 4740| ID| Error Message| 4741| ------- | -------------------------------------------- | 4742| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4743| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4744| 1300002 | This window state is abnormal. | 4745| 1300004 | Unauthorized operation. | 4746 4747**Example** 4748 4749```ts 4750// EntryAbility.ets 4751import { UIAbility } from '@kit.AbilityKit'; 4752import { window } from '@kit.ArkUI'; 4753 4754export default class EntryAbility extends UIAbility { 4755 4756 onWindowStageCreate(windowStage: window.WindowStage) { 4757 console.info('onWindowStageCreate'); 4758 const callback = () => { 4759 // ... 4760 return new Promise<boolean>((resolve, reject) => { 4761 // Whether to close the window. 4762 let result: boolean = true; 4763 resolve(result); 4764 }); 4765 } 4766 try { 4767 let windowClass = windowStage.getMainWindowSync(); 4768 windowClass.on('windowWillClose', callback); 4769 } catch (exception) { 4770 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4771 } 4772 } 4773} 4774``` 4775 4776### off('windowWillClose')<sup>15+</sup> 4777 4778off(type: 'windowWillClose', callback?: Callback<void, Promise<boolean>>): void 4779 4780Unsubscribes from the event indicating that the main window or child window will be closed. 4781 4782<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> <br> 4783 4784**Atomic service API**: This API can be used in atomic services since API version 15. 4785 4786**System capability**: SystemCapability.Window.SessionManager 4787 4788**Parameters** 4789 4790| Name | Type | Mandatory| Description | 4791| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4792| type | string | Yes | Event type. The value is fixed at **'windowWillClose'**, indicating the window close event.| 4793| callback | Callback<void, Promise<boolean>> | No | Callback used to when the close button in the upper right corner of the window is clicked. It does not return any parameter. The internal logic of the callback function requires a return value of the Promise<boolean> type. In the returned Promise function, **resolve(true)** means not to close the window, and **resolve(false)** or **reject** means to continue to close the window.| 4794 4795**Error codes** 4796 4797For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4798 4799| ID| Error Message| 4800| ------- | -------------------------------------------- | 4801| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4802| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4803| 1300002 | This window state is abnormal. | 4804| 1300004 | Unauthorized operation. | 4805 4806**Example** 4807 4808```ts 4809// EntryAbility.ets 4810import { UIAbility } from '@kit.AbilityKit'; 4811import { window } from '@kit.ArkUI'; 4812 4813export default class EntryAbility extends UIAbility { 4814 4815 onWindowStageCreate(windowStage: window.WindowStage) { 4816 console.info('onWindowStageCreate'); 4817 try { 4818 const callback = () => { 4819 // ... 4820 return new Promise<boolean>((resolve, reject) => { 4821 // Whether to close the window. 4822 let result: boolean = true; 4823 resolve(result); 4824 }); 4825 } 4826 let windowClass = windowStage.getMainWindowSync(); 4827 windowClass.on('windowWillClose', callback); 4828 windowClass.off('windowWillClose', callback); 4829 // Unregister all the callbacks that have been registered through on(). 4830 windowClass.off('windowWillClose'); 4831 } catch (exception) { 4832 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4833 } 4834 } 4835} 4836``` 4837 4838### on('windowHighlightChange')<sup>15+</sup> 4839 4840on(type: 'windowHighlightChange', callback: Callback<boolean>): void 4841 4842Subscribes to the highlighted state change event of the window. 4843 4844**Atomic service API**: This API can be used in atomic services since API version 15. 4845 4846**System capability**: SystemCapability.Window.SessionManager 4847 4848**Parameters** 4849 4850| Name | Type | Mandatory| Description | 4851| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4852| type | string | Yes | Event type. The value is fixed at **'windowHighlightChange'**, indicating the window highlighted state change event.| 4853| callback | Callback<boolean> | Yes | Callback used to return the highlighted state of the window. which is a Boolean value. The value **true** means that the window is hightlighted, and **false** means the opposite. | 4854 4855**Error codes** 4856 4857For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4858 4859| ID| Error Message| 4860| ------- | -------------------------------------------- | 4861| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4862| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4863| 1300002 | This window state is abnormal. | 4864| 1300003 | This window manager service works abnormally. | 4865 4866**Example** 4867 4868```ts 4869try { 4870 windowClass.on('windowHighlightChange', (data: boolean) => { 4871 console.info(`Window highlight Change: ${data}`); 4872 }); 4873} catch (exception) { 4874 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4875} 4876``` 4877 4878### off('windowHighlightChange')<sup>15+</sup> 4879 4880off(type: 'windowHighlightChange', callback?: Callback<boolean>): void 4881 4882Unsubscribes from the highlighted state change event of the window. 4883 4884**Atomic service API**: This API can be used in atomic services since API version 15. 4885 4886**System capability**: SystemCapability.Window.SessionManager 4887 4888**Parameters** 4889 4890| Name | Type | Mandatory| Description | 4891| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4892| type | string | Yes | Event type. The value is fixed at **'windowHighlightChange'**, indicating the window highlighted state change event. | 4893| callback | Callback<boolean> | No | Callback used to return the highlighted state of the window. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.| 4894 4895**Error codes** 4896 4897For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4898 4899| ID| Error Message| 4900| ------- | -------------------------------------------- | 4901| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4902| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4903| 1300002 | This window state is abnormal. | 4904| 1300003 | This window manager service works abnormally. | 4905 4906**Example** 4907 4908```ts 4909const callback = (data: boolean) => { 4910 // ... 4911} 4912try { 4913 // Enable listening through the on API. 4914 windowClass.on('windowHighlightChange', callback); 4915 // Disable the listening of a specified callback. 4916 windowClass.off('windowHighlightChange', callback); 4917 // Unregister all the callbacks that have been registered through on(). 4918 windowClass.off('windowHighlightChange'); 4919} catch (exception) { 4920 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4921} 4922``` 4923 4924### isWindowSupportWideGamut<sup>9+</sup> 4925 4926isWindowSupportWideGamut(callback: AsyncCallback<boolean>): void 4927 4928Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 4929 4930**Atomic service API**: This API can be used in atomic services since API version 12. 4931 4932**System capability**: SystemCapability.WindowManager.WindowManager.Core 4933 4934**Parameters** 4935 4936| Name| Type| Mandatory| Description| 4937| -------- | ---------------------------- | -- | -------------------------------------------------------------------------------- | 4938| 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.| 4939 4940**Error codes** 4941 4942For details about the error codes, see [Window Error Codes](errorcode-window.md). 4943 4944| ID| Error Message| 4945| ------- | ------------------------------ | 4946| 1300002 | This window state is abnormal. | 4947 4948**Example** 4949 4950```ts 4951import { BusinessError } from '@kit.BasicServicesKit'; 4952 4953windowClass.isWindowSupportWideGamut((err: BusinessError, data) => { 4954 const errCode: number = err.code; 4955 if (errCode) { 4956 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 4957 return; 4958 } 4959 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 4960}); 4961``` 4962 4963### isWindowSupportWideGamut<sup>9+</sup> 4964 4965isWindowSupportWideGamut(): Promise<boolean> 4966 4967Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 4968 4969**Atomic service API**: This API can be used in atomic services since API version 12. 4970 4971**System capability**: SystemCapability.WindowManager.WindowManager.Core 4972 4973**Return value** 4974 4975| Type| Description| 4976| ---------------------- | ------------------------------------------------------------------------------------ | 4977| 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.| 4978 4979**Error codes** 4980 4981For details about the error codes, see [Window Error Codes](errorcode-window.md). 4982 4983| ID| Error Message| 4984| ------- | ------------------------------ | 4985| 1300002 | This window state is abnormal. | 4986 4987**Example** 4988 4989```ts 4990import { BusinessError } from '@kit.BasicServicesKit'; 4991 4992let promise = windowClass.isWindowSupportWideGamut(); 4993promise.then((data) => { 4994 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 4995}).catch((err: BusinessError) => { 4996 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 4997}); 4998``` 4999 5000### setWindowColorSpace<sup>9+</sup> 5001 5002setWindowColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 5003 5004Sets a color space for this window. This API uses an asynchronous callback to return the result. 5005 5006**Atomic service API**: This API can be used in atomic services since API version 12. 5007 5008**System capability**: SystemCapability.WindowManager.WindowManager.Core 5009 5010**Parameters** 5011 5012| Name| Type| Mandatory| Description| 5013| ---------- | ------------------------- | -- | ----------- | 5014| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 5015| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 5016 5017**Error codes** 5018 5019For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5020 5021| ID| Error Message| 5022| ------- | ------------------------------ | 5023| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5024| 1300002 | This window state is abnormal. | 5025 5026**Example** 5027 5028```ts 5029import { BusinessError } from '@kit.BasicServicesKit'; 5030 5031try { 5032 windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 5033 const errCode: number = err.code; 5034 if (errCode) { 5035 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 5036 return; 5037 } 5038 console.info('Succeeded in setting window colorspace.'); 5039 }); 5040} catch (exception) { 5041 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 5042} 5043``` 5044 5045### setWindowColorSpace<sup>9+</sup> 5046 5047setWindowColorSpace(colorSpace:ColorSpace): Promise<void> 5048 5049Sets a color space for this window. This API uses a promise to return the result. 5050 5051**Atomic service API**: This API can be used in atomic services since API version 12. 5052 5053**System capability**: SystemCapability.WindowManager.WindowManager.Core 5054 5055**Parameters** 5056 5057| Name| Type| Mandatory| Description| 5058| ---------- | ------------------------- | -- | ------------- | 5059| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 5060 5061**Return value** 5062 5063| Type| Description| 5064| ------------------- | ------------------------ | 5065| Promise<void> | Promise that returns no value.| 5066 5067**Error codes** 5068 5069For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5070 5071| ID| Error Message| 5072| ------- | ------------------------------ | 5073| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5074| 1300002 | This window state is abnormal. | 5075 5076**Example** 5077 5078```ts 5079import { BusinessError } from '@kit.BasicServicesKit'; 5080 5081try { 5082 let promise = windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT); 5083 promise.then(() => { 5084 console.info('Succeeded in setting window colorspace.'); 5085 }).catch((err: BusinessError) => { 5086 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 5087 }); 5088} catch (exception) { 5089 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 5090} 5091``` 5092 5093### getWindowColorSpace<sup>9+</sup> 5094 5095getWindowColorSpace(): ColorSpace 5096 5097Obtains the color space of this window. 5098 5099**Atomic service API**: This API can be used in atomic services since API version 12. 5100 5101**System capability**: SystemCapability.WindowManager.WindowManager.Core 5102 5103**Return value** 5104 5105| Type| Description| 5106| ------------------------- | ------------- | 5107| [ColorSpace](#colorspace8) | Color space obtained.| 5108 5109**Error codes** 5110 5111For details about the error codes, see [Window Error Codes](errorcode-window.md). 5112 5113| ID| Error Message| 5114| ------- | ------------------------------ | 5115| 1300002 | This window state is abnormal. | 5116 5117**Example** 5118 5119```ts 5120let colorSpace = windowClass.getWindowColorSpace(); 5121``` 5122 5123### setWindowBackgroundColor<sup>9+</sup> 5124 5125setWindowBackgroundColor(color: string): void 5126 5127Sets 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. 5128 5129**System capability**: SystemCapability.WindowManager.WindowManager.Core 5130 5131**Atomic service API**: This API can be used in atomic services since API version 11. 5132 5133**Parameters** 5134 5135| Name| Type| Mandatory| Description| 5136| ----- | ------ | -- | ----------------------------------------------------------------------- | 5137| 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'**.| 5138 5139**Error codes** 5140 5141For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5142 5143| ID| Error Message| 5144| ------- | ------------------------------ | 5145| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5146| 1300002 | This window state is abnormal. | 5147 5148**Example** 5149 5150```ts 5151import { BusinessError } from '@kit.BasicServicesKit'; 5152 5153let storage: LocalStorage = new LocalStorage(); 5154storage.setOrCreate('storageSimpleProp', 121); 5155windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 5156 let errCode: number = err.code; 5157 if (errCode) { 5158 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 5159 return; 5160 } 5161 console.info('Succeeded in loading the content.'); 5162 let color: string = '#00ff33'; 5163 try { 5164 windowClass?.setWindowBackgroundColor(color); 5165 } catch (exception) { 5166 console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`); 5167 }; 5168}); 5169``` 5170 5171### setWindowBrightness<sup>9+</sup> 5172 5173setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void 5174 5175Sets the screen brightness for the main window. This API uses an asynchronous callback to return the result. 5176 5177When 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. 5178 5179**System capability**: SystemCapability.WindowManager.WindowManager.Core 5180 5181**Atomic service API**: This API can be used in atomic services since API version 11. 5182 5183**Parameters** 5184 5185| Name| Type| Mandatory| Description | 5186| ---------- | ------------------------- | -- |-------------------------------------------| 5187| 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.| 5188| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 5189 5190**Error codes** 5191 5192For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5193 5194| ID| Error Message| 5195| ------- | -------------------------------------------- | 5196| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5197| 1300002 | This window state is abnormal. | 5198| 1300003 | This window manager service works abnormally. | 5199 5200**Example** 5201 5202```ts 5203// EntryAbility.ets 5204import { UIAbility } from '@kit.AbilityKit'; 5205import { BusinessError } from '@kit.BasicServicesKit'; 5206 5207export default class EntryAbility extends UIAbility { 5208 // ... 5209 onWindowStageCreate(windowStage: window.WindowStage): void { 5210 console.info('onWindowStageCreate'); 5211 let windowClass: window.Window | undefined = undefined; 5212 windowStage.getMainWindow((err: BusinessError, data) => { 5213 const errCode: number = err.code; 5214 if (errCode) { 5215 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5216 return; 5217 } 5218 windowClass = data; 5219 let brightness: number = 1; 5220 try { 5221 windowClass.setWindowBrightness(brightness, (err: BusinessError) => { 5222 const errCode: number = err.code; 5223 if (errCode) { 5224 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 5225 return; 5226 } 5227 console.info('Succeeded in setting the brightness.'); 5228 }); 5229 } catch (exception) { 5230 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 5231 } 5232 }); 5233 } 5234} 5235``` 5236 5237### setWindowBrightness<sup>9+</sup> 5238 5239setWindowBrightness(brightness: number): Promise<void> 5240 5241Sets the screen brightness for the main window. This API uses a promise to return the result. 5242 5243When 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. 5244 5245**System capability**: SystemCapability.WindowManager.WindowManager.Core 5246 5247**Atomic service API**: This API can be used in atomic services since API version 11. 5248 5249**Parameters** 5250 5251| Name| Type| Mandatory| Description | 5252| ---------- | ------ | -- |----------------------------------------| 5253| 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.| 5254 5255**Return value** 5256 5257| Type| Description| 5258| ------------------- | ------------------------ | 5259| Promise<void> | Promise that returns no value.| 5260 5261**Error codes** 5262 5263For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5264 5265| ID| Error Message| 5266| ------- | -------------------------------------------- | 5267| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5268| 1300002 | This window state is abnormal. | 5269| 1300003 | This window manager service works abnormally. | 5270 5271**Example** 5272 5273```ts 5274// EntryAbility.ets 5275import { UIAbility } from '@kit.AbilityKit'; 5276import { BusinessError } from '@kit.BasicServicesKit'; 5277 5278export default class EntryAbility extends UIAbility { 5279 // ... 5280 onWindowStageCreate(windowStage: window.WindowStage): void { 5281 console.info('onWindowStageCreate'); 5282 let windowClass: window.Window | undefined = undefined; 5283 windowStage.getMainWindow((err: BusinessError, data) => { 5284 const errCode: number = err.code; 5285 if (errCode) { 5286 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5287 return; 5288 } 5289 windowClass = data; 5290 let brightness: number = 1; 5291 try { 5292 let promise = windowClass.setWindowBrightness(brightness); 5293 promise.then(() => { 5294 console.info('Succeeded in setting the brightness.'); 5295 }).catch((err: BusinessError) => { 5296 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 5297 }); 5298 } catch (exception) { 5299 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 5300 } 5301 }); 5302 } 5303} 5304``` 5305 5306### setWindowFocusable<sup>9+</sup> 5307 5308setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 5309 5310Sets 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. 5311 5312**Atomic service API**: This API can be used in atomic services since API version 12. 5313 5314**System capability**: SystemCapability.WindowManager.WindowManager.Core 5315 5316**Parameters** 5317 5318| Name| Type| Mandatory| Description| 5319| ----------- | ------------------------- | -- | ------------------------------------------------------- | 5320| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.| 5321| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 5322 5323**Error codes** 5324 5325For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5326 5327| ID| Error Message| 5328| ------- | -------------------------------------------- | 5329| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5330| 1300002 | This window state is abnormal. | 5331| 1300003 | This window manager service works abnormally. | 5332 5333**Example** 5334 5335```ts 5336import { BusinessError } from '@kit.BasicServicesKit'; 5337 5338let isFocusable: boolean = true; 5339try { 5340 windowClass.setWindowFocusable(isFocusable, (err: BusinessError) => { 5341 const errCode: number = err.code; 5342 if (errCode) { 5343 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 5344 return; 5345 } 5346 console.info('Succeeded in setting the window to be focusable.'); 5347 }); 5348} catch (exception) { 5349 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 5350} 5351``` 5352 5353### setWindowFocusable<sup>9+</sup> 5354 5355setWindowFocusable(isFocusable: boolean): Promise<void> 5356 5357Sets 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. 5358 5359**Atomic service API**: This API can be used in atomic services since API version 12. 5360 5361**System capability**: SystemCapability.WindowManager.WindowManager.Core 5362 5363**Parameters** 5364 5365| Name| Type| Mandatory| Description| 5366| ----------- | ------- | -- | -------------------------------------------------------- | 5367| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 5368 5369**Return value** 5370 5371| Type| Description| 5372| ------------------- | ------------------------ | 5373| Promise<void> | Promise that returns no value.| 5374 5375**Error codes** 5376 5377For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5378 5379| ID| Error Message| 5380| ------- | -------------------------------------------- | 5381| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5382| 1300002 | This window state is abnormal. | 5383| 1300003 | This window manager service works abnormally. | 5384 5385**Example** 5386 5387```ts 5388import { BusinessError } from '@kit.BasicServicesKit'; 5389 5390let isFocusable: boolean = true; 5391try { 5392 let promise = windowClass.setWindowFocusable(isFocusable); 5393 promise.then(() => { 5394 console.info('Succeeded in setting the window to be focusable.'); 5395 }).catch((err: BusinessError) => { 5396 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 5397 }); 5398} catch (exception) { 5399 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 5400} 5401``` 5402 5403### setWindowKeepScreenOn<sup>9+</sup> 5404 5405setWindowKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 5406 5407Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 5408 5409Set **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. 5410 5411**System capability**: SystemCapability.WindowManager.WindowManager.Core 5412 5413**Atomic service API**: This API can be used in atomic services since API version 11. 5414 5415**Parameters** 5416 5417| Name| Type| Mandatory| Description| 5418| -------------- | ------------------------- | -- | ---------------------------------------------------- | 5419| 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. | 5420| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 5421 5422**Error codes** 5423 5424For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5425 5426| ID| Error Message| 5427| ------- | -------------------------------------------- | 5428| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5429| 1300002 | This window state is abnormal. | 5430| 1300003 | This window manager service works abnormally. | 5431 5432**Example** 5433 5434```ts 5435import { BusinessError } from '@kit.BasicServicesKit'; 5436 5437let isKeepScreenOn: boolean = true; 5438try { 5439 windowClass.setWindowKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 5440 const errCode: number = err.code; 5441 if (errCode) { 5442 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 5443 return; 5444 } 5445 console.info('Succeeded in setting the screen to be always on.'); 5446 }); 5447} catch (exception) { 5448 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 5449} 5450``` 5451 5452### setWindowKeepScreenOn<sup>9+</sup> 5453 5454setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 5455 5456Sets whether to keep the screen always on. This API uses a promise to return the result. 5457 5458Set **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. 5459 5460**System capability**: SystemCapability.WindowManager.WindowManager.Core 5461 5462**Atomic service API**: This API can be used in atomic services since API version 11. 5463 5464**Parameters** 5465 5466| Name| Type| Mandatory| Description| 5467| -------------- | ------- | -- | --------------------------------------------------- | 5468| 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.| 5469 5470**Return value** 5471 5472| Type| Description| 5473| ------------------- | ------------------------ | 5474| Promise<void> | Promise that returns no value.| 5475 5476**Error codes** 5477 5478For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5479 5480| ID| Error Message| 5481| ------- | -------------------------------------------- | 5482| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5483| 1300002 | This window state is abnormal. | 5484| 1300003 | This window manager service works abnormally. | 5485 5486**Example** 5487 5488```ts 5489import { BusinessError } from '@kit.BasicServicesKit'; 5490 5491let isKeepScreenOn: boolean = true; 5492try { 5493 let promise = windowClass.setWindowKeepScreenOn(isKeepScreenOn); 5494 promise.then(() => { 5495 console.info('Succeeded in setting the screen to be always on.'); 5496 }).catch((err: BusinessError) => { 5497 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 5498 }); 5499} catch (exception) { 5500 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 5501} 5502``` 5503 5504### setWindowPrivacyMode<sup>9+</sup> 5505 5506setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 5507 5508Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 5509 5510A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 5511 5512**System capability**: SystemCapability.WindowManager.WindowManager.Core 5513 5514**Atomic service API**: This API can be used in atomic services since API version 12. 5515 5516**Required permissions**: ohos.permission.PRIVACY_WINDOW 5517 5518**Parameters** 5519 5520| Name| Type| Mandatory| Description| 5521| ------------- | ------------------------- | -- | ------------------------------------------------------ | 5522| 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. | 5523| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 5524 5525**Error codes** 5526 5527For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5528 5529| ID| Error Message| 5530| ------- | ------------------------------ | 5531| 201 | Permission verification failed. The application does not have the permission required to call the API. | 5532| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5533| 1300002 | This window state is abnormal. | 5534 5535**Example** 5536 5537```ts 5538import { BusinessError } from '@kit.BasicServicesKit'; 5539 5540let isPrivacyMode: boolean = true; 5541try { 5542 windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => { 5543 const errCode: number = err.code; 5544 if (errCode) { 5545 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 5546 return; 5547 } 5548 console.info('Succeeded in setting the window to privacy mode.'); 5549 }); 5550} catch (exception) { 5551 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 5552} 5553``` 5554 5555### setWindowPrivacyMode<sup>9+</sup> 5556 5557setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 5558 5559Sets whether this window is in privacy mode. This API uses a promise to return the result. 5560 5561A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 5562 5563**System capability**: SystemCapability.WindowManager.WindowManager.Core 5564 5565**Atomic service API**: This API can be used in atomic services since API version 12. 5566 5567**Required permissions**: ohos.permission.PRIVACY_WINDOW 5568 5569**Parameters** 5570 5571| Name| Type| Mandatory| Description| 5572| ------------- | ------- | -- | ----------------------------------------------------- | 5573| 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.| 5574 5575**Return value** 5576 5577| Type| Description| 5578| ------------------- | ------------------------ | 5579| Promise<void> | Promise that returns no value.| 5580 5581**Error codes** 5582 5583For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5584 5585| ID| Error Message| 5586| ------- | ------------------------------ | 5587| 201 | Permission verification failed. The application does not have the permission required to call the API. | 5588| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5589| 1300002 | This window state is abnormal. | 5590 5591**Example** 5592 5593```ts 5594import { BusinessError } from '@kit.BasicServicesKit'; 5595 5596let isPrivacyMode: boolean = true; 5597try { 5598 let promise = windowClass.setWindowPrivacyMode(isPrivacyMode); 5599 promise.then(() => { 5600 console.info('Succeeded in setting the window to privacy mode.'); 5601 }).catch((err: BusinessError) => { 5602 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 5603 }); 5604} catch (exception) { 5605 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 5606} 5607``` 5608 5609### setWindowTouchable<sup>9+</sup> 5610 5611setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 5612 5613Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 5614 5615**Atomic service API**: This API can be used in atomic services since API version 12. 5616 5617**System capability**: SystemCapability.WindowManager.WindowManager.Core 5618 5619**Parameters** 5620 5621| Name| Type| Mandatory| Description| 5622| ----------- | ------------------------- | -- | ----------------------------------------------- | 5623| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 5624| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 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| 1300002 | This window state is abnormal. | 5634| 1300003 | This window manager service works abnormally. | 5635 5636**Example** 5637 5638```ts 5639import { BusinessError } from '@kit.BasicServicesKit'; 5640 5641let isTouchable = true; 5642try { 5643 windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => { 5644 const errCode: number = err.code; 5645 if (errCode) { 5646 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 5647 return; 5648 } 5649 console.info('Succeeded in setting the window to be touchable.'); 5650 }); 5651} catch (exception) { 5652 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 5653} 5654``` 5655 5656### setWindowTouchable<sup>9+</sup> 5657 5658setWindowTouchable(isTouchable: boolean): Promise<void> 5659 5660Sets whether this window is touchable. This API uses a promise to return the result. 5661 5662**Atomic service API**: This API can be used in atomic services since API version 12. 5663 5664**System capability**: SystemCapability.WindowManager.WindowManager.Core 5665 5666**Parameters** 5667 5668| Name| Type| Mandatory| Description| 5669| ----------- | ------- | -- | ----------------------------------------------- | 5670| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 5671 5672**Return value** 5673 5674| Type| Description| 5675| ------------------- | ------------------------- | 5676| Promise<void> | Promise that returns no value.| 5677 5678**Error codes** 5679 5680For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5681 5682| ID| Error Message| 5683| ------- | -------------------------------------------- | 5684| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5685| 1300002 | This window state is abnormal. | 5686| 1300003 | This window manager service works abnormally. | 5687 5688**Example** 5689 5690```ts 5691import { BusinessError } from '@kit.BasicServicesKit'; 5692 5693let isTouchable: boolean = true; 5694try { 5695 let promise = windowClass.setWindowTouchable(isTouchable); 5696 promise.then(() => { 5697 console.info('Succeeded in setting the window to be touchable.'); 5698 }).catch((err: BusinessError) => { 5699 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 5700 }); 5701} catch (exception) { 5702 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 5703} 5704``` 5705 5706### snapshot<sup>9+</sup> 5707 5708snapshot(callback: AsyncCallback<image.PixelMap>): void 5709 5710Captures this window. This API uses an asynchronous callback to return the result. 5711 5712**Atomic service API**: This API can be used in atomic services since API version 12. 5713 5714**System capability**: SystemCapability.WindowManager.WindowManager.Core 5715 5716**Parameters** 5717 5718| Name | Type | Mandatory | Description | 5719| -------- | ------------------------------------------------------------ | --------- | ----------------------------------- | 5720| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. | 5721 5722**Error codes** 5723 5724For details about the error codes, see [Window Error Codes](errorcode-window.md). 5725 5726| ID | Error Message | 5727| ------- | ------------------------------ | 5728| 1300002 | This window state is abnormal. | 5729 5730**Example** 5731 5732```ts 5733import { BusinessError } from '@kit.BasicServicesKit'; 5734import { image } from '@kit.ImageKit'; 5735 5736windowClass.snapshot((err: BusinessError, pixelMap: image.PixelMap) => { 5737 const errCode: number = err.code; 5738 if (errCode) { 5739 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 5740 return; 5741 } 5742 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 5743 pixelMap.release(); // Release the memory in time after the PixelMap is used. 5744}); 5745``` 5746 5747### snapshot<sup>9+</sup> 5748 5749snapshot(): Promise<image.PixelMap> 5750 5751Captures this window. This API uses a promise to return the result. 5752 5753**Atomic service API**: This API can be used in atomic services since API version 12. 5754 5755**System capability**: SystemCapability.WindowManager.WindowManager.Core 5756 5757**Return value** 5758 5759| Type | Description | 5760| ------------------------------------------------------------ | --------------------------------------------- | 5761| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot. | 5762 5763**Error codes** 5764 5765For details about the error codes, see [Window Error Codes](errorcode-window.md). 5766 5767| ID | Error Message | 5768| ------- | ------------------------------ | 5769| 1300002 | This window state is abnormal. | 5770 5771**Example** 5772 5773```ts 5774import { BusinessError } from '@kit.BasicServicesKit'; 5775import { image } from '@kit.ImageKit'; 5776 5777let promise = windowClass.snapshot(); 5778promise.then((pixelMap: image.PixelMap) => { 5779 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 5780 pixelMap.release(); // Release the memory in time after the PixelMap is used. 5781}).catch((err: BusinessError) => { 5782 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 5783}); 5784``` 5785 5786### setAspectRatio<sup>10+</sup> 5787 5788setAspectRatio(ratio: number): Promise<void> 5789 5790Sets the aspect ratio of the window content layout. This API uses a promise to return the result. 5791 5792When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**. 5793 5794This 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. 5795 5796**Atomic service API**: This API can be used in atomic services since API version 12. 5797 5798**System capability**: SystemCapability.WindowManager.WindowManager.Core 5799 5800**Parameters** 5801 5802| Name | Type | Mandatory | Description | 5803| ----- | ------ | --------- | ------------------------------------------------------------ | 5804| 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**. | 5805 5806**Return value** 5807 5808| Type | Description | 5809| ------------------- | ------------------------------ | 5810| Promise<void> | Promise that returns no value. | 5811 5812**Error codes** 5813 5814For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5815 5816| ID | Error Message | 5817| ------- | ------------------------------------------------------------ | 5818| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5819| 1300002 | This window state is abnormal. | 5820| 1300004 | Unauthorized operation. | 5821 5822**Example** 5823<!--code_no_check--> 5824 5825```ts 5826// EntryAbility.ets 5827import { UIAbility } from '@kit.AbilityKit'; 5828import { BusinessError } from '@kit.BasicServicesKit'; 5829 5830export default class EntryAbility extends UIAbility { 5831 5832 // ... 5833 onWindowStageCreate(windowStage: window.WindowStage) { 5834 console.info('onWindowStageCreate'); 5835 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5836 if (!windowClass) { 5837 console.info('windowClass is null'); 5838 } 5839 try { 5840 let ratio = 1.0; 5841 let promise = windowClass.setAspectRatio(ratio); 5842 promise.then(() => { 5843 console.info('Succeeded in setting aspect ratio of window.'); 5844 }).catch((err: BusinessError) => { 5845 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5846 }); 5847 } catch (exception) { 5848 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5849 } 5850 } 5851} 5852``` 5853 5854### setAspectRatio<sup>10+</sup> 5855 5856setAspectRatio(ratio: number, callback: AsyncCallback<void>): void 5857 5858Sets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 5859 5860When the window size is set by using other APIs such as [resize](#resize9) and [resizeAsync](#resizeasync12), the window size is not restricted by **ratio**. 5861 5862This 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. 5863 5864**Atomic service API**: This API can be used in atomic services since API version 12. 5865 5866**System capability**: SystemCapability.WindowManager.WindowManager.Core 5867 5868**Parameters** 5869 5870| Name | Type | Mandatory | Description | 5871| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 5872| 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**. | 5873| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 5874 5875**Error codes** 5876 5877For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5878 5879| ID | Error Message | 5880| ------- | ------------------------------------------------------------ | 5881| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5882| 1300002 | This window state is abnormal. | 5883| 1300004 | Unauthorized operation. | 5884 5885**Example** 5886<!--code_no_check--> 5887```ts 5888// EntryAbility.ets 5889import { UIAbility } from '@kit.AbilityKit'; 5890import { BusinessError } from '@kit.BasicServicesKit'; 5891 5892export default class EntryAbility extends UIAbility { 5893 5894 // ... 5895 onWindowStageCreate(windowStage: window.WindowStage) { 5896 console.info('onWindowStageCreate'); 5897 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5898 if (!windowClass) { 5899 console.info('Failed to load the content. Cause: windowClass is null'); 5900 } 5901 try { 5902 let ratio = 1.0; 5903 windowClass.setAspectRatio(ratio, (err: BusinessError) => { 5904 const errCode: number = err.code; 5905 if (errCode) { 5906 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5907 return; 5908 } 5909 console.info('Succeeded in setting the aspect ratio of window.'); 5910 }); 5911 } catch (exception) { 5912 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5913 } 5914 } 5915} 5916 5917``` 5918 5919### resetAspectRatio<sup>10+</sup> 5920 5921resetAspectRatio(): Promise<void> 5922 5923Resets the aspect ratio of the window content layout. This API uses a promise to return the result. 5924 5925This 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. 5926 5927**Atomic service API**: This API can be used in atomic services since API version 12. 5928 5929**System capability**: SystemCapability.WindowManager.WindowManager.Core 5930 5931**Return value** 5932 5933| Type | Description | 5934| ------------------- | ------------------------------ | 5935| Promise<void> | Promise that returns no value. | 5936 5937**Error codes** 5938 5939For details about the error codes, see [Window Error Codes](errorcode-window.md). 5940 5941| ID | Error Message | 5942| ------- | ------------------------------ | 5943| 1300002 | This window state is abnormal. | 5944| 1300004 | Unauthorized operation. | 5945 5946**Example** 5947<!--code_no_check--> 5948```ts 5949// EntryAbility.ets 5950import { UIAbility } from '@kit.AbilityKit'; 5951import { BusinessError } from '@kit.BasicServicesKit'; 5952 5953export default class EntryAbility extends UIAbility { 5954 5955 // ... 5956 onWindowStageCreate(windowStage: window.WindowStage) { 5957 console.info('onWindowStageCreate'); 5958 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5959 if (!windowClass) { 5960 console.info('Failed to load the content. Cause: windowClass is null'); 5961 } 5962 try { 5963 let promise = windowClass.resetAspectRatio(); 5964 promise.then(() => { 5965 console.info('Succeeded in resetting aspect ratio of window.'); 5966 }).catch((err: BusinessError) => { 5967 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5968 }); 5969 } catch (exception) { 5970 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5971 } 5972 } 5973} 5974``` 5975 5976### resetAspectRatio<sup>10+</sup> 5977 5978resetAspectRatio(callback: AsyncCallback<void>): void 5979 5980Resets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 5981 5982This 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. 5983 5984**Atomic service API**: This API can be used in atomic services since API version 12. 5985 5986**System capability**: SystemCapability.WindowManager.WindowManager.Core 5987 5988**Parameters** 5989 5990| Name | Type | Mandatory | Description | 5991| -------- | ------------------------- | --------- | ----------------------------------- | 5992| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 5993 5994**Error codes** 5995 5996For details about the error codes, see [Window Error Codes](errorcode-window.md). 5997 5998| ID | Error Message | 5999| ------- | ------------------------------ | 6000| 1300002 | This window state is abnormal. | 6001| 1300004 | Unauthorized operation. | 6002 6003**Example** 6004<!--code_no_check--> 6005```ts 6006// EntryAbility.ets 6007import { UIAbility } from '@kit.AbilityKit'; 6008import { BusinessError } from '@kit.BasicServicesKit'; 6009 6010export default class EntryAbility extends UIAbility { 6011 6012 // ... 6013 onWindowStageCreate(windowStage: window.WindowStage) { 6014 console.info('onWindowStageCreate'); 6015 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 6016 if (!windowClass) { 6017 console.info('Failed to load the content. Cause: windowClass is null'); 6018 } 6019 try { 6020 windowClass.resetAspectRatio((err: BusinessError) => { 6021 const errCode: number = err.code; 6022 if (errCode) { 6023 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 6024 return; 6025 } 6026 console.info('Succeeded in resetting aspect ratio of window.'); 6027 }); 6028 } catch (exception) { 6029 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 6030 } 6031 } 6032} 6033``` 6034 6035### minimize<sup>11+</sup> 6036 6037minimize(callback: AsyncCallback<void>): void 6038 6039The behavior of this API varies based on the caller: 6040 6041- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. 6042 6043- Hides the child window if the caller is a child window. The child window cannot be restored in the dock bar. 6044 6045This API uses an asynchronous callback to return the result. 6046 6047**Atomic service API**: This API can be used in atomic services since API version 12. 6048 6049**System capability**: SystemCapability.Window.SessionManager 6050 6051**Parameters** 6052 6053| Name | Type | Mandatory | Description | 6054| -------- | ------------------------- | --------- | ----------------------------------- | 6055| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6056 6057**Error codes** 6058 6059For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6060 6061| ID | Error Message | 6062| ------- | ------------------------------------------------------------ | 6063| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6064| 1300002 | This window state is abnormal. | 6065| 1300003 | This window manager service works abnormally. | 6066 6067**Example** 6068 6069```ts 6070import { BusinessError } from '@kit.BasicServicesKit'; 6071 6072windowClass.minimize((err: BusinessError) => { 6073 const errCode: number = err.code; 6074 if (errCode) { 6075 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 6076 return; 6077 } 6078 console.info('Succeeded in minimizing the window.'); 6079}); 6080``` 6081 6082### minimize<sup>11+</sup> 6083 6084minimize(): Promise<void> 6085 6086The behavior of this API varies based on the caller: 6087 6088- Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. 6089 6090- Hides the child window if the caller is a child window. The child window cannot be restored in the dock bar. 6091 6092This API uses a promise to return the result. 6093 6094**Atomic service API**: This API can be used in atomic services since API version 12. 6095 6096**System capability**: SystemCapability.Window.SessionManager 6097 6098**Return value** 6099 6100| Type | Description | 6101| ------------------- | ------------------------------ | 6102| Promise<void> | Promise that returns no value. | 6103 6104**Error codes** 6105 6106For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6107 6108| ID | Error Message | 6109| ------- | ------------------------------------------------------------ | 6110| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6111| 1300002 | This window state is abnormal. | 6112| 1300003 | This window manager service works abnormally. | 6113 6114**Example** 6115 6116```ts 6117import { BusinessError } from '@kit.BasicServicesKit'; 6118 6119let promise = windowClass.minimize(); 6120promise.then(() => { 6121 console.info('Succeeded in minimizing the window.'); 6122}).catch((err: BusinessError) => { 6123 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 6124}); 6125``` 6126 6127### maximize<sup>12+</sup> 6128maximize(presentation?: MaximizePresentation): Promise<void> 6129 6130Maximizes the main window. This API uses a promise to return the result. 6131 6132<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 6133 6134**Atomic service API**: This API can be used in atomic services since API version 12. 6135 6136**System capability**: SystemCapability.Window.SessionManager 6137 6138**Parameters** 6139 6140| Name | Type | Mandatory | Description | 6141| ------------ | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 6142| 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. | 6143 6144**Return value** 6145 6146| Type | Description | 6147| ------------------- | ------------------------------ | 6148| Promise<void> | Promise that returns no value. | 6149 6150**Error codes** 6151 6152For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6153 6154| ID | Error Message | 6155| ------- | ------------------------------------------------------------ | 6156| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6157| 1300002 | This window state is abnormal. | 6158| 1300003 | This window manager service works abnormally. | 6159| 1300004 | Unauthorized operation. | 6160| 1300005 | This window stage is abnormal. | 6161 6162**Example** 6163 6164```ts 6165// EntryAbility.ets 6166import { UIAbility } from '@kit.AbilityKit'; 6167import { BusinessError } from '@kit.BasicServicesKit'; 6168export default class EntryAbility extends UIAbility { 6169 // ... 6170 6171 onWindowStageCreate(windowStage: window.WindowStage) { 6172 console.info('onWindowStageCreate'); 6173 let windowClass: window.Window | undefined = undefined; 6174 windowStage.getMainWindow((err: BusinessError, data) => { 6175 const errCode: number = err.code; 6176 if (errCode) { 6177 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6178 return; 6179 } 6180 windowClass = data; 6181 let promise = windowClass.maximize(); 6182 // let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 6183 promise.then(() => { 6184 console.info('Succeeded in maximizing the window.'); 6185 }).catch((err: BusinessError) => { 6186 console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`); 6187 }); 6188 }); 6189 } 6190}; 6191``` 6192 6193### setResizeByDragEnabled<sup>14+</sup> 6194setResizeByDragEnabled(enable: boolean, callback: AsyncCallback<void>): void 6195 6196Sets whether to enable the main window or child window with decorations to resize itself by dragging. This API uses an asynchronous callback to return the result. 6197 6198**Atomic service API**: This API can be used in atomic services since API version 14. 6199 6200**System capability**: SystemCapability.Window.SessionManager 6201 6202**Parameters** 6203 6204| Name | Type | Mandatory | Description | 6205| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 6206| 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. | 6207| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6208 6209**Error codes** 6210 6211For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6212 6213| ID | Error Message | 6214| ------- | ------------------------------------------------------------ | 6215| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6216| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6217| 1300002 | This window state is abnormal. | 6218| 1300003 | This window manager service works abnormally. | 6219 6220**Example** 6221 6222```ts 6223import { BusinessError } from '@kit.BasicServicesKit'; 6224 6225let enabled = false; 6226windowClass.setResizeByDragEnabled(enabled, (err) => { 6227 if (err.code) { 6228 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 6229 return; 6230 } 6231 console.info('Succeeded in setting the function of disabling the resize by drag window.'); 6232}); 6233``` 6234 6235### setResizeByDragEnabled<sup>14+</sup> 6236setResizeByDragEnabled(enable: boolean): Promise<void> 6237 6238Sets whether to enable the main window or child window with decorations to resize itself by dragging. This API uses a promise to return the result. 6239 6240**Atomic service API**: This API can be used in atomic services since API version 14. 6241 6242**System capability**: SystemCapability.Window.SessionManager 6243 6244**Parameters** 6245 6246| Name | Type | Mandatory | Description | 6247| ------ | ------- | --------- | ------------------------------------------------------------ | 6248| 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. | 6249 6250**Return value** 6251 6252| Type | Description | 6253| ------------------- | ------------------------------ | 6254| Promise<void> | Promise that returns no value. | 6255 6256**Error codes** 6257 6258For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6259 6260| ID | Error Message | 6261| ------- | ------------------------------------------------------------ | 6262| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6263| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6264| 1300002 | This window state is abnormal. | 6265| 1300003 | This window manager service works abnormally. | 6266 6267**Example** 6268 6269```ts 6270import { BusinessError } from '@kit.BasicServicesKit'; 6271 6272let enabled = false; 6273let promise = windowClass.setResizeByDragEnabled(enabled); 6274promise.then(() => { 6275 console.info('Succeeded in setting the function of disabling the resize by drag window.'); 6276}).catch((err: BusinessError) => { 6277 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 6278}); 6279``` 6280 6281### recover<sup>11+</sup> 6282 6283recover(): Promise<void> 6284 6285Restores 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. 6286 6287<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 6288 6289**Atomic service API**: This API can be used in atomic services since API version 12. 6290 6291**System capability**: SystemCapability.Window.SessionManager 6292 6293**Return value** 6294 6295| Type | Description | 6296| ------------------- | ------------------------------ | 6297| Promise<void> | Promise that returns no value. | 6298 6299**Error codes** 6300 6301For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6302 6303| ID | Error Message | 6304| ------- | ------------------------------------------------------------ | 6305| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6306| 1300001 | Repeated operation. | 6307| 1300002 | This window state is abnormal. | 6308 6309**Example** 6310 6311```ts 6312// EntryAbility.ets 6313import { UIAbility } from '@kit.AbilityKit'; 6314import { BusinessError } from '@kit.BasicServicesKit'; 6315 6316export default class EntryAbility extends UIAbility { 6317 // ... 6318 onWindowStageCreate(windowStage: window.WindowStage): void { 6319 console.info('onWindowStageCreate'); 6320 let windowClass: window.Window | undefined = undefined; 6321 windowStage.getMainWindow((err: BusinessError, data) => { 6322 const errCode: number = err.code; 6323 if (errCode) { 6324 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6325 return; 6326 } 6327 windowClass = data; 6328 let promise = windowClass.recover(); 6329 promise.then(() => { 6330 console.info('Succeeded in recovering the window.'); 6331 }).catch((err: BusinessError) => { 6332 console.error(`Failed to recover the window. Cause code: ${err.code}, message: ${err.message}`); 6333 }); 6334 }); 6335 } 6336} 6337``` 6338 6339### restore<sup>14+</sup> 6340 6341restore(): Promise<void> 6342 6343Restores 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. 6344 6345This API takes effect only in the multi-window stack layout when the main window is minimized and the UIAbility is in the **onForeground** state. 6346 6347<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 6348 6349**Atomic service API**: This API can be used in atomic services since API version 14. 6350 6351**System capability**: SystemCapability.Window.SessionManager 6352 6353**Return value** 6354 6355| Type | Description | 6356| ------------------- | ------------------------------ | 6357| Promise<void> | Promise that returns no value. | 6358 6359**Error codes** 6360 6361For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6362 6363| **ID** | **Error Message** | 6364| ------- | ------------------------------------------------------------ | 6365| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6366| 1300002 | This window state is abnormal. | 6367| 1300003 | This window manager service works abnormally. | 6368| 1300004 | Unauthorized operation. | 6369 6370**Example** 6371 6372```ts 6373// EntryAbility.ets 6374import { UIAbility } from '@kit.AbilityKit'; 6375import { BusinessError } from '@kit.BasicServicesKit'; 6376import { window } from '@kit.ArkUI'; 6377import { BusinessError } from '@kit.BasicServicesKit'; 6378 6379export default class EntryAbility extends UIAbility { 6380 onWindowStageCreate(windowStage: window.WindowStage): void { 6381 // Load the page corresponding to the main window. 6382 windowStage.loadContent('pages/Index', (err) => { 6383 let mainWindow: window.Window | undefined = undefined; 6384 // Obtain the main window. 6385 windowStage.getMainWindow().then( 6386 data => { 6387 mainWindow = data; 6388 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 6389 // Call minimize() to minimize the main window. 6390 mainWindow.minimize(); 6391 // Set the delay function to restore the main window after a delay of 5 seconds. 6392 setTimeout(()=>{ 6393 // Call restore() to restore the main window. 6394 let promise = mainWindow.restore(); 6395 promise.then(() => { 6396 console.info('Succeeded in restoring the window.'); 6397 }).catch((err: BusinessError) => { 6398 console.error(`Failed to restore the window. Cause code: ${err.code}, 6399 message: ${err.message}`); 6400 }); 6401 },5000); 6402 } 6403 ).catch((err: BusinessError) => { 6404 if(err.code){ 6405 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6406 } 6407 }); 6408 }); 6409 } 6410} 6411``` 6412 6413### getWindowLimits<sup>11+</sup> 6414 6415getWindowLimits(): WindowLimits 6416 6417Obtains the size limits of this application window. 6418 6419**Atomic service API**: This API can be used in atomic services since API version 12. 6420 6421**System capability**: SystemCapability.Window.SessionManager 6422 6423**Return value** 6424 6425| Type | Description | 6426| ------------------------------- | ------------------- | 6427| [WindowLimits](#windowlimits11) | Window size limits. | 6428 6429**Error codes** 6430 6431For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6432 6433| ID | Error Message | 6434| :------ | :----------------------------------------------------------- | 6435| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6436| 1300002 | This window state is abnormal. | 6437 6438**Example** 6439 6440```ts 6441try { 6442 let windowLimits = windowClass.getWindowLimits(); 6443} catch (exception) { 6444 console.error(`Failed to obtain the window limits of window. Cause code: ${exception.code}, message: ${exception.message}`); 6445} 6446``` 6447 6448### setWindowLimits<sup>11+</sup> 6449 6450setWindowLimits(windowLimits: WindowLimits): Promise<WindowLimits> 6451 6452Sets the size limits for this application window. This API uses a promise to return the result. 6453By 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. 6454 6455**Atomic service API**: This API can be used in atomic services since API version 12. 6456 6457**System capability**: SystemCapability.Window.SessionManager 6458 6459**Parameters** 6460 6461| Name | Type | Mandatory | Description | 6462| :----------- | :------------------------------ | :-------- | :------------------------- | 6463| windowLimits | [WindowLimits](#windowlimits11) | Yes | Target size limits, in px. | 6464 6465**Return value** 6466 6467| Type | Description | 6468| :--------------------------------------------- | :----------------------------------------------------------- | 6469| 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. | 6470 6471**Error codes** 6472 6473For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6474 6475| ID | Error Message | 6476| :------ | :----------------------------------------------------------- | 6477| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6478| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6479| 1300002 | This window state is abnormal. | 6480| 1300003 | This window manager service works abnormally. | 6481| 1300004 | Unauthorized operation. | 6482 6483**Example** 6484 6485```ts 6486import { BusinessError } from '@kit.BasicServicesKit'; 6487try { 6488 let windowLimits: window.WindowLimits = { 6489 maxWidth: 1500, 6490 maxHeight: 1000, 6491 minWidth: 500, 6492 minHeight: 400 6493 }; 6494 let promise = windowClass.setWindowLimits(windowLimits); 6495 promise.then((data) => { 6496 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 6497 }).catch((err: BusinessError) => { 6498 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 6499 }); 6500} catch (exception) { 6501 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 6502} 6503``` 6504 6505### setWindowLimits<sup>15+</sup> 6506 6507setWindowLimits(windowLimits: WindowLimits, isForcible: boolean): Promise<WindowLimits> 6508 6509Sets the size limits for this application window. This API uses a promise to return the result. 6510 6511By 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. 6512 6513This API can be used only on 2-in-1 devices. 6514 6515**Atomic service API**: This API can be used in atomic services since API version 15. 6516 6517**System capability**: SystemCapability.Window.SessionManager 6518 6519**Parameters** 6520 6521| Name | Type | Mandatory | Description | 6522| :----------- | :------------------------------ | :-------- | :----------------------------------------------------------- | 6523| windowLimits | [WindowLimits](#windowlimits11) | Yes | Target size limits, in px. | 6524| isForcible | boolean | Yes | Whether to forcibly set the window size limits.<br>If this parameter is set to **true**, the minimum width and height of the window are determined by the lower value between the system size limits and 40 vp, and the maximum width and height depend on the system size limits.<br>If this parameter is set to **false**, the minimum and maximum window width and height are restricted by the system size limits. | 6525 6526**Return value** 6527 6528| Type | Description | 6529| :--------------------------------------------- | :----------------------------------------------------------- | 6530| Promise<[WindowLimits](#windowlimits11)> | Promise used to return the new window size limits. Depending on the value of **isForcible**, the return value represents the intersection between the value passed and the system size limits. | 6531 6532**Error codes** 6533 6534For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6535 6536| ID | Error Message | 6537| :------ | :----------------------------------------------------------- | 6538| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6539| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6540| 1300002 | This window state is abnormal. | 6541| 1300003 | This window manager service works abnormally. | 6542| 1300004 | Unauthorized operation. | 6543 6544**Example** 6545 6546```ts 6547import { BusinessError } from '@kit.BasicServicesKit'; 6548try { 6549 let windowLimits: window.WindowLimits = { 6550 maxWidth: 1500, 6551 maxHeight: 1000, 6552 minWidth: 100, 6553 minHeight: 100 6554 }; 6555 let promise = windowClass.setWindowLimits(windowLimits, true); 6556 promise.then((data) => { 6557 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 6558 }).catch((err: BusinessError) => { 6559 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 6560 }); 6561} catch (exception) { 6562 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 6563} 6564``` 6565 6566### setWindowMask<sup>12+</sup> 6567 6568setWindowMask(windowMask: Array<Array<number>>): Promise<void>; 6569 6570Sets a mask for this window to get an irregularly shaped window. This API uses a promise to return the result. 6571 6572The mask is used to describe the shape of the irregularly shaped window. 6573 6574This API is available only for child windows and global floating windows. 6575 6576When the size of an irregularly shaped window changes, the actual display content is the intersection of the mask size and the window size. 6577 6578<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 6579 6580**Atomic service API**: This API can be used in atomic services since API version 12. 6581 6582**System capability**: SystemCapability.Window.SessionManager 6583 6584**Parameters** 6585 6586| Name | Type | Mandatory | Description | 6587| :--------- | :------------------------------- | :-------- | :----------------------------------------------------------- | 6588| 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. | 6589 6590**Return value** 6591 6592| Type | Description | 6593| :------------------ | :----------------------------- | 6594| Promise<void> | Promise that returns no value. | 6595 6596**Error codes** 6597 6598For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6599 6600| ID | Error Message | 6601| :------ | :----------------------------------------------------------- | 6602| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6603| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6604| 1300002 | This window state is abnormal. | 6605| 1300003 | This window manager service works abnormally. | 6606| 1300004 | Unauthorized operation. | 6607 6608**Example** 6609 6610```ts 6611import { BusinessError } from '@kit.BasicServicesKit'; 6612try { 6613 let windowMask: Array<Array<number>> = [ 6614 [0, 0, 0, 1, 0, 0, 0], 6615 [0, 0, 1, 1, 1, 0, 0], 6616 [0, 1, 1, 0, 1, 1, 0], 6617 [1, 1, 0, 0, 0, 1, 1] 6618 ]; 6619 let promise = windowClass.setWindowMask(windowMask); 6620 promise.then(() => { 6621 console.info('Succeeded in setting the window mask.'); 6622 }).catch((err: BusinessError) => { 6623 console.error(`Failed to set the window mask. Cause code: ${err.code}, message: ${err.message}`); 6624 }); 6625} catch (exception) { 6626 console.error(`Failed to set the window mask. Cause code: ${exception.code}, message: ${exception.message}`); 6627} 6628``` 6629 6630### keepKeyboardOnFocus<sup>11+</sup> 6631 6632keepKeyboardOnFocus(keepKeyboardFlag: boolean): void 6633 6634Sets whether to keep the soft keyboard created by others when a window has focus. This API can be called only by a system window or an application child window. 6635 6636**Atomic service API**: This API can be used in atomic services since API version 12. 6637 6638**System capability**: SystemCapability.Window.SessionManager 6639 6640**Parameters** 6641 6642| Name | Type | Mandatory | Description | 6643| ---------------- | ------- | --------- | ------------------------------------------------------------ | 6644| 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. | 6645 6646**Error codes** 6647 6648For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6649 6650| ID | Error Message | 6651| ------- | ------------------------------------------------------------ | 6652| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6653| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6654| 1300002 | This window state is abnormal. | 6655| 1300004 | Unauthorized operation. | 6656 6657**Example** 6658 6659```ts 6660try { 6661 windowClass.keepKeyboardOnFocus(true); 6662} catch (exception) { 6663 console.error(`Failed to keep keyboard onFocus. Cause code: ${exception.code}, message: ${exception.message}`); 6664} 6665``` 6666 6667### setWindowDecorVisible<sup>11+</sup> 6668 6669setWindowDecorVisible(isVisible: boolean): void 6670 6671Sets 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. 6672 6673When 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). 6674 6675**Atomic service API**: This API can be used in atomic services since API version 12. 6676 6677**System capability**: SystemCapability.Window.SessionManager 6678 6679**Parameters** 6680 6681| Name | Type | Mandatory | Description | 6682| --------- | ------- | --------- | ------------------------------------------------------------ | 6683| isVisible | boolean | Yes | Whether the title bar is visible. The value **true** means that the title bar is visible and **false** means the opposite. | 6684 6685**Error codes** 6686 6687For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6688 6689| ID | Error Message | 6690| ------- | ------------------------------------------------------------ | 6691| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6692| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6693| 1300002 | This window state is abnormal. | 6694| 1300004 | Unauthorized operation. | 6695 6696**Example** 6697 6698```ts 6699import { BusinessError } from '@kit.BasicServicesKit'; 6700let storage: LocalStorage = new LocalStorage(); 6701storage.setOrCreate('storageSimpleProp', 121); 6702windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 6703 let errCode: number = err.code; 6704 if (errCode) { 6705 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 6706 return; 6707 } 6708 console.info('Succeeded in loading the content.'); 6709 let isVisible = false; 6710 // Call setWindowDecorVisible. 6711 try { 6712 windowClass?.setWindowDecorVisible(isVisible); 6713 } catch (exception) { 6714 console.error(`Failed to set the visibility of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 6715 } 6716}); 6717``` 6718 6719### setWindowTitle<sup>15+</sup> 6720 6721setWindowTitle(titleName: string): Promise<void> 6722 6723Sets the window title. This API uses a promise to return the result. The setting takes effect for a window with a title bar. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 6724 6725This API can be used only 2-in-1 devices and tablets. 6726 6727**Atomic service API**: This API can be used in atomic services since API version 15. 6728 6729**System capability**: SystemCapability.Window.SessionManager 6730 6731**Parameters** 6732 6733| Name | Type | Mandatory | Description | 6734| --------- | ------ | --------- | ------------- | 6735| titleName | string | Yes | Window title. | 6736 6737**Return value** 6738 6739| Type | Description | 6740| ------------------- | ------------------------------ | 6741| Promise<void> | Promise that returns no value. | 6742 6743**Error codes** 6744 6745For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6746 6747| ID | Error Message | 6748| ------- | ------------------------------------------------------------ | 6749| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6750| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6751| 1300002 | This window state is abnormal. | 6752 6753**Example** 6754 6755```ts 6756import { window } from '@kit.ArkUI'; 6757import { BusinessError } from '@kit.BasicServicesKit'; 6758 6759let windowClass: window.Window | undefined = undefined; 6760try { 6761 let promise = window.getLastWindow(this.context); 6762 promise.then((data) => { 6763 windowClass = data; 6764 let title = "title"; 6765 windowClass.setWindowTitle(title).then(() => { 6766 console.info('Succeeded in setting the window title.'); 6767 }).catch((err: BusinessError) => { 6768 console.error(`Failed to set the window title. Cause code: ${err.code}, message: ${err.message}`); 6769 }); 6770 }).catch((err: BusinessError) => { 6771 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 6772 }); 6773} catch (exception) { 6774 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 6775} 6776``` 6777 6778### setWindowTitleMoveEnabled<sup>14+</sup> 6779 6780setWindowTitleMoveEnabled(enabled: boolean): void 6781 6782Enables or disables the capability to move the window (either main window or child window) by dragging its title bar and to maximize the window with a double-click. When this capability is disabled, you can use [startMoving()](#startmoving14) to move the window by dragging in the application's hot zone and use [maximize()](#maximize12) to maximize the window. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 6783 6784<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 6785 6786**Atomic service API**: This API can be used in atomic services since API version 14. 6787 6788**System capability**: SystemCapability.Window.SessionManager 6789 6790**Parameters** 6791 6792| Name | Type | Mandatory | Description | 6793| ------- | ------- | --------- | ------------------------------------------------------------ | 6794| enabled | boolean | Yes | Whether to enable the capability to move the window by dragging the title bar and to maximize the window with a double-click. The value **true** means to enable the capability, and **false** means the opposite. | 6795 6796**Error codes** 6797 6798For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6799 6800| ID | Error Message | 6801| ------- | ------------------------------------------------------------ | 6802| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6803| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6804| 1300002 | This window state is abnormal. | 6805| 1300004 | Unauthorized operation. | 6806 6807**Example** 6808 6809```ts 6810windowClass.setUIContent('pages/WindowPage').then(() => { 6811 try { 6812 let enabled = false; 6813 windowClass.setWindowTitleMoveEnabled(enabled); 6814 } catch (exception) { 6815 console.error(`Failed to set the window title move enabled. Cause code: ${exception.code}, message: ${exception.message}`); 6816 } 6817}) 6818``` 6819 6820### setSubWindowModal<sup>12+</sup> 6821 6822setSubWindowModal(isModal: boolean): Promise<void> 6823 6824Enables the modal property of the child window. This API uses a promise to return the result. 6825 6826This API must be called by a child window and the setting takes effect for the child window. 6827 6828 After the modal property is enabled, the parent window does not respond to user interactions until the child window is closed or the child window's modal property is disabled. 6829 6830If this API is called by a main window, an error is reported. 6831 6832**Atomic service API**: This API can be used in atomic services since API version 12. 6833 6834**System capability**: SystemCapability.Window.SessionManager 6835 6836**Parameters** 6837 6838| Name | Type | Mandatory | Description | 6839| ------- | ------- | --------- | ------------------------------------------------------------ | 6840| isModal | boolean | Yes | Whether to enable the modal property of the child window. The value **true** means to enable the modal property, and **false** means the opposite. | 6841 6842 6843**Return value** 6844 6845| Type | Description | 6846| ------------------- | ------------------------------ | 6847| Promise<void> | Promise that returns no value. | 6848 6849**Error codes** 6850 6851For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6852 6853| ID | Error Message | 6854| ------- | ------------------------------------------------------------ | 6855| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6856| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6857| 1300002 | This window state is abnormal. | 6858| 1300004 | Unauthorized operation. | 6859 6860**Example** 6861 6862```ts 6863// EntryAbility.ets 6864import { UIAbility } from '@kit.AbilityKit'; 6865import { BusinessError } from '@kit.BasicServicesKit'; 6866 6867export default class EntryAbility extends UIAbility { 6868 // ... 6869 onWindowStageCreate(windowStage: window.WindowStage): void { 6870 console.info('onWindowStageCreate'); 6871 let windowClass: window.Window | undefined = undefined; 6872 // Create a child window. 6873 try { 6874 let subWindow = windowStage.createSubWindow("testSubWindow"); 6875 subWindow.then((data) => { 6876 if (data == null) { 6877 console.error("Failed to create the subWindow. Cause: The data is empty"); 6878 return; 6879 } 6880 windowClass = data; 6881 let promise = windowClass.setSubWindowModal(true); 6882 promise.then(() => { 6883 console.info('Succeeded in setting subwindow modal'); 6884 }).catch((err: BusinessError) => { 6885 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 6886 }); 6887 }); 6888 } catch (exception) { 6889 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 6890 } 6891 } 6892} 6893``` 6894 6895### setSubWindowModal<sup>14+</sup> 6896 6897setSubWindowModal(isModal: boolean, modalityType: ModalityType): Promise<void> 6898 6899Sets the modality type of the child window. This API uses a promise to return the result. 6900 6901When the child window is of the window-modal type, its parent window does not respond to user interactions until the child window is closed or the child window's modal property is disabled. 6902 6903When the child window is of the application-modal type, its parent window and the windows from other instances of the application do not respond to user interactions until the child window is closed or the child window's modal property is disabled. 6904 6905This API is used to set the modality type. To disable the modal property, you are advised to use [setSubWindowModal<sup>12+</sup>](#setsubwindowmodal12). 6906 6907If this API is called by a main window, an error is reported. 6908 6909**Atomic service API**: This API can be used in atomic services since API version 14. 6910 6911**System capability**: SystemCapability.Window.SessionManager 6912 6913**Parameters** 6914 6915| Name | Type | Mandatory | Description | 6916| ------------ | ------------------------------- | --------- | ------------------------------------------------------------ | 6917| isModal | boolean | Yes | Whether to enable the modal property of the child window. The value **true** means to enable the modal property, and **false** means the opposite. Currently, this parameter can only be set to **true**. | 6918| modalityType | [ModalityType](#modalitytype14) | Yes | Modality type of the child window. | 6919 6920**Return value** 6921 6922| Type | Description | 6923| ------------------- | ------------------------------ | 6924| Promise<void> | Promise that returns no value. | 6925 6926**Error codes** 6927 6928For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6929 6930| ID | Error Message | 6931| ------- | ------------------------------------------------------------ | 6932| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6933| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6934| 1300002 | This window state is abnormal. | 6935| 1300004 | Unauthorized operation. | 6936 6937**Example** 6938 6939```ts 6940// EntryAbility.ets 6941import { UIAbility } from '@kit.AbilityKit'; 6942import { BusinessError } from '@kit.BasicServicesKit'; 6943import { window } from '@kit.ArkUI'; 6944 6945export default class EntryAbility extends UIAbility { 6946 // ... 6947 onWindowStageCreate(windowStage: window.WindowStage): void { 6948 console.info('onWindowStageCreate'); 6949 let windowClass: window.Window | undefined = undefined; 6950 // Create a child window. 6951 try { 6952 let subWindow = windowStage.createSubWindow("testSubWindow"); 6953 subWindow.then((data) => { 6954 if (data == null) { 6955 console.error("Failed to create the subWindow. Cause: The data is empty"); 6956 return; 6957 } 6958 windowClass = data; 6959 let promise = windowClass.setSubWindowModal(true, window.ModalityType.WINDOW_MODALITY); 6960 promise.then(() => { 6961 console.info('Succeeded in setting subwindow modal'); 6962 }).catch((err: BusinessError) => { 6963 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 6964 }); 6965 }); 6966 } catch (exception) { 6967 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 6968 } 6969 } 6970} 6971``` 6972 6973### setWindowDecorHeight<sup>11+</sup> 6974 6975setWindowDecorHeight(height: number): void 6976 6977<!--RP1--> 6978Sets 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. 6979<!--RP1End--> 6980 6981When 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. 6982 6983**Atomic service API**: This API can be used in atomic services since API version 12. 6984 6985**System capability**: SystemCapability.Window.SessionManager 6986 6987**Parameters** 6988 6989| Name | Type | Mandatory | Description | 6990| ------ | ------ | --------- | ------------------------------------------------------------ | 6991| 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. | 6992 6993**Error codes** 6994 6995For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6996 6997| ID | Error Message | 6998| ------- | ------------------------------------------------------------ | 6999| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 7000| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7001| 1300002 | This window state is abnormal. | 7002 7003**Example** 7004 7005```ts 7006windowClass.setUIContent('pages/WindowPage').then(() => { 7007 let height: number = 50; 7008 try { 7009 windowClass?.setWindowDecorHeight(height); 7010 console.info(`Succeeded in setting the height of window decor: ${height}`); 7011 } catch (exception) { 7012 console.error(`Failed to set the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 7013 } 7014}) 7015``` 7016 7017### setDecorButtonStyle<sup>14+</sup> 7018 7019setDecorButtonStyle(dectorStyle: DecorButtonStyle): void 7020 7021Sets the button style of the decoration bar. The setting takes effect only for the main window and the child window with the window title enabled. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 7022 7023<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7024 7025**Atomic service API**: This API can be used in atomic services since API version 14. 7026 7027**System capability**: SystemCapability.Window.SessionManager 7028 7029**Parameters** 7030 7031| Name | Type | Mandatory | Description | 7032| ----------- | --------------------------------------- | --------- | ----------------------------------- | 7033| dectorStyle | [DecorButtonStyle](#decorbuttonstyle14) | Yes | Button style of the decoration bar. | 7034 7035**Error codes** 7036 7037For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7038 7039| ID | Error Message | 7040| ------- | ------------------------------------------------------------ | 7041| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7042| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7043| 1300002 | This window state is abnormal. | 7044| 1300004 | Unauthorized operation. | 7045 7046**Example** 7047 7048```ts 7049import { ConfigurationConstant } from '@kit.AbilityKit'; 7050 7051windowClass.setUIContent('pages/WindowPage').then(() => { 7052 try { 7053 let colorMode : ConfigurationConstant.ColorMode = ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT; 7054 let style: window.DecorButtonStyle = { 7055 colorMode: colorMode, 7056 buttonBackgroundSize: 24, 7057 spacingBetweenButtons: 12, 7058 closeButtonRightMargin: 20 7059 }; 7060 windowClass.setDecorButtonStyle(style); 7061 console.info('Succeeded in setting the style of button. Data: ' + JSON.stringify(style)); 7062 } catch (exception) { 7063 console.error(`Failed to set the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 7064 } 7065}) 7066``` 7067 7068### getDecorButtonStyle<sup>14+</sup> 7069 7070getDecorButtonStyle(): DecorButtonStyle 7071 7072Obtains the button style of the decoration bar. The setting takes effect only for the main window and the child window with the window title enabled. 7073 7074<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7075 7076**Atomic service API**: This API can be used in atomic services since API version 14. 7077 7078**System capability**: SystemCapability.Window.SessionManager 7079 7080**Return value** 7081 7082| Type | Description | 7083| --------------------------------------- | ------------------------------------------------------------ | 7084| [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. | 7085 7086**Error codes** 7087 7088For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7089 7090| ID | Error Message | 7091| ------- | ------------------------------------------------------------ | 7092| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7093| 1300002 | This window state is abnormal. | 7094| 1300003 | This window manager service works abnormally. | 7095| 1300004 | Unauthorized operation. | 7096 7097**Example** 7098 7099```ts 7100try { 7101 let decorButtonStyle = windowClass.getDecorButtonStyle(); 7102 console.info('Succeeded in getting the style of button. Data: ' + JSON.stringify(decorButtonStyle)); 7103} catch (exception) { 7104 console.error(`Failed to get the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 7105} 7106``` 7107 7108### getWindowDecorHeight<sup>11+</sup> 7109 7110getWindowDecorHeight(): number 7111 7112<!--RP2--> 7113Obtains 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. 7114<!--RP2End--> 7115 7116**Atomic service API**: This API can be used in atomic services since API version 12. 7117 7118**System capability**: SystemCapability.Window.SessionManager 7119 7120**Return value** 7121 7122| Type | Description | 7123| ------ | ------------------------------------------------------------ | 7124| number | Height of the title bar. The value is an integer in the range [37,112]. The unit is vp. | 7125 7126**Error codes** 7127 7128For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7129 7130| ID | Error Message | 7131| ------- | ------------------------------------------------------------ | 7132| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7133| 1300002 | This window state is abnormal. | 7134 7135**Example** 7136 7137```ts 7138windowClass.setUIContent('pages/WindowPage').then(() => { 7139 try { 7140 let height = windowClass?.getWindowDecorHeight(); 7141 console.info(`Succeeded in getting the height of window decor: ${height}`); 7142 } catch (exception) { 7143 console.error(`Failed to get the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 7144 } 7145}) 7146``` 7147 7148### getTitleButtonRect<sup>11+</sup> 7149 7150getTitleButtonRect(): TitleButtonRect 7151 7152Obtains the rectangle that holds the minimize, maximize, and close buttons on the title bar of the main window or the decorated child window. 7153 7154**Atomic service API**: This API can be used in atomic services since API version 12. 7155 7156**System capability**: SystemCapability.Window.SessionManager 7157 7158**Return value** 7159 7160| Type | Description | 7161| ------------------------------------- | ------------------------------------------------------------ | 7162| [TitleButtonRect](#titlebuttonrect11) | Rectangle obtained, which is located in the upper right corner of the window. | 7163 7164**Error codes** 7165 7166For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7167 7168| ID | Error Message | 7169| ------- | ------------------------------------------------------------ | 7170| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7171| 1300002 | This window state is abnormal. | 7172 7173**Example** 7174 7175```ts 7176// EntryAbility.ets 7177import { UIAbility } from '@kit.AbilityKit'; 7178import { BusinessError } from '@kit.BasicServicesKit'; 7179 7180export default class EntryAbility extends UIAbility { 7181 // ... 7182 onWindowStageCreate(windowStage: window.WindowStage): void { 7183 console.info('onWindowStageCreate'); 7184 let windowClass: window.Window | undefined = undefined; 7185 windowStage.getMainWindow((err: BusinessError, data) => { 7186 const errCode: number = err.code; 7187 if (errCode) { 7188 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7189 return; 7190 } 7191 windowClass = data; 7192 try { 7193 let titleButtonArea = windowClass.getTitleButtonRect(); 7194 console.info('Succeeded in obtaining the area of title buttons. Data: ' + JSON.stringify(titleButtonArea)); 7195 } catch (exception) { 7196 console.error(`Failed to get the area of title buttons. Cause code: ${exception.code}, message: ${exception.message}`); 7197 } 7198 }); 7199 } 7200} 7201``` 7202 7203### getWindowStatus<sup>12+</sup> 7204 7205getWindowStatus(): WindowStatusType 7206 7207Obtains the mode of this window. 7208 7209> **NOTE** 7210> 7211> When this API is called on 2-in-1 devices, the return value is **WindowStatusType::FULL_SCREEN** when the window is maximized. 7212> 7213> 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. 7214 7215**Atomic service API**: This API can be used in atomic services since API version 12. 7216 7217**System capability**: SystemCapability.Window.SessionManager 7218 7219**Return value** 7220 7221| Type | Description | 7222| --------------------------------------- | ------------ | 7223| [WindowStatusType](#windowstatustype11) | Window mode. | 7224 7225**Error codes** 7226 7227For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7228 7229| ID | Error Message | 7230| ------- | ------------------------------------------------------------ | 7231| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7232| 1300002 | This window state is abnormal. | 7233 7234**Example** 7235 7236```ts 7237try { 7238 let windowStatusType = windowClass.getWindowStatus(); 7239} catch (exception) { 7240 console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); 7241} 7242``` 7243 7244### isFocused<sup>12+</sup> 7245 7246isFocused(): boolean 7247 7248Checks whether this window is focused. 7249 7250**System capability**: SystemCapability.WindowManager.WindowManager.Core 7251 7252**Atomic service API**: This API can be used in atomic services since API version 12. 7253 7254**Return value** 7255 7256| Type | Description | 7257| ------- | ------------------------------------------------------------ | 7258| boolean | Result indicating whether the window is focused. The value **true** means that the window is focused, and **false** means the opposite. | 7259 7260**Error codes** 7261 7262For details about the error codes, see [Window Error Codes](errorcode-window.md). 7263 7264| ID | Error Message | 7265| ------- | ------------------------------ | 7266| 1300002 | This window state is abnormal. | 7267 7268**Example** 7269 7270```ts 7271try { 7272 let focus = windowClass.isFocused(); 7273 console.info('Succeeded in checking whether the window is focused. Data: ' + JSON.stringify(focus)); 7274} catch (exception) { 7275 console.error(`Failed to check whether the window is focused. Cause code: ${exception.code}, message: ${exception.message}`); 7276} 7277``` 7278 7279### createSubWindowWithOptions<sup>12+</sup> 7280 7281createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 7282 7283Creates a child window under the main window, another child window, or floating window. This API uses a promise to return the result. 7284 7285<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7286 7287**Model restriction**: This API can be used only in the stage model. 7288 7289**System capability**: SystemCapability.Window.SessionManager 7290 7291**Atomic service API**: This API can be used in atomic services since API version 12. 7292 7293**Parameters** 7294 7295| Name | Type | Mandatory | Description | 7296| ------- | --------------------------------------- | --------- | ---------------------------------------------- | 7297| name | string | Yes | Name of the child window. | 7298| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the child window. | 7299 7300**Return value** 7301 7302| Type | Description | 7303| -------------------------------- | -------------------------------------------------------- | 7304| Promise<[Window](#window)> | Promise used to used to return the child window created. | 7305 7306**Error codes** 7307 7308For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7309 7310| ID | Error Message | 7311| ------- | ------------------------------------------------------------ | 7312| 401 | Parameter error. Possible cause: Incorrect parameter types. | 7313| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7314| 1300002 | This window state is abnormal. | 7315| 1300003 | This window manager service works abnormally. | 7316| 1300004 | Unauthorized operation. | 7317 7318**Example** 7319 7320```ts 7321import { BusinessError } from '@kit.BasicServicesKit'; 7322 7323try { 7324 let options : window.SubWindowOptions = { 7325 title: 'title', 7326 decorEnabled: true, 7327 isModal: true 7328 }; 7329 let promise = windowClass.createSubWindowWithOptions('mySubWindow', options); 7330 promise.then((data) => { 7331 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 7332 }).catch((err: BusinessError) => { 7333 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 7334 }); 7335} catch (exception) { 7336 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 7337} 7338``` 7339 7340### setWindowTitleButtonVisible<sup>14+</sup> 7341 7342setWindowTitleButtonVisible(isMaximizeButtonVisible: boolean, isMinimizeButtonVisible: boolean, isCloseButtonVisible?: boolean): void 7343 7344Shows or hides the maximize, minimize, and close buttons on the title bar of the main window. 7345 7346<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7347 7348**Atomic service API**: This API can be used in atomic services since API version 14. 7349 7350**System capability**: SystemCapability.Window.SessionManager 7351 7352**Parameters** 7353 7354| Name | Type | Mandatory | Description | 7355| ----------------------- | ------- | --------- | ------------------------------------------------------------ | 7356| isMaximizeButtonVisible | boolean | Yes | Whether to show the maximize button. The value **true** means to show the button, and **false** means the opposite. If the maximize button is hidden, the corresponding restore button is also hidden in the maximize scenario. | 7357| isMinimizeButtonVisible | boolean | Yes | Whether to show the minimize button. The value **true** means to show the button, and **false** means the opposite. | 7358| isCloseButtonVisible | boolean | No | Whether to show the close button. The value **true** means to show the button, and **false** means the opposite. | 7359 7360**Error codes** 7361 7362For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7363 7364| ID | Error Message | 7365| ------- | ------------------------------------------------------------ | 7366| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7367| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7368| 1300002 | This window state is abnormal. | 7369| 1300004 | Unauthorized operation. | 7370 7371**Example** 7372 7373```ts 7374// EntryAbility.ets 7375import { UIAbility } from '@kit.AbilityKit'; 7376import { BusinessError } from '@kit.BasicServicesKit'; 7377import { window } from '@kit.ArkUI'; 7378 7379export default class EntryAbility extends UIAbility { 7380 onWindowStageCreate(windowStage: window.WindowStage): void { 7381 // Load the page corresponding to the main window. 7382 windowStage.loadContent('pages/Index', (err) => { 7383 let mainWindow: window.Window | undefined = undefined; 7384 // Obtain the main window. 7385 windowStage.getMainWindow().then( 7386 data => { 7387 mainWindow = data; 7388 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 7389 // Call setWindowTitleButtonVisible to hide the maximize, minimize, and close buttons on the title bar of the main window. 7390 mainWindow.setWindowTitleButtonVisible(false, false, false); 7391 } 7392 ).catch((err: BusinessError) => { 7393 if(err.code){ 7394 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7395 } 7396 }); 7397 }); 7398 } 7399} 7400``` 7401 7402### setWindowTopmost<sup>14+</sup> 7403 7404setWindowTopmost(isWindowTopmost: boolean): Promise<void> 7405 7406Places the main window above all the other windows of the application. This API uses a promise to return the result. 7407 7408Applications use custom shortcut keys to pin or unpin the main window. 7409 7410<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7411 7412**Atomic service API**: This API can be used in atomic services since API version 14. 7413 7414**System capability**: SystemCapability.Window.SessionManager 7415 7416**Required permissions**: ohos.permission.WINDOW_TOPMOST 7417 7418**Parameters** 7419 7420| Name | Type | Mandatory | Description | 7421| --------------- | ------- | --------- | ------------------------------------------------------------ | 7422| 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. | 7423 7424 7425**Error codes** 7426 7427For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7428 7429| ID | Error Message | 7430| ------- | ------------------------------------------------------------ | 7431| 201 | Permission verification failed. The application does not have the permission required to call the API. | 7432| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7433| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7434| 1300002 | This window state is abnormal. | 7435| 1300004 | Unauthorized operation. | 7436 7437**Example** 7438 7439```ts 7440// ets/pages/Index.ets 7441import { window } from '@kit.ArkUI'; 7442import { common } from '@kit.AbilityKit'; 7443import { BusinessError } from '@kit.BasicServicesKit'; 7444 7445const context = (getContext(this) as common.UIAbilityContext); 7446let windowClass: window.Window | undefined; 7447let keyUpEventAry: string[] = []; 7448 7449@Entry 7450@Component 7451struct Index { 7452 build() { 7453 RelativeContainer() { 7454 Button("Pin") 7455 .onClick(() => { 7456 try { 7457 let promiseCtx = window.getLastWindow(context); 7458 promiseCtx.then((data) => { 7459 windowClass = data; 7460 // The value true means to pin the window on top, and false means to unpin the window. 7461 let isWindowTopmost: boolean = true; 7462 let promiseTopmost = windowClass.setWindowTopmost(isWindowTopmost); 7463 promiseTopmost.then(() => { 7464 console.info('Succeeded in setting the main window to be topmost.'); 7465 }).catch((err: BusinessError) => { 7466 console.error(`Failed to set the main window to be topmost. Cause code: ${err.code}, message: ${err.message}`); 7467 }); 7468 }) 7469 } catch (exception) { 7470 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`) 7471 } 7472 }) 7473 } 7474 .height('100%') 7475 .width('100%') 7476 .onKeyEvent((event) => { 7477 if(event) { 7478 if(event.type === KeyType.Down) { 7479 keyUpEventAry = []; 7480 } 7481 if(event.type === KeyType.Up) { 7482 keyUpEventAry.push(event.keyText); 7483 // Press Ctrl+T to pin or unpin the main window. 7484 if(windowClass && keyUpEventAry.includes('KEYCODE_CTRL_LEFT') && keyUpEventAry.includes('KEYCODE_T')) { 7485 let isWindowTopmost: boolean = false; 7486 windowClass.setWindowTopmost(isWindowTopmost); 7487 } 7488 } 7489 } 7490 }) 7491 } 7492} 7493``` 7494 7495### raiseToAppTop<sup>14+</sup> 7496 7497raiseToAppTop(): Promise<void> 7498 7499Called by a child window to elevate the child window to the topmost layer. Its effect is limited to child windows of the same type that share the same parent window of the current application. This API uses a promise to return the result. 7500 7501**System capability**: SystemCapability.WindowManager.WindowManager.Core 7502 7503**Return value** 7504 7505| Type | Description | 7506| ------------------- | ------------------------------ | 7507| Promise<void> | Promise that returns no value. | 7508 7509**Error codes** 7510 7511For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7512 7513| ID | Error Message | 7514| ------- | --------------------------------------------- | 7515| 1300002 | This window state is abnormal. | 7516| 1300003 | This window manager service works abnormally. | 7517| 1300004 | Unauthorized operation. | 7518| 1300009 | The parent window is invalid. | 7519 7520**Example** 7521 7522```ts 7523import { BusinessError } from '@kit.BasicServicesKit'; 7524 7525let promise = windowClass.raiseToAppTop(); 7526promise.then(() => { 7527 console.info('Succeeded in raising the window to app top.'); 7528}).catch((err: BusinessError) => { 7529 console.error(`Failed to raise the window to app top. Cause code: ${err.code}, message: ${err.message}`); 7530}); 7531``` 7532 7533### setRaiseByClickEnabled<sup>14+</sup> 7534 7535setRaiseByClickEnabled(enable: boolean): Promise<void> 7536 7537Sets whether to enable a child window to raise itself by click. This API uses a promise to return the result. 7538 7539Generally, when a child window is clicked, it is brought to the forefront among sibling child windows of the same type that share the same parent window within the application. If the **enable** parameter is set to **false**, when the child window is clicked, it still stays in its existing position. 7540 7541**System capability**: SystemCapability.Window.SessionManager 7542 7543**Parameters** 7544 7545| Name | Type | Mandatory | Description | 7546| ------ | ------- | --------- | ------------------------------------------------------------ | 7547| enable | boolean | Yes | Whether a child window can be raised by clicking. The value **true** means that the child window can be raised by clicking, and **false** means the opposite. | 7548 7549**Return value** 7550 7551| Type | Description | 7552| ------------------- | ------------------------------ | 7553| Promise<void> | Promise that returns no value. | 7554 7555**Error codes** 7556 7557For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7558 7559| ID | Error Message | 7560| ------- | ------------------------------------------------------------ | 7561| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7562| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7563| 1300002 | This window state is abnormal. | 7564| 1300003 | This window manager service works abnormally. | 7565| 1300004 | Unauthorized operation. | 7566| 1300009 | The parent window is invalid. | 7567 7568**Example** 7569 7570```ts 7571// EntryAbility.ets 7572import { UIAbility } from '@kit.AbilityKit'; 7573import { BusinessError } from '@kit.BasicServicesKit'; 7574 7575export default class EntryAbility extends UIAbility { 7576 // ... 7577 onWindowStageCreate(windowStage: window.WindowStage): void { 7578 console.info('onWindowStageCreate'); 7579 let windowClass: window.Window | undefined = undefined; 7580 // Create a child window. 7581 try { 7582 let subWindow = windowStage.createSubWindow("testSubWindow"); 7583 subWindow.then((data) => { 7584 if (data == null) { 7585 console.error("Failed to create the subWindow. Cause: The data is empty"); 7586 return; 7587 } 7588 windowClass = data; 7589 let enabled = false; 7590 let promise = windowClass.setRaiseByClickEnabled(enabled); 7591 promise.then(()=> { 7592 console.info('Succeeded in disabling the raise-by-click function.'); 7593 }).catch((err: BusinessError)=>{ 7594 console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`); 7595 }); 7596 }); 7597 } catch (exception) { 7598 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 7599 } 7600 } 7601} 7602``` 7603 7604### enableLandscapeMultiWindow<sup>12+</sup> 7605 7606enableLandscapeMultiWindow(): Promise<void> 7607 7608Enables 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. 7609 7610This 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. 7611 7612**Atomic service API**: This API can be used in atomic services since API version 12. 7613 7614**System capability**: SystemCapability.Window.SessionManager 7615 7616**Return value** 7617 7618| Type | Description | 7619| ------------------- | ------------------------------ | 7620| Promise<void> | Promise that returns no value. | 7621 7622**Error codes** 7623 7624For details about the error codes, see [Window Error Codes](errorcode-window.md). 7625 7626| ID | Error Message | 7627| ------- | --------------------------------------------- | 7628| 1300002 | This window state is abnormal. | 7629| 1300003 | This window manager service works abnormally. | 7630 7631**Example** 7632 7633```ts 7634// EntryAbility.ets 7635import { UIAbility } from '@kit.AbilityKit'; 7636import { BusinessError } from '@kit.BasicServicesKit'; 7637import { window } from '@kit.ArkUI'; 7638 7639export default class EntryAbility extends UIAbility { 7640 // ... 7641 onWindowStageCreate(windowStage: window.WindowStage): void { 7642 console.info('onWindowStageCreate'); 7643 let windowClass: window.Window | undefined = undefined; 7644 windowStage.getMainWindow((err: BusinessError, data) => { 7645 const errCode: number = err.code; 7646 if (errCode) { 7647 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7648 return; 7649 } 7650 windowClass = data; 7651 let promise = windowClass.enableLandscapeMultiWindow(); 7652 promise.then(() => { 7653 console.info('Succeeded in making multi-window become landscape.'); 7654 }).catch((err: BusinessError) => { 7655 console.error(`Failed to make multi-window become landscape. Cause code: ${err.code}, message: ${err.message}`); 7656 }); 7657 }); 7658 } 7659} 7660``` 7661 7662### disableLandscapeMultiWindow<sup>12+</sup> 7663 7664disableLandscapeMultiWindow(): Promise<void> 7665 7666Disables the landscape multi-window mode for the UI page that supports the horizontal layout. 7667 7668This 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. 7669 7670**Atomic service API**: This API can be used in atomic services since API version 12. 7671 7672**System capability**: SystemCapability.Window.SessionManager 7673 7674**Return value** 7675 7676| Type | Description | 7677| ------------------- | ------------------------------ | 7678| Promise<void> | Promise that returns no value. | 7679 7680**Error codes** 7681 7682For details about the error codes, see [Window Error Codes](errorcode-window.md). 7683 7684| ID | Error Message | 7685| ------- | --------------------------------------------- | 7686| 1300002 | This window state is abnormal. | 7687| 1300003 | This window manager service works abnormally. | 7688 7689**Example** 7690 7691```ts 7692// EntryAbility.ets 7693import { UIAbility } from '@kit.AbilityKit'; 7694import { BusinessError } from '@kit.BasicServicesKit'; 7695import { window } from '@kit.ArkUI'; 7696 7697export default class EntryAbility extends UIAbility { 7698 // ... 7699 onWindowStageCreate(windowStage: window.WindowStage): void { 7700 console.info('onWindowStageCreate'); 7701 let windowClass: window.Window | undefined = undefined; 7702 windowStage.getMainWindow((err: BusinessError, data) => { 7703 const errCode: number = err.code; 7704 if (errCode) { 7705 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7706 return; 7707 } 7708 windowClass = data; 7709 let promise = windowClass.disableLandscapeMultiWindow(); 7710 promise.then(() => { 7711 console.info('Succeeded in making multi-window become not landscape.'); 7712 }).catch((err: BusinessError) => { 7713 console.error(`Failed to make multi-window become not landscape. Cause code: ${err.code}, message: ${err.message}`); 7714 }); 7715 }); 7716 } 7717} 7718``` 7719 7720### setDialogBackGestureEnabled<sup>12+</sup> 7721 7722setDialogBackGestureEnabled(enabled: boolean): Promise<void> 7723 7724Sets 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. 7725 7726**System capability**: SystemCapability.Window.SessionManager 7727 7728**Atomic service API**: This API can be used in atomic services since API version 12. 7729 7730**Parameters** 7731 7732| Name | Type | Mandatory | Description | 7733| ------- | ------- | --------- | ------------------------------------------------------------ | 7734| 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> | 7735 7736**Return value** 7737 7738| Type | Description | 7739| ------------------- | ------------------------------ | 7740| Promise<void> | Promise that returns no value. | 7741 7742**Error codes** 7743 7744For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7745 7746| ID | Error Message | 7747| ------- | ------------------------------------------------------------ | 7748| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7749| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7750| 1300002 | This window state is abnormal. | 7751| 1300003 | This window manager service works abnormally. | 7752| 1300004 | Unauthorized operation. | 7753 7754**Example** 7755 7756```ts 7757// EntryAbility.ets 7758import { UIAbility } from '@kit.AbilityKit'; 7759import { BusinessError } from '@kit.BasicServicesKit'; 7760 7761export default class EntryAbility extends UIAbility { 7762 onWindowStageCreate(windowStage: window.WindowStage): void { 7763 console.info('onWindowStageCreate'); 7764 let windowClass: window.Window | undefined = undefined; 7765 let config: window.Configuration = { 7766 name: "test", 7767 windowType: window.WindowType.TYPE_DIALOG, 7768 ctx: this.context 7769 }; 7770 try { 7771 window.createWindow(config, (err: BusinessError, data) => { 7772 const errCode: number = err.code; 7773 if (errCode) { 7774 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 7775 return; 7776 } 7777 windowClass = data; 7778 windowClass.setUIContent("pages/Index"); 7779 let enabled = true; 7780 let promise = windowClass.setDialogBackGestureEnabled(enabled); 7781 promise.then(() => { 7782 console.info('Succeeded in setting dialog window to respond back gesture.'); 7783 }).catch((err: BusinessError) => { 7784 console.error(`Failed to set dialog window to respond back gesture. Cause code: ${err.code}, message: ${err.message}`); 7785 }); 7786 }); 7787 } catch (exception) { 7788 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 7789 } 7790 } 7791} 7792``` 7793 7794```ts 7795// ets/pages/Index.ets 7796@Entry 7797@Component 7798struct Index { 7799 @State message: string = 'Hello World' 7800 build() { 7801 RelativeContainer() { 7802 Text(this.message) 7803 .id('HelloWorld') 7804 .fontSize(50) 7805 .fontWeight(FontWeight.Bold) 7806 } 7807 .height('100%') 7808 .width('100%') 7809 } 7810 7811 onBackPress(): boolean | void { 7812 console.info('Succeeded in setting dialog window to respond back gesture.'); 7813 return true; 7814 } 7815} 7816``` 7817 7818### startMoving<sup>14+</sup> 7819 7820startMoving(): Promise<void> 7821 7822Starts moving this window. This API uses a promise to return the result. 7823 7824The 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**. 7825 7826<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7827 7828This API takes effect only for the main window, child window, and system window. If it is called for other device types or window types, an error is reported. 7829 7830**System capability**: SystemCapability.Window.SessionManager 7831 7832**Atomic service API**: This API can be used in atomic services since API version 14. 7833 7834**Return value** 7835 7836| Type | Description | 7837| ------------------- | ------------------------------ | 7838| Promise<void> | Promise that returns no value. | 7839 7840**Error codes** 7841 7842For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7843 7844| ID | Error Message | 7845| ------- | ------------------------------------------------------------ | 7846| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7847| 1300001 | Repeated operation. | 7848| 1300002 | This window state is abnormal. | 7849| 1300003 | This window manager service works abnormally. | 7850| 1300004 | Unauthorized operation. | 7851 7852**Example** 7853 7854```ts 7855// ets/pages/Index.ets 7856import { BusinessError } from '@kit.BasicServicesKit'; 7857 7858@Entry 7859@Component 7860struct Index { 7861 build() { 7862 Row() { 7863 Column() { 7864 Blank('160') 7865 .color(Color.Blue) 7866 .onTouch((event: TouchEvent) => { 7867 if (event.type === TouchType.Down) { 7868 try { 7869 windowClass.startMoving().then(() => { 7870 console.info('Succeeded in starting moving window.') 7871 }).catch((err: BusinessError) => { 7872 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 7873 }); 7874 } catch (exception) { 7875 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 7876 } 7877 } 7878 }) 7879 }.width('100%') 7880 }.height('100%').width('100%') 7881 } 7882} 7883``` 7884 7885### startMoving<sup>15+</sup> 7886 7887startMoving(offsetX: number, offsetY: number): Promise<void> 7888 7889Specifies the cursor position within the window and moves the window. This API uses a promise to return the result. 7890 7891When windows within the same application are split or merged, and the mouse is pressed down to move the new window directly, the cursor may move outside the window if it moves too quickly. This API allows you to set the cursor position within the window during movement. It first adjusts the window to the cursor position before starting to move the window. 7892 7893The 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**. 7894 7895<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7896 7897**System capability**: SystemCapability.Window.SessionManager 7898 7899**Atomic service API**: This API can be used in atomic services since API version 15. 7900 7901**Parameters** 7902 7903| Name | Type | Mandatory | Description | 7904| ------- | ------ | --------- | ------------------------------------------------------------ | 7905| offsetX | number | Yes | X-axis offset of the cursor position relative to the upper left corner of the window during movement, measured in px. This parameter only accepts integer values; any floating-point input will be rounded down. Negative values or values exceeding the window width are invalid. The window width can be obtained from [WindowProperties](#windowproperties). | 7906| offsetY | number | Yes | Y-axis offset of the cursor position relative to the upper left corner of the window during movement, measured in px. This parameter only accepts integer values; any floating-point input will be rounded down. Negative values or values exceeding the window height are invalid. The window height can be obtained from [WindowProperties](#windowproperties). | 7907 7908**Return value** 7909 7910| Type | Description | 7911| ------------------- | ------------------------------ | 7912| Promise<void> | Promise that returns no value. | 7913 7914**Error codes** 7915 7916For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7917 7918| ID | Error Message | 7919| ------- | ------------------------------------------------------------ | 7920| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7921| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7922| 1300001 | Repeated operation. | 7923| 1300002 | This window state is abnormal. | 7924| 1300003 | This window manager service works abnormally. | 7925| 1300004 | Unauthorized operation. | 7926 7927**Example** 7928 7929```ts 7930// ets/pages/Index.ets 7931import { BusinessError } from '@kit.BasicServicesKit'; 7932 7933@Entry 7934@Component 7935struct Index { 7936 build() { 7937 Row() { 7938 Column() { 7939 Blank('160') 7940 .color(Color.Blue) 7941 .onTouch((event: TouchEvent) => { 7942 if (event.type === TouchType.Down) { 7943 try { 7944 windowClass.startMoving(100, 50).then(() => { 7945 console.info('Succeeded in starting moving window.') 7946 }).catch((err: BusinessError) => { 7947 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 7948 }); 7949 } catch (exception) { 7950 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 7951 } 7952 } 7953 }) 7954 }.width('100%') 7955 }.height('100%').width('100%') 7956 } 7957} 7958``` 7959 7960### stopMoving<sup>15+</sup> 7961 7962stopMoving(): Promise<void> 7963 7964Stops window movement when a window is being dragged. This API uses a promise to return the result. 7965 7966<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 7967 7968**System capability**: SystemCapability.Window.SessionManager 7969 7970**Atomic service API**: This API can be used in atomic services since API version 15. 7971 7972**Return value** 7973 7974| Type | Description | 7975| ------------------- | ------------------------------ | 7976| Promise<void> | Promise that returns no value. | 7977 7978**Error codes** 7979 7980For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 7981 7982| ID | Error Message | 7983| ------- | ------------------------------------------------------------ | 7984| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7985| 1300002 | This window state is abnormal. | 7986| 1300003 | This window manager service works abnormally. | 7987| 1300004 | Unauthorized operation. | 7988 7989**Example** 7990 7991```ts 7992// EntryAbility.ets 7993import { UIAbility } from '@kit.AbilityKit'; 7994import { window } from '@kit.ArkUI'; 7995import { BusinessError } from '@kit.BasicServicesKit'; 7996 7997export default class EntryAbility extends UIAbility { 7998 7999 onWindowStageCreate(windowStage: window.WindowStage) { 8000 try { 8001 let windowClass = windowStage.getMainWindowSync(); 8002 windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 8003 if (data.reason === window.RectChangeReason.MOVE) { 8004 windowClass.stopMoving().then(() => { 8005 console.info('Succeeded in stopping moving window.') 8006 }).catch((err: BusinessError) => { 8007 console.error(`Failed to stop moving. Cause code: ${err.code}, message: ${err.message}`); 8008 }); 8009 } 8010 }); 8011 } catch (exception) { 8012 console.error(`Failed to stop moving window. Cause code: ${exception.code}, message: ${exception.message}`); 8013 } 8014 } 8015} 8016``` 8017 8018### setGestureBackEnabled<sup>13+<sup> 8019 8020setGestureBackEnabled(enabled: boolean): Promise<void> 8021 8022Sets 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. 8023 8024When 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. 8025 8026When 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. 8027 8028**System capability**: SystemCapability.Window.SessionManager 8029 8030**Atomic service API**: This API can be used in atomic services since API version 13. 8031 8032**Parameters** 8033 8034| Name | Type | Mandatory | Description | 8035| ------- | ------- | --------- | ------------------------------------------------------------ | 8036| enabled | boolean | Yes | Whether to enable the back gesture feature. The value **true** means to enable the feature, and **false** means the opposite. | 8037 8038**Return value** 8039 8040| Type | Description | 8041| ------------------- | ------------------------------ | 8042| Promise<void> | Promise that returns no value. | 8043 8044**Error codes** 8045 8046For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8047 8048| ID | Error Message | 8049| ------- | ------------------------------------------------------------ | 8050| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8051| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8052| 1300002 | This window state is abnormal. | 8053| 1300003 | This window manager service works abnormally. | 8054| 1300004 | Unauthorized operation. | 8055 8056**Example** 8057 8058```ts 8059// EntryAbility.ets 8060import { UIAbility } from '@kit.AbilityKit'; 8061import { BusinessError } from '@kit.BasicServicesKit'; 8062import { window } from '@kit.ArkUI'; 8063 8064export default class EntryAbility extends UIAbility { 8065 // ... 8066 onWindowStageCreate(windowStage: window.WindowStage): void { 8067 console.info('onWindowStageCreate'); 8068 let windowClass: window.Window | undefined = undefined; 8069 windowStage.getMainWindow((err: BusinessError, data) => { 8070 const errCode: number = err.code; 8071 if (errCode) { 8072 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8073 return; 8074 } 8075 windowClass = data; 8076 8077 // Disable the back gesture feature in the current window. 8078 try { 8079 let gestureBackEnabled: boolean = false; 8080 let promise = windowClass.setGestureBackEnabled(gestureBackEnabled); 8081 promise.then(() => { 8082 console.info(`Succeeded in setting gesture back disabled`); 8083 }).catch((err: BusinessError) => { 8084 console.error(`Failed to set gesture back disabled, Cause code: ${err.code}, message: ${err.message}`); 8085 }); 8086 } catch(exception) { 8087 console.error(`Failed to set gesture back disabled, Cause code: ${exception.code}, message: ${exception.message}`); 8088 } 8089 }); 8090 } 8091} 8092``` 8093 8094### isGestureBackEnabled<sup>13+<sup> 8095 8096isGestureBackEnabled(): boolean 8097 8098Checks 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. 8099 8100**System capability**: SystemCapability.Window.SessionManager 8101 8102**Atomic service API**: This API can be used in atomic services since API version 13. 8103 8104**Return value** 8105 8106| Type | Description | 8107| ------- | ------------------------------------------------------------ | 8108| 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. | 8109 8110**Error codes** 8111 8112For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8113 8114| ID | Error Message | 8115| ------- | ------------------------------------------------------------ | 8116| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8117| 1300002 | This window state is abnormal. | 8118| 1300003 | This window manager service works abnormally. | 8119| 1300004 | Unauthorized operation. | 8120 8121**Example** 8122 8123```ts 8124// EntryAbility.ets 8125import { UIAbility } from '@kit.AbilityKit'; 8126import { BusinessError } from '@kit.BasicServicesKit'; 8127import { window } from '@kit.ArkUI'; 8128 8129export default class EntryAbility extends UIAbility { 8130 // ... 8131 onWindowStageCreate(windowStage: window.WindowStage): void { 8132 console.info('onWindowStageCreate'); 8133 let windowClass: window.Window | undefined = undefined; 8134 windowStage.getMainWindow((err: BusinessError, data) => { 8135 const errCode: number = err.code; 8136 if (errCode) { 8137 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8138 return; 8139 } 8140 windowClass = data; 8141 8142 // Check whether the back gesture feature is enabled in the current window. 8143 try { 8144 let gestureBackEnabled: boolean = windowClass.isGestureBackEnabled(); 8145 console.info(`Succeeded in obtaining gesture back enabled status: ${gestureBackEnabled}`); 8146 } catch (exception) { 8147 console.error(`Failed to get gesture back enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 8148 } 8149 }); 8150 } 8151} 8152``` 8153 8154### setExclusivelyHighlighted<sup>15+<sup> 8155 8156setExclusivelyHighlighted(exclusivelyHighlighted: boolean): Promise<void> 8157 8158Sets the exclusive highlight property for the window. When a window set to exclusive highlight gains focus, other windows in the current parent-child window chain that are in the highlighted state will lose their highlighted state. This API uses a promise to return the result. 8159 8160This API does not take effect for the main window, modal window, and dialog boxes. 8161 8162**System capability**: SystemCapability.Window.SessionManager 8163 8164**Atomic service API**: This API can be used in atomic services since API version 15. 8165 8166**Parameters** 8167 8168| Name | Type | Mandatory | Description | 8169| ---------------------- | ------- | --------- | ------------------------------------------------------------ | 8170| exclusivelyHighlighted | boolean | Yes | Whether to set exclusive highlight for the window. The value **true** means to set exclusive highlight for the window, and **false** means the opposite. | 8171 8172**Return value** 8173 8174| Type | Description | 8175| ------------------- | ------------------------------ | 8176| Promise<void> | Promise that returns no value. | 8177 8178**Error codes** 8179 8180For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8181 8182| ID | Error Message | 8183| ------- | ------------------------------------------------------------ | 8184| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 8185| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8186| 1300002 | This window state is abnormal. | 8187| 1300003 | This window manager service works abnormally. | 8188| 1300004 | Unauthorized operation. | 8189 8190**Example** 8191 8192```ts 8193import { BusinessError } from '@kit.BasicServicesKit'; 8194 8195let exclusivelyHighlighted: boolean = true; 8196try { 8197 let promise = windowClass.setExclusivelyHighlighted(exclusivelyHighlighted); 8198 promise.then(() => { 8199 console.info('Succeeded in setting the window to be exclusively highlight.'); 8200 }).catch((err: BusinessError) => { 8201 console.error(`Failed to set the window to be exclusively highlight. Cause code: ${err.code}, message: ${err.message}`); 8202 }); 8203} catch (exception) { 8204 console.error(`Failed to set the window to be exclusively highlight. Cause code: ${exception.code}, message: ${exception.message}`); 8205} 8206``` 8207 8208### setWindowSystemBarProperties<sup>(deprecated)</sup> 8209 8210setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 8211 8212Sets 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--> 8213 8214This API does not take effect when it is called by a child window. 8215 8216> **NOTE** 8217> 8218> 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. 8219 8220**System capability**: SystemCapability.WindowManager.WindowManager.Core 8221 8222**Atomic service API**: This API can be used in atomic services since API version 12. 8223 8224**Parameters** 8225 8226| Name | Type | Mandatory | Description | 8227| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 8228| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar. | 8229| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8230 8231**Error codes** 8232 8233For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8234 8235| ID | Error Message | 8236| ------- | ------------------------------------------------------------ | 8237| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8238| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8239| 1300002 | This window state is abnormal. | 8240| 1300003 | This window manager service works abnormally. | 8241 8242**Example** 8243 8244```ts 8245// EntryAbility.ets 8246import { UIAbility } from '@kit.AbilityKit'; 8247import { BusinessError } from '@kit.BasicServicesKit'; 8248 8249export default class EntryAbility extends UIAbility { 8250 // ... 8251 onWindowStageCreate(windowStage: window.WindowStage): void { 8252 console.info('onWindowStageCreate'); 8253 let windowClass: window.Window | undefined = undefined; 8254 windowStage.getMainWindow((err: BusinessError, data) => { 8255 const errCode: number = err.code; 8256 if (errCode) { 8257 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8258 return; 8259 } 8260 windowClass = data; 8261 let SystemBarProperties: window.SystemBarProperties = { 8262 statusBarColor: '#ff00ff', 8263 navigationBarColor: '#00ff00', 8264 // The following properties are supported since API version 8. 8265 statusBarContentColor: '#ffffff', 8266 navigationBarContentColor: '#00ffff' 8267 }; 8268 try { 8269 windowClass.setWindowSystemBarProperties(SystemBarProperties, (err: BusinessError) => { 8270 const errCode: number = err.code; 8271 if (errCode) { 8272 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 8273 return; 8274 } 8275 console.info('Succeeded in setting the system bar properties.'); 8276 }); 8277 } catch (exception) { 8278 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 8279 } 8280 }); 8281 } 8282} 8283``` 8284 8285### setWindowSystemBarEnable<sup>(deprecated)</sup> 8286 8287setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 8288 8289Sets 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--> 8290 8291The 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 child window. 8292 8293> **NOTE** 8294> 8295> 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. 8296 8297**Atomic service API**: This API can be used in atomic services since API version 12. 8298 8299**System capability**: SystemCapability.WindowManager.WindowManager.Core 8300 8301**Parameters** 8302 8303| Name | Type | Mandatory | Description | 8304| -------- | ----------------------------- | --------- | ------------------------------------------------------------ | 8305| 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. | 8306| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8307 8308**Error codes** 8309 8310For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8311 8312| ID | Error Message | 8313| ------- | ------------------------------------------------------------ | 8314| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8315| 1300002 | This window state is abnormal. | 8316| 1300003 | This window manager service works abnormally. | 8317 8318**Example** 8319 8320```ts 8321// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 8322// EntryAbility.ets 8323import { UIAbility } from '@kit.AbilityKit'; 8324import { BusinessError } from '@kit.BasicServicesKit'; 8325 8326export default class EntryAbility extends UIAbility { 8327 // ... 8328 onWindowStageCreate(windowStage: window.WindowStage): void { 8329 console.info('onWindowStageCreate'); 8330 let windowClass: window.Window | undefined = undefined; 8331 windowStage.getMainWindow((err: BusinessError, data) => { 8332 const errCode: number = err.code; 8333 if (errCode) { 8334 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8335 return; 8336 } 8337 windowClass = data; 8338 let names: Array<'status' | 'navigation'> = []; 8339 try { 8340 windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => { 8341 const errCode: number = err.code; 8342 if (errCode) { 8343 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 8344 return; 8345 } 8346 console.info('Succeeded in setting the system bar to be invisible.'); 8347 }); 8348 } catch (exception) { 8349 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 8350 } 8351 }); 8352 } 8353} 8354``` 8355 8356### setWindowLayoutFullScreen<sup>(deprecated)</sup> 8357 8358setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 8359 8360Sets whether the main window layout or the child window layout is immersive. This API uses an asynchronous callback to return the result. 8361- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 8362- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 8363 8364> **NOTE** 8365> 8366> 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. 8367 8368**System capability**: SystemCapability.WindowManager.WindowManager.Core 8369 8370**Atomic service API**: This API can be used in atomic services since API version 12. 8371 8372**Parameters** 8373 8374| Name | Type | Mandatory | Description | 8375| ------------------ | ------------------------- | --------- | ------------------------------------------------------------ | 8376| 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. | 8377| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8378 8379**Error codes** 8380 8381For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8382 8383| ID | Error Message | 8384| ------- | ------------------------------------------------------------ | 8385| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8386| 1300002 | This window state is abnormal. | 8387| 1300003 | This window manager service works abnormally. | 8388 8389**Example** 8390 8391```ts 8392// EntryAbility.ets 8393import { UIAbility } from '@kit.AbilityKit'; 8394import { BusinessError } from '@kit.BasicServicesKit'; 8395 8396export default class EntryAbility extends UIAbility { 8397 // ... 8398 onWindowStageCreate(windowStage: window.WindowStage): void { 8399 console.info('onWindowStageCreate'); 8400 let windowClass: window.Window | undefined = undefined; 8401 windowStage.getMainWindow((err: BusinessError, data) => { 8402 const errCode: number = err.code; 8403 if (errCode) { 8404 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8405 return; 8406 } 8407 windowClass = data; 8408 let isLayoutFullScreen = true; 8409 try { 8410 windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 8411 const errCode: number = err.code; 8412 if (errCode) { 8413 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 8414 return; 8415 } 8416 console.info('Succeeded in setting the window layout to full-screen mode.'); 8417 }); 8418 } catch (exception) { 8419 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 8420 } 8421 }); 8422 } 8423} 8424``` 8425 8426### show<sup>(deprecated)</sup> 8427 8428show(callback: AsyncCallback<void>): void 8429 8430Shows this window. This API uses an asynchronous callback to return the result. 8431 8432> **NOTE** 8433> 8434> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9) instead. 8435 8436**System capability**: SystemCapability.WindowManager.WindowManager.Core 8437 8438**Parameters** 8439 8440| Name | Type | Mandatory | Description | 8441| -------- | ------------------------- | --------- | ----------------------------------- | 8442| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8443 8444**Example** 8445 8446```ts 8447import { BusinessError } from '@kit.BasicServicesKit'; 8448 8449windowClass.show((err: BusinessError) => { 8450 const errCode: number = err.code; 8451 if (errCode) { 8452 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 8453 return; 8454 } 8455 console.info('Succeeded in showing the window.'); 8456}); 8457``` 8458 8459### show<sup>(deprecated)</sup> 8460 8461show(): Promise<void> 8462 8463Shows this window. This API uses a promise to return the result. 8464 8465> **NOTE** 8466> 8467> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9-1) instead. 8468 8469**System capability**: SystemCapability.WindowManager.WindowManager.Core 8470 8471**Return value** 8472 8473| Type | Description | 8474| ------------------- | ------------------------------ | 8475| Promise<void> | Promise that returns no value. | 8476 8477**Example** 8478 8479```ts 8480import { BusinessError } from '@kit.BasicServicesKit'; 8481 8482let promise = windowClass.show(); 8483promise.then(() => { 8484 console.info('Succeeded in showing the window.'); 8485}).catch((err: BusinessError) => { 8486 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 8487}); 8488``` 8489 8490### destroy<sup>(deprecated)</sup> 8491 8492destroy(callback: AsyncCallback<void>): void 8493 8494Destroys this window. This API uses an asynchronous callback to return the result. 8495 8496> **NOTE** 8497> 8498> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9) instead. 8499 8500**System capability**: SystemCapability.WindowManager.WindowManager.Core 8501 8502**Parameters** 8503 8504| Name | Type | Mandatory | Description | 8505| -------- | ------------------------- | --------- | ----------------------------------- | 8506| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8507 8508**Example** 8509 8510```ts 8511import { BusinessError } from '@kit.BasicServicesKit'; 8512 8513windowClass.destroy((err: BusinessError) => { 8514 const errCode: number = err.code; 8515 if (err.code) { 8516 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 8517 return; 8518 } 8519 console.info('Succeeded in destroying the window.'); 8520}); 8521``` 8522 8523### destroy<sup>(deprecated)</sup> 8524 8525destroy(): Promise<void> 8526 8527Destroys this window. This API uses a promise to return the result. 8528 8529> **NOTE** 8530> 8531> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9-1) instead. 8532 8533**System capability**: SystemCapability.WindowManager.WindowManager.Core 8534 8535**Return value** 8536 8537| Type | Description | 8538| ------------------- | ------------------------------ | 8539| Promise<void> | Promise that returns no value. | 8540 8541**Example** 8542 8543```ts 8544import { BusinessError } from '@kit.BasicServicesKit'; 8545 8546let promise = windowClass.destroy(); 8547promise.then(() => { 8548 console.info('Succeeded in destroying the window.'); 8549}).catch((err: BusinessError) => { 8550 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 8551}); 8552``` 8553 8554### moveTo<sup>(deprecated)</sup> 8555 8556moveTo(x: number, y: number, callback: AsyncCallback<void>): void 8557 8558Moves this window. This API uses an asynchronous callback to return the result. 8559 8560This operation is not supported in a window in full-screen mode. 8561 8562> **NOTE** 8563> 8564> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9) instead. 8565 8566**System capability**: SystemCapability.WindowManager.WindowManager.Core 8567 8568**Parameters** 8569 8570| Name | Type | Mandatory | Description | 8571| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 8572| x | number | Yes | Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 8573| y | number | Yes | Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 8574| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8575 8576**Example** 8577 8578```ts 8579import { BusinessError } from '@kit.BasicServicesKit'; 8580 8581windowClass.moveTo(300, 300, (err: BusinessError) => { 8582 const errCode: number = err.code; 8583 if (errCode) { 8584 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 8585 return; 8586 } 8587 console.info('Succeeded in moving the window.'); 8588}); 8589``` 8590 8591### moveTo<sup>(deprecated)</sup> 8592 8593moveTo(x: number, y: number): Promise<void> 8594 8595Moves this window. This API uses a promise to return the result. 8596 8597This operation is not supported in a window in full-screen mode. 8598 8599> **NOTE** 8600> 8601> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9-1) instead. 8602 8603**System capability**: SystemCapability.WindowManager.WindowManager.Core 8604 8605**Parameters** 8606 8607| Name | Type | Mandatory | Description | 8608| ---- | ------ | --------- | ------------------------------------------------------------ | 8609| x | number | Yes | Coordinate position along the x-axis to which the window is moved, measured in px. A positive value means the position is to the right of the x-axis origin; a negative value means it is to the left; the value **0** means it is at the x-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 8610| y | number | Yes | Coordinate position along the y-axis to which the window is moved, measured in px. A positive value means the position is below the y-axis origin; a negative value means it is above; the value **0** means it is at the y-axis origin. The value must be an integer. If a non-integer is passed in, the value is rounded down. | 8611 8612**Return value** 8613 8614| Type | Description | 8615| ------------------- | ------------------------------ | 8616| Promise<void> | Promise that returns no value. | 8617 8618**Example** 8619 8620```ts 8621import { BusinessError } from '@kit.BasicServicesKit'; 8622 8623let promise = windowClass.moveTo(300, 300); 8624promise.then(() => { 8625 console.info('Succeeded in moving the window.'); 8626}).catch((err: BusinessError) => { 8627 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 8628}); 8629``` 8630 8631### resetSize<sup>(deprecated)</sup> 8632 8633resetSize(width: number, height: number, callback: AsyncCallback<void>): void 8634 8635Changes the size of this window. This API uses an asynchronous callback to return the result. 8636 8637- The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 8638- The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 8639 8640The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 8641 8642The window width and height you set must meet the limits. The rules are as follows: 8643- 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. 8644- 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. 8645 8646This operation is not supported in a window in full-screen mode. 8647 8648> **NOTE** 8649> 8650> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9) instead. 8651 8652**System capability**: SystemCapability.WindowManager.WindowManager.Core 8653 8654**Parameters** 8655 8656| Name | Type | Mandatory | Description | 8657| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 8658| 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. | 8659| 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. | 8660| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8661 8662**Example** 8663 8664```ts 8665import { BusinessError } from '@kit.BasicServicesKit'; 8666 8667windowClass.resetSize(500, 1000, (err: BusinessError) => { 8668 const errCode: number = err.code; 8669 if (errCode) { 8670 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 8671 return; 8672 } 8673 console.info('Succeeded in changing the window size.'); 8674}); 8675``` 8676 8677### resetSize<sup>(deprecated)</sup> 8678 8679resetSize(width: number, height: number): Promise<void> 8680 8681Changes the size of this window. This API uses a promise to return the result. 8682 8683- The main window and child window have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 8684- The minimum width and height of the main window and child window of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 8685 8686The system window has the following size limits: (0, 1920] in width and (0, 1920] in height, both in units of vp. 8687 8688The window width and height you set must meet the limits. The rules are as follows: 8689- 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. 8690- 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. 8691 8692This operation is not supported in a window in full-screen mode. 8693 8694> **NOTE** 8695> 8696> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9-1) instead. 8697 8698**System capability**: SystemCapability.WindowManager.WindowManager.Core 8699 8700**Parameters** 8701 8702| Name | Type | Mandatory | Description | 8703| ------ | ------ | --------- | ------------------------------------------------------------ | 8704| 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. | 8705| 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. | 8706 8707**Return value** 8708 8709| Type | Description | 8710| ------------------- | ------------------------------ | 8711| Promise<void> | Promise that returns no value. | 8712 8713**Example** 8714 8715```ts 8716import { BusinessError } from '@kit.BasicServicesKit'; 8717 8718let promise = windowClass.resetSize(500, 1000); 8719promise.then(() => { 8720 console.info('Succeeded in changing the window size.'); 8721}).catch((err: BusinessError) => { 8722 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 8723}); 8724``` 8725 8726### getProperties<sup>(deprecated)</sup> 8727 8728getProperties(callback: AsyncCallback<WindowProperties>): void 8729 8730Obtains the properties of this window. This API uses an asynchronous callback to return the result. 8731 8732> **NOTE** 8733> 8734> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 8735 8736**System capability**: SystemCapability.WindowManager.WindowManager.Core 8737 8738**Parameters** 8739 8740| Name | Type | Mandatory | Description | 8741| -------- | ---------------------------------------------------------- | --------- | ---------------------------------------------- | 8742| callback | AsyncCallback<[WindowProperties](#windowproperties)> | Yes | Callback used to return the window properties. | 8743 8744**Example** 8745 8746```ts 8747import { BusinessError } from '@kit.BasicServicesKit'; 8748 8749windowClass.getProperties((err: BusinessError, data) => { 8750 const errCode: number = err.code; 8751 if (errCode) { 8752 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 8753 return; 8754 } 8755 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 8756}); 8757``` 8758 8759### getProperties<sup>(deprecated)</sup> 8760 8761getProperties(): Promise<WindowProperties> 8762 8763Obtains the properties of this window. This API uses a promise to return the result. 8764 8765> **NOTE** 8766> 8767> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 8768 8769**System capability**: SystemCapability.WindowManager.WindowManager.Core 8770 8771**Return value** 8772 8773| Type | Description | 8774| ---------------------------------------------------- | --------------------------------------------- | 8775| Promise<[WindowProperties](#windowproperties)> | Promise used to return the window properties. | 8776 8777**Example** 8778 8779```ts 8780import { BusinessError } from '@kit.BasicServicesKit'; 8781 8782let promise = windowClass.getProperties(); 8783promise.then((data) => { 8784 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 8785}).catch((err: BusinessError) => { 8786 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 8787}); 8788``` 8789 8790### getAvoidArea<sup>(deprecated)</sup> 8791 8792getAvoidArea(type: [AvoidAreaType](#avoidareatype7), callback: AsyncCallback<[AvoidArea](#avoidarea7)>): void 8793 8794Obtains 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. 8795 8796> **NOTE** 8797> 8798> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 8799 8800**System capability**: SystemCapability.WindowManager.WindowManager.Core 8801 8802**Parameters** 8803 8804| Name | Type | Mandatory | Description | 8805| -------- | --------------------------------------------- | --------- | --------------------------------- | 8806| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. | 8807| callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 8808 8809**Example** 8810 8811```ts 8812import { BusinessError } from '@kit.BasicServicesKit'; 8813 8814let type = window.AvoidAreaType.TYPE_SYSTEM; 8815windowClass.getAvoidArea(type, (err: BusinessError, data) => { 8816 const errCode: number = err.code; 8817 if (errCode) { 8818 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 8819 return; 8820 } 8821 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 8822}); 8823``` 8824 8825### getAvoidArea<sup>(deprecated)</sup> 8826 8827getAvoidArea(type: [AvoidAreaType](#avoidareatype7)): Promise<[AvoidArea](#avoidarea7)> 8828 8829Obtains 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. 8830 8831> **NOTE** 8832> 8833> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 8834 8835**System capability**: SystemCapability.WindowManager.WindowManager.Core 8836 8837**Parameters** 8838 8839| Name | Type | Mandatory | Description | 8840| ---- | -------------------------------- | --------- | ----------------- | 8841| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. | 8842 8843**Return value** 8844 8845| Type | Description | 8846| --------------------------------------- | -------------------------------- | 8847| Promise<[AvoidArea](#avoidarea7)> | Promise used to return the area. | 8848 8849**Example** 8850 8851```ts 8852import { BusinessError } from '@kit.BasicServicesKit'; 8853 8854let type = window.AvoidAreaType.TYPE_SYSTEM; 8855let promise = windowClass.getAvoidArea(type); 8856promise.then((data) => { 8857 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 8858}).catch((err: BusinessError) => { 8859 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 8860}); 8861``` 8862 8863### setFullScreen<sup>(deprecated)</sup> 8864 8865setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void 8866 8867Sets whether the main window or the child window is in full-screen mode. This API uses an asynchronous callback to return the result. 8868- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them. 8869- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them. 8870 8871> **NOTE** 8872> 8873> 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. 8874 8875**System capability**: SystemCapability.WindowManager.WindowManager.Core 8876 8877**Parameters** 8878 8879| Name | Type | Mandatory | Description | 8880| ------------ | ------------------------- | --------- | ------------------------------------------------------------ | 8881| 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. | 8882| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8883 8884**Example** 8885 8886```ts 8887// EntryAbility.ets 8888import { UIAbility } from '@kit.AbilityKit'; 8889import { BusinessError } from '@kit.BasicServicesKit'; 8890 8891export default class EntryAbility extends UIAbility { 8892 // ... 8893 onWindowStageCreate(windowStage: window.WindowStage): void { 8894 console.info('onWindowStageCreate'); 8895 let windowClass: window.Window | undefined = undefined; 8896 windowStage.getMainWindow((err: BusinessError, data) => { 8897 const errCode: number = err.code; 8898 if (errCode) { 8899 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8900 return; 8901 } 8902 windowClass = data; 8903 let isFullScreen: boolean = true; 8904 windowClass.setFullScreen(isFullScreen, (err: BusinessError) => { 8905 const errCode: number = err.code; 8906 if (errCode) { 8907 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 8908 return; 8909 } 8910 console.info('Succeeded in enabling the full-screen mode.'); 8911 }); 8912 }); 8913 } 8914} 8915``` 8916 8917### setFullScreen<sup>(deprecated)</sup> 8918 8919setFullScreen(isFullScreen: boolean): Promise<void> 8920 8921Sets whether the main window or the child window is in full-screen mode. This API uses a promise to return the result. 8922- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them. 8923- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them. 8924 8925> **NOTE** 8926> 8927> 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. 8928 8929**System capability**: SystemCapability.WindowManager.WindowManager.Core 8930 8931**Parameters** 8932 8933| Name | Type | Mandatory | Description | 8934| ------------ | ------- | --------- | ------------------------------------------------------------ | 8935| 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. | 8936 8937**Return value** 8938 8939| Type | Description | 8940| ------------------- | ------------------------------ | 8941| Promise<void> | Promise that returns no value. | 8942 8943**Example** 8944 8945```ts 8946// EntryAbility.ets 8947import { UIAbility } from '@kit.AbilityKit'; 8948import { BusinessError } from '@kit.BasicServicesKit'; 8949 8950export default class EntryAbility extends UIAbility { 8951 // ... 8952 onWindowStageCreate(windowStage: window.WindowStage): void { 8953 console.info('onWindowStageCreate'); 8954 let windowClass: window.Window | undefined = undefined; 8955 windowStage.getMainWindow((err: BusinessError, data) => { 8956 const errCode: number = err.code; 8957 if (errCode) { 8958 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8959 return; 8960 } 8961 windowClass = data; 8962 let isFullScreen: boolean = true; 8963 let promise = windowClass.setFullScreen(isFullScreen); 8964 promise.then(() => { 8965 console.info('Succeeded in enabling the full-screen mode.'); 8966 }).catch((err: BusinessError) => { 8967 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 8968 }); 8969 }); 8970 } 8971} 8972``` 8973 8974### setLayoutFullScreen<sup>(deprecated)</sup> 8975 8976setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 8977 8978Sets whether the main window layout or the child window layout is immersive. This API uses an asynchronous callback to return the result. 8979- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 8980- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 8981 8982> **NOTE** 8983> 8984> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9) instead. 8985 8986**System capability**: SystemCapability.WindowManager.WindowManager.Core 8987 8988**Parameters** 8989 8990| Name | Type | Mandatory | Description | 8991| ------------------ | ------------------------- | --------- | ------------------------------------------------------------ | 8992| 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. | 8993| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8994 8995**Example** 8996 8997```ts 8998// EntryAbility.ets 8999import { UIAbility } from '@kit.AbilityKit'; 9000import { BusinessError } from '@kit.BasicServicesKit'; 9001 9002export default class EntryAbility extends UIAbility { 9003 // ... 9004 onWindowStageCreate(windowStage: window.WindowStage): void { 9005 console.info('onWindowStageCreate'); 9006 let windowClass: window.Window | undefined = undefined; 9007 windowStage.getMainWindow((err: BusinessError, data) => { 9008 const errCode: number = err.code; 9009 if (errCode) { 9010 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9011 return; 9012 } 9013 windowClass = data; 9014 let isLayoutFullScreen: boolean = true; 9015 windowClass.setLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 9016 const errCode: number = err.code; 9017 if (errCode) { 9018 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 9019 return; 9020 } 9021 console.info('Succeeded in setting the window layout to full-screen mode.'); 9022 }); 9023 }); 9024 } 9025} 9026``` 9027 9028### setLayoutFullScreen<sup>(deprecated)</sup> 9029 9030setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 9031 9032Sets whether the main window layout or the child window layout is immersive. This API uses a promise to return the result. 9033- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 9034- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 9035 9036> **NOTE** 9037> 9038> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9-1) instead. 9039 9040**System capability**: SystemCapability.WindowManager.WindowManager.Core 9041 9042**Parameters** 9043 9044| Name | Type | Mandatory | Description | 9045| ------------------ | ------- | --------- | ------------------------------------------------------------ | 9046| 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. | 9047 9048**Return value** 9049 9050| Type | Description | 9051| ------------------- | ------------------------------ | 9052| Promise<void> | Promise that returns no value. | 9053 9054**Example** 9055 9056```ts 9057// EntryAbility.ets 9058import { UIAbility } from '@kit.AbilityKit'; 9059import { BusinessError } from '@kit.BasicServicesKit'; 9060 9061export default class EntryAbility extends UIAbility { 9062 // ... 9063 onWindowStageCreate(windowStage: window.WindowStage): void { 9064 console.info('onWindowStageCreate'); 9065 let windowClass: window.Window | undefined = undefined; 9066 windowStage.getMainWindow((err: BusinessError, data) => { 9067 const errCode: number = err.code; 9068 if (errCode) { 9069 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9070 return; 9071 } 9072 windowClass = data; 9073 let isLayoutFullScreen: boolean = true; 9074 let promise = windowClass.setLayoutFullScreen(isLayoutFullScreen); 9075 promise.then(() => { 9076 console.info('Succeeded in setting the window layout to full-screen mode.'); 9077 }).catch((err: BusinessError) => { 9078 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 9079 }); 9080 }); 9081 } 9082} 9083``` 9084 9085### setSystemBarEnable<sup>(deprecated)</sup> 9086 9087setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 9088 9089Sets 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--> 9090 9091The 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 child window. 9092 9093> **NOTE** 9094> 9095> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) instead. 9096 9097**System capability**: SystemCapability.WindowManager.WindowManager.Core 9098 9099**Parameters** 9100 9101| Name | Type | Mandatory | Description | 9102| -------- | ----------------------------- | --------- | ------------------------------------------------------------ | 9103| 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. | 9104| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9105 9106 9107**Example** 9108 9109```ts 9110// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 9111// EntryAbility.ets 9112import { UIAbility } from '@kit.AbilityKit'; 9113import { BusinessError } from '@kit.BasicServicesKit'; 9114 9115export default class EntryAbility extends UIAbility { 9116 // ... 9117 onWindowStageCreate(windowStage: window.WindowStage): void { 9118 console.info('onWindowStageCreate'); 9119 let windowClass: window.Window | undefined = undefined; 9120 windowStage.getMainWindow((err: BusinessError, data) => { 9121 const errCode: number = err.code; 9122 if (errCode) { 9123 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9124 return; 9125 } 9126 windowClass = data; 9127 let names: Array<'status' | 'navigation'> = []; 9128 windowClass.setSystemBarEnable(names, (err: BusinessError) => { 9129 const errCode: number = err.code; 9130 if (errCode) { 9131 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 9132 return; 9133 } 9134 console.info('Succeeded in setting the system bar to be invisible.'); 9135 }); 9136 }); 9137 } 9138} 9139``` 9140 9141### setSystemBarEnable<sup>(deprecated)</sup> 9142 9143setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 9144 9145Sets 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--> 9146 9147The 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 child window. 9148 9149> **NOTE** 9150> 9151> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9-1) instead. 9152 9153**System capability**: SystemCapability.WindowManager.WindowManager.Core 9154 9155**Parameters** 9156 9157| Name | Type | Mandatory | Description | 9158| ----- | ----------------------------- | --------- | ------------------------------------------------------------ | 9159| 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. | 9160 9161**Return value** 9162 9163| Type | Description | 9164| ------------------- | ------------------------------ | 9165| Promise<void> | Promise that returns no value. | 9166 9167 9168**Example** 9169 9170```ts 9171// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 9172// EntryAbility.ets 9173import { UIAbility } from '@kit.AbilityKit'; 9174import { BusinessError } from '@kit.BasicServicesKit'; 9175 9176export default class EntryAbility extends UIAbility { 9177 // ... 9178 onWindowStageCreate(windowStage: window.WindowStage): void { 9179 console.info('onWindowStageCreate'); 9180 let windowClass: window.Window | undefined = undefined; 9181 windowStage.getMainWindow((err: BusinessError, data) => { 9182 const errCode: number = err.code; 9183 if (errCode) { 9184 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9185 return; 9186 } 9187 windowClass = data; 9188 let names: Array<'status' | 'navigation'> = []; 9189 let promise = windowClass.setSystemBarEnable(names); 9190 promise.then(() => { 9191 console.info('Succeeded in setting the system bar to be invisible.'); 9192 }).catch((err: BusinessError) => { 9193 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 9194 }); 9195 }); 9196 } 9197} 9198``` 9199 9200### setSystemBarProperties<sup>(deprecated)</sup> 9201 9202setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 9203 9204Sets 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--> 9205 9206This API does not take effect when it is called by a child window. 9207 9208> **NOTE** 9209> 9210> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9) instead. 9211 9212**System capability**: SystemCapability.WindowManager.WindowManager.Core 9213 9214**Parameters** 9215 9216| Name | Type | Mandatory | Description | 9217| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 9218| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar. | 9219| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9220 9221**Example** 9222 9223```ts 9224// EntryAbility.ets 9225import { UIAbility } from '@kit.AbilityKit'; 9226import { BusinessError } from '@kit.BasicServicesKit'; 9227 9228export default class EntryAbility extends UIAbility { 9229 // ... 9230 onWindowStageCreate(windowStage: window.WindowStage): void { 9231 console.info('onWindowStageCreate'); 9232 let windowClass: window.Window | undefined = undefined; 9233 windowStage.getMainWindow((err: BusinessError, data) => { 9234 const errCode: number = err.code; 9235 if (errCode) { 9236 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9237 return; 9238 } 9239 windowClass = data; 9240 let SystemBarProperties: window.SystemBarProperties = { 9241 statusBarColor: '#ff00ff', 9242 navigationBarColor: '#00ff00', 9243 // The following properties are supported since API version 8. 9244 statusBarContentColor: '#ffffff', 9245 navigationBarContentColor: '#00ffff' 9246 }; 9247 windowClass.setSystemBarProperties(SystemBarProperties, (err) => { 9248 const errCode: number = err.code; 9249 if (errCode) { 9250 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 9251 return; 9252 } 9253 console.info('Succeeded in setting the system bar properties.'); 9254 }); 9255 }); 9256 } 9257} 9258``` 9259 9260### setSystemBarProperties<sup>(deprecated)</sup> 9261 9262setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 9263 9264Sets 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--> 9265 9266This API does not take effect when it is called by a child window. 9267 9268> **NOTE** 9269> 9270> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9-1) instead. 9271 9272**System capability**: SystemCapability.WindowManager.WindowManager.Core 9273 9274**Parameters** 9275 9276| Name | Type | Mandatory | Description | 9277| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 9278| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar. | 9279 9280**Return value** 9281 9282| Type | Description | 9283| ------------------- | ------------------------------ | 9284| Promise<void> | Promise that returns no value. | 9285 9286**Example** 9287 9288```ts 9289// EntryAbility.ets 9290import { UIAbility } from '@kit.AbilityKit'; 9291import { BusinessError } from '@kit.BasicServicesKit'; 9292 9293export default class EntryAbility extends UIAbility { 9294 // ... 9295 onWindowStageCreate(windowStage: window.WindowStage): void { 9296 console.info('onWindowStageCreate'); 9297 let windowClass: window.Window | undefined = undefined; 9298 windowStage.getMainWindow((err: BusinessError, data) => { 9299 const errCode: number = err.code; 9300 if (errCode) { 9301 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9302 return; 9303 } 9304 windowClass = data; 9305 let SystemBarProperties: window.SystemBarProperties = { 9306 statusBarColor: '#ff00ff', 9307 navigationBarColor: '#00ff00', 9308 // The following properties are supported since API version 8. 9309 statusBarContentColor: '#ffffff', 9310 navigationBarContentColor: '#00ffff' 9311 }; 9312 let promise = windowClass.setSystemBarProperties(SystemBarProperties); 9313 promise.then(() => { 9314 console.info('Succeeded in setting the system bar properties.'); 9315 }).catch((err: BusinessError) => { 9316 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 9317 }); 9318 }); 9319 } 9320} 9321``` 9322 9323### loadContent<sup>(deprecated)</sup> 9324 9325loadContent(path: string, callback: AsyncCallback<void>): void 9326 9327Loads content from a page to this window. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 9328 9329> **NOTE** 9330> 9331> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9) instead. 9332 9333**System capability**: SystemCapability.WindowManager.WindowManager.Core 9334 9335**Parameters** 9336 9337| Name | Type | Mandatory | Description | 9338| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 9339| 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. | 9340| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9341 9342**Example** 9343 9344```ts 9345import { BusinessError } from '@kit.BasicServicesKit'; 9346 9347windowClass.loadContent('pages/page2/page3', (err: BusinessError) => { 9348 const errCode: number = err.code; 9349 if (errCode) { 9350 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 9351 return; 9352 } 9353 console.info('Succeeded in loading the content.'); 9354}); 9355``` 9356 9357### loadContent<sup>(deprecated)</sup> 9358 9359loadContent(path: string): Promise<void> 9360 9361Loads content from a page to this window. This API uses a promise to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 9362 9363> **NOTE** 9364> 9365> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9-1) instead. 9366 9367**System capability**: SystemCapability.WindowManager.WindowManager.Core 9368 9369**Parameters** 9370 9371| Name | Type | Mandatory | Description | 9372| ---- | ------ | --------- | ------------------------------------------------------------ | 9373| 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. | 9374 9375**Return value** 9376 9377| Type | Description | 9378| ------------------- | ------------------------------ | 9379| Promise<void> | Promise that returns no value. | 9380 9381**Example** 9382 9383```ts 9384import { BusinessError } from '@kit.BasicServicesKit'; 9385 9386let promise = windowClass.loadContent('pages/page2/page3'); 9387promise.then(() => { 9388 console.info('Succeeded in loading the content.'); 9389}).catch((err: BusinessError) => { 9390 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 9391}); 9392``` 9393 9394### isShowing<sup>(deprecated)</sup> 9395 9396isShowing(callback: AsyncCallback<boolean>): void 9397 9398Checks whether this window is displayed. This API uses an asynchronous callback to return the result. 9399 9400> **NOTE** 9401> 9402> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 9403 9404**System capability**: SystemCapability.WindowManager.WindowManager.Core 9405 9406**Parameters** 9407 9408| Name | Type | Mandatory | Description | 9409| -------- | ---------------------------- | --------- | ------------------------------------------------------------ | 9410| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the window is displayed, and **false** means the opposite. | 9411 9412**Example** 9413 9414```ts 9415import { BusinessError } from '@kit.BasicServicesKit'; 9416 9417windowClass.isShowing((err: BusinessError, data) => { 9418 const errCode: number = err.code; 9419 if (errCode) { 9420 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 9421 return; 9422 } 9423 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 9424}); 9425``` 9426 9427### isShowing<sup>(deprecated)</sup> 9428 9429isShowing(): Promise<boolean> 9430 9431Checks whether this window is displayed. This API uses a promise to return the result. 9432 9433> **NOTE** 9434> 9435> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 9436 9437**System capability**: SystemCapability.WindowManager.WindowManager.Core 9438 9439**Return value** 9440 9441| Type | Description | 9442| ---------------------- | ------------------------------------------------------------ | 9443| Promise<boolean> | Promise used to return the result. The value **true** means that the window is displayed, and **false** means the opposite. | 9444 9445**Example** 9446 9447```ts 9448import { BusinessError } from '@kit.BasicServicesKit'; 9449 9450let promise = windowClass.isShowing(); 9451promise.then((data) => { 9452 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 9453}).catch((err: BusinessError) => { 9454 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 9455}); 9456``` 9457 9458### on('systemAvoidAreaChange')<sup>(deprecated)</sup> 9459 9460on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void 9461 9462Subscribes to the event indicating changes to the area where this window cannot be displayed. 9463 9464> **NOTE** 9465> 9466> This API is supported since API version 7 and deprecated since API version 9. Use [on('avoidAreaChange')](#onavoidareachange9) instead. 9467 9468**System capability**: SystemCapability.WindowManager.WindowManager.Core 9469 9470**Parameters** 9471 9472| Name | Type | Mandatory | Description | 9473| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------ | 9474| 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. | 9475| callback | Callback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 9476 9477 9478**Example** 9479 9480```ts 9481windowClass.on('systemAvoidAreaChange', (data) => { 9482 console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data)); 9483}); 9484``` 9485 9486### off('systemAvoidAreaChange')<sup>(deprecated)</sup> 9487 9488off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void 9489 9490Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 9491 9492> **NOTE** 9493> 9494> This API is supported since API version 7 and deprecated since API version 9. Use [off('avoidAreaChange')](#offavoidareachange9) instead. 9495 9496**System capability**: SystemCapability.WindowManager.WindowManager.Core 9497 9498**Parameters** 9499 9500| Name | Type | Mandatory | Description | 9501| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------ | 9502| 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. | 9503| 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. | 9504 9505**Example** 9506 9507```ts 9508const callback = (avoidArea: window.AvoidArea) => { 9509 // ... 9510} 9511windowClass.on('systemAvoidAreaChange', callback); 9512windowClass.off('systemAvoidAreaChange', callback); 9513// Unregister all the callbacks that have been registered through on(). 9514windowClass.off('systemAvoidAreaChange'); 9515``` 9516 9517### isSupportWideGamut<sup>(deprecated)</sup> 9518 9519isSupportWideGamut(callback: AsyncCallback<boolean>): void 9520 9521Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 9522 9523> **NOTE** 9524> 9525> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9) instead. 9526 9527**System capability**: SystemCapability.WindowManager.WindowManager.Core 9528 9529**Parameters** 9530 9531| Name | Type | Mandatory | Description | 9532| -------- | ---------------------------- | --------- | ------------------------------------------------------------ | 9533| 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. | 9534 9535**Example** 9536 9537```ts 9538import { BusinessError } from '@kit.BasicServicesKit'; 9539 9540windowClass.isSupportWideGamut((err: BusinessError, data) => { 9541 const errCode: number = err.code; 9542 if (errCode) { 9543 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 9544 return; 9545 } 9546 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 9547}); 9548``` 9549 9550### isSupportWideGamut<sup>(deprecated)</sup> 9551 9552isSupportWideGamut(): Promise<boolean> 9553 9554Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 9555 9556> **NOTE** 9557> 9558> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9-1) instead. 9559 9560**System capability**: SystemCapability.WindowManager.WindowManager.Core 9561 9562**Return value** 9563 9564| Type | Description | 9565| ---------------------- | ------------------------------------------------------------ | 9566| 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. | 9567 9568**Example** 9569 9570```ts 9571import { BusinessError } from '@kit.BasicServicesKit'; 9572 9573let promise = windowClass.isSupportWideGamut(); 9574promise.then((data) => { 9575 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 9576}).catch((err: BusinessError) => { 9577 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 9578}); 9579``` 9580 9581### setColorSpace<sup>(deprecated)</sup> 9582 9583setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 9584 9585Sets a color space for this window. This API uses an asynchronous callback to return the result. 9586 9587> **NOTE** 9588> 9589> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9) instead. 9590 9591**System capability**: SystemCapability.WindowManager.WindowManager.Core 9592 9593**Parameters** 9594 9595| Name | Type | Mandatory | Description | 9596| ---------- | -------------------------- | --------- | ----------------------------------- | 9597| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set. | 9598| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9599 9600 9601**Example** 9602 9603```ts 9604import { BusinessError } from '@kit.BasicServicesKit'; 9605 9606windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 9607 const errCode: number = err.code; 9608 if (errCode) { 9609 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 9610 return; 9611 } 9612 console.info('Succeeded in setting window colorspace.'); 9613}); 9614``` 9615 9616### setColorSpace<sup>(deprecated)</sup> 9617 9618setColorSpace(colorSpace:ColorSpace): Promise<void> 9619 9620Sets a color space for this window. This API uses a promise to return the result. 9621 9622> **NOTE** 9623> 9624> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9-1) instead. 9625 9626**System capability**: SystemCapability.WindowManager.WindowManager.Core 9627 9628**Parameters** 9629 9630| Name | Type | Mandatory | Description | 9631| ---------- | -------------------------- | --------- | ------------------- | 9632| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set. | 9633 9634**Return value** 9635 9636| Type | Description | 9637| ------------------- | ------------------------------ | 9638| Promise<void> | Promise that returns no value. | 9639 9640 9641**Example** 9642 9643```ts 9644import { BusinessError } from '@kit.BasicServicesKit'; 9645 9646let promise = windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT); 9647promise.then(() => { 9648 console.info('Succeeded in setting window colorspace.'); 9649}).catch((err: BusinessError) => { 9650 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 9651}); 9652``` 9653 9654### getColorSpace<sup>(deprecated)</sup> 9655 9656getColorSpace(callback: AsyncCallback<ColorSpace>): void 9657 9658Obtains the color space of this window. This API uses an asynchronous callback to return the result. 9659 9660> **NOTE** 9661> 9662> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 9663 9664**System capability**: SystemCapability.WindowManager.WindowManager.Core 9665 9666**Parameters** 9667 9668| Name | Type | Mandatory | Description | 9669| -------- | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 9670| 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. | 9671 9672**Example** 9673 9674```ts 9675import { BusinessError } from '@kit.BasicServicesKit'; 9676 9677windowClass.getColorSpace((err: BusinessError, data) => { 9678 const errCode: number = err.code; 9679 if (errCode) { 9680 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 9681 return; 9682 } 9683 console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data)); 9684}); 9685``` 9686 9687### getColorSpace<sup>(deprecated)</sup> 9688 9689getColorSpace(): Promise<ColorSpace> 9690 9691Obtains the color space of this window. This API uses a promise to return the result. 9692 9693> **NOTE** 9694> 9695> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 9696 9697**System capability**: SystemCapability.WindowManager.WindowManager.Core 9698 9699**Return value** 9700 9701| Type | Description | 9702| ----------------------------------------- | ----------------------------------------------- | 9703| Promise<[ColorSpace](#colorspace8)> | Promise used to return the current color space. | 9704 9705**Example** 9706 9707```ts 9708import { BusinessError } from '@kit.BasicServicesKit'; 9709 9710let promise = windowClass.getColorSpace(); 9711promise.then((data) => { 9712 console.info('Succeeded in getting window color space. Cause:' + JSON.stringify(data)); 9713}).catch((err: BusinessError) => { 9714 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 9715}); 9716``` 9717 9718### setBackgroundColor<sup>(deprecated)</sup> 9719 9720setBackgroundColor(color: string, callback: AsyncCallback<void>): void 9721 9722Sets 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. 9723 9724> **NOTE** 9725> 9726> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 9727 9728**System capability**: SystemCapability.WindowManager.WindowManager.Core 9729 9730**Parameters** 9731 9732| Name | Type | Mandatory | Description | 9733| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 9734| 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'**. | 9735| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9736 9737 9738**Example** 9739 9740```ts 9741import { BusinessError } from '@kit.BasicServicesKit'; 9742 9743let color: string = '#00ff33'; 9744windowClass.setBackgroundColor(color, (err: BusinessError) => { 9745 const errCode: number = err.code; 9746 if (errCode) { 9747 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 9748 return; 9749 } 9750 console.info('Succeeded in setting the background color.'); 9751}); 9752``` 9753 9754### setBackgroundColor<sup>(deprecated)</sup> 9755 9756setBackgroundColor(color: string): Promise<void> 9757 9758Sets 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. 9759 9760> **NOTE** 9761> 9762> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 9763 9764**System capability**: SystemCapability.WindowManager.WindowManager.Core 9765 9766**Parameters** 9767 9768| Name | Type | Mandatory | Description | 9769| ----- | ------ | --------- | ------------------------------------------------------------ | 9770| 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'**. | 9771 9772**Return value** 9773 9774| Type | Description | 9775| ------------------- | ------------------------------ | 9776| Promise<void> | Promise that returns no value. | 9777 9778 9779**Example** 9780 9781```ts 9782import { BusinessError } from '@kit.BasicServicesKit'; 9783 9784let color: string = '#00ff33'; 9785let promise = windowClass.setBackgroundColor(color); 9786promise.then(() => { 9787 console.info('Succeeded in setting the background color.'); 9788}).catch((err: BusinessError) => { 9789 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 9790}); 9791``` 9792 9793### setBrightness<sup>(deprecated)</sup> 9794 9795setBrightness(brightness: number, callback: AsyncCallback<void>): void 9796 9797Sets the screen brightness for this window. This API uses an asynchronous callback to return the result. 9798 9799When 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. 9800 9801> **NOTE** 9802> 9803> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9) instead. 9804 9805**System capability**: SystemCapability.WindowManager.WindowManager.Core 9806 9807**Parameters** 9808 9809| Name | Type | Mandatory | Description | 9810| ---------- | ------------------------- | --------- | ------------------------------------------------------------ | 9811| 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. | 9812| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9813 9814 9815**Example** 9816 9817```ts 9818import { BusinessError } from '@kit.BasicServicesKit'; 9819 9820let brightness: number = 1; 9821windowClass.setBrightness(brightness, (err: BusinessError) => { 9822 const errCode: number = err.code; 9823 if (errCode) { 9824 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 9825 return; 9826 } 9827 console.info('Succeeded in setting the brightness.'); 9828}); 9829``` 9830 9831### setBrightness<sup>(deprecated)</sup> 9832 9833setBrightness(brightness: number): Promise<void> 9834 9835Sets the screen brightness for this window. This API uses a promise to return the result. 9836 9837When 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. 9838 9839> **NOTE** 9840> 9841> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9-1) instead. 9842 9843**System capability**: SystemCapability.WindowManager.WindowManager.Core 9844 9845**Parameters** 9846 9847| Name | Type | Mandatory | Description | 9848| ---------- | ------ | --------- | ------------------------------------------------------------ | 9849| 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. | 9850 9851**Return value** 9852 9853| Type | Description | 9854| ------------------- | ------------------------------ | 9855| Promise<void> | Promise that returns no value. | 9856 9857 9858**Example** 9859 9860```ts 9861import { BusinessError } from '@kit.BasicServicesKit'; 9862 9863let brightness: number = 1; 9864let promise = windowClass.setBrightness(brightness); 9865promise.then(() => { 9866 console.info('Succeeded in setting the brightness.'); 9867}).catch((err: BusinessError) => { 9868 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 9869}); 9870``` 9871 9872### setDimBehind<sup>(deprecated)</sup> 9873 9874setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void 9875 9876Sets the dimness of the window that is not on top. This API uses an asynchronous callback to return the result. 9877 9878> **NOTE** 9879> 9880> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 9881 9882**System capability**: SystemCapability.WindowManager.WindowManager.Core 9883 9884**Parameters** 9885 9886| Name | Type | Mandatory | Description | 9887| -------------- | ------------------------- | --------- | ------------------------------------------------------------ | 9888| 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. | 9889| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9890 9891**Example** 9892 9893```ts 9894import { BusinessError } from '@kit.BasicServicesKit'; 9895 9896windowClass.setDimBehind(0.5, (err: BusinessError) => { 9897 const errCode: number = err.code; 9898 if (errCode) { 9899 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 9900 return; 9901 } 9902 console.info('Succeeded in setting the dimness.'); 9903}); 9904``` 9905 9906### setDimBehind<sup>(deprecated)</sup> 9907 9908setDimBehind(dimBehindValue: number): Promise<void> 9909 9910Sets the dimness of the window that is not on top. This API uses a promise to return the result. 9911 9912> **NOTE** 9913> 9914> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 9915 9916**System capability**: SystemCapability.WindowManager.WindowManager.Core 9917 9918**Parameters** 9919 9920| Name | Type | Mandatory | Description | 9921| -------------- | ------ | --------- | ------------------------------------------------------------ | 9922| dimBehindValue | number | Yes | Dimness of the window to set. The value ranges from 0 to 1. The value **1** indicates the dimmest. | 9923 9924**Return value** 9925 9926| Type | Description | 9927| ------------------- | ------------------------------ | 9928| Promise<void> | Promise that returns no value. | 9929 9930**Example** 9931 9932```ts 9933import { BusinessError } from '@kit.BasicServicesKit'; 9934 9935let promise = windowClass.setDimBehind(0.5); 9936promise.then(() => { 9937 console.info('Succeeded in setting the dimness.'); 9938}).catch((err: BusinessError) => { 9939 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 9940}); 9941``` 9942 9943### setFocusable<sup>(deprecated)</sup> 9944 9945setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 9946 9947Sets 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. 9948 9949> **NOTE** 9950> 9951> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9) instead. 9952 9953**System capability**: SystemCapability.WindowManager.WindowManager.Core 9954 9955**Parameters** 9956 9957| Name | Type | Mandatory | Description | 9958| ----------- | ------------------------- | --------- | ------------------------------------------------------------ | 9959| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 9960| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 9961 9962 9963**Example** 9964 9965```ts 9966import { BusinessError } from '@kit.BasicServicesKit'; 9967 9968let isFocusable: boolean = true; 9969windowClass.setFocusable(isFocusable, (err: BusinessError) => { 9970 const errCode: number = err.code; 9971 if (errCode) { 9972 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 9973 return; 9974 } 9975 console.info('Succeeded in setting the window to be focusable.'); 9976}); 9977``` 9978 9979### setFocusable<sup>(deprecated)</sup> 9980 9981setFocusable(isFocusable: boolean): Promise<void> 9982 9983Sets 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. 9984 9985> **NOTE** 9986> 9987> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9-1) instead. 9988 9989**System capability**: SystemCapability.WindowManager.WindowManager.Core 9990 9991**Parameters** 9992 9993| Name | Type | Mandatory | Description | 9994| ----------- | ------- | --------- | ------------------------------------------------------------ | 9995| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 9996 9997**Return value** 9998 9999| Type | Description | 10000| ------------------- | ------------------------------ | 10001| Promise<void> | Promise that returns no value. | 10002 10003 10004**Example** 10005 10006```ts 10007import { BusinessError } from '@kit.BasicServicesKit'; 10008 10009let isFocusable: boolean = true; 10010let promise = windowClass.setFocusable(isFocusable); 10011promise.then(() => { 10012 console.info('Succeeded in setting the window to be focusable.'); 10013}).catch((err: BusinessError) => { 10014 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 10015}); 10016``` 10017 10018### setKeepScreenOn<sup>(deprecated)</sup> 10019 10020setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 10021 10022Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 10023 10024> **NOTE** 10025> 10026> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9) instead. 10027 10028**System capability**: SystemCapability.WindowManager.WindowManager.Core 10029 10030**Parameters** 10031 10032| Name | Type | Mandatory | Description | 10033| -------------- | ------------------------- | --------- | ------------------------------------------------------------ | 10034| 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. | 10035| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10036 10037 10038**Example** 10039 10040```ts 10041import { BusinessError } from '@kit.BasicServicesKit'; 10042 10043let isKeepScreenOn: boolean = true; 10044windowClass.setKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 10045 const errCode: number = err.code; 10046 if (errCode) { 10047 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 10048 return; 10049 } 10050 console.info('Succeeded in setting the screen to be always on.'); 10051}); 10052``` 10053 10054### setKeepScreenOn<sup>(deprecated)</sup> 10055 10056setKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 10057 10058Sets whether to keep the screen always on. This API uses a promise to return the result. 10059 10060> **NOTE** 10061> 10062> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9-1) instead. 10063 10064**System capability**: SystemCapability.WindowManager.WindowManager.Core 10065 10066**Parameters** 10067 10068| Name | Type | Mandatory | Description | 10069| -------------- | ------- | --------- | ------------------------------------------------------------ | 10070| 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. | 10071 10072**Return value** 10073 10074| Type | Description | 10075| ------------------- | ------------------------------ | 10076| Promise<void> | Promise that returns no value. | 10077 10078**Example** 10079 10080```ts 10081import { BusinessError } from '@kit.BasicServicesKit'; 10082 10083let isKeepScreenOn: boolean = true; 10084let promise = windowClass.setKeepScreenOn(isKeepScreenOn); 10085promise.then(() => { 10086 console.info('Succeeded in setting the screen to be always on.'); 10087}).catch((err: BusinessError) => { 10088 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 10089}); 10090``` 10091 10092### setOutsideTouchable<sup>(deprecated)</sup> 10093 10094setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): void 10095 10096Sets whether the area outside the child window is touchable. This API uses an asynchronous callback to return the result. 10097 10098> **NOTE** 10099> 10100> This API is supported since API version 7 and deprecated since API version 9. 10101> 10102> Since API version 9, the area outside the child window is touchable by default. This API is no longer supported and no substitute API is provided. 10103 10104**System capability**: SystemCapability.WindowManager.WindowManager.Core 10105 10106**Parameters** 10107 10108| Name | Type | Mandatory | Description | 10109| --------- | ------------------------- | --------- | ------------------------------------------------------------ | 10110| touchable | boolean | Yes | Whether the area outside the child window is touchable. The value **true** means the area outside the child window is touchable, and **false** means the opposite. | 10111| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10112 10113**Example** 10114 10115```ts 10116import { BusinessError } from '@kit.BasicServicesKit'; 10117 10118windowClass.setOutsideTouchable(true, (err: BusinessError) => { 10119 const errCode: number = err.code; 10120 if (errCode) { 10121 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 10122 return; 10123 } 10124 console.info('Succeeded in setting the area to be touchable.'); 10125}); 10126``` 10127 10128### setOutsideTouchable<sup>(deprecated)</sup> 10129 10130setOutsideTouchable(touchable: boolean): Promise<void> 10131 10132Sets whether the area outside the child window is touchable. This API uses a promise to return the result. 10133 10134> **NOTE** 10135> 10136> This API is supported since API version 7 and deprecated since API version 9. 10137> 10138> Since API version 9, the area outside the child window is touchable by default. This API is no longer supported and no substitute API is provided. 10139 10140**System capability**: SystemCapability.WindowManager.WindowManager.Core 10141 10142**Parameters** 10143 10144| Name | Type | Mandatory | Description | 10145| --------- | ------- | --------- | ------------------------------------------------------------ | 10146| touchable | boolean | Yes | Whether the area outside the child window is touchable. The value **true** means the area outside the child window is touchable, and **false** means the opposite. | 10147 10148**Return value** 10149 10150| Type | Description | 10151| ------------------- | ------------------------------ | 10152| Promise<void> | Promise that returns no value. | 10153 10154**Example** 10155 10156```ts 10157import { BusinessError } from '@kit.BasicServicesKit'; 10158 10159let promise = windowClass.setOutsideTouchable(true); 10160promise.then(() => { 10161 console.info('Succeeded in setting the area to be touchable.'); 10162}).catch((err: BusinessError) => { 10163 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 10164}); 10165``` 10166 10167### setPrivacyMode<sup>(deprecated)</sup> 10168 10169setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 10170 10171Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 10172 10173A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 10174 10175> **NOTE** 10176> 10177> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9) instead. 10178 10179**System capability**: SystemCapability.WindowManager.WindowManager.Core 10180 10181**Parameters** 10182 10183| Name | Type | Mandatory | Description | 10184| ------------- | ------------------------- | --------- | ------------------------------------------------------------ | 10185| 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. | 10186| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10187 10188**Example** 10189 10190```ts 10191import { BusinessError } from '@kit.BasicServicesKit'; 10192 10193let isPrivacyMode: boolean = true; 10194windowClass.setPrivacyMode(isPrivacyMode, (err: BusinessError) => { 10195 const errCode: number = err.code; 10196 if (errCode) { 10197 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 10198 return; 10199 } 10200 console.info('Succeeded in setting the window to privacy mode.'); 10201}); 10202``` 10203 10204### setPrivacyMode<sup>(deprecated)</sup> 10205 10206setPrivacyMode(isPrivacyMode: boolean): Promise<void> 10207 10208Sets whether this window is in privacy mode. This API uses a promise to return the result. 10209 10210A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 10211 10212> **NOTE** 10213> 10214> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9-1) instead. 10215 10216**System capability**: SystemCapability.WindowManager.WindowManager.Core 10217 10218**Parameters** 10219 10220| Name | Type | Mandatory | Description | 10221| ------------- | ------- | --------- | ------------------------------------------------------------ | 10222| 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. | 10223 10224**Return value** 10225 10226| Type | Description | 10227| ------------------- | ------------------------------ | 10228| Promise<void> | Promise that returns no value. | 10229 10230**Example** 10231 10232```ts 10233import { BusinessError } from '@kit.BasicServicesKit'; 10234 10235let isPrivacyMode: boolean = true; 10236let promise = windowClass.setPrivacyMode(isPrivacyMode); 10237promise.then(() => { 10238 console.info('Succeeded in setting the window to privacy mode.'); 10239}).catch((err: BusinessError) => { 10240 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 10241}); 10242``` 10243 10244### setTouchable<sup>(deprecated)</sup> 10245 10246setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 10247 10248Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 10249 10250> **NOTE** 10251> 10252> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9) instead. 10253 10254**System capability**: SystemCapability.WindowManager.WindowManager.Core 10255 10256**Parameters** 10257 10258| Name | Type | Mandatory | Description | 10259| ----------- | ------------------------- | --------- | ------------------------------------------------------------ | 10260| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite. | 10261| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10262 10263 10264**Example** 10265 10266```ts 10267import { BusinessError } from '@kit.BasicServicesKit'; 10268 10269let isTouchable = true; 10270windowClass.setTouchable(isTouchable, (err: BusinessError) => { 10271 const errCode: number = err.code; 10272 if (errCode) { 10273 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 10274 return; 10275 } 10276 console.info('Succeeded in setting the window to be touchable.'); 10277}); 10278``` 10279 10280### setTouchable<sup>(deprecated)</sup> 10281 10282setTouchable(isTouchable: boolean): Promise<void> 10283 10284Sets whether this window is touchable. This API uses a promise to return the result. 10285 10286> **NOTE** 10287> 10288> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9-1) instead. 10289 10290**System capability**: SystemCapability.WindowManager.WindowManager.Core 10291 10292**Parameters** 10293 10294| Name | Type | Mandatory | Description | 10295| ----------- | ------- | --------- | ------------------------------------------------------------ | 10296| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite. | 10297 10298**Return value** 10299 10300| Type | Description | 10301| ------------------- | ------------------------------ | 10302| Promise<void> | Promise that returns no value. | 10303 10304 10305**Example** 10306 10307```ts 10308import { BusinessError } from '@kit.BasicServicesKit'; 10309 10310let isTouchable = true; 10311let promise = windowClass.setTouchable(isTouchable); 10312promise.then(() => { 10313 console.info('Succeeded in setting the window to be touchable.'); 10314}).catch((err: BusinessError) => { 10315 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 10316}); 10317``` 10318 10319## WindowStageEventType<sup>9+</sup> 10320 10321Describes the lifecycle of a window stage. 10322 10323**Model restriction**: This API can be used only in the stage model. 10324 10325**System capability**: SystemCapability.WindowManager.WindowManager.Core 10326 10327**Atomic service API**: This API can be used in atomic services since API version 11. 10328 10329| Name | Value | Description | 10330| --------------------- | ----- | ------------------------------------------------------------ | 10331| 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. | 10332| 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. | 10333| 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. | 10334| 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. | 10335| 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. | 10336| 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. | 10337 10338## ModalityType<sup>14+</sup> 10339 10340Enumerates the modality types of the child window. 10341 10342**System capability**: SystemCapability.Window.SessionManager 10343 10344**Atomic service API**: This API can be used in atomic services since API version 14. 10345 10346| Name | Value | Description | 10347| -------------------- | ----- | ------------------------------------------------------------ | 10348| WINDOW_MODALITY | 0 | Window-modal. Select this value when you want the parent window not to respond to user interactions. | 10349| 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. | 10350 10351## SubWindowOptions<sup>11+</sup> 10352 10353Describes the parameters used for creating a child window. 10354 10355**System capability**: SystemCapability.Window.SessionManager 10356 10357| Name | Type | Read-Only | Optional | Description | 10358| -------------------------- | ------------------------------- | --------- | -------- | ------------------------------------------------------------ | 10359| title<sup>11+</sup> | string | No | No | Title of the child window.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 10360| decorEnabled<sup>11+</sup> | boolean | No | No | Whether decorations are displayed in the child window. 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. | 10361| isModal<sup>12+</sup> | boolean | No | Yes | Whether the modal property is enabled for the child window. The value** true** means that the modal property is enabled for the child window, and **false** means to disable it. The default value is **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 10362| modalityType<sup>14+</sup> | [ModalityType](#modalitytype14) | No | Yes | Modality type of the child window. This parameter takes effect only when the modal property is enabled for the child window. **WINDOW_MODALITY** means window-modal, and **APPLICATION_MODALITY** means application-modal. The default value is **WINDOW_MODALITY**.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 10363 10364## WindowStage<sup>9+</sup> 10365 10366Implements a window manager, which manages each basic window unit, that is, [Window](#window) instance. 10367 10368Before 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. 10369 10370### getMainWindow<sup>9+</sup> 10371 10372getMainWindow(callback: AsyncCallback<Window>): void 10373 10374Obtains the main window of this window stage. This API uses an asynchronous callback to return the result. 10375 10376**Model restriction**: This API can be used only in the stage model. 10377 10378**System capability**: SystemCapability.WindowManager.WindowManager.Core 10379 10380**Atomic service API**: This API can be used in atomic services since API version 11. 10381 10382**Parameters** 10383 10384| Name | Type | Mandatory | Description | 10385| -------- | -------------------------------------- | --------- | ---------------------------------------- | 10386| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window. | 10387 10388**Error codes** 10389 10390For details about the error codes, see [Window Error Codes](errorcode-window.md). 10391 10392| ID | Error Message | 10393| ------- | ------------------------------ | 10394| 1300002 | This window state is abnormal. | 10395| 1300005 | This window stage is abnormal. | 10396 10397**Example** 10398 10399```ts 10400// EntryAbility.ets 10401import { UIAbility } from '@kit.AbilityKit'; 10402import { BusinessError } from '@kit.BasicServicesKit'; 10403 10404export default class EntryAbility extends UIAbility { 10405 // ... 10406 10407 onWindowStageCreate(windowStage: window.WindowStage) { 10408 console.info('onWindowStageCreate'); 10409 let windowClass: window.Window | undefined = undefined; 10410 windowStage.getMainWindow((err: BusinessError, data) => { 10411 const errCode: number = err.code; 10412 if (errCode) { 10413 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10414 return; 10415 } 10416 windowClass = data; 10417 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 10418 }); 10419 } 10420}; 10421``` 10422 10423### getMainWindow<sup>9+</sup> 10424 10425getMainWindow(): Promise<Window> 10426 10427Obtains the main window of this window stage. This API uses a promise to return the result. 10428 10429**Model restriction**: This API can be used only in the stage model. 10430 10431**System capability**: SystemCapability.WindowManager.WindowManager.Core 10432 10433**Atomic service API**: This API can be used in atomic services since API version 11. 10434 10435**Return value** 10436 10437| Type | Description | 10438| -------------------------------- | --------------------------------------- | 10439| Promise<[Window](#window)> | Promise used to return the main window. | 10440 10441**Error codes** 10442 10443For details about the error codes, see [Window Error Codes](errorcode-window.md). 10444 10445| ID | Error Message | 10446| ------- | ------------------------------ | 10447| 1300002 | This window state is abnormal. | 10448| 1300005 | This window stage is abnormal. | 10449 10450**Example** 10451 10452```ts 10453// EntryAbility.ets 10454import { UIAbility } from '@kit.AbilityKit'; 10455import { BusinessError } from '@kit.BasicServicesKit'; 10456 10457export default class EntryAbility extends UIAbility { 10458 // ... 10459 10460 onWindowStageCreate(windowStage: window.WindowStage) { 10461 console.info('onWindowStageCreate'); 10462 let windowClass: window.Window | undefined = undefined; 10463 let promise = windowStage.getMainWindow(); 10464 promise.then((data) => { 10465 windowClass = data; 10466 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 10467 }).catch((err: BusinessError) => { 10468 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10469 }); 10470 } 10471}; 10472``` 10473 10474### getMainWindowSync<sup>9+</sup> 10475 10476getMainWindowSync(): Window 10477 10478Obtains the main window of this window stage. 10479 10480**Model restriction**: This API can be used only in the stage model. 10481 10482**System capability**: SystemCapability.WindowManager.WindowManager.Core 10483 10484**Atomic service API**: This API can be used in atomic services since API version 11. 10485 10486**Return value** 10487 10488| Type | Description | 10489| ----------------- | ------------ | 10490| [Window](#window) | Main window. | 10491 10492**Error codes** 10493 10494For details about the error codes, see [Window Error Codes](errorcode-window.md). 10495 10496| ID | Error Message | 10497| ------- | ------------------------------ | 10498| 1300002 | This window state is abnormal. | 10499| 1300005 | This window stage is abnormal. | 10500 10501**Example** 10502<!--code_no_check--> 10503```ts 10504// EntryAbility.ets 10505import { UIAbility } from '@kit.AbilityKit'; 10506 10507export default class EntryAbility extends UIAbility { 10508 // ... 10509 10510 onWindowStageCreate(windowStage: window.WindowStage) { 10511 console.info('onWindowStageCreate'); 10512 try { 10513 let windowClass = windowStage.getMainWindowSync(); 10514 } catch (exception) { 10515 console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`); 10516 } 10517 } 10518}; 10519``` 10520 10521### createSubWindow<sup>9+</sup> 10522 10523createSubWindow(name: string, callback: AsyncCallback<Window>): void 10524 10525Creates a child window for this window stage. This API uses an asynchronous callback to return the result. 10526 10527**Model restriction**: This API can be used only in the stage model. 10528 10529**System capability**: SystemCapability.WindowManager.WindowManager.Core 10530 10531**Atomic service API**: This API can be used in atomic services since API version 11. 10532 10533**Parameters** 10534 10535| Name | Type | Mandatory | Description | 10536| -------- | -------------------------------------- | --------- | ----------------------------------------- | 10537| name | string | Yes | Name of the child window. | 10538| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the child window. | 10539 10540**Error codes** 10541 10542For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10543 10544| ID | Error Message | 10545| ------- | ----------------------------------------------------------- | 10546| 401 | Parameter error. Possible cause: Incorrect parameter types. | 10547| 1300002 | This window state is abnormal. | 10548| 1300005 | This window stage is abnormal. | 10549 10550**Example** 10551 10552```ts 10553// EntryAbility.ets 10554import { UIAbility } from '@kit.AbilityKit'; 10555import { BusinessError } from '@kit.BasicServicesKit'; 10556 10557export default class EntryAbility extends UIAbility { 10558 // ... 10559 10560 onWindowStageCreate(windowStage: window.WindowStage) { 10561 console.info('onWindowStageCreate'); 10562 let windowClass: window.Window | undefined = undefined; 10563 try { 10564 windowStage.createSubWindow('mySubWindow', (err: BusinessError, data) => { 10565 const errCode: number = err.code; 10566 if (errCode) { 10567 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 10568 return; 10569 } 10570 windowClass = data; 10571 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 10572 if (!windowClass) { 10573 console.info('Failed to load the content. Cause: windowClass is null'); 10574 } 10575 else { 10576 (windowClass as window.Window).resize(500, 1000); 10577 } 10578 }); 10579 } catch (exception) { 10580 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 10581 } 10582 } 10583}; 10584``` 10585 10586### createSubWindow<sup>9+</sup> 10587 10588createSubWindow(name: string): Promise<Window> 10589 10590Creates a child window for this window stage. This API uses a promise to return the result. 10591 10592**Model restriction**: This API can be used only in the stage model. 10593 10594**System capability**: SystemCapability.WindowManager.WindowManager.Core 10595 10596**Atomic service API**: This API can be used in atomic services since API version 11. 10597 10598**Parameters** 10599 10600| Name | Type | Mandatory | Description | 10601| ---- | ------ | --------- | ------------------------- | 10602| name | string | Yes | Name of the child window. | 10603 10604**Return value** 10605 10606| Type | Description | 10607| -------------------------------- | ---------------------------------------- | 10608| Promise<[Window](#window)> | Promise used to return the child window. | 10609 10610**Error codes** 10611 10612For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10613 10614| ID | Error Message | 10615| ------- | ----------------------------------------------------------- | 10616| 401 | Parameter error. Possible cause: Incorrect parameter types. | 10617| 1300002 | This window state is abnormal. | 10618| 1300005 | This window stage is abnormal. | 10619 10620**Example** 10621 10622```ts 10623// EntryAbility.ets 10624import { UIAbility } from '@kit.AbilityKit'; 10625import { BusinessError } from '@kit.BasicServicesKit'; 10626 10627export default class EntryAbility extends UIAbility { 10628 // ... 10629 10630 onWindowStageCreate(windowStage: window.WindowStage) { 10631 console.info('onWindowStageCreate'); 10632 let windowClass: window.Window | undefined = undefined; 10633 try { 10634 let promise = windowStage.createSubWindow('mySubWindow'); 10635 promise.then((data) => { 10636 windowClass = data; 10637 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 10638 }).catch((err: BusinessError) => { 10639 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 10640 }); 10641 } catch (exception) { 10642 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 10643 } 10644 } 10645}; 10646``` 10647 10648### createSubWindowWithOptions<sup>11+</sup> 10649 10650createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 10651 10652Creates a child window for this window stage. This API uses a promise to return the result. 10653 10654**Model restriction**: This API can be used only in the stage model. 10655 10656**Atomic service API**: This API can be used in atomic services since API version 12. 10657 10658**System capability**: SystemCapability.Window.SessionManager 10659 10660**Parameters** 10661 10662| Name | Type | Mandatory | Description | 10663| ------- | --------------------------------------- | --------- | ---------------------------------------------- | 10664| name | string | Yes | Name of the child window. | 10665| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the child window. | 10666 10667**Return value** 10668 10669| Type | Description | 10670| -------------------------------- | ------------------------------------------------ | 10671| Promise<[Window](#window)> | Promise used to return the child window created. | 10672 10673**Error codes** 10674 10675For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10676 10677| ID | Error Message | 10678| ------- | ------------------------------------------------------------ | 10679| 401 | Parameter error. Possible cause: Incorrect parameter types. | 10680| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 10681| 1300002 | This window state is abnormal. | 10682| 1300005 | This window stage is abnormal. | 10683 10684**Example** 10685 10686```ts 10687// EntryAbility.ets 10688import { UIAbility } from '@kit.AbilityKit'; 10689import { BusinessError } from '@kit.BasicServicesKit'; 10690 10691export default class EntryAbility extends UIAbility { 10692 // ... 10693 10694 onWindowStageCreate(windowStage: window.WindowStage) { 10695 console.info('onWindowStageCreate'); 10696 let windowClass: window.Window | undefined = undefined; 10697 try { 10698 let options : window.SubWindowOptions = { 10699 title: 'title', 10700 decorEnabled: true 10701 }; 10702 let promise = windowStage.createSubWindowWithOptions('mySubWindow', options); 10703 promise.then((data) => { 10704 windowClass = data; 10705 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 10706 }).catch((err: BusinessError) => { 10707 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 10708 }); 10709 } catch (exception) { 10710 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 10711 } 10712 } 10713}; 10714``` 10715 10716### getSubWindow<sup>9+</sup> 10717 10718getSubWindow(callback: AsyncCallback<Array<Window>>): void 10719 10720Obtains all the child windows of this window stage. This API uses an asynchronous callback to return the result. 10721 10722**Model restriction**: This API can be used only in the stage model. 10723 10724**System capability**: SystemCapability.WindowManager.WindowManager.Core 10725 10726**Atomic service API**: This API can be used in atomic services since API version 11. 10727 10728**Parameters** 10729 10730| Name | Type | Mandatory | Description | 10731| -------- | --------------------------------------------------- | --------- | ---------------------------------------------- | 10732| callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the child windows. | 10733 10734**Error codes** 10735 10736For details about the error codes, see [Window Error Codes](errorcode-window.md). 10737 10738| ID | Error Message | 10739| ------- | ------------------------------ | 10740| 1300005 | This window stage is abnormal. | 10741 10742**Example** 10743<!--code_no_check--> 10744```ts 10745// EntryAbility.ets 10746import { UIAbility } from '@kit.AbilityKit'; 10747import { BusinessError } from '@kit.BasicServicesKit'; 10748 10749export default class EntryAbility extends UIAbility { 10750 // ... 10751 10752 onWindowStageCreate(windowStage: window.WindowStage) { 10753 console.info('onWindowStageCreate'); 10754 let windowClass: window.Window[] = []; 10755 windowStage.getSubWindow((err: BusinessError, data) => { 10756 const errCode: number = err.code; 10757 if (errCode) { 10758 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 10759 return; 10760 } 10761 windowClass = data; 10762 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 10763 }); 10764 } 10765}; 10766``` 10767 10768### getSubWindow<sup>9+</sup> 10769 10770getSubWindow(): Promise<Array<Window>> 10771 10772Obtains all the child windows of this window stage. This API uses a promise to return the result. 10773 10774**Model restriction**: This API can be used only in the stage model. 10775 10776**System capability**: SystemCapability.WindowManager.WindowManager.Core 10777 10778**Atomic service API**: This API can be used in atomic services since API version 11. 10779 10780**Return value** 10781 10782| Type | Description | 10783| --------------------------------------------- | --------------------------------------------- | 10784| Promise<Array<[Window](#window)>> | Promise used to return all the child windows. | 10785 10786**Error codes** 10787 10788For details about the error codes, see [Window Error Codes](errorcode-window.md). 10789 10790| ID | Error Message | 10791| ------- | ------------------------------ | 10792| 1300005 | This window stage is abnormal. | 10793 10794**Example** 10795<!--code_no_check--> 10796```ts 10797// EntryAbility.ets 10798import { UIAbility } from '@kit.AbilityKit'; 10799import { BusinessError } from '@kit.BasicServicesKit'; 10800 10801export default class EntryAbility extends UIAbility { 10802 // ... 10803 10804 onWindowStageCreate(windowStage: window.WindowStage) { 10805 console.info('onWindowStageCreate'); 10806 let windowClass: window.Window[] = []; 10807 let promise = windowStage.getSubWindow(); 10808 promise.then((data) => { 10809 windowClass = data; 10810 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 10811 }).catch((err: BusinessError) => { 10812 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 10813 }); 10814 } 10815}; 10816``` 10817 10818### loadContent<sup>9+</sup> 10819 10820loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 10821 10822Loads the content of a page, with its path in the current project specified, to the main window of this window stage, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 10823 10824**Model restriction**: This API can be used only in the stage model. 10825 10826**System capability**: SystemCapability.WindowManager.WindowManager.Core 10827 10828**Atomic service API**: This API can be used in atomic services since API version 11. 10829 10830**Parameters** 10831 10832| Name | Type | Mandatory | Description | 10833| -------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | 10834| 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. | 10835| 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. | 10836| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10837 10838**Error codes** 10839 10840For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10841 10842| ID | Error Message | 10843| ------- | ------------------------------------------------------------ | 10844| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10845| 1300002 | This window state is abnormal. | 10846| 1300005 | This window stage is abnormal. | 10847 10848**Example** 10849 10850```ts 10851// EntryAbility.ets 10852import { UIAbility } from '@kit.AbilityKit'; 10853import { BusinessError } from '@kit.BasicServicesKit'; 10854 10855export default class EntryAbility extends UIAbility { 10856 // ... 10857 10858 storage: LocalStorage = new LocalStorage(); 10859 10860 onWindowStageCreate(windowStage: window.WindowStage) { 10861 this.storage.setOrCreate('storageSimpleProp', 121); 10862 console.info('onWindowStageCreate'); 10863 try { 10864 windowStage.loadContent('pages/page2', this.storage, (err: BusinessError) => { 10865 const errCode: number = err.code; 10866 if (errCode) { 10867 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10868 return; 10869 } 10870 console.info('Succeeded in loading the content.'); 10871 }); 10872 } catch (exception) { 10873 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 10874 } 10875 } 10876}; 10877``` 10878 10879### loadContent<sup>9+</sup> 10880 10881loadContent(path: string, storage?: LocalStorage): Promise<void> 10882 10883Loads the content of a page, with its path in the current project specified, to the main window of this window stage, and transfers the state attribute to the page through a local storage. This API uses a promise to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 10884 10885**Model restriction**: This API can be used only in the stage model. 10886 10887**System capability**: SystemCapability.WindowManager.WindowManager.Core 10888 10889**Atomic service API**: This API can be used in atomic services since API version 11. 10890 10891**Parameters** 10892 10893| Name | Type | Mandatory | Description | 10894| ------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | 10895| 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. | 10896| 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. | 10897 10898**Return value** 10899 10900| Type | Description | 10901| ------------------- | ------------------------------ | 10902| Promise<void> | Promise that returns no value. | 10903 10904**Error codes** 10905 10906For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10907 10908| ID | Error Message | 10909| ------- | ------------------------------------------------------------ | 10910| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10911| 1300002 | This window state is abnormal. | 10912| 1300005 | This window stage is abnormal. | 10913 10914**Example** 10915 10916```ts 10917// EntryAbility.ets 10918import { UIAbility } from '@kit.AbilityKit'; 10919import { BusinessError } from '@kit.BasicServicesKit'; 10920 10921export default class EntryAbility extends UIAbility { 10922 // ... 10923 10924 storage: LocalStorage = new LocalStorage(); 10925 10926 onWindowStageCreate(windowStage: window.WindowStage) { 10927 this.storage.setOrCreate('storageSimpleProp', 121); 10928 console.info('onWindowStageCreate'); 10929 try { 10930 let promise = windowStage.loadContent('pages/page2', this.storage); 10931 promise.then(() => { 10932 console.info('Succeeded in loading the content.'); 10933 }).catch((err: BusinessError) => { 10934 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10935 }); 10936 } catch (exception) { 10937 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 10938 } 10939 ; 10940 } 10941}; 10942``` 10943 10944### loadContent<sup>9+</sup> 10945 10946loadContent(path: string, callback: AsyncCallback<void>): void 10947 10948Loads content from a page to this window stage. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 10949 10950**Model restriction**: This API can be used only in the stage model. 10951 10952**System capability**: SystemCapability.WindowManager.WindowManager.Core 10953 10954**Atomic service API**: This API can be used in atomic services since API version 11. 10955 10956**Parameters** 10957 10958| Name | Type | Mandatory | Description | 10959| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 10960| 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. | 10961| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 10962 10963**Error codes** 10964 10965For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 10966 10967| ID | Error Message | 10968| ------- | ------------------------------------------------------------ | 10969| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 10970| 1300002 | This window state is abnormal. | 10971| 1300005 | This window stage is abnormal. | 10972 10973**Example** 10974 10975```ts 10976// EntryAbility.ets 10977import { UIAbility } from '@kit.AbilityKit'; 10978import { BusinessError } from '@kit.BasicServicesKit'; 10979 10980export default class EntryAbility extends UIAbility { 10981 // ... 10982 10983 onWindowStageCreate(windowStage: window.WindowStage) { 10984 console.info('onWindowStageCreate'); 10985 try { 10986 windowStage.loadContent('pages/page2', (err: BusinessError) => { 10987 const errCode: number = err.code; 10988 if (errCode) { 10989 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10990 return; 10991 } 10992 console.info('Succeeded in loading the content.'); 10993 }); 10994 } catch (exception) { 10995 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 10996 } 10997 } 10998}; 10999``` 11000 11001### loadContentByName<sup>11+</sup> 11002 11003loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 11004 11005Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window stage, and transfers the state attribute to the page through a local storage. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 11006 11007**Model restriction**: This API can be used only in the stage model. 11008 11009**System capability**: SystemCapability.WindowManager.WindowManager.Core 11010 11011**Atomic service API**: This API can be used in atomic services since API version 11. 11012 11013**Parameters** 11014 11015| Name | Type | Mandatory | Description | 11016| -------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | 11017| name | string | Yes | Name of the named route page. | 11018| 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. | 11019| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11020 11021**Error codes** 11022 11023For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11024 11025| ID | Error Message | 11026| ------- | ------------------------------------------------------------ | 11027| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11028| 1300002 | This window state is abnormal. | 11029| 1300003 | This window manager service works abnormally. | 11030 11031**Example** 11032 11033<!--code_no_check--> 11034```ts 11035// EntryAbility.ets 11036import { UIAbility } from '@kit.AbilityKit'; 11037import { BusinessError } from '@kit.BasicServicesKit'; 11038import * as Index from '../pages/Index'; // Import the named route page. 11039 11040export default class EntryAbility extends UIAbility { 11041 // ... 11042 11043 storage: LocalStorage = new LocalStorage(); 11044 11045 onWindowStageCreate(windowStage: window.WindowStage) { 11046 console.info('onWindowStageCreate'); 11047 this.storage.setOrCreate('storageSimpleProp', 121); 11048 try { 11049 windowStage.loadContentByName(Index.entryName, this.storage, (err: BusinessError) => { 11050 const errCode: number = err.code; 11051 if (errCode) { 11052 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 11053 return; 11054 } 11055 console.info('Succeeded in loading the content.'); 11056 }); 11057 } catch (exception) { 11058 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 11059 } 11060 } 11061}; 11062``` 11063<!--code_no_check--> 11064```ts 11065// ets/pages/Index.ets 11066export const entryName : string = 'Index'; 11067@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 11068@Component 11069export struct Index { 11070 @State message: string = 'Hello World' 11071 build() { 11072 Row() { 11073 Column() { 11074 Text(this.message) 11075 .fontSize(50) 11076 .fontWeight(FontWeight.Bold) 11077 } 11078 .width('100%') 11079 } 11080 .height('100%') 11081 } 11082} 11083``` 11084 11085### loadContentByName<sup>11+</sup> 11086 11087loadContentByName(name: string, callback: AsyncCallback<void>): void 11088 11089Loads the content of a [named route](../../ui/arkts-routing.md#named-route) page to this window stage. This API uses an asynchronous callback to return the result. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 11090 11091**Model restriction**: This API can be used only in the stage model. 11092 11093**System capability**: SystemCapability.WindowManager.WindowManager.Core 11094 11095**Atomic service API**: This API can be used in atomic services since API version 11. 11096 11097**Parameters** 11098 11099| Name | Type | Mandatory | Description | 11100| -------- | ------------------------- | --------- | ----------------------------------- | 11101| name | string | Yes | Name of the named route page. | 11102| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 11103 11104**Error codes** 11105 11106For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11107 11108| ID | Error Message | 11109| ------- | ------------------------------------------------------------ | 11110| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11111| 1300002 | This window state is abnormal. | 11112| 1300003 | This window manager service works abnormally. | 11113 11114**Example** 11115 11116<!--code_no_check--> 11117```ts 11118// EntryAbility.ets 11119import { UIAbility } from '@kit.AbilityKit'; 11120import { BusinessError } from '@kit.BasicServicesKit'; 11121import * as Index from '../pages/Index'; // Import the named route page. 11122 11123export default class EntryAbility extends UIAbility { 11124 // ... 11125 11126 onWindowStageCreate(windowStage: window.WindowStage) { 11127 console.info('onWindowStageCreate'); 11128 try { 11129 windowStage.loadContentByName(Index.entryName, (err: BusinessError) => { 11130 const errCode: number = err.code; 11131 if (errCode) { 11132 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 11133 return; 11134 } 11135 console.info('Succeeded in loading the content.'); 11136 }); 11137 } catch (exception) { 11138 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 11139 } 11140 } 11141}; 11142``` 11143<!--code_no_check--> 11144```ts 11145// ets/pages/Index.ets 11146export const entryName : string = 'Index'; 11147@Entry({routeName: entryName}) 11148@Component 11149export struct Index { 11150 @State message: string = 'Hello World' 11151 build() { 11152 Row() { 11153 Column() { 11154 Text(this.message) 11155 .fontSize(50) 11156 .fontWeight(FontWeight.Bold) 11157 } 11158 .width('100%') 11159 } 11160 .height('100%') 11161 } 11162} 11163``` 11164 11165### loadContentByName<sup>11+</sup> 11166 11167loadContentByName(name: string, storage?: LocalStorage): Promise<void>; 11168 11169Loads 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. You are advised to call this API during UIAbility startup. If called multiple times, this API will destroy the existing page content (UIContent) before loading the new content. Exercise caution when using it. 11170 11171**Model restriction**: This API can be used only in the stage model. 11172 11173**System capability**: SystemCapability.WindowManager.WindowManager.Core 11174 11175**Atomic service API**: This API can be used in atomic services since API version 11. 11176 11177**Parameters** 11178 11179| Name | Type | Mandatory | Description | 11180| ------- | ------------ | --------- | ------------------------------------------------------------ | 11181| name | string | Yes | Name of the named route page. | 11182| storage | LocalStorage | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page. | 11183 11184**Error codes** 11185 11186For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11187 11188| ID | Error Message | 11189| ------- | ------------------------------------------------------------ | 11190| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11191| 1300002 | This window state is abnormal. | 11192| 1300003 | This window manager service works abnormally. | 11193 11194**Example** 11195 11196<!--code_no_check--> 11197```ts 11198// EntryAbility.ets 11199import { UIAbility } from '@kit.AbilityKit'; 11200import { BusinessError } from '@kit.BasicServicesKit'; 11201import * as Index from '../pages/Index'; // Import the named route page. 11202 11203export default class EntryAbility extends UIAbility { 11204 // ... 11205 11206 storage: LocalStorage = new LocalStorage(); 11207 11208 onWindowStageCreate(windowStage: window.WindowStage) { 11209 console.info('onWindowStageCreate'); 11210 this.storage.setOrCreate('storageSimpleProp', 121); 11211 try { 11212 let promise = windowStage.loadContentByName(Index.entryName, this.storage); 11213 promise.then(() => { 11214 console.info('Succeeded in loading the content.'); 11215 }).catch((err: BusinessError) => { 11216 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 11217 }); 11218 } catch (exception) { 11219 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 11220 } 11221 } 11222}; 11223``` 11224<!--code_no_check--> 11225```ts 11226// ets/pages/Index.ets 11227export const entryName : string = 'Index'; 11228@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 11229@Component 11230export struct Index { 11231 @State message: string = 'Hello World' 11232 build() { 11233 Row() { 11234 Column() { 11235 Text(this.message) 11236 .fontSize(50) 11237 .fontWeight(FontWeight.Bold) 11238 } 11239 .width('100%') 11240 } 11241 .height('100%') 11242 } 11243} 11244``` 11245 11246### on('windowStageEvent')<sup>9+</sup> 11247 11248on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void 11249 11250Subscribes to the window stage lifecycle change event. 11251 11252**Model restriction**: This API can be used only in the stage model. 11253 11254**System capability**: SystemCapability.WindowManager.WindowManager.Core 11255 11256**Atomic service API**: This API can be used in atomic services since API version 11. 11257 11258**Parameters** 11259 11260| Name | Type | Mandatory | Description | 11261| --------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 11262| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. | 11263| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the window stage lifecycle state. | 11264 11265**Error codes** 11266 11267For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11268 11269| ID | Error Message | 11270| ------- | ------------------------------------------------------------ | 11271| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 11272| 1300002 | This window state is abnormal. | 11273| 1300005 | This window stage is abnormal. | 11274 11275**Example** 11276 11277```ts 11278// EntryAbility.ets 11279import { UIAbility } from '@kit.AbilityKit'; 11280 11281export default class EntryAbility extends UIAbility { 11282 // ... 11283 11284 onWindowStageCreate(windowStage: window.WindowStage) { 11285 console.info('onWindowStageCreate'); 11286 try { 11287 windowStage.on('windowStageEvent', (data) => { 11288 console.info('Succeeded in enabling the listener for window stage event changes. Data: ' + 11289 JSON.stringify(data)); 11290 }); 11291 } catch (exception) { 11292 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 11293 } 11294 } 11295}; 11296``` 11297 11298### off('windowStageEvent')<sup>9+</sup> 11299 11300off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType>): void 11301 11302Unsubscribes from the window stage lifecycle change event. 11303 11304**Model restriction**: This API can be used only in the stage model. 11305 11306**System capability**: SystemCapability.WindowManager.WindowManager.Core 11307 11308**Atomic service API**: This API can be used in atomic services since API version 11. 11309 11310**Parameters** 11311 11312| Name | Type | Mandatory | Description | 11313| --------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 11314| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. | 11315| 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. | 11316 11317**Error codes** 11318 11319For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11320 11321| ID | Error Message | 11322| ------- | ------------------------------------------------------------ | 11323| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 11324| 1300002 | This window state is abnormal. | 11325| 1300005 | This window stage is abnormal. | 11326 11327**Example** 11328 11329```ts 11330// EntryAbility.ets 11331import { UIAbility } from '@kit.AbilityKit'; 11332 11333export default class EntryAbility extends UIAbility { 11334 // ... 11335 11336 onWindowStageCreate(windowStage: window.WindowStage) { 11337 console.info('onWindowStageCreate'); 11338 const callback = (windowStageEventType: window.WindowStageEventType) => { 11339 // ... 11340 } 11341 try { 11342 windowStage.on('windowStageEvent', callback); 11343 } catch (exception) { 11344 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 11345 } 11346 try { 11347 windowStage.off('windowStageEvent', callback); 11348 // Unregister all the callbacks that have been registered through on(). 11349 windowStage.off('windowStageEvent'); 11350 } catch (exception) { 11351 console.error(`Failed to disable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 11352 } 11353 } 11354}; 11355``` 11356 11357### on('windowStageClose')<sup>14+</sup> 11358 11359on(eventType: 'windowStageClose', callback: Callback<void>): void 11360 11361Subscribes to the click event on the close button in the three-button navigation bar of the main window. This event is triggered when the close button in the three-button navigation bar of the main window is clicked. The registered lifecycle callback function [UIAbility.onPrepareToTerminate](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonpreparetoterminate10) is not executed. 11362 11363If the event is subscribed to multiple times, only the most recently subscribed-to event takes effect. 11364 11365The callback function in this API is executed synchronously. For asynchronous close events of the main window, refer to [on('windowWillClose')](#onwindowwillclose15). 11366 11367If there is an existing event subscribed to by calling [on('windowWillClose')](#onwindowwillclose15), only the [on('windowWillClose')](#onwindowwillclose15) API will be responded to. 11368 11369<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 11370 11371**Model restriction**: This API can be used only in the stage model. 11372 11373**System capability**: SystemCapability.Window.SessionManager 11374 11375**Atomic service API**: This API can be used in atomic services since API version 14. 11376 11377**Parameters** 11378 11379| Name | Type | Mandatory | Description | 11380| --------- | -------------------- | --------- | ------------------------------------------------------------ | 11381| 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 | 11382| 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. | 11383 11384**Error codes** 11385 11386For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11387 11388| ID | Error Message | 11389| ------- | ------------------------------------------------------------ | 11390| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 11391| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11392| 1300002 | This window state is abnormal. | 11393 11394**Example** 11395 11396```ts 11397// EntryAbility.ets 11398import { UIAbility } from '@kit.AbilityKit'; 11399import { window } from '@kit.ArkUI'; 11400 11401export default class EntryAbility extends UIAbility { 11402 // ... 11403 11404 onWindowStageCreate(windowStage: window.WindowStage) { 11405 console.info('onWindowStageCreate'); 11406 try { 11407 windowStage.on('windowStageClose', () => { 11408 console.info('Succeeded in enabling the listener for window stage close event.'); 11409 return false; 11410 }); 11411 } catch (exception) { 11412 console.error(`Failed to enable the listener for window stage close event. Cause code: ${exception.code}, message: ${exception.message}`); 11413 } 11414 } 11415}; 11416``` 11417 11418### off('windowStageClose')<sup>14+</sup> 11419 11420off(eventType: 'windowStageClose', callback?: Callback<void>): void 11421 11422Unsubscribes from the event indicating that the main window is closed. 11423 11424<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 11425 11426**Model restriction**: This API can be used only in the stage model. 11427 11428**System capability**: SystemCapability.Window.SessionManager 11429 11430**Atomic service API**: This API can be used in atomic services since API version 14. 11431 11432**Parameters** 11433 11434| Name | Type | Mandatory | Description | 11435| --------- | -------------------- | --------- | ------------------------------------------------------------ | 11436| 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. | 11437| 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. | 11438 11439**Error codes** 11440 11441For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11442 11443| ID | Error Message | 11444| ------- | ------------------------------------------------------------ | 11445| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 11446| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11447| 1300002 | This window state is abnormal. | 11448 11449**Example** 11450 11451```ts 11452// EntryAbility.ets 11453import { UIAbility } from '@kit.AbilityKit'; 11454import { window } from '@kit.ArkUI'; 11455 11456export default class EntryAbility extends UIAbility { 11457 // ... 11458 11459 onWindowStageCreate(windowStage: window.WindowStage) { 11460 console.info('onWindowStageCreate'); 11461 const callback = () => { 11462 // ... 11463 return false; 11464 } 11465 try { 11466 windowStage.on('windowStageClose', callback); 11467 windowStage.off('windowStageClose', callback); 11468 windowStage.off('windowStageClose'); 11469 } catch (exception) { 11470 console.error(`Failed to disable the listener for window stage close changes. Cause code: ${exception.code}, message: ${exception.message}`); 11471 } 11472 } 11473}; 11474``` 11475 11476### setDefaultDensityEnabled<sup>12+</sup> 11477 11478setDefaultDensityEnabled(enabled: boolean): void 11479 11480Enables the system's default density. 11481 11482By default, the system's default density is not used, and the window layout changes with the system display size. 11483 11484**Model restriction**: This API can be used only in the stage model. 11485 11486**Atomic service API**: This API can be used in atomic services since API version 12. 11487 11488**System capability**: SystemCapability.Window.SessionManager 11489 11490**Parameters** 11491 11492| Name | Type | Mandatory | Description | 11493| ------- | ------- | --------- | ------------------------------------------------------------ | 11494| 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. | 11495 11496**Error codes** 11497 11498For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11499 11500| ID | Error Message | 11501| ------- | ------------------------------------------------------------ | 11502| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11503| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11504| 1300002 | This window state is abnormal. | 11505| 1300005 | This window stage is abnormal. | 11506 11507**Example** 11508 11509```ts 11510// EntryAbility.ets 11511import { UIAbility } from '@kit.AbilityKit'; 11512 11513export default class EntryAbility extends UIAbility { 11514 // ... 11515 11516 onWindowStageCreate(windowStage: window.WindowStage) { 11517 console.info('onWindowStageCreate'); 11518 try { 11519 windowStage.setDefaultDensityEnabled(true); 11520 } catch (exception) { 11521 console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`); 11522 } 11523 } 11524}; 11525``` 11526 11527### setCustomDensity<sup>15+</sup> 11528 11529setCustomDensity(density: number): void 11530 11531Called by the main window to set its own display size scale factor for the main window. Any child windows will adopt the same scale factor as the main window. If both this API and [setDefaultDensityEnabled(true)](#setdefaultdensityenabled12) are called to set a display size scale factor, the settings from the last called API will be applied. 11532 11533**Model restriction**: This API can be used only in the stage model. 11534 11535**Atomic service API**: This API can be used in atomic services since API version 15. 11536 11537**System capability**: SystemCapability.Window.SessionManager 11538 11539**Parameters** 11540 11541| Name | Type | Mandatory | Description | 11542| ------- | ------ | --------- | ------------------------------------------------------------ | 11543| density | number | Yes | Custom display size scale factor. The value is a floating point number in the range [0.5, 4.0] or set to **-1.0**, The value **4.0** indicates the largest permissible display size scale factor for the window, and **-1.0** means that the window uses the system's default display size scale factor. | 11544 11545**Error codes** 11546 11547For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11548 11549| ID | Error Message | 11550| ------- | ------------------------------------------------------------ | 11551| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11552| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11553| 1300002 | This window state is abnormal. | 11554| 1300005 | This window stage is abnormal. | 11555 11556**Example** 11557 11558```ts 11559// EntryAbility.ets 11560import { UIAbility } from '@kit.AbilityKit'; 11561 11562export default class EntryAbility extends UIAbility { 11563 // ... 11564 11565 onWindowStageCreate(windowStage: window.WindowStage) { 11566 console.info('onWindowStageCreate'); 11567 try { 11568 windowStage.setCustomDensity(-1.0); 11569 } catch (exception) { 11570 console.error(`Failed to set custom density. Cause code: ${exception.code}, message: ${exception.message}`); 11571 } 11572 } 11573}; 11574``` 11575 11576### setWindowModal<sup>14+</sup> 11577 11578setWindowModal(isModal: boolean): Promise<void> 11579 11580Enables the modal property of the main window. This API uses a promise to return the result. 11581 11582This API must be called by the main window and the setting takes effect for the main window. After the modal property of the main window is enabled, other main windows in the same application process and their child windows do not respond to user interactions until the main window is closed or the main window's modal property is disabled. 11583 11584<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 11585 11586**Model restriction**: This API can be used only in the stage model. 11587 11588**Atomic service API**: This API can be used in atomic services since API version 14. 11589 11590**System capability**: SystemCapability.Window.SessionManager 11591 11592**Parameters** 11593 11594| Name | Type | Mandatory | Description | 11595| ------- | ------- | --------- | ------------------------------------------------------------ | 11596| 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. | 11597 11598 11599**Return value** 11600 11601| Type | Description | 11602| ------------------- | ------------------------------ | 11603| Promise<void> | Promise that returns no value. | 11604 11605**Error codes** 11606 11607For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11608 11609| ID | Error Message | 11610| ------- | ------------------------------------------------------------ | 11611| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11612| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11613| 1300002 | This window state is abnormal. | 11614| 1300003 | This window manager service works abnormally. | 11615 11616**Example** 11617 11618```ts 11619// EntryAbility.ets 11620import { UIAbility } from '@kit.AbilityKit'; 11621import { BusinessError } from '@kit.BasicServicesKit'; 11622 11623export default class EntryAbility extends UIAbility { 11624 // ... 11625 onWindowStageCreate(windowStage: window.WindowStage): void { 11626 console.info('onWindowStageCreate'); 11627 try { 11628 let promise = windowStage.setWindowModal(true); 11629 promise.then(() => { 11630 console.info('Succeeded in setting window modal'); 11631 }).catch((err: BusinessError) => { 11632 console.error(`Failed to set window modal. Cause code: ${err.code}, message: ${err.message}`); 11633 }); 11634 } catch (exception) { 11635 console.error(`Failed to set window modal. Cause code: ${exception.code}, message: ${exception.message}`); 11636 } 11637 } 11638} 11639``` 11640 11641### removeStartingWindow<sup>14+</sup> 11642 11643removeStartingWindow(): Promise<void> 11644 11645Allows the application to control the time when the launch page disappears. 11646 11647This 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**. 11648 11649If 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. 11650 11651If 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. 11652 11653**Model restriction**: This API can be used only in the stage model. 11654 11655**Atomic service API**: This API can be used in atomic services since API version 14. 11656 11657**System capability**: SystemCapability.Window.SessionManager 11658 11659**Return value** 11660 11661| Type | Description | 11662| ------------------- | ------------------------------ | 11663| Promise<void> | Promise that returns no value. | 11664 11665**Error codes** 11666 11667For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11668 11669| ID | Error Message | 11670| ------- | ------------------------------------------------------------ | 11671| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11672| 1300002 | This window state is abnormal. | 11673| 1300003 | This window manager service works abnormally. | 11674 11675**Example** 11676 11677```ts 11678// EntryAbility.ets 11679import { UIAbility } from '@kit.AbilityKit'; 11680import { BusinessError } from '@kit.BasicServicesKit'; 11681 11682export default class EntryAbility extends UIAbility { 11683 // ... 11684 11685 onWindowStageCreate(windowStage: window.WindowStage) { 11686 console.info('onWindowStageCreate'); 11687 windowStage.removeStartingWindow().then(() => { 11688 console.info('Succeeded in removing starting window.'); 11689 }).catch((err: BusinessError) => { 11690 console.error(`Failed to remove starting window. Cause code: ${err.code}, message: ${err.message}`); 11691 }); 11692 } 11693}; 11694``` 11695 11696### setWindowRectAutoSave<sup>14+</sup> 11697 11698setWindowRectAutoSave(enabled: boolean): Promise<void> 11699 11700Sets 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. 11701 11702This 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. 11703 11704Upon relaunch, the window will reopen in accordance with these remembered size and state. 11705 11706The following rules apply in stacking scenarios: 11707 117081. If the current instance is a free-form window, the next opened window will adopt the same size when stacked. 117092. If the current instance is maximized or in full-screen mode, the next opened window will maintain the maximized state when stacked. 11710 11711The following table describes the memory rules: 11712 11713| Last Window State | Memorizing Rule | 11714| ------------------- | ------------------------------------------------------------ | 11715| Free-form window | Retains the size/position of the free-form window, rebound if exceeding the workspace | 11716| Split-screen window | Retains the size and position of the free-form window before screen splitting. | 11717| Maximized window | Retains the maximized state. | 11718| Immersive window | Retains the size and position of the free-form window before immersive mode. | 11719| Minimized window | Retains the size and position of the free-form window before minimization. | 11720 11721**Model restriction**: This API can be used only in the stage model. 11722 11723**Atomic service API**: This API can be used in atomic services since API version 14. 11724 11725**System capability**: SystemCapability.Window.SessionManager 11726 11727**Parameters** 11728 11729| Name | Type | Mandatory | Description | 11730| ------- | ------- | --------- | ------------------------------------------------------------ | 11731| 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. | 11732 11733 11734**Return value** 11735 11736| Type | Description | 11737| ------------------- | ------------------------------ | 11738| Promise<void> | Promise that returns no value. | 11739 11740**Error codes** 11741 11742For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11743 11744| ID | Error Message | 11745| ------- | ------------------------------------------------------------ | 11746| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11747| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11748| 1300002 | This window state is abnormal. | 11749| 1300003 | This window manager service works abnormally. | 11750 11751**Example** 11752 11753```ts 11754// EntryAbility.ets 11755import { UIAbility } from '@kit.AbilityKit'; 11756import { BusinessError } from '@kit.BasicServicesKit'; 11757 11758export default class EntryAbility extends UIAbility { 11759 // ... 11760 onWindowStageCreate(windowStage: window.WindowStage): void { 11761 console.info('onWindowStageCreate'); 11762 try { 11763 let promise = windowStage.setWindowRectAutoSave(true); 11764 promise.then(() => { 11765 console.info('Succeeded in setting window rect auto-save'); 11766 }).catch((err: BusinessError) => { 11767 console.error(`Failed to set window rect auto-save. Cause code: ${err.code}, message: ${err.message}`); 11768 }); 11769 } catch (exception) { 11770 console.error(`Failed to set window rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`); 11771 } 11772 } 11773} 11774``` 11775 11776### isWindowRectAutoSave<sup>14+</sup> 11777 11778isWindowRectAutoSave(): Promise<boolean> 11779 11780Checks 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. 11781 11782**Model restriction**: This API can be used only in the stage model. 11783 11784**Atomic service API**: This API can be used in atomic services since API version 14. 11785 11786**System capability**: SystemCapability.Window.SessionManager 11787 11788**Return value** 11789 11790| Type | Description | 11791| ---------------------- | ------------------------------------------------------------ | 11792| Promise<boolean> | Promise used to return the result. The value **true** means that the auto-save feature is enabled, and **false** means the opposite. | 11793 11794**Error codes** 11795 11796For details about the error codes, see [Window Error Codes](errorcode-window.md). 11797 11798| ID | Error Message | 11799| ------- | ------------------------------------------------------------ | 11800| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11801| 1300002 | This window state is abnormal. | 11802 11803**Example** 11804 11805```ts 11806// EntryAbility.ets 11807import { UIAbility } from '@kit.AbilityKit'; 11808import { BusinessError } from '@kit.BasicServicesKit'; 11809 11810export default class EntryAbility extends UIAbility { 11811 // ... 11812 onWindowStageCreate(windowStage: window.WindowStage): void { 11813 console.info('onWindowStageCreate'); 11814 try { 11815 let promise = windowStage.isWindowRectAutoSave(); 11816 promise.then((data) => { 11817 console.info('Succeeded in checking whether the window support the rect auto-save. Data: ' + JSON.stringify(data)); 11818 }).catch((err: BusinessError) => { 11819 console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${err.code}, message: ${err.message}`); 11820 }); 11821 } catch (exception) { 11822 console.error(`Failed to check whether the window support the rect auto-save. Cause code: ${exception.code}, message: ${exception.message}`); 11823 } 11824 } 11825} 11826``` 11827 11828### setSupportedWindowModes<sup>15+</sup> 11829 11830setSupportedWindowModes(supportedWindowModes: Array<bundleManager.SupportWindowMode>): Promise<void> 11831 11832Sets the supported window modes of the main window. This API uses a promise to return the result. 11833 11834<!--RP6-->This API can be used only on 2-in-1 devices.<!--RP6End--> 11835 11836**Model restriction**: This API can be used only in the stage model. 11837 11838**Atomic service API**: This API can be used in atomic services since API version 15. 11839 11840**System capability**: SystemCapability.Window.SessionManager 11841 11842**Parameters** 11843 11844| Name | Type | Mandatory | Description | 11845| -------------------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 11846| supportedWindowModes | Array<[bundleManager.SupportWindowMode](../apis-ability-kit/js-apis-bundleManager.md#supportwindowmode)> | Yes | Supported window modes.<br>- **FULL_SCREEN**: full-screen mode.<br>- **FLOATING**: floating window mode.<br>- **SPLIT**: split-screen mode. **FULL_SCREEN** or **FLOATING** must be used together. Configuring only **SPLIT** is not supported.<br> Note: The values of the **SupportWindowMode** field in the array should not conflict with the values of the **supportWindowMode** field under [abilities](../../quick-start/module-configuration-file.md#abilities) of the [module.json5 file](../../quick-start/module-configuration-file.md) corresponding to this UIAbility, or with the values of the **supportWindowModes** field in [StartOptions](../apis-ability-kit/js-apis-app-ability-startOptions.md). In case of a conflict, the window support mode set by this parameter will take precedence. | 11847 11848**Return value** 11849 11850| Type | Description | 11851| ------------------- | ------------------------------ | 11852| Promise<void> | Promise that returns no value. | 11853 11854**Error codes** 11855 11856For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 11857 11858| ID | Error Message | 11859| ------- | ------------------------------------------------------------ | 11860| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 11861| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 11862| 1300002 | This window state is abnormal. | 11863| 1300003 | This window manager service works abnormally. | 11864 11865**Example** 11866 11867```ts 11868// EntryAbility.ets 11869import { UIAbility, bundleManager } from '@kit.AbilityKit'; 11870import { BusinessError } from '@kit.BasicServicesKit'; 11871 11872export default class EntryAbility extends UIAbility { 11873 // ... 11874 onWindowStageCreate(windowStage: window.WindowStage): void { 11875 console.info('onWindowStageCreate'); 11876 try { 11877 let promise = windowStage.setSupportedWindowModes([ 11878 bundleManager.SupportWindowMode.FULL_SCREEN, 11879 bundleManager.SupportWindowMode.SPLIT, 11880 bundleManager.SupportWindowMode.FLOATING 11881 ]); 11882 promise.then(() => { 11883 console.info('Succeeded in setting window support modes'); 11884 }).catch((err: BusinessError) => { 11885 console.error(`Failed to set window support modes. Cause code: ${err.code}, message: ${err.message}`); 11886 }); 11887 } catch (exception) { 11888 console.error(`Failed to set window support modes. Cause code: ${exception.code}, message: ${exception.message}`); 11889 } 11890 } 11891} 11892```