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 functions: 6 7- [Window](#window): window instance, which is the basic unit managed by the window manager. 8- [WindowStage](#windowstage9): window manager that manages windows. 9 10> **NOTE** 11> 12> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 13 14## Modules to Import 15 16```ts 17import { window } from '@kit.ArkUI'; 18``` 19 20## WindowType<sup>7+</sup> 21 22Enumerates the window types. 23 24**System capability**: SystemCapability.WindowManager.WindowManager.Core 25 26| Name | Value| Description | 27|-------------------------------------| ------ |----------------------------------------------------------------------------------------| 28| TYPE_APP | 0 | Application subwindow.<br>**Model restriction**: This API can be used only in the FA model. | 29| TYPE_SYSTEM_ALERT | 1 | System alert window.<br>**NOTE**<br>This property is supported since API version 7 and deprecated since API version 11. | 30| TYPE_FLOAT<sup>9+</sup> | 8 | Floating window.<br>**Model restriction**: This API can be used only in the stage model.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 31| TYPE_DIALOG<sup>10+</sup> | 16 | Modal window.<br>**Model restriction**: This API can be used only in the stage model.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 32 33## Configuration<sup>9+</sup> 34 35Defines the parameters for creating a subwindow or system window. 36 37**Atomic service API**: This API can be used in atomic services since API version 12. 38 39**System capability**: SystemCapability.WindowManager.WindowManager.Core 40 41| Name| Type| Mandatory| Description | 42| ---------- | -------------------------- | -- |-----------------------------------------------------------------------------| 43| name | string | Yes| Name of the window. | 44| windowType | [WindowType](#windowtype7) | Yes| Window type. | 45| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | No| Current application context. If no value is passed, no context is used.<br>In the FA model, do not pass in this parameter when creating a subwindow. Otherwise, an error is reported.<br>In the stage model, you must pass in this parameter when creating a floating window, modal window, or system window.| 46| displayId | number | No| ID of the current physical screen. If no value is passed, the default value **-1** is used. The value must be an integer. | 47| parentId | number | No| ID of the parent window. If no value is passed, the default value **-1** is used. The value must be an integer. | 48| decorEnabled<sup>12+</sup> | boolean | No| Whether the window decoration is enabled. This parameter is valid only when **windowType** is set to **TYPE_DIALOG**. The value **true** means that the window decoration is enabled, and **false** means the opposite. The default value is **false**.<br>**System capability**: SystemCapability.Window.SessionManager| 49| title<sup>12+</sup> | string| No| Title of the window when **decorEnabled** is set to **true**. If this parameter is not set, an empty string is used by default.<br>**System capability**: SystemCapability.Window.SessionManager| 50 51## AvoidAreaType<sup>7+</sup> 52 53Enumerates the types of the area where the window cannot be displayed. 54 55**System capability**: SystemCapability.WindowManager.WindowManager.Core 56 57**Atomic service API**: This API can be used in atomic services since API version 11. 58 59| Name | Value | Description | 60| -------------------------------- | ---- | ------------------------------------------------------------ | 61| TYPE_SYSTEM | 0 | Default area of the system. Generally, the status bar and navigation bar are included. The default area may vary according to the device in use.| 62| TYPE_CUTOUT | 1 | Notch. | 63| TYPE_SYSTEM_GESTURE<sup>9+</sup> | 2 | Gesture area. | 64| TYPE_KEYBOARD<sup>9+</sup> | 3 | Soft keyboard area. | 65| TYPE_NAVIGATION_INDICATOR<sup>11+</sup> | 4 | Navigation bar area. | 66 67 68## SystemBarProperties 69 70Describes the properties of the status bar and navigation bar. These properties are valid for the window-level status bar and navigation bar. 71 72**Atomic service API**: This API can be used in atomic services since API version 12. 73 74| Name | Type| Mandatory| Description | 75| -------------------------------------- | -------- | ---- | ------------------------------------------------------------ | 76| statusBarColor | string | No | Background color of the status bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**. The default value is **'#0x66000000'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 77| isStatusBarLightIcon<sup>7+</sup> | boolean | No | Whether any icon on the status bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 78| statusBarContentColor<sup>8+</sup> | string | No | Color of the text on the status bar. After this property is set, the setting of **isStatusBarLightIcon** is invalid. The default value is **'#0xE5FFFFFF'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 79| navigationBarColor | string | No | Background color of the navigation bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **'#00FF00'** or **'#FF00FF00'**. The default value is **'#0x66000000'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 80| isNavigationBarLightIcon<sup>7+</sup> | boolean | No | Whether any icon on the navigation bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 81| navigationBarContentColor<sup>8+</sup> | string | No | Color of the text on the navigation bar. After this property is set, the setting of **isNavigationBarLightIcon** is invalid. The default value is **'#0xE5FFFFFF'**.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 82| enableStatusBarAnimation<sup>12+</sup> | boolean | No | Whether to enable animation for a status bar property change. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.<br>**System capability**: SystemCapability.Window.SessionManager| 83| enableNavigationBarAnimation<sup>12+</sup> | boolean | No | Whether to enable animation for a navigation bar property change. The value **true** means to enable animation, and **false** means the opposite. The default value is **false**.<br>**System capability**: SystemCapability.Window.SessionManager| 84 85## SystemBarStyle<sup>12+</sup> 86 87Describes the properties of the status bar. These properties are valid for the page-level status bar. 88 89**Atomic service API**: This API can be used in atomic services since API version 12. 90 91**System capability**: SystemCapability.WindowManager.WindowManager.Core 92 93| Name | Type| Read Only| Optional| Description | 94| ------ | -------- | ---- | ---- | ------------------ | 95| statusBarContentColor | string | Yes | Yes | Color of the text on the status bar. The default value is **'#0xE5FFFFFF'**.| 96 97## Orientation<sup>9+</sup> 98 99Enumerates the window orientations. 100 101| Name | Value | Description | 102| ------------------------------------- | ---- | ----------------------------- | 103| UNSPECIFIED | 0 | Unspecified. The orientation is determined by the system.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 104| PORTRAIT | 1 | Portrait.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 105| LANDSCAPE | 2 | Landscape.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 106| PORTRAIT_INVERTED | 3 | Reverse portrait.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 107| LANDSCAPE_INVERTED | 4 | Reverse landscape.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 108| AUTO_ROTATION | 5 | Automatically rotates with the sensor. The orientation can be portrait, landscape, reverse portrait, or reverse landscape.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 109| AUTO_ROTATION_PORTRAIT | 6 | Automatically rotates with the sensor in the vertical direction. The orientation can be portrait or reverse portrait.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 110| AUTO_ROTATION_LANDSCAPE | 7 | Automatically rotates with the sensor in the horizontal direction. The orientation can be landscape or reverse landscape.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 111| AUTO_ROTATION_RESTRICTED | 8 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation can be portrait, landscape, reverse portrait, or reverse landscape.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 112| AUTO_ROTATION_PORTRAIT_RESTRICTED | 9 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation can be portrait or reverse portrait.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 113| AUTO_ROTATION_LANDSCAPE_RESTRICTED | 10 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation can be landscape or reverse landscape.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 114| LOCKED | 11 | Locked.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 115| AUTO_ROTATION_UNSPECIFIED<sup>12+</sup> | 12 | Automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system. For example, the window can rotate to portrait, landscape, or reverse landscape, but not reverse portrait, on a certain device.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 116| USER_ROTATION_PORTRAIT<sup>12+</sup> | 13 | Temporarily rotates to portrait mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 117| USER_ROTATION_LANDSCAPE<sup>12+</sup> | 14 | Temporarily rotates to landscape mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 118| USER_ROTATION_PORTRAIT_INVERTED<sup>12+</sup> | 15 | Temporarily rotates to reverse portrait mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 119| USER_ROTATION_LANDSCAPE_INVERTED<sup>12+</sup> | 16 | Temporarily rotates to reverse landscape mode, and then automatically rotates with the sensor, under the restriction of the rotation switch in the Control Panel. The orientation that can be rotated to is determined by the system.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 120| FOLLOW_DESKTOP<sup>12+</sup> | 17 | Follows the orientation of the home screen.<br>**Atomic service API**: This API can be used in atomic services since API version 12.<br>**System capability**: SystemCapability.Window.SessionManager| 121 122## Rect<sup>7+</sup> 123 124Describes the rectangular area of the window. 125 126**System capability**: SystemCapability.WindowManager.WindowManager.Core 127 128**Atomic service API**: This API can be used in atomic services since API version 11. 129 130| Name | Type| Readable| Writable| Description | 131| ------ | -------- | ---- | ---- | ------------------ | 132| left | number | Yes | Yes | Left boundary of the rectangle, in px. The value must be an integer.| 133| top | number | Yes | Yes | Top boundary of the rectangle, in px. The value must be an integer.| 134| width | number | Yes | Yes | Width of the rectangle, in px. The value must be an integer.| 135| height | number | Yes | Yes | Height of the rectangle, in px. The value must be an integer.| 136 137## AvoidArea<sup>7+</sup> 138 139Describes the area where the window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. Touch events will not be responded in this area. 140 141Pay attention to the following restrictions on this area: 142 143- The non-navigation bar area in the gesture area at the bottom supports transparent transmission of touch events, touch and hold events, but not drag events. 144 145- The gesture area on the left and right sides supports transparent transmission of touch events, touch and hold events, and swipe up and down events, but not drag events. 146 147- The navigation bar area supports responding to touch events, touch and hold events, and drag events. However, it does not support transparent transmission of events. 148 149**System capability**: SystemCapability.WindowManager.WindowManager.Core 150 151**Atomic service API**: This API can be used in atomic services since API version 11. 152 153| Name | Type | Readable| Writable| Description | 154| ---------- | ------------- | ---- | ---- | ------------------ | 155| visible<sup>9+</sup> | boolean | Yes | Yes | Whether the window can be displayed in the area. The value **true** means that the window can be displayed in the area, and **false** means the opposite.| 156| leftRect | [Rect](#rect7) | Yes | Yes | Rectangle on the left of the screen.| 157| topRect | [Rect](#rect7) | Yes | Yes | Rectangle at the top of the screen.| 158| rightRect | [Rect](#rect7) | Yes | Yes | Rectangle on the right of the screen.| 159| bottomRect | [Rect](#rect7) | Yes | Yes | Rectangle at the bottom of the screen.| 160 161## Size<sup>7+</sup> 162 163Describes the window size. 164 165**System capability**: SystemCapability.WindowManager.WindowManager.Core 166 167**Atomic service API**: This API can be used in atomic services since API version 11. 168 169| Name | Type| Readable| Writable| Description | 170| ------ | -------- | ---- | ---- | ---------- | 171| width | number | Yes | Yes | Window width, in px. The value must be an integer.| 172| height | number | Yes | Yes | Window height, in px. The value must be an integer.| 173 174## RectChangeReason<sup>12+</sup> 175 176Enumerates the reasons for window rectangle (position and size) changes. 177 178**System capability**: SystemCapability.Window.SessionManager 179 180**Atomic service API**: This API can be used in atomic services since API version 12. 181 182| Name | Value | Description | 183| --------------------- | ---- | ------------------------------------------------------------ | 184| UNDEFINED | 0 | Default value. | 185| MAXIMIZE | 1 | The window is maximized. | 186| RECOVER | 2 | The window is restored to the previous state. | 187| MOVE | 3 | The window is moved.| 188| DRAG | 4 | The window is zoomed in or out by dragging.| 189| DRAG_START | 5 | The window starts zooming in or out.| 190| DRAG_END | 6 | The window finishes zooming in or out.| 191 192## RectChangeOptions<sup>12+</sup> 193 194Describes the value and reason returned upon a window rectangle (position and size) change. 195 196**System capability**: SystemCapability.Window.SessionManager 197 198**Atomic service API**: This API can be used in atomic services since API version 12. 199 200| Name | Type | Readable| Writable| Description | 201| ---------- | ------------- | ---- | ---- | ------------------ | 202| rect | [Rect](#rect7) | Yes | Yes | New value of the window rectangle.| 203| reason | [RectChangeReason](#rectchangereason12) | Yes | Yes | Reason for the window rectangle change.| 204 205## AvoidAreaOptions<sup>12+</sup> 206 207Describes the new area where the window cannot be displayed. The new area is returned when the corresponding event is triggered. 208 209**System capability**: SystemCapability.WindowManager.WindowManager.Core 210 211**Atomic service API**: This API can be used in atomic services since API version 12. 212 213| Name | Type | Readable| Writable| Description | 214| ---------- | ------------- | ---- | ---- | ------------------ | 215| type | [AvoidAreaType](#avoidareatype7) | Yes | Yes | Type of the new area returned.| 216| area | [AvoidArea](#avoidarea7) | Yes | Yes | New area returned.| 217 218## WindowProperties 219 220Describes the window properties. 221 222**System capability**: SystemCapability.WindowManager.WindowManager.Core 223 224| Name | Type | Read Only| Optional| Description | 225| ------------------------------------- | ------------------------- | ---- | ---- |--------------------------------------------------------------------------------------------------------| 226| windowRect<sup>7+</sup> | [Rect](#rect7) | No | No | Window size.<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## ColorSpace<sup>8+</sup> 243 244Enumerates the color spaces. 245 246**Atomic service API**: This API can be used in atomic services since API version 12. 247 248**System capability**: SystemCapability.WindowManager.WindowManager.Core 249 250| Name | Value| Description | 251| ---------- | ------ | -------------- | 252| DEFAULT | 0 | Default SRGB gamut.| 253| WIDE_GAMUT | 1 | Wide-gamut. | 254 255## WindowEventType<sup>10+</sup> 256 257Enumerates the window lifecycle states. 258 259**Atomic service API**: This API can be used in atomic services since API version 11. 260 261| Name | Value| Description | 262| ---------- | ------ | ---------- | 263| WINDOW_SHOWN | 1 | The window is running in the foreground.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 264| WINDOW_ACTIVE | 2 | The window gains focus.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 265| WINDOW_INACTIVE | 3 | The window loses focus.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 266| WINDOW_HIDDEN | 4 | The window is running in the background.<br>**System capability**: SystemCapability.WindowManager.WindowManager.Core| 267| WINDOW_DESTROYED<sup>11+</sup> | 7 | The window is destroyed.<br>**System capability**: SystemCapability.Window.SessionManager| 268 269## WindowLimits<sup>11+</sup> 270 271Defines 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. 272 273**Atomic service API**: This API can be used in atomic services since API version 12. 274 275**System capability**: SystemCapability.Window.SessionManager 276 277| Name | Type | Readable| Writable| Description | 278| :-------- | :----- | :--- | :--- | :----------------------------------------------------------- | 279| 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. | 280| 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. | 281| 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. | 282| 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. | 283 284## WindowStatusType<sup>11+</sup> 285 286Enumerates the window modes. 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 | Value | Description | 293| ---------- | ---- | ----------------------------- | 294| UNDEFINED | 0 | The window mode is not defined by the application. | 295| FULL_SCREEN | 1 | The application is displayed in full screen. | 296| MAXIMIZE | 2 | The application window is maximized. | 297| MINIMIZE | 3 | The application window is minimized. | 298| FLOATING | 4 | The application is displayed in a floating window. | 299| SPLIT_SCREEN | 5 | The application is displayed in split-screen mode. | 300 301## TitleButtonRect<sup>11+</sup> 302 303Defines 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. 304 305**Atomic service API**: This API can be used in atomic services since API version 12. 306 307**System capability**: SystemCapability.Window.SessionManager 308 309| Name | Type | Readable| Writable| Description | 310| ------ | ------ | ---- | ---- | ------------------------------------------ | 311| right | number | Yes | Yes | Right boundary of the rectangle, in vp. The value must be an integer.| 312| top | number | Yes | Yes | Top boundary of the rectangle, in vp. The value must be an integer.| 313| width | number | Yes | Yes | Width of the rectangle, in vp. The value must be an integer. | 314| height | number | Yes | Yes | Height of the rectangle, in vp. The value must be an integer. | 315 316## MaximizePresentation<sup>12+</sup> 317 318Enumerates the layout when the window is maximized. 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 | Value | Description | 325| ---------- | ---- | ----------------------------- | 326| FOLLOW_APP_IMMERSIVE_SETTING | 0 | The window, when maximized, follows the immersive layout of the application. | 327| EXIT_IMMERSIVE | 1 | The window, when maximized, exits the immersive layout. | 328| ENTER_IMMERSIVE | 2 | The window, when maximized, enters the immersive layout. | 329 330## window.createWindow<sup>9+</sup> 331 332createWindow(config: Configuration, callback: AsyncCallback<Window>): void 333 334Creates a subwindow or system window. This API uses an asynchronous callback to return the result. 335 336**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**) 337 338**Atomic service API**: This API can be used in atomic services since API version 12. 339 340**System capability**: SystemCapability.WindowManager.WindowManager.Core 341 342**Parameters** 343 344| Name| Type| Mandatory| Description| 345| -------- | -------------------------------------- | -- | --------------------------------- | 346| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window. | 347| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the window created.| 348 349**Error codes** 350 351For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 352 353| ID| Error Message| 354| ------- | -------------------------------- | 355| 201 | Permission verification failed. The application does not have the permission required to call the API. | 356| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 357| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 358| 1300001 | Repeated operation. | 359| 1300002 | This window state is abnormal. | 360| 1300004 | Unauthorized operation. | 361| 1300006 | This window context is abnormal. | 362| 1300008 | The display device is abnormal. | 363| 1300009 | The parent window is invalid. | 364 365**Example** 366 367```ts 368import { BusinessError } from '@kit.BasicServicesKit'; 369 370let windowClass: window.Window | undefined = undefined; 371let config: window.Configuration = { 372 name: "test", 373 windowType: window.WindowType.TYPE_DIALOG, 374 ctx: this.context 375}; 376try { 377 window.createWindow(config, (err: BusinessError, data) => { 378 const errCode: number = err.code; 379 if (errCode) { 380 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 381 return; 382 } 383 windowClass = data; 384 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 385 windowClass.resize(500, 1000); 386 }); 387} catch (exception) { 388 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 389} 390``` 391 392## window.createWindow<sup>9+</sup> 393 394createWindow(config: Configuration): Promise<Window> 395 396Creates a subwindow or system window. This API uses a promise to return the result. 397 398**Required permissions**: ohos.permission.SYSTEM_FLOAT_WINDOW (required when the window type is **window.WindowType.TYPE_FLOAT**) 399 400**Atomic service API**: This API can be used in atomic services since API version 12. 401 402**System capability**: SystemCapability.WindowManager.WindowManager.Core 403 404**Parameters** 405 406| Name| Type| Mandatory| Description| 407| ------ | -------------------------------- | -- | ------------------ | 408| config | [Configuration](#configuration9) | Yes| Parameters used for creating the window.| 409 410**Return value** 411 412| Type| Description| 413| -------------------------------- | ------------------------------------ | 414| Promise<[Window](#window)> | Promise used to return the window created.| 415 416**Error codes** 417 418For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 419 420| ID| Error Message| 421| ------- | -------------------------------- | 422| 201 | Permission verification failed. The application does not have the permission required to call the API. | 423| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 424| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 425| 1300001 | Repeated operation. | 426| 1300002 | This window state is abnormal. | 427| 1300004 | Unauthorized operation. | 428| 1300006 | This window context is abnormal. | 429| 1300008 | The display device is abnormal. | 430| 1300009 | The parent window is invalid. | 431 432**Example** 433 434```ts 435import { BusinessError } from '@kit.BasicServicesKit'; 436 437let windowClass: window.Window | undefined = undefined; 438let config: window.Configuration = { 439 name: "test", 440 windowType: window.WindowType.TYPE_DIALOG, 441 ctx: this.context 442}; 443try { 444 let promise = window.createWindow(config); 445 promise.then((data) => { 446 windowClass = data; 447 console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); 448 }).catch((err: BusinessError) => { 449 console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`); 450 }); 451} catch (exception) { 452 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 453} 454``` 455 456## window.findWindow<sup>9+</sup> 457 458findWindow(name: string): Window 459 460Finds a window based on the name. 461 462**System capability**: SystemCapability.WindowManager.WindowManager.Core 463 464**Atomic service API**: This API can be used in atomic services since API version 11. 465 466**Parameters** 467 468| Name| Type | Mandatory| Description | 469| ------ | ------ | ---- | -------- | 470| name | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 471 472**Return value** 473 474| Type| Description| 475| ----------------- | ------------------- | 476| [Window](#window) | Window found.| 477 478**Error codes** 479 480For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 481 482| ID| Error Message| 483| ------- | -------------------------------- | 484| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 485| 1300002 | This window state is abnormal. | 486 487**Example** 488 489```ts 490let windowClass: window.Window | undefined = undefined; 491try { 492 windowClass = window.findWindow('test'); 493} catch (exception) { 494 console.error(`Failed to find the Window. Cause code: ${exception.code}, message: ${exception.message}`); 495} 496``` 497 498## window.getLastWindow<sup>9+</sup> 499 500getLastWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 501 502Obtains the top window of the current application. This API uses an asynchronous callback to return the result. If no subwindow is available, the main window of the application is returned. 503 504**Atomic service API**: This API can be used in atomic services since API version 12. 505 506**System capability**: SystemCapability.WindowManager.WindowManager.Core 507 508**Parameters** 509 510| Name| Type| Mandatory| Description| 511| -------- | -------------------------------------- | -- | ---------------------------------------- | 512| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes| Current application context.| 513| callback | AsyncCallback<[Window](#window)> | Yes| Callback used to return the top window obtained.| 514 515**Error codes** 516 517For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 518 519| ID| Error Message| 520| ------- | -------------------------------- | 521| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 522| 1300002 | This window state is abnormal. | 523| 1300006 | This window context is abnormal. | 524 525**Example** 526 527```ts 528// EntryAbility.ets 529import { UIAbility } from '@kit.AbilityKit'; 530import { BusinessError } from '@kit.BasicServicesKit'; 531 532export default class EntryAbility extends UIAbility { 533 // ... 534 onWindowStageCreate(windowStage: window.WindowStage) { 535 console.info('onWindowStageCreate'); 536 let windowClass: window.Window | undefined = undefined; 537 try { 538 window.getLastWindow(this.context, (err: BusinessError, data) => { 539 const errCode: number = err.code; 540 if (errCode) { 541 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 542 return; 543 } 544 windowClass = data; 545 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 546 }); 547 } catch (exception) { 548 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 549 } 550 } 551} 552``` 553 554## window.getLastWindow<sup>9+</sup> 555 556getLastWindow(ctx: BaseContext): Promise<Window> 557 558Obtains the top window of the current application. This API uses a promise to return the result. If no subwindow is available, the main window of the application is returned. 559 560**Atomic service API**: This API can be used in atomic services since API version 12. 561 562**System capability**: SystemCapability.WindowManager.WindowManager.Core 563 564**Parameters** 565 566| Name| Type| Mandatory| Description| 567| ------ | ----------- | ---- | ------------------------------------------------------------ | 568| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 569 570**Return value** 571 572| Type| Description| 573| -------------------------------- | ------------------------------------------- | 574| Promise<[Window](#window)> | Promise used to return the top window obtained.| 575 576**Error codes** 577 578For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 579 580| ID| Error Message| 581| ------- | -------------------------------- | 582| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 583| 1300002 | This window state is abnormal. | 584| 1300006 | This window context is abnormal. | 585 586**Example** 587 588```ts 589// EntryAbility.ets 590import { UIAbility } from '@kit.AbilityKit'; 591import { BusinessError } from '@kit.BasicServicesKit'; 592 593export default class EntryAbility extends UIAbility { 594 // ... 595 onWindowStageCreate(windowStage: window.WindowStage) { 596 console.info('onWindowStageCreate'); 597 let windowClass: window.Window | undefined = undefined; 598 try { 599 let promise = window.getLastWindow(this.context); 600 promise.then((data) => { 601 windowClass = data; 602 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 603 }).catch((err: BusinessError) => { 604 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 605 }); 606 } catch (exception) { 607 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`); 608 } 609 } 610} 611``` 612 613## window.shiftAppWindowFocus<sup>11+</sup> 614shiftAppWindowFocus(sourceWindowId: number, targetWindowId: number): Promise<void> 615 616Shifts the window focus from the source window to the target window in the same application. The window focus can be shifted between the main window and a subwindow. 617 618**Atomic service API**: This API can be used in atomic services since API version 12. 619 620**System capability**: SystemCapability.Window.SessionManager 621 622**Parameters** 623 624| Name | Type | Mandatory | Description | 625| -------------- | ------ | ----- | ----------------------- | 626| sourceWindowId | number | Yes | ID of the source window, which is having the focus.| 627| targetWindowId | number | Yes | ID of the target window. | 628 629**Return value** 630 631| Type | Description | 632| ------------------- | ------------------------- | 633| Promise<void> | Promise that returns no value.| 634 635**Error codes** 636 637For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 638 639| ID| Error Message | 640| ------- | --------------------------------------------- | 641| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 642| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 643| 1300002 | This window state is abnormal. | 644| 1300003 | This window manager service works abnormally. | 645| 1300004 | Unauthorized operation. | 646 647**Example** 648 649```ts 650// EntryAbility.ets 651import { UIAbility } from '@kit.AbilityKit'; 652import { BusinessError } from '@kit.BasicServicesKit'; 653 654export default class EntryAbility extends UIAbility { 655 onWindowStageCreate(windowStage: window.WindowStage) { 656 // ... 657 console.info('onWindowStageCreate'); 658 let windowClass: window.Window | undefined = undefined; 659 let subWindowClass: window.Window | undefined = undefined; 660 let windowClassId: number = -1; 661 let subWindowClassId: number = -1; 662 663 try { 664 // Obtain the main window and ID of the application. 665 let promise = windowStage.getMainWindow(); 666 promise.then((data) => { 667 if (data == null) { 668 console.error("Failed to obtaining the window. Cause: The data is empty"); 669 return; 670 } 671 windowClass = data; 672 windowClass.setUIContent("pages/Index"); 673 windowClassId = windowClass.getWindowProperties().id; 674 console.info('Succeeded in obtaining the window') 675 }).catch((err: BusinessError) => { 676 console.error(`Failed to obtaining the window. Cause code: ${err.code}, message: ${err.message}`); 677 }); 678 679 // Create or obtain a subwindow and its ID. In this case, the subwindow has focus. 680 let promiseSub = windowStage.createSubWindow("testSubWindow"); 681 promiseSub.then((data) => { 682 if (data == null) { 683 console.error("Failed to obtaining the window. Cause: The data is empty"); 684 return; 685 } 686 subWindowClass = data; 687 subWindowClassId = subWindowClass.getWindowProperties().id; 688 subWindowClass.resize(500, 500); 689 subWindowClass.setUIContent("pages/Index2"); 690 subWindowClass.showWindow(); 691 692 // Listen for the window status and ensure that the window is ready. 693 subWindowClass.on("windowEvent", (windowEvent) => { 694 if (windowEvent == window.WindowEventType.WINDOW_ACTIVE) { 695 // Switch the focus. 696 let promise = window.shiftAppWindowFocus(subWindowClassId, windowClassId); 697 promise.then(() => { 698 console.info('Succeeded in shifting app window focus'); 699 }).catch((err: BusinessError) => { 700 console.error(`Failed to shift app window focus. Cause code: ${err.code}, message: ${err.message}`); 701 }); 702 } 703 }); 704 }); 705 } catch (exception) { 706 console.error(`Failed to shift app focus. Cause code: ${exception.code}, message: ${exception.message}`); 707 } 708 } 709} 710``` 711 712## window.create<sup>(deprecated)</sup> 713 714create(id: string, type: WindowType, callback: AsyncCallback<Window>): void 715 716Creates a subwindow. This API uses an asynchronous callback to return the result. 717 718> **NOTE** 719> 720> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 721 722**Model restriction**: This API can be used only in the FA model. 723 724**System capability**: SystemCapability.WindowManager.WindowManager.Core 725 726**Parameters** 727 728| Name | Type | Mandatory| Description | 729| -------- | -------------------------------------- | ---- | ------------------------------------ | 730| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 731| type | [WindowType](#windowtype7) | Yes | Window type. | 732| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created.| 733 734 735**Example** 736 737```ts 738import { BusinessError } from '@kit.BasicServicesKit'; 739 740let windowClass: window.Window | undefined = undefined; 741window.create('test', window.WindowType.TYPE_APP, (err: BusinessError, data) => { 742 const errCode: number = err.code; 743 if (errCode) { 744 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 745 return; 746 } 747 windowClass = data; 748 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 749}); 750``` 751 752## window.create<sup>(deprecated)</sup> 753 754create(id: string, type: WindowType): Promise<Window> 755 756Creates a subwindow. This API uses a promise to return the result. 757 758> **NOTE** 759> 760> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 761 762**Model restriction**: This API can be used only in the FA model. 763 764**System capability**: SystemCapability.WindowManager.WindowManager.Core 765 766**Parameters** 767 768| Name| Type | Mandatory| Description | 769| ------ | ------------------------- | ---- | ---------- | 770| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 771| type | [WindowType](#windowtype7) | Yes | Window type.| 772 773**Return value** 774 775| Type | Description | 776| -------------------------------- | --------------------------------------- | 777| Promise<[Window](#window)> | Promise used to return the subwindow created.| 778 779 780**Example** 781 782```ts 783import { BusinessError } from '@kit.BasicServicesKit'; 784 785let windowClass: window.Window | undefined = undefined; 786let promise = window.create('test', window.WindowType.TYPE_APP); 787promise.then((data) => { 788 windowClass = data; 789 console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data)); 790}).catch((err: BusinessError) => { 791 console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`); 792}); 793``` 794 795## window.create<sup>(deprecated)</sup> 796 797create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void 798 799Creates a system window. This API uses an asynchronous callback to return the result. 800 801> **NOTE** 802> 803> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9) instead. 804 805**System capability**: SystemCapability.WindowManager.WindowManager.Core 806 807**Parameters** 808 809| Name | Type | Mandatory| Description | 810| -------- | ------------------------------------------------------- | ---- | ------------------------------------ | 811| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context. | 812| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9). | 813| type | [WindowType](#windowtype7) | Yes | Window type. | 814| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow created.| 815 816 817**Example** 818 819```ts 820import { BusinessError } from '@kit.BasicServicesKit'; 821 822let windowClass: window.Window | undefined = undefined; 823window.create('test', window.WindowType.TYPE_SYSTEM_ALERT, (err: BusinessError, data) => { 824 const errCode: number = err.code; 825 if (errCode) { 826 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 827 return; 828 } 829 windowClass = data; 830 console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data)); 831 windowClass.resetSize(500, 1000); 832}); 833``` 834 835## window.create<sup>(deprecated)</sup> 836 837create(ctx: BaseContext, id: string, type: WindowType): Promise<Window> 838 839Creates a system window. This API uses a promise to return the result. 840 841> **NOTE** 842> 843> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [createWindow()](#windowcreatewindow9-1) instead. 844 845**System capability**: SystemCapability.WindowManager.WindowManager.Core 846 847**Parameters** 848 849| Name| Type | Mandatory| Description | 850| ------ | ------------------------- | ---- | ------------------------------------------------------------ | 851| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 852| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 853| type | [WindowType](#windowtype7) | Yes | Window type. | 854 855**Return value** 856 857| Type | Description | 858| -------------------------------- | --------------------------------------- | 859| Promise<[Window](#window)> | Promise used to return the subwindow created.| 860 861 862**Example** 863 864```ts 865import { BusinessError } from '@kit.BasicServicesKit'; 866 867let windowClass: window.Window | undefined = undefined; 868let promise = window.create('test', window.WindowType.TYPE_SYSTEM_ALERT); 869promise.then((data) => { 870 windowClass = data; 871 console.info('Succeeded in creating the window. Data:' + JSON.stringify(data)); 872}).catch((err: BusinessError) => { 873 console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`); 874}); 875``` 876 877## window.find<sup>(deprecated)</sup> 878 879find(id: string, callback: AsyncCallback<Window>): void 880 881Finds a window based on the ID. This API uses an asynchronous callback to return the result. 882 883> **NOTE** 884> 885> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 886 887**System capability**: SystemCapability.WindowManager.WindowManager.Core 888 889**Parameters** 890 891| Name | Type | Mandatory| Description | 892| -------- | -------------------------------------- | ---- | ------------------------------------ | 893| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 894| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the window found.| 895 896**Example** 897 898```ts 899import { BusinessError } from '@kit.BasicServicesKit'; 900 901let windowClass: window.Window | undefined = undefined; 902window.find('test', (err: BusinessError, data) => { 903 const errCode: number = err.code; 904 if (errCode) { 905 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 906 return; 907 } 908 windowClass = data; 909 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 910}); 911``` 912 913## window.find<sup>(deprecated)</sup> 914 915find(id: string): Promise<Window> 916 917Finds a window based on the ID. This API uses a promise to return the result. 918 919> **NOTE** 920> 921> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [findWindow()](#windowfindwindow9) instead. 922 923**System capability**: SystemCapability.WindowManager.WindowManager.Core 924 925**Parameters** 926 927| Name| Type | Mandatory| Description | 928| ------ | ------ | ---- | -------- | 929| id | string | Yes | Window name, that is, the value of **name** in [Configuration](#configuration9).| 930 931**Return value** 932 933| Type | Description | 934| -------------------------------- | ------------------------------------- | 935| Promise<[Window](#window)> | Promise used to return the window found.| 936 937**Example** 938 939```ts 940import { BusinessError } from '@kit.BasicServicesKit'; 941 942let windowClass: window.Window | undefined = undefined; 943let promise = window.find('test'); 944promise.then((data) => { 945 windowClass = data; 946 console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data)); 947}).catch((err: BusinessError) => { 948 console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`); 949}); 950``` 951 952## window.getTopWindow<sup>(deprecated)</sup> 953 954getTopWindow(callback: AsyncCallback<Window>): void 955 956Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 957 958> **NOTE** 959> 960> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 961 962**Model restriction**: This API can be used only in the FA model. 963 964**System capability**: SystemCapability.WindowManager.WindowManager.Core 965 966**Parameters** 967 968| Name | Type | Mandatory| Description | 969| -------- | -------------------------------------- | ---- | -------------------------------------------- | 970| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained.| 971 972**Example** 973 974```ts 975import { BusinessError } from '@kit.BasicServicesKit'; 976 977let windowClass: window.Window | undefined = undefined; 978window.getTopWindow((err: BusinessError, data) => { 979 const errCode: number = err.code; 980 if (errCode) { 981 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 982 return; 983 } 984 windowClass = data; 985 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 986}); 987``` 988 989## window.getTopWindow<sup>(deprecated)</sup> 990 991getTopWindow(): Promise<Window> 992 993Obtains the top window of the current application. This API uses a promise to return the result. 994 995> **NOTE** 996> 997> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 998 999**Model restriction**: This API can be used only in the FA model. 1000 1001**System capability**: SystemCapability.WindowManager.WindowManager.Core 1002 1003**Return value** 1004 1005| Type | Description | 1006| -------------------------------- | ----------------------------------------------- | 1007| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1008 1009**Example** 1010 1011```ts 1012import { BusinessError } from '@kit.BasicServicesKit'; 1013 1014let windowClass: window.Window | undefined = undefined; 1015let promise = window.getTopWindow(); 1016promise.then((data)=> { 1017 windowClass = data; 1018 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1019}).catch((err: BusinessError)=>{ 1020 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1021}); 1022``` 1023 1024## window.getTopWindow<sup>(deprecated)</sup> 1025 1026getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void 1027 1028Obtains the top window of the current application. This API uses an asynchronous callback to return the result. 1029 1030> **NOTE** 1031> 1032> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9) instead. 1033 1034**System capability**: SystemCapability.WindowManager.WindowManager.Core 1035 1036**Parameters** 1037 1038| Name | Type | Mandatory| Description | 1039| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1040| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1041| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the top window obtained. | 1042 1043**Example** 1044 1045```ts 1046// EntryAbility.ets 1047import { UIAbility } from '@kit.AbilityKit'; 1048import { BusinessError } from '@kit.BasicServicesKit'; 1049 1050export default class EntryAbility extends UIAbility { 1051 onWindowStageCreate(windowStage:window.WindowStage){ 1052 console.info('onWindowStageCreate'); 1053 let windowClass: window.Window | undefined = undefined; 1054 try { 1055 window.getTopWindow(this.context, (err: BusinessError, data) => { 1056 const errCode: number = err.code; 1057 if(errCode){ 1058 console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`); 1059 return ; 1060 } 1061 windowClass = data; 1062 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1063 }); 1064 } catch(error){ 1065 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1066 } 1067 } 1068} 1069``` 1070 1071## window.getTopWindow<sup>(deprecated)</sup> 1072 1073getTopWindow(ctx: BaseContext): Promise<Window> 1074 1075Obtains the top window of the current application. This API uses a promise to return the result. 1076 1077> **NOTE** 1078> 1079> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getLastWindow()](#windowgetlastwindow9-1) instead. 1080 1081**System capability**: SystemCapability.WindowManager.WindowManager.Core 1082 1083**Parameters** 1084 1085| Name| Type | Mandatory| Description | 1086| ------ | ----------- | ---- | ------------------------------------------------------------ | 1087| ctx | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Current application context.| 1088 1089**Return value** 1090 1091| Type | Description | 1092| -------------------------------- | ----------------------------------------------- | 1093| Promise<[Window](#window)> | Promise used to return the top window obtained.| 1094 1095**Example** 1096 1097```ts 1098// EntryAbility.ets 1099import { UIAbility } from '@kit.AbilityKit'; 1100import { BusinessError } from '@kit.BasicServicesKit'; 1101 1102export default class EntryAbility extends UIAbility { 1103 onWindowStageCreate(windowStage:window.WindowStage) { 1104 console.info('onWindowStageCreate'); 1105 let windowClass: window.Window | undefined = undefined; 1106 let promise = window.getTopWindow(this.context); 1107 promise.then((data) => { 1108 windowClass = data; 1109 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 1110 }).catch((error: BusinessError) => { 1111 console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`); 1112 }); 1113 } 1114} 1115``` 1116 1117## SpecificSystemBar<sup>11+</sup> 1118 1119type SpecificSystemBar = 'status' \| 'navigation' \| 'navigationIndicator' 1120 1121Enumerates the types of system bars that can be displayed or hidden. 1122 1123**System capability**: SystemCapability.Window.SessionManager 1124 1125**Atomic service API**: This API can be used in atomic services since API version 11. 1126 1127| Type | Description | 1128|------------|--------| 1129| 'status' | Status bar. | 1130| 'navigation' | Three-button navigation bar. | 1131| 'navigationIndicator' | Bottom navigation bar.| 1132 1133## Window 1134 1135Represents a window instance, which is the basic unit managed by the window manager. 1136 1137In 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. 1138 1139### showWindow<sup>9+</sup> 1140 1141showWindow(callback: AsyncCallback<void>): void 1142 1143Shows this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application subwindow. For the main window of an application, this API moves it at the top when the main window is already displayed. 1144 1145**System capability**: SystemCapability.WindowManager.WindowManager.Core 1146 1147**Atomic service API**: This API can be used in atomic services since API version 11. 1148 1149**Parameters** 1150 1151| Name| Type| Mandatory| Description| 1152| -------- | ------------------------- | -- | --------- | 1153| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1154 1155**Error codes** 1156 1157For details about the error codes, see [Window Error Codes](errorcode-window.md). 1158 1159| ID| Error Message| 1160| ------- | ------------------------------ | 1161| 1300002 | This window state is abnormal. | 1162 1163**Example** 1164 1165```ts 1166import { BusinessError } from '@kit.BasicServicesKit'; 1167 1168windowClass.showWindow((err: BusinessError) => { 1169 const errCode: number = err.code; 1170 if (errCode) { 1171 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1172 return; 1173 } 1174 console.info('Succeeded in showing the window.'); 1175}); 1176``` 1177 1178### showWindow<sup>9+</sup> 1179 1180showWindow(): Promise<void> 1181 1182Shows this window. This API uses a promise to return the result. This API takes effect only for a system window or an application subwindow. For the main window of an application, this API moves it at the top when the main window is already displayed. 1183 1184**System capability**: SystemCapability.WindowManager.WindowManager.Core 1185 1186**Atomic service API**: This API can be used in atomic services since API version 11. 1187 1188**Return value** 1189 1190| Type| Description| 1191| ------------------- | ----------------------- | 1192| Promise<void> | Promise that returns no value.| 1193 1194**Error codes** 1195 1196For details about the error codes, see [Window Error Codes](errorcode-window.md). 1197 1198| ID| Error Message| 1199| ------- | ------------------------------ | 1200| 1300002 | This window state is abnormal. | 1201 1202**Example** 1203 1204```ts 1205import { BusinessError } from '@kit.BasicServicesKit'; 1206 1207let promise = windowClass.showWindow(); 1208promise.then(() => { 1209 console.info('Succeeded in showing the window.'); 1210}).catch((err: BusinessError) => { 1211 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 1212}); 1213``` 1214 1215### destroyWindow<sup>9+</sup> 1216 1217destroyWindow(callback: AsyncCallback<void>): void 1218 1219Destroys this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application subwindow. 1220 1221**System capability**: SystemCapability.WindowManager.WindowManager.Core 1222 1223**Atomic service API**: This API can be used in atomic services since API version 11. 1224 1225**Parameters** 1226 1227| Name| Type| Mandatory| Description| 1228| -------- | ------------------------- | -- | --------- | 1229| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1230 1231**Error codes** 1232 1233For details about the error codes, see [Window Error Codes](errorcode-window.md). 1234 1235| ID| Error Message| 1236| ------- | -------------------------------------------- | 1237| 1300002 | This window state is abnormal. | 1238| 1300003 | This window manager service works abnormally. | 1239 1240**Example** 1241 1242```ts 1243import { BusinessError } from '@kit.BasicServicesKit'; 1244 1245windowClass.destroyWindow((err) => { 1246 const errCode: number = err.code; 1247 if (errCode) { 1248 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 1249 return; 1250 } 1251 console.info('Succeeded in destroying the window.'); 1252}); 1253``` 1254 1255### destroyWindow<sup>9+</sup> 1256 1257destroyWindow(): Promise<void> 1258 1259Destroys this window. This API uses a promise to return the result. This API takes effect only for a system window or an application subwindow. 1260 1261**System capability**: SystemCapability.WindowManager.WindowManager.Core 1262 1263**Atomic service API**: This API can be used in atomic services since API version 11. 1264 1265**Return value** 1266 1267| Type| Description| 1268| ------------------- | ------------------------ | 1269| Promise<void> | Promise that returns no value.| 1270 1271**Error codes** 1272 1273For details about the error codes, see [Window Error Codes](errorcode-window.md). 1274 1275| ID| Error Message| 1276| ------- | -------------------------------------------- | 1277| 1300002 | This window state is abnormal. | 1278| 1300003 | This window manager service works abnormally. | 1279 1280**Example** 1281 1282```ts 1283import { BusinessError } from '@kit.BasicServicesKit'; 1284 1285let promise = windowClass.destroyWindow(); 1286promise.then(() => { 1287 console.info('Succeeded in destroying the window.'); 1288}).catch((err: BusinessError) => { 1289 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 1290}); 1291``` 1292 1293### moveWindowTo<sup>9+</sup> 1294 1295moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void 1296 1297Moves this window. This API uses an asynchronous callback to return the result. 1298 1299<!--RP4--> 1300In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 1301 1302On a 2-in-1 device, the window moves relative to the screen. On other devices, the window moves relative to the parent window. 1303 1304**System capability**: SystemCapability.WindowManager.WindowManager.Core 1305 1306**Atomic service API**: This API can be used in atomic services since API version 11. 1307 1308**Parameters** 1309 1310| Name| Type| Mandatory| Description| 1311| -------- | ------------------------- | -- | --------------------------------------------- | 1312| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1313| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1314| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 1315 1316**Error codes** 1317 1318For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1319 1320| ID| Error Message| 1321| ------- | -------------------------------------------- | 1322| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1323| 1300002 | This window state is abnormal. | 1324| 1300003 | This window manager service works abnormally. | 1325 1326**Example** 1327 1328```ts 1329import { BusinessError } from '@kit.BasicServicesKit'; 1330 1331try { 1332 windowClass.moveWindowTo(300, 300, (err: BusinessError) => { 1333 const errCode: number = err.code; 1334 if (errCode) { 1335 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1336 return; 1337 } 1338 console.info('Succeeded in moving the window.'); 1339 }); 1340} catch (exception) { 1341 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1342} 1343``` 1344 1345### moveWindowTo<sup>9+</sup> 1346 1347moveWindowTo(x: number, y: number): Promise<void> 1348 1349Moves this window. This API uses a promise to return the result. The result is returned once the API is called successfully. However, the final effect cannot be obtained immediately after the result is returned. To obtain the final effect immediately, call [moveWindowToAsync()](#movewindowtoasync12). 1350 1351<!--RP4--> 1352In full-screen mode, this API takes effect only on 2-in-1 devices.<!--RP4End--> 1353 1354On a 2-in-1 device, the window moves relative to the screen. On other devices, the window moves relative to the parent window. 1355 1356**System capability**: SystemCapability.WindowManager.WindowManager.Core 1357 1358**Atomic service API**: This API can be used in atomic services since API version 11. 1359 1360**Parameters** 1361 1362| Name| Type| Mandatory| Description| 1363| -- | ----- | -- | --------------------------------------------- | 1364| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1365| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1366 1367**Return value** 1368 1369| Type| Description| 1370| ------------------- | ------------------------ | 1371| Promise<void> | Promise that returns no value.| 1372 1373**Error codes** 1374 1375For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1376 1377| ID| Error Message| 1378| ------- | -------------------------------------------- | 1379| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1380| 1300002 | This window state is abnormal. | 1381| 1300003 | This window manager service works abnormally. | 1382 1383**Example** 1384 1385```ts 1386import { BusinessError } from '@kit.BasicServicesKit'; 1387 1388try { 1389 let promise = windowClass.moveWindowTo(300, 300); 1390 promise.then(() => { 1391 console.info('Succeeded in moving the window.'); 1392 }).catch((err: BusinessError) => { 1393 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1394 }); 1395} catch (exception) { 1396 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1397} 1398``` 1399 1400### moveWindowToAsync<sup>12+</sup> 1401 1402moveWindowToAsync(x: number, y: number): Promise<void> 1403 1404Moves this window. This API uses a promise to return the result. 1405 1406The result is returned once the API is called successfully. However, the final effect cannot be obtained immediately after the result is returned. To obtain the final effect immediately, call **getWindowProperties** (see the code snippet below). 1407 1408This operation is not supported in a window in full-screen mode. 1409 1410On a 2-in-1 device, the window moves relative to the screen. On other devices, the window moves relative to the parent window. 1411 1412**System capability**: SystemCapability.Window.SessionManager 1413 1414**Atomic service API**: This API can be used in atomic services since API version 12. 1415 1416**Parameters** 1417 1418| Name| Type| Mandatory| Description| 1419| -- | ----- | -- | --------------------------------------------- | 1420| x | number | Yes| Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1421| y | number | Yes| Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down.| 1422 1423**Return value** 1424 1425| Type| Description| 1426| ------------------- | ------------------------ | 1427| Promise<void> | Promise that returns no value.| 1428 1429**Error codes** 1430 1431For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1432 1433| ID| Error Message| 1434| ------- | -------------------------------------------- | 1435| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1436| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1437| 1300002 | This window state is abnormal. | 1438| 1300003 | This window manager service works abnormally. | 1439| 1300010 | The operation is not supported in full-screen mode. | 1440 1441**Example** 1442 1443```ts 1444import { BusinessError } from '@kit.BasicServicesKit'; 1445 1446try { 1447 let promise = windowClass.moveWindowToAsync(300, 300); 1448 promise.then(() => { 1449 console.info('Succeeded in moving the window.'); 1450 let rect = windowClass.getWindowProperties().windowRect; 1451 console.info(`Get window rect: ` + JSON.stringify(rect)); 1452 }).catch((err: BusinessError) => { 1453 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 1454 }); 1455} catch (exception) { 1456 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 1457} 1458``` 1459 1460### resize<sup>9+</sup> 1461 1462resize(width: number, height: number, callback: AsyncCallback<void>): void 1463 1464Changes the size of this window. This API uses an asynchronous callback to return the result. 1465 1466The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1467 1468The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1469 1470The system window has the following size limits: [0, 1920] in width and [0, 1920] in height, both in units of vp. 1471 1472The window width and height you set must meet the limits. The rules are as follows: 1473- 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. 1474- 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. 1475 1476This operation is not supported in a window in full-screen mode. 1477 1478**System capability**: SystemCapability.WindowManager.WindowManager.Core 1479 1480**Atomic service API**: This API can be used in atomic services since API version 11. 1481 1482**Parameters** 1483 1484| Name| Type| Mandatory| Description| 1485| -------- | ------------------------- | -- | ------------------------ | 1486| 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.| 1487| 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.| 1488| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 1489 1490**Error codes** 1491 1492For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1493 1494| ID| Error Message| 1495| ------- | -------------------------------------------- | 1496| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1497| 1300002 | This window state is abnormal. | 1498| 1300003 | This window manager service works abnormally. | 1499 1500**Example** 1501 1502```ts 1503import { BusinessError } from '@kit.BasicServicesKit'; 1504 1505try { 1506 windowClass.resize(500, 1000, (err: BusinessError) => { 1507 const errCode: number = err.code; 1508 if (errCode) { 1509 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 1510 return; 1511 } 1512 console.info('Succeeded in changing the window size.'); 1513 }); 1514} catch (exception) { 1515 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 1516} 1517``` 1518 1519### resize<sup>9+</sup> 1520 1521resize(width: number, height: number): Promise<void> 1522 1523Changes the size of this window. This API uses a promise to return the result. 1524 1525The result is returned once the API is called successfully. However, the final effect cannot be obtained immediately after the result is returned. To obtain the final effect immediately, call [resizeAsync()](#resizeasync12). 1526 1527The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1528 1529The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1530 1531The system window has the following size limits: [0, 1920] in width and [0, 1920] in height, both in units of vp. 1532 1533The window width and height you set must meet the limits. The rules are as follows: 1534- 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. 1535- 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. 1536 1537This operation is not supported in a window in full-screen mode. 1538 1539**System capability**: SystemCapability.WindowManager.WindowManager.Core 1540 1541**Atomic service API**: This API can be used in atomic services since API version 11. 1542 1543**Parameters** 1544 1545| Name| Type| Mandatory| Description| 1546| ------ | ------ | -- | ------------------------ | 1547| 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.| 1548| 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.| 1549 1550**Return value** 1551 1552| Type| Description| 1553| ------------------- | ------------------------ | 1554| Promise<void> | Promise that returns no value.| 1555 1556**Error codes** 1557 1558For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1559 1560| ID| Error Message| 1561| ------- | -------------------------------------------- | 1562| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1563| 1300002 | This window state is abnormal. | 1564| 1300003 | This window manager service works abnormally. | 1565 1566**Example** 1567 1568```ts 1569import { BusinessError } from '@kit.BasicServicesKit'; 1570 1571try { 1572 let promise = windowClass.resize(500, 1000); 1573 promise.then(() => { 1574 console.info('Succeeded in changing the window size.'); 1575 }).catch((err: BusinessError) => { 1576 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 1577 }); 1578} catch (exception) { 1579 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 1580} 1581``` 1582 1583### resizeAsync<sup>12+</sup> 1584 1585resizeAsync(width: number, height: number): Promise<void> 1586 1587Changes the size of this window. This API uses a promise to return the result. 1588 1589 The result is returned once the API is called successfully. However, the final effect cannot be obtained immediately after the result is returned. To obtain the final effect immediately, call **getWindowProperties** (see the code snippet below). 1590 1591The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 1592 1593The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 1594 1595The system window has the following size limits: [0, 1920] in width and [0, 1920] in height, both in units of vp. 1596 1597The window width and height you set must meet the limits. The rules are as follows: 1598 1599- 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. 1600- 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. 1601 1602This operation is not supported in a window in full-screen mode. 1603 1604**System capability**: SystemCapability.Window.SessionManager 1605 1606**Atomic service API**: This API can be used in atomic services since API version 12. 1607 1608**Parameters** 1609 1610| Name| Type| Mandatory| Description| 1611| ------ | ------ | -- | ------------------------ | 1612| 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.| 1613| 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.| 1614 1615**Return value** 1616 1617| Type| Description| 1618| ------------------- | ------------------------ | 1619| Promise<void> | Promise that returns no value.| 1620 1621**Error codes** 1622 1623For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1624 1625| ID| Error Message| 1626| ------- | -------------------------------------------- | 1627| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1628| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1629| 1300002 | This window state is abnormal. | 1630| 1300003 | This window manager service works abnormally. | 1631| 1300010 | The operation is not supported in full-screen mode. | 1632 1633**Example** 1634 1635```ts 1636import { BusinessError } from '@kit.BasicServicesKit'; 1637 1638try { 1639 let promise = windowClass.resizeAsync(500, 1000); 1640 promise.then(() => { 1641 console.info('Succeeded in changing the window size.'); 1642 let rect = windowClass.getWindowProperties().windowRect; 1643 console.info(`Get window rect: ` + JSON.stringify(rect)); 1644 }).catch((err: BusinessError) => { 1645 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 1646 }); 1647} catch (exception) { 1648 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 1649} 1650``` 1651 1652### getWindowProperties<sup>9+</sup> 1653 1654getWindowProperties(): WindowProperties 1655 1656Obtains the properties of this window. 1657 1658**System capability**: SystemCapability.WindowManager.WindowManager.Core 1659 1660**Atomic service API**: This API can be used in atomic services since API version 11. 1661 1662**Return value** 1663 1664| Type| Description| 1665| ------------------------------------- | ------------- | 1666| [WindowProperties](#windowproperties) | Window properties obtained.| 1667 1668**Error codes** 1669 1670For details about the error codes, see [Window Error Codes](errorcode-window.md). 1671 1672| ID| Error Message| 1673| ------- | ------------------------------ | 1674| 1300002 | This window state is abnormal. | 1675 1676**Example** 1677 1678```ts 1679try { 1680 let properties = windowClass.getWindowProperties(); 1681} catch (exception) { 1682 console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`); 1683} 1684``` 1685 1686### getWindowAvoidArea<sup>9+</sup> 1687 1688getWindowAvoidArea(type: AvoidAreaType): AvoidArea 1689 1690Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. 1691 1692This 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. 1693 1694**System capability**: SystemCapability.WindowManager.WindowManager.Core 1695 1696**Atomic service API**: This API can be used in atomic services since API version 11. 1697 1698**Parameters** 1699 1700| Name| Type| Mandatory| Description| 1701| ---- |----------------------------------| -- | ------------------------------------------------------------ | 1702| type | [AvoidAreaType](#avoidareatype7) | Yes| Type of the area.| 1703 1704**Return value** 1705 1706| Type| Description| 1707|--------------------------| ----------------- | 1708| [AvoidArea](#avoidarea7) | Area where the window cannot be displayed.| 1709 1710**Error codes** 1711 1712For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1713 1714| ID| Error Message| 1715| ------- | ------------------------------ | 1716| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1717| 1300002 | This window state is abnormal. | 1718 1719**Example** 1720 1721```ts 1722let type = window.AvoidAreaType.TYPE_SYSTEM; 1723try { 1724 let avoidArea = windowClass.getWindowAvoidArea(type); 1725} catch (exception) { 1726 console.error(`Failed to obtain the area. Cause code: ${exception.code}, message: ${exception.message}`); 1727} 1728``` 1729 1730### setWindowLayoutFullScreen<sup>9+</sup> 1731 1732setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 1733 1734Sets whether the main window layout or the subwindow layout is immersive. This API uses a promise to return the result. 1735- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 1736- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 1737 1738**System capability**: SystemCapability.WindowManager.WindowManager.Core 1739 1740**Atomic service API**: This API can be used in atomic services since API version 12. 1741 1742**Parameters** 1743 1744| Name| Type| Mandatory| Description| 1745| ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ | 1746| 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.| 1747 1748**Return value** 1749 1750| Type| Description| 1751| ------------------- | ------------------------ | 1752| Promise<void> | Promise that returns no value.| 1753 1754**Error codes** 1755 1756For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1757 1758| ID| Error Message| 1759| ------- | -------------------------------------------- | 1760| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1761| 1300002 | This window state is abnormal. | 1762| 1300003 | This window manager service works abnormally. | 1763 1764**Example** 1765 1766```ts 1767// EntryAbility.ets 1768import { UIAbility } from '@kit.AbilityKit'; 1769import { BusinessError } from '@kit.BasicServicesKit'; 1770 1771export default class EntryAbility extends UIAbility { 1772 // ... 1773 onWindowStageCreate(windowStage: window.WindowStage): void { 1774 console.info('onWindowStageCreate'); 1775 let windowClass: window.Window | undefined = undefined; 1776 windowStage.getMainWindow((err: BusinessError, data) => { 1777 const errCode: number = err.code; 1778 if (errCode) { 1779 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1780 return; 1781 } 1782 windowClass = data; 1783 let isLayoutFullScreen = true; 1784 try { 1785 let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen); 1786 promise.then(() => { 1787 console.info('Succeeded in setting the window layout to full-screen mode.'); 1788 }).catch((err: BusinessError) => { 1789 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 1790 }); 1791 } catch (exception) { 1792 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 1793 } 1794 }); 1795 } 1796} 1797``` 1798 1799### setImmersiveModeEnabledState<sup>12+</sup> 1800 1801setImmersiveModeEnabledState(enabled: boolean): void 1802 1803Sets whether to enable the immersive layout for the main window. This API does not change the window mode or size. 1804 1805**System capability**: SystemCapability.WindowManager.WindowManager.Core 1806 1807**Atomic service API**: This API can be used in atomic services since API version 12. 1808 1809**Parameters** 1810 1811| Name | Type | Mandatory| Description | 1812| ---------- | ------- | ---- | ------------------------------------------------------------ | 1813| enabled | boolean | Yes | Whether to enable the immersive layout.<br>The value **true** means to enable the immersive layout, and **false** means the opposite. | 1814 1815**Error codes** 1816 1817For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1818 1819| ID| Error Message| 1820| ------- | -------------------------------------------- | 1821| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1822| 1300002 | This window state is abnormal. | 1823| 1300003 | This window manager service works abnormally. | 1824| 1300004 | Unauthorized operation. | 1825 1826**Example** 1827 1828```ts 1829try { 1830 let enabled = false; 1831 windowClass.setImmersiveModeEnabledState(enabled); 1832} catch (exception) { 1833 console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 1834} 1835``` 1836 1837### getImmersiveModeEnabledState<sup>12+</sup> 1838 1839getImmersiveModeEnabledState(): boolean 1840 1841Checks whether the immersive layout is enabled for this window. 1842 1843**System capability**: SystemCapability.WindowManager.WindowManager.Core 1844 1845**Atomic service API**: This API can be used in atomic services since API version 12. 1846 1847**Return value** 1848| Type | Description | 1849| ------- | ------------------------------------------------------------------------------------ | 1850| 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.<br>| 1851 1852**Error codes** 1853 1854For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1855 1856| ID| Error Message| 1857| -------- | -------------------------------------------- | 1858| 1300002 | This window state is abnormal. | 1859| 1300003 | This window manager service works abnormally. | 1860| 1300004 | Unauthorized operation. | 1861 1862**Example** 1863 1864```ts 1865try { 1866 let isEnabled = windowClass.getImmersiveModeEnabledState(); 1867} catch (exception) { 1868 console.error(`Failed to get the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 1869} 1870``` 1871 1872### setWindowSystemBarEnable<sup>9+</sup> 1873 1874setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 1875 1876Sets 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--> 1877 1878This API does not take effect when it is called by a subwindow. 1879 1880**Atomic service API**: This API can be used in atomic services since API version 12. 1881 1882**System capability**: SystemCapability.WindowManager.WindowManager.Core 1883 1884**Parameters** 1885 1886| Name| Type | Mandatory| Description| 1887| ----- | ---------------------------- | -- | --------------------------------- | 1888| 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 show all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed.| 1889 1890**Return value** 1891 1892| Type| Description| 1893| ------------------- | ------------------------ | 1894| Promise<void> | Promise that returns no value.| 1895 1896**Error codes** 1897 1898For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1899 1900| ID| Error Message| 1901| ------- | -------------------------------------------- | 1902| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1903| 1300002 | This window state is abnormal. | 1904| 1300003 | This window manager service works abnormally. | 1905 1906**Example** 1907 1908```ts 1909// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 1910// EntryAbility.ets 1911import { UIAbility } from '@kit.AbilityKit'; 1912import { BusinessError } from '@kit.BasicServicesKit'; 1913 1914export default class EntryAbility extends UIAbility { 1915 // ... 1916 onWindowStageCreate(windowStage: window.WindowStage): void { 1917 console.info('onWindowStageCreate'); 1918 let windowClass: window.Window | undefined = undefined; 1919 windowStage.getMainWindow((err: BusinessError, data) => { 1920 const errCode: number = err.code; 1921 if (errCode) { 1922 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1923 return; 1924 } 1925 windowClass = data; 1926 let names: Array<'status' | 'navigation'> = []; 1927 try { 1928 let promise = windowClass.setWindowSystemBarEnable(names); 1929 promise.then(() => { 1930 console.info('Succeeded in setting the system bar to be invisible.'); 1931 }).catch((err: BusinessError) => { 1932 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 1933 }); 1934 } catch (exception) { 1935 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 1936 } 1937 }); 1938 } 1939} 1940``` 1941 1942### setSpecificSystemBarEnabled<sup>11+</sup> 1943 1944setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void> 1945 1946Sets 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--> 1947 1948This API does not take effect when it is called by a subwindow. 1949 1950**System capability**: SystemCapability.Window.SessionManager 1951 1952**Atomic service API**: This API can be used in atomic services since API version 11. 1953 1954**Parameters** 1955 1956| Name| Type | Mandatory| Description| 1957| ----- | ---------------------------- | -- | --------------------------------- | 1958| name | [SpecificSystemBar](#specificsystembar11) | Yes| Type of the system bar to be shown or hidden.| 1959| 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.| 1960| 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**.| 1961 1962**Return value** 1963 1964| Type| Description| 1965| ------------------- | ------------------------ | 1966| Promise<void> | Promise that returns no value.| 1967 1968**Error codes** 1969 1970For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1971 1972| ID| Error Message| 1973| ------- | -------------------------------------------- | 1974| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1975| 1300002 | This window state is abnormal. | 1976| 1300003 | This window manager service works abnormally. | 1977 1978**Example** 1979 1980```ts 1981// Hide the bottom navigation bar. 1982// EntryAbility.ets 1983import { UIAbility } from '@kit.AbilityKit'; 1984import { BusinessError } from '@kit.BasicServicesKit'; 1985 1986export default class EntryAbility extends UIAbility { 1987 // ... 1988 onWindowStageCreate(windowStage: window.WindowStage): void { 1989 console.info('onWindowStageCreate'); 1990 let windowClass: window.Window | undefined = undefined; 1991 windowStage.getMainWindow((err: BusinessError, data) => { 1992 const errCode: number = err.code; 1993 if (errCode) { 1994 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1995 return; 1996 } 1997 windowClass = data; 1998 try { 1999 let promise = windowClass.setSpecificSystemBarEnabled('navigationIndicator', false); 2000 promise.then(() => { 2001 console.info('Succeeded in setting the system bar to be invisible.'); 2002 }).catch((err: BusinessError) => { 2003 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 2004 }); 2005 } catch (exception) { 2006 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 2007 } 2008 }); 2009 } 2010} 2011``` 2012 2013### setWindowSystemBarProperties<sup>9+</sup> 2014 2015setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 2016 2017Sets 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--> 2018 2019This API does not take effect when it is called by a subwindow. 2020 2021**System capability**: SystemCapability.WindowManager.WindowManager.Core 2022 2023**Atomic service API**: This API can be used in atomic services since API version 12. 2024 2025**Parameters** 2026 2027| Name | Type | Mandatory| Description | 2028| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2029| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar.| 2030 2031**Return value** 2032 2033| Type | Description | 2034| ------------------- | ------------------------- | 2035| Promise<void> | Promise that returns no value.| 2036 2037**Error codes** 2038 2039For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2040 2041| ID| Error Message| 2042| ------- | -------------------------------------------- | 2043| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2044| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 2045| 1300002 | This window state is abnormal. | 2046| 1300003 | This window manager service works abnormally. | 2047 2048**Example** 2049 2050```ts 2051// EntryAbility.ets 2052import { UIAbility } from '@kit.AbilityKit'; 2053import { BusinessError } from '@kit.BasicServicesKit'; 2054 2055export default class EntryAbility extends UIAbility { 2056 // ... 2057 onWindowStageCreate(windowStage: window.WindowStage): void { 2058 console.info('onWindowStageCreate'); 2059 let windowClass: window.Window | undefined = undefined; 2060 windowStage.getMainWindow((err: BusinessError, data) => { 2061 const errCode: number = err.code; 2062 if (errCode) { 2063 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2064 return; 2065 } 2066 windowClass = data; 2067 let SystemBarProperties: window.SystemBarProperties = { 2068 statusBarColor: '#ff00ff', 2069 navigationBarColor: '#00ff00', 2070 // The following properties are supported since API version 8. 2071 statusBarContentColor: '#ffffff', 2072 navigationBarContentColor: '#00ffff' 2073 }; 2074 try { 2075 let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties); 2076 promise.then(() => { 2077 console.info('Succeeded in setting the system bar properties.'); 2078 }).catch((err: BusinessError) => { 2079 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 2080 }); 2081 } catch (exception) { 2082 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 2083 } 2084 }); 2085 } 2086} 2087``` 2088 2089### getWindowSystemBarProperties<sup>12+</sup> 2090 2091getWindowSystemBarProperties(): SystemBarProperties 2092 2093Obtains the properties of the three-button navigation bar and status bar of the main window. 2094 2095**System capability**: SystemCapability.WindowManager.WindowManager.Core 2096 2097**Atomic service API**: This API can be used in atomic services since API version 12. 2098 2099**Return value** 2100 2101| Type| Description| 2102| ------------------------------------- | ------------- | 2103| [SystemBarProperties](#systembarproperties) | Properties of the three-button navigation bar and status bar.| 2104 2105**Error codes** 2106 2107For details about the error codes, see [Window Error Codes](errorcode-window.md). 2108 2109| ID| Error Message| 2110| ------- | ------------------------------ | 2111| 1300002 | This window state is abnormal. | 2112| 1300003 | This window manager service works abnormally. | 2113| 1300004 | Unauthorized operation. | 2114 2115 2116**Example** 2117 2118```ts 2119// EntryAbility.ets 2120import { UIAbility } from '@kit.AbilityKit'; 2121import { BusinessError } from '@kit.BasicServicesKit'; 2122 2123export default class EntryAbility extends UIAbility { 2124 // ... 2125 2126 onWindowStageCreate(windowStage: window.WindowStage) { 2127 let windowClass: window.Window | undefined = undefined; 2128 windowStage.getMainWindow((err: BusinessError, data) => { 2129 const errCode: number = err.code; 2130 if (errCode) { 2131 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2132 return; 2133 } 2134 windowClass = data; 2135 try { 2136 let systemBarProperty = windowClass.getWindowSystemBarProperties(); 2137 console.info('Success in obtaining system bar properties. Property: ' + JSON.stringify(systemBarProperty)); 2138 } catch (err) { 2139 console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`); 2140 } 2141 }); 2142 } 2143}; 2144``` 2145 2146### setPreferredOrientation<sup>9+</sup> 2147 2148setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 2149 2150Sets the preferred orientation for the main window. This API uses an asynchronous callback to return the result. This API takes effect only on the device that supports rotation with the sensor. It does not take effect after it is called by the subwindow. 2151 2152**System capability**: SystemCapability.WindowManager.WindowManager.Core 2153 2154**Atomic service API**: This API can be used in atomic services since API version 11. 2155 2156**Parameters** 2157 2158| Name | Type | Mandatory| Description | 2159| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2160| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 2161| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 2162 2163**Error codes** 2164 2165For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2166 2167| ID| Error Message| 2168| ------- | ------------------------------ | 2169| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2170| 1300002 | This window state is abnormal. | 2171 2172**Example** 2173 2174```ts 2175// EntryAbility.ets 2176import { UIAbility } from '@kit.AbilityKit'; 2177import { BusinessError } from '@kit.BasicServicesKit'; 2178 2179export default class EntryAbility extends UIAbility { 2180 // ... 2181 onWindowStageCreate(windowStage: window.WindowStage): void { 2182 console.info('onWindowStageCreate'); 2183 let windowClass: window.Window | undefined = undefined; 2184 windowStage.getMainWindow((err: BusinessError, data) => { 2185 const errCode: number = err.code; 2186 if (errCode) { 2187 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2188 return; 2189 } 2190 windowClass = data; 2191 let orientation = window.Orientation.AUTO_ROTATION; 2192 try { 2193 windowClass.setPreferredOrientation(orientation, (err: BusinessError) => { 2194 const errCode: number = err.code; 2195 if (errCode) { 2196 console.error(`Failed to set window orientation. Cause code: ${err.code}, message: ${err.message}`); 2197 return; 2198 } 2199 console.info('Succeeded in setting window orientation.'); 2200 }); 2201 } catch (exception) { 2202 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2203 } 2204 }); 2205 } 2206} 2207``` 2208 2209### setPreferredOrientation<sup>9+</sup> 2210 2211setPreferredOrientation(orientation: Orientation): Promise<void> 2212 2213Sets the preferred orientation for the main window. This API uses a promise to return the result. This API takes effect only on the device that supports rotation with the sensor. It does not take effect after it is called by the subwindow. 2214 2215**System capability**: SystemCapability.WindowManager.WindowManager.Core 2216 2217**Atomic service API**: This API can be used in atomic services since API version 11. 2218 2219**Parameters** 2220 2221| Name | Type | Mandatory| Description | 2222| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2223| orientation | [Orientation](#orientation9) | Yes | Orientation to set. | 2224 2225**Return value** 2226 2227| Type | Description | 2228| ------------------- | ------------------------- | 2229| Promise<void> | Promise that returns no value.| 2230 2231**Error codes** 2232 2233For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2234 2235| ID| Error Message| 2236| ------- | ------------------------------ | 2237| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2238| 1300002 | This window state is abnormal. | 2239 2240**Example** 2241 2242```ts 2243// EntryAbility.ets 2244import { UIAbility } from '@kit.AbilityKit'; 2245import { BusinessError } from '@kit.BasicServicesKit'; 2246 2247export default class EntryAbility extends UIAbility { 2248 // ... 2249 onWindowStageCreate(windowStage: window.WindowStage): void { 2250 console.info('onWindowStageCreate'); 2251 let windowClass: window.Window | undefined = undefined; 2252 windowStage.getMainWindow((err: BusinessError, data) => { 2253 const errCode: number = err.code; 2254 if (errCode) { 2255 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2256 return; 2257 } 2258 windowClass = data; 2259 let orientation = window.Orientation.AUTO_ROTATION; 2260 try { 2261 let promise = windowClass.setPreferredOrientation(orientation); 2262 promise.then(() => { 2263 console.info('Succeeded in setting the window orientation.'); 2264 }).catch((err: BusinessError) => { 2265 console.error(`Failed to set the window orientation. Cause code: ${err.code}, message: ${err.message}`); 2266 }); 2267 } catch (exception) { 2268 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2269 } 2270 }); 2271 } 2272} 2273``` 2274 2275### getPreferredOrientation<sup>12+</sup> 2276 2277getPreferredOrientation(): Orientation 2278 2279Obtains the orientation of the main window. This API can be called only by the main window. 2280 2281**System capability**: SystemCapability.WindowManager.WindowManager.Core 2282 2283**Atomic service API**: This API can be used in atomic services since API version 12. 2284 2285**Return value** 2286 2287| Type| Description| 2288|------------------------------| ------------------ | 2289| [Orientation](#orientation9) | Orientation.| 2290 2291**Error codes** 2292 2293For details about the error codes, see [Window Error Codes](errorcode-window.md). 2294 2295| ID| Error Message| 2296| ------- | ------------------------------ | 2297| 1300002 | This window state is abnormal. | 2298 2299**Example** 2300 2301```ts 2302// EntryAbility.ets 2303import { UIAbility } from '@kit.AbilityKit'; 2304import { BusinessError } from '@kit.BasicServicesKit'; 2305export default class EntryAbility extends UIAbility { 2306 // ... 2307 2308 onWindowStageCreate(windowStage: window.WindowStage) { 2309 console.info('onWindowStageCreate'); 2310 let windowClass: window.Window | undefined = undefined; 2311 windowStage.getMainWindow((err: BusinessError, data) => { 2312 const errCode: number = err.code; 2313 if (errCode) { 2314 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2315 return; 2316 } 2317 windowClass = data; 2318 try { 2319 let orientation = windowClass.getPreferredOrientation(); 2320 } catch (exception) { 2321 console.error(`Failed to get window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2322 } 2323 }); 2324 } 2325}; 2326``` 2327 2328### getUIContext<sup>10+</sup> 2329 2330getUIContext(): UIContext 2331 2332Obtain a **UIContext** instance. 2333 2334**Model restriction**: This API can be used only in the stage model. 2335 2336**System capability**: SystemCapability.WindowManager.WindowManager.Core 2337 2338**Atomic service API**: This API can be used in atomic services since API version 11. 2339 2340**Return value** 2341 2342| Type | Description | 2343| ---------- | ---------------------- | 2344| [UIContext](js-apis-arkui-UIContext.md#uicontext) | **UIContext** instance obtained.| 2345 2346**Error codes** 2347 2348For details about the error codes, see [Window Error Codes](errorcode-window.md). 2349 2350| ID| Error Message| 2351| ------- | ------------------------------ | 2352| 1300002 | This window state is abnormal. | 2353 2354**Example** 2355 2356```ts 2357// EntryAbility.ets 2358import { UIAbility } from '@kit.AbilityKit'; 2359import { window, UIContext } from '@kit.ArkUI'; 2360import { BusinessError } from '@kit.BasicServicesKit'; 2361 2362export default class EntryAbility extends UIAbility { 2363 onWindowStageCreate(windowStage: window.WindowStage) { 2364 // Load content for the main window. 2365 windowStage.loadContent("pages/page2", (err: BusinessError) => { 2366 let errCode: number = err.code; 2367 if (errCode) { 2368 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2369 return; 2370 } 2371 console.info('Succeeded in loading the content.'); 2372 // Obtain the main window. 2373 let windowClass: window.Window | undefined = undefined; 2374 windowStage.getMainWindow((err: BusinessError, data) => { 2375 let errCode: number = err.code; 2376 if (errCode) { 2377 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2378 return; 2379 } 2380 windowClass = data; 2381 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 2382 // Obtain a UIContext instance. 2383 let uiContext: UIContext | null = null; 2384 uiContext = windowClass.getUIContext(); 2385 }); 2386 }); 2387 } 2388}; 2389``` 2390 2391### setUIContent<sup>9+</sup> 2392 2393setUIContent(path: string, callback: AsyncCallback<void>): void 2394 2395Loads 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. 2396 2397**System capability**: SystemCapability.WindowManager.WindowManager.Core 2398 2399**Atomic service API**: This API can be used in atomic services since API version 11. 2400 2401**Parameters** 2402 2403| Name| Type| Mandatory| Description| 2404| -------- | ------------------------- | -- | -------------------- | 2405| 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.| 2406| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 2407 2408**Error codes** 2409 2410For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2411 2412| ID| Error Message| 2413| ------- | -------------------------------------------- | 2414| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2415| 1300002 | This window state is abnormal. | 2416| 1300003 | This window manager service works abnormally. | 2417 2418**Example** 2419 2420```ts 2421import { BusinessError } from '@kit.BasicServicesKit'; 2422 2423try { 2424 windowClass.setUIContent('pages/page2/page3', (err: BusinessError) => { 2425 const errCode: number = err.code; 2426 if (errCode) { 2427 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2428 return; 2429 } 2430 console.info('Succeeded in loading the content.'); 2431 }); 2432} catch (exception) { 2433 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2434} 2435``` 2436 2437### setUIContent<sup>9+</sup> 2438 2439setUIContent(path: string): Promise<void> 2440 2441Loads 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. 2442 2443**System capability**: SystemCapability.WindowManager.WindowManager.Core 2444 2445**Atomic service API**: This API can be used in atomic services since API version 11. 2446 2447**Parameters** 2448 2449| Name| Type| Mandatory| Description| 2450| ---- | ------ | -- | ------------------ | 2451| 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.| 2452 2453**Return value** 2454 2455| Type| Description| 2456| ------------------- | ------------------------ | 2457| Promise<void> | Promise that returns no value.| 2458 2459**Error codes** 2460 2461For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2462 2463| ID| Error Message| 2464| ------- | -------------------------------------------- | 2465| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2466| 1300002 | This window state is abnormal. | 2467| 1300003 | This window manager service works abnormally. | 2468 2469**Example** 2470 2471```ts 2472import { BusinessError } from '@kit.BasicServicesKit'; 2473 2474try { 2475 let promise = windowClass.setUIContent('pages/page2/page3'); 2476 promise.then(() => { 2477 console.info('Succeeded in loading the content.'); 2478 }).catch((err: BusinessError) => { 2479 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2480 }); 2481} catch (exception) { 2482 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2483} 2484``` 2485 2486### loadContent<sup>9+</sup> 2487 2488loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 2489 2490Loads 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. 2491 2492**Model restriction**: This API can be used only in the stage model. 2493 2494**System capability**: SystemCapability.WindowManager.WindowManager.Core 2495 2496**Atomic service API**: This API can be used in atomic services since API version 11. 2497 2498**Parameters** 2499 2500| Name | Type | Mandatory| Description | 2501| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 2502| 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.| 2503| 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.| 2504| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 2505 2506**Error codes** 2507 2508For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2509 2510| ID| Error Message| 2511| ------- | -------------------------------------------- | 2512| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2513| 1300002 | This window state is abnormal. | 2514| 1300003 | This window manager service works abnormally. | 2515 2516**Example** 2517 2518```ts 2519import { BusinessError } from '@kit.BasicServicesKit'; 2520 2521let storage: LocalStorage = new LocalStorage(); 2522storage.setOrCreate('storageSimpleProp', 121); 2523windowClass.loadContent('pages/page2', storage, (err: BusinessError) => { 2524 const errCode: number = err.code; 2525 if (errCode) { 2526 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2527 return; 2528 } 2529 console.info('Succeeded in loading the content.'); 2530}); 2531``` 2532 2533### loadContent<sup>9+</sup> 2534 2535loadContent(path: string, storage: LocalStorage): Promise<void> 2536 2537Loads 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. 2538 2539**Model restriction**: This API can be used only in the stage model. 2540 2541**System capability**: SystemCapability.WindowManager.WindowManager.Core 2542 2543**Atomic service API**: This API can be used in atomic services since API version 11. 2544 2545**Parameters** 2546 2547| Name | Type | Mandatory| Description | 2548| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 2549| 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.| 2550| 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.| 2551 2552**Return value** 2553 2554| Type | Description | 2555| ------------------- | ------------------------- | 2556| Promise<void> | Promise that returns no value.| 2557 2558**Error codes** 2559 2560For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2561 2562| ID| Error Message| 2563| ------- | -------------------------------------------- | 2564| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2565| 1300002 | This window state is abnormal. | 2566| 1300003 | This window manager service works abnormally. | 2567 2568**Example** 2569 2570```ts 2571import { BusinessError } from '@kit.BasicServicesKit'; 2572 2573let storage: LocalStorage = new LocalStorage(); 2574storage.setOrCreate('storageSimpleProp', 121); 2575let promise = windowClass.loadContent('pages/page2', storage); 2576promise.then(() => { 2577 console.info('Succeeded in loading the content.'); 2578}).catch((err: BusinessError) => { 2579 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2580}); 2581``` 2582 2583### loadContentByName<sup>11+</sup> 2584 2585loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 2586 2587Loads 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. 2588 2589**Model restriction**: This API can be used only in the stage model. 2590 2591**System capability**: SystemCapability.WindowManager.WindowManager.Core 2592 2593**Atomic service API**: This API can be used in atomic services since API version 11. 2594 2595**Parameters** 2596 2597| Name | Type | Mandatory| Description | 2598| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 2599| name | string | Yes | Name of the named route page. | 2600| 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.| 2601| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 2602 2603**Error codes** 2604 2605For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2606 2607| ID| Error Message | 2608| -------- | --------------------------------------------- | 2609| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2610| 1300002 | This window state is abnormal. | 2611| 1300003 | This window manager service works abnormally. | 2612 2613**Example** 2614<!--code_no_check--> 2615```ts 2616import { BusinessError } from '@kit.BasicServicesKit'; 2617import * as Index from '../pages/Index'; // Import the named route page. 2618 2619console.info('onWindowStageCreate'); 2620let storage: LocalStorage = new LocalStorage(); 2621storage.setOrCreate('storageSimpleProp', 121); 2622try { 2623 (windowClass as window.Window).loadContentByName(Index.entryName, storage, (err: BusinessError) => { 2624 const errCode: number = err.code; 2625 if (errCode) { 2626 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2627 return; 2628 } 2629 console.info('Succeeded in loading the content.'); 2630 }); 2631} catch (exception) { 2632 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2633} 2634``` 2635<!--code_no_check--> 2636```ts 2637// ets/pages/Index.ets 2638export const entryName : string = 'Index'; 2639@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 2640@Component 2641export struct Index { 2642 @State message: string = 'Hello World' 2643 build() { 2644 Row() { 2645 Column() { 2646 Text(this.message) 2647 .fontSize(50) 2648 .fontWeight(FontWeight.Bold) 2649 } 2650 .width('100%') 2651 } 2652 .height('100%') 2653 } 2654} 2655``` 2656 2657### loadContentByName<sup>11+</sup> 2658 2659loadContentByName(name: string, callback: AsyncCallback<void>): void 2660 2661Loads 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. 2662 2663**Model restriction**: This API can be used only in the stage model. 2664 2665**System capability**: SystemCapability.WindowManager.WindowManager.Core 2666 2667**Atomic service API**: This API can be used in atomic services since API version 11. 2668 2669**Parameters** 2670 2671| Name | Type | Mandatory| Description | 2672| -------- | ------------------------- | ---- | ---------------- | 2673| name | string | Yes | Name of the named route page.| 2674| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 2675 2676**Error codes** 2677 2678For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2679 2680| ID| Error Message | 2681| -------- | --------------------------------------------- | 2682| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2683| 1300002 | This window state is abnormal. | 2684| 1300003 | This window manager service works abnormally. | 2685 2686**Example** 2687<!--code_no_check--> 2688```ts 2689import { BusinessError } from '@kit.BasicServicesKit'; 2690import * as Index from '../pages/Index'; // Import the named route page. 2691 2692try { 2693 (windowClass as window.Window).loadContentByName(Index.entryName, (err: BusinessError) => { 2694 const errCode: number = err.code; 2695 if (errCode) { 2696 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2697 return; 2698 } 2699 console.info('Succeeded in loading the content.'); 2700 }); 2701} catch (exception) { 2702 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2703} 2704``` 2705<!--code_no_check--> 2706```ts 2707// ets/pages/Index.ets 2708export const entryName : string = 'Index'; 2709@Entry({routeName: entryName}) 2710@Component 2711export struct Index { 2712 @State message: string = 'Hello World' 2713 build() { 2714 Row() { 2715 Column() { 2716 Text(this.message) 2717 .fontSize(50) 2718 .fontWeight(FontWeight.Bold) 2719 } 2720 .width('100%') 2721 } 2722 .height('100%') 2723 } 2724} 2725``` 2726 2727### loadContentByName<sup>11+</sup> 2728 2729loadContentByName(name: string, storage?: LocalStorage): Promise<void> 2730 2731Loads 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. 2732 2733**Model restriction**: This API can be used only in the stage model. 2734 2735**System capability**: SystemCapability.WindowManager.WindowManager.Core 2736 2737**Atomic service API**: This API can be used in atomic services since API version 11. 2738 2739**Parameters** 2740 2741| Name | Type | Mandatory| Description | 2742| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 2743| name | string | Yes | Name of the named route page. | 2744| 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.| 2745 2746**Return value** 2747 2748| Type | Description | 2749| ------------------- | ------------------------- | 2750| Promise<void> | Promise that returns no value.| 2751 2752**Error codes** 2753 2754For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 2755 2756| ID| Error Message | 2757| -------- | --------------------------------------------- | 2758| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2759| 1300002 | This window state is abnormal. | 2760| 1300003 | This window manager service works abnormally. | 2761 2762**Example** 2763<!--code_no_check--> 2764```ts 2765import { BusinessError } from '@kit.BasicServicesKit'; 2766import * as Index from '../pages/Index'; // Import the named route page. 2767 2768let storage: LocalStorage = new LocalStorage(); 2769storage.setOrCreate('storageSimpleProp', 121); 2770try { 2771 let promise = (windowClass as window.Window).loadContentByName(Index.entryName, storage); 2772 promise.then(() => { 2773 console.info('Succeeded in loading the content.'); 2774 }).catch((err: BusinessError) => { 2775 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2776 }); 2777} catch (exception) { 2778 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2779} 2780``` 2781<!--code_no_check--> 2782```ts 2783// ets/pages/Index.ets 2784export const entryName : string = 'Index'; 2785@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 2786@Component 2787export struct Index { 2788 @State message: string = 'Hello World' 2789 build() { 2790 Row() { 2791 Column() { 2792 Text(this.message) 2793 .fontSize(50) 2794 .fontWeight(FontWeight.Bold) 2795 } 2796 .width('100%') 2797 } 2798 .height('100%') 2799 } 2800} 2801``` 2802 2803### isWindowShowing<sup>9+</sup> 2804 2805isWindowShowing(): boolean 2806 2807Checks whether this window is displayed. 2808 2809**System capability**: SystemCapability.WindowManager.WindowManager.Core 2810 2811**Atomic service API**: This API can be used in atomic services since API version 11. 2812 2813**Return value** 2814 2815| Type| Description| 2816| ------- | ------------------------------------------------------------------ | 2817| boolean | Whether the window is displayed. The value **true** means that the window is displayed, and **false** means the opposite.| 2818 2819**Error codes** 2820 2821For details about the error codes, see [Window Error Codes](errorcode-window.md). 2822 2823| ID| Error Message| 2824| ------- | ------------------------------ | 2825| 1300002 | This window state is abnormal. | 2826 2827**Example** 2828 2829```ts 2830try { 2831 let data = windowClass.isWindowShowing(); 2832 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 2833} catch (exception) { 2834 console.error(`Failed to check whether the window is showing. Cause code: ${exception.code}, message: ${exception.message}`); 2835} 2836``` 2837 2838### on('windowSizeChange')<sup>7+</sup> 2839 2840on(type: 'windowSizeChange', callback: Callback<Size>): void 2841 2842Subscribes to the window size change event. 2843 2844**System capability**: SystemCapability.WindowManager.WindowManager.Core 2845 2846**Atomic service API**: This API can be used in atomic services since API version 11. 2847 2848**Parameters** 2849 2850| Name | Type | Mandatory| Description | 2851| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 2852| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 2853| callback | Callback<[Size](#size7)> | Yes | Callback used to return the window size. | 2854 2855**Error codes** 2856 2857For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2858 2859| ID| Error Message| 2860| ------- | -------------------------------------------- | 2861| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2862 2863**Example** 2864 2865```ts 2866try { 2867 windowClass.on('windowSizeChange', (data) => { 2868 console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data)); 2869 }); 2870} catch (exception) { 2871 console.error(`Failed to enable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 2872} 2873``` 2874 2875### off('windowSizeChange')<sup>7+</sup> 2876 2877off(type: 'windowSizeChange', callback?: Callback<Size>): void 2878 2879Unsubscribes from the window size change event. 2880 2881**System capability**: SystemCapability.WindowManager.WindowManager.Core 2882 2883**Atomic service API**: This API can be used in atomic services since API version 11. 2884 2885**Parameters** 2886 2887| Name | Type | Mandatory| Description | 2888| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 2889| type | string | Yes | Event type. The value is fixed at **'windowSizeChange'**, indicating the window size change event.| 2890| 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. | 2891 2892**Error codes** 2893 2894For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2895 2896| ID| Error Message| 2897| ------- | -------------------------------------------- | 2898| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 2899 2900**Example** 2901 2902```ts 2903const callback = (size: window.Size) => { 2904 // ... 2905} 2906try { 2907 // Enable listening through the on API. 2908 windowClass.on('windowSizeChange', callback); 2909 // Disable the listening of a specified callback. 2910 windowClass.off('windowSizeChange', callback); 2911 // Unregister all the callbacks that have been registered through on(). 2912 windowClass.off('windowSizeChange'); 2913} catch (exception) { 2914 console.error(`Failed to disable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 2915} 2916``` 2917 2918### on('avoidAreaChange')<sup>9+</sup> 2919 2920on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void 2921 2922Subscribes to the event indicating changes to the area where this window cannot be displayed. 2923 2924**System capability**: SystemCapability.WindowManager.WindowManager.Core 2925 2926**Atomic service API**: This API can be used in atomic services since API version 11. 2927 2928**Parameters** 2929 2930| Name | Type | Mandatory| Description | 2931| -------- |----------------------------------| ---- |--------------------------------------| 2932| 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.| 2933| callback | Callback<[AvoidAreaOptions](#avoidareaoptions12)> | Yes | Callback used to return the area and area type.| 2934 2935**Error codes** 2936 2937For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2938 2939| ID| Error Message| 2940| ------- | -------------------------------------------- | 2941| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2942 2943**Example** 2944 2945```ts 2946try { 2947 windowClass.on('avoidAreaChange', (data) => { 2948 console.info('Succeeded in enabling the listener for system avoid area changes. type:' + 2949 JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area)); 2950 }); 2951} catch (exception) { 2952 console.error(`Failed to enable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 2953} 2954``` 2955 2956### off('avoidAreaChange')<sup>9+</sup> 2957 2958off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaOptions>): void 2959 2960Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 2961 2962**System capability**: SystemCapability.WindowManager.WindowManager.Core 2963 2964**Atomic service API**: This API can be used in atomic services since API version 11. 2965 2966**Parameters** 2967 2968| Name | Type | Mandatory| Description | 2969| -------- |----------------------------------|------|------------------------------------| 2970| 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.| 2971| 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.| 2972 2973**Error codes** 2974 2975For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2976 2977| ID| Error Message| 2978| ------- | -------------------------------------------- | 2979| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 2980 2981**Example** 2982 2983```ts 2984interface Param { 2985 type: window.AvoidAreaType, 2986 area: window.AvoidArea 2987} 2988const callback = (data: Param) => { 2989 // ... 2990} 2991try { 2992 windowClass.on('avoidAreaChange', callback); 2993 2994 windowClass.off('avoidAreaChange', callback); 2995 // Unregister all the callbacks that have been registered through on(). 2996 windowClass.off('avoidAreaChange'); 2997} catch (exception) { 2998 console.error(`Failed to enable or disable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 2999} 3000``` 3001 3002### on('keyboardHeightChange')<sup>7+</sup> 3003 3004on(type: 'keyboardHeightChange', callback: Callback<number>): void 3005 3006Subscribes to the event indicating soft keyboard height changes in fixed state. 3007 3008The system notifies the keyboard height change when the soft keyboard is invoked by the window and overlaps with the window. 3009 3010Since 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). 3011 3012**Atomic service API**: This API can be used in atomic services since API version 12. 3013 3014**System capability**: SystemCapability.WindowManager.WindowManager.Core 3015 3016**Parameters** 3017 3018| Name | Type | Mandatory| Description | 3019| -------- | ------------------- | ---- |-------------------------------------------| 3020| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 3021| callback | Callback<number> | Yes | Callback used to return the current keyboard height, which is an integer, in px. | 3022 3023**Error codes** 3024 3025For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3026 3027| ID| Error Message| 3028| ------- | -------------------------------------------- | 3029| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3030 3031**Example** 3032 3033```ts 3034import { BusinessError } from '@kit.BasicServicesKit'; 3035 3036try { 3037 windowClass.on('keyboardHeightChange', (data) => { 3038 console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data)); 3039 }); 3040} catch (exception) { 3041 console.error(`Failed to enable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 3042} 3043``` 3044 3045### off('keyboardHeightChange')<sup>7+</sup> 3046 3047off(type: 'keyboardHeightChange', callback?: Callback<number>): void 3048 3049Unsubscribes from the event indicating soft keyboard height changes in fixed state. 3050 3051Since 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). 3052 3053**Atomic service API**: This API can be used in atomic services since API version 12. 3054 3055**System capability**: SystemCapability.WindowManager.WindowManager.Core 3056 3057**Parameters** 3058 3059| Name | Type | Mandatory| Description | 3060| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3061| type | string | Yes | Event type. The value is fixed at **'keyboardHeightChange'**, indicating the keyboard height change event.| 3062| 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. | 3063 3064**Error codes** 3065 3066For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3067 3068| ID| Error Message| 3069| ------- | -------------------------------------------- | 3070| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3071 3072**Example** 3073 3074```ts 3075import { BusinessError } from '@kit.BasicServicesKit'; 3076 3077const callback = (height: number) => { 3078 // ... 3079} 3080try { 3081 windowClass.on('keyboardHeightChange', callback); 3082 3083 windowClass.off('keyboardHeightChange', callback); 3084 // Unregister all the callbacks that have been registered through on(). 3085 windowClass.off('keyboardHeightChange'); 3086} catch (exception) { 3087 console.error(`Failed to disable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 3088} 3089``` 3090 3091### on('touchOutside')<sup>11+</sup> 3092 3093on(type: 'touchOutside', callback: Callback<void>): void 3094 3095Subscribes to the touch event outside this window. 3096 3097**System capability**: SystemCapability.WindowManager.WindowManager.Core 3098 3099**Atomic service API**: This API can be used in atomic services since API version 11. 3100 3101**Parameters** 3102 3103| Name | Type | Mandatory| Description | 3104| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3105| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 3106| callback | Callback<void> | Yes | Callback used to return the touch event outside this window. | 3107 3108**Error codes** 3109 3110For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3111 3112| ID| Error Message| 3113| ------- | -------------------------------------------- | 3114| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3115 3116**Example** 3117 3118```ts 3119try { 3120 windowClass.on('touchOutside', () => { 3121 console.info('touch outside'); 3122 }); 3123} catch (exception) { 3124 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3125} 3126``` 3127 3128### off('touchOutside')<sup>11+</sup> 3129 3130off(type: 'touchOutside', callback?: Callback<void>): void 3131 3132Unsubscribes from the touch event outside this window. 3133 3134**System capability**: SystemCapability.WindowManager.WindowManager.Core 3135 3136**Atomic service API**: This API can be used in atomic services since API version 11. 3137 3138**Parameters** 3139 3140| Name | Type | Mandatory| Description | 3141| -------- |----------------------| ---- |--------------------------------------| 3142| type | string | Yes | Event type. The value is fixed at **'touchOutside'**, indicating the touch event outside this window.| 3143| 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. | 3144 3145**Error codes** 3146 3147For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3148 3149| ID| Error Message| 3150| ------- | -------------------------------------------- | 3151| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3152 3153**Example** 3154 3155```ts 3156const callback = () => { 3157 // ... 3158} 3159try { 3160 windowClass.on('touchOutside', callback); 3161 windowClass.off('touchOutside', callback); 3162 // Unregister all the callbacks that have been registered through on(). 3163 windowClass.off('touchOutside'); 3164} catch (exception) { 3165 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3166} 3167``` 3168 3169### on('screenshot')<sup>9+</sup> 3170 3171on(type: 'screenshot', callback: Callback<void>): void 3172 3173Subscribes to the screenshot event. 3174 3175**Atomic service API**: This API can be used in atomic services since API version 12. 3176 3177**System capability**: SystemCapability.WindowManager.WindowManager.Core 3178 3179**Parameters** 3180 3181| Name | Type | Mandatory| Description | 3182| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3183| 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.| 3184| callback | Callback<void> | Yes | Callback invoked when a screenshot event occurs. | 3185 3186**Error codes** 3187 3188For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3189 3190| ID| Error Message| 3191| ------- | -------------------------------------------- | 3192| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3193 3194**Example** 3195 3196```ts 3197try { 3198 windowClass.on('screenshot', () => { 3199 console.info('screenshot happened'); 3200 }); 3201} catch (exception) { 3202 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3203} 3204``` 3205 3206### off('screenshot')<sup>9+</sup> 3207 3208off(type: 'screenshot', callback?: Callback<void>): void 3209 3210Unsubscribes from the screenshot event. 3211 3212**Atomic service API**: This API can be used in atomic services since API version 12. 3213 3214**System capability**: SystemCapability.WindowManager.WindowManager.Core 3215 3216**Parameters** 3217 3218| Name | Type | Mandatory| Description | 3219| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3220| type | string | Yes | Event type. The value is fixed at **'screenshot'**, indicating the screenshot event.| 3221| 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.| 3222 3223**Error codes** 3224 3225For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3226 3227| ID| Error Message| 3228| ------- | -------------------------------------------- | 3229| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3230 3231**Example** 3232 3233```ts 3234let callback = () => { 3235 console.info('screenshot happened'); 3236}; 3237try { 3238 windowClass.on('screenshot', callback); 3239 windowClass.off('screenshot', callback); 3240 // Unregister all the callbacks that have been registered through on(). 3241 windowClass.off('screenshot'); 3242} catch (exception) { 3243 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3244} 3245``` 3246 3247### on('dialogTargetTouch')<sup>10+</sup> 3248 3249on(type: 'dialogTargetTouch', callback: Callback<void>): void 3250 3251Subscribes 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. 3252 3253**Atomic service API**: This API can be used in atomic services since API version 12. 3254 3255**System capability**: SystemCapability.WindowManager.WindowManager.Core 3256 3257**Parameters** 3258 3259| Name | Type | Mandatory| Description | 3260| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3261| 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.| 3262| callback | Callback<void>| Yes | Callback invoked when a click or touch event occurs in the window covered by the modal window.| 3263 3264**Error codes** 3265 3266For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3267 3268| ID| Error Message| 3269| ------- | -------------------------------------------- | 3270| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3271 3272**Example** 3273 3274```ts 3275try { 3276 windowClass.on('dialogTargetTouch', () => { 3277 console.info('touch dialog target'); 3278 }); 3279} catch (exception) { 3280 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3281} 3282``` 3283 3284### off('dialogTargetTouch')<sup>10+</sup> 3285 3286off(type: 'dialogTargetTouch', callback?: Callback<void>): void 3287 3288Unsubscribes from the touch event of the target window in the modal window mode. 3289 3290**Atomic service API**: This API can be used in atomic services since API version 12. 3291 3292**System capability**: SystemCapability.WindowManager.WindowManager.Core 3293 3294**Parameters** 3295 3296| Name | Type | Mandatory| Description | 3297| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3298| type | string | Yes | Event type. The value is fixed at **'dialogTargetTouch'**, indicating the touch event of the target window in the modal window mode.| 3299| 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.| 3300 3301**Error codes** 3302 3303For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3304 3305| ID| Error Message| 3306| ------- | -------------------------------------------- | 3307| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3308 3309**Example** 3310 3311```ts 3312const callback = () => { 3313 // ... 3314} 3315try { 3316 windowClass.on('dialogTargetTouch', callback); 3317 windowClass.off('dialogTargetTouch', callback); 3318 // Unregister all the callbacks that have been registered through on(). 3319 windowClass.off('dialogTargetTouch'); 3320} catch (exception) { 3321 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3322} 3323``` 3324 3325### on('windowEvent')<sup>10+</sup> 3326 3327on(type: 'windowEvent', callback: Callback<WindowEventType>): void 3328 3329Subscribes to the window lifecycle change event. 3330 3331**System capability**: SystemCapability.WindowManager.WindowManager.Core 3332 3333**Atomic service API**: This API can be used in atomic services since API version 11. 3334 3335**Parameters** 3336 3337| Name | Type | Mandatory| Description | 3338| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3339| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 3340| callback | Callback<[WindowEventType](#windoweventtype10)> | Yes | Callback used to return the window lifecycle state. | 3341 3342**Error codes** 3343 3344For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3345 3346| ID| Error Message| 3347| ------- | -------------------------------------------- | 3348| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3349 3350**Example** 3351 3352```ts 3353try { 3354 windowClass.on('windowEvent', (data) => { 3355 console.info('Window event happened. Event:' + JSON.stringify(data)); 3356 }); 3357} catch (exception) { 3358 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3359} 3360``` 3361 3362### off('windowEvent')<sup>10+</sup> 3363 3364off(type: 'windowEvent', callback?: Callback<WindowEventType>): void 3365 3366Unsubscribes from the window lifecycle change event. 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**Parameters** 3373 3374| Name | Type | Mandatory| Description | 3375| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3376| type | string | Yes | Event type. The value is fixed at **'windowEvent'**, indicating the window lifecycle change event.| 3377| 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. | 3378 3379**Error codes** 3380 3381For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3382 3383| ID| Error Message| 3384| ------- | -------------------------------------------- | 3385| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3386 3387**Example** 3388 3389```ts 3390const callback = (windowEventType: window.WindowEventType) => { 3391 // ... 3392} 3393try { 3394 // Enable listening through the on API. 3395 windowClass.on('windowEvent', callback); 3396 // Disable the listening of a specified callback. 3397 windowClass.off('windowEvent', callback); 3398 // Unregister all the callbacks that have been registered through on(). 3399 windowClass.off('windowEvent'); 3400} catch (exception) { 3401 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3402} 3403``` 3404 3405### on('windowVisibilityChange')<sup>11+</sup> 3406 3407on(type: 'windowVisibilityChange', callback: Callback<boolean>): void 3408 3409Subscribes to the visibility status change event of this window. 3410 3411**Atomic service API**: This API can be used in atomic services since API version 12. 3412 3413**System capability**: SystemCapability.Window.SessionManager 3414 3415**Parameters** 3416 3417| Name | Type | Mandatory| Description | 3418| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3419| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 3420| 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. | 3421 3422**Error codes** 3423 3424For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3425 3426| ID| Error Message| 3427| ------- | ------------------------------ | 3428| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3429| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3430| 1300002 | This window state is abnormal. | 3431| 1300003 | This window manager service works abnormally. | 3432 3433**Example** 3434 3435```ts 3436try { 3437 windowClass.on('windowVisibilityChange', (boolean) => { 3438 console.info('Window visibility changed, isVisible=' + boolean); 3439 }); 3440} catch (exception) { 3441 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3442} 3443``` 3444 3445### off('windowVisibilityChange')<sup>11+</sup> 3446 3447off(type: 'windowVisibilityChange', callback?: Callback<boolean>): void 3448 3449Unsubscribes from the visibility status change event of this window. 3450 3451**Atomic service API**: This API can be used in atomic services since API version 12. 3452 3453**System capability**: SystemCapability.Window.SessionManager 3454 3455**Parameters** 3456 3457| Name | Type | Mandatory| Description | 3458| -------- |----------------------------| ---- |--------------------------------------| 3459| type | string | Yes | Event type. The value is fixed at **'windowVisibilityChange'**, indicating the visibility status change event.| 3460| 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. | 3461 3462**Error codes** 3463 3464For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3465 3466| ID| Error Message| 3467| ------- | ------------------------------ | 3468| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3469| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3470| 1300002 | This window state is abnormal. | 3471| 1300003 | This window manager service works abnormally. | 3472 3473**Example** 3474 3475```ts 3476const callback = (bool: boolean) => { 3477 // ... 3478} 3479try { 3480 // Enable listening through the on API. 3481 windowClass.on('windowVisibilityChange', callback); 3482 // Disable the listening of a specified callback. 3483 windowClass.off('windowVisibilityChange', callback); 3484 // Unregister all the callbacks that have been registered through on(). 3485 windowClass.off('windowVisibilityChange'); 3486} catch (exception) { 3487 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3488} 3489``` 3490 3491### on('noInteractionDetected')<sup>12+</sup> 3492 3493on(type: 'noInteractionDetected', timeout: number, callback: Callback<void>): void 3494 3495Subscribes to non-interaction events in a window within the specified period. 3496 3497Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 3498 3499**Atomic service API**: This API can be used in atomic services since API version 12. 3500 3501**System capability**: SystemCapability.Window.SessionManager 3502 3503**Parameters** 3504 3505| Name | Type | Mandatory| Description | 3506| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3507| 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.| 3508| timeout | number | Yes | Period during which no interaction is performed, in seconds. The value must be an integer. Negative numbers and decimals are invalid.| 3509| callback | Callback<void> | Yes | Callback invoked when there is no interaction event in the current window within the specified period. | 3510 3511**Error codes** 3512 3513For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3514 3515| ID| Error Message| 3516| ------- | ------------------------------ | 3517| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3518| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3519| 1300002 | This window state is abnormal. | 3520| 1300003 | This window manager service works abnormally. | 3521 3522**Example** 3523 3524```ts 3525try { 3526 windowClass.on('noInteractionDetected', 60, () => { 3527 console.info('no interaction in 60s'); 3528 }); 3529} catch (exception) { 3530 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3531} 3532``` 3533 3534### off('noInteractionDetected')<sup>12+</sup> 3535 3536off(type: 'noInteractionDetected', callback?: Callback<void>): void 3537 3538Unsubscribes from non-interaction events in a window within the specified period. 3539 3540Interaction events include physical keyboard input events and screen touch/click events, but not soft keyboard input events. 3541 3542**Atomic service API**: This API can be used in atomic services since API version 12. 3543 3544**System capability**: SystemCapability.Window.SessionManager 3545 3546**Parameters** 3547 3548| Name | Type | Mandatory| Description | 3549| -------- |----------------------------| ---- |--------------------------------------| 3550| 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.| 3551| 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.| 3552 3553**Error codes** 3554 3555For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3556 3557| ID| Error Message| 3558| ------- | ------------------------------ | 3559| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3560| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3561| 1300002 | This window state is abnormal. | 3562| 1300003 | This window manager service works abnormally. | 3563 3564**Example** 3565 3566```ts 3567const callback = () => { 3568 // ... 3569} 3570try { 3571 windowClass.on('noInteractionDetected', 60, callback); 3572 windowClass.off('noInteractionDetected', callback); 3573 // Unregister all the callbacks that have been registered through on(). 3574 windowClass.off('noInteractionDetected'); 3575} catch (exception) { 3576 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3577} 3578``` 3579 3580### on('windowStatusChange')<sup>11+</sup> 3581 3582on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void 3583 3584Subscribes to the window status change event. 3585 3586**Atomic service API**: This API can be used in atomic services since API version 12. 3587 3588**System capability**: SystemCapability.Window.SessionManager 3589 3590**Parameters** 3591 3592| Name | Type | Mandatory| Description | 3593| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 3594| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 3595| callback | Callback<[WindowStatusType](#windowstatustype11)> | Yes | Callback used to return the window status. | 3596 3597**Error codes** 3598 3599For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3600 3601| ID| Error Message| 3602| ------- | ------------------------------ | 3603| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3604| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3605 3606**Example** 3607 3608```ts 3609try { 3610 windowClass.on('windowStatusChange', (WindowStatusType) => { 3611 console.info('Succeeded in enabling the listener for window status changes. Data: ' + JSON.stringify(WindowStatusType)); 3612 }); 3613} catch (exception) { 3614 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3615} 3616``` 3617 3618### off('windowStatusChange')<sup>11+</sup> 3619 3620off(type: 'windowStatusChange', callback?: Callback<WindowStatusType>): void 3621 3622Unsubscribes from the window status change event. 3623 3624**Atomic service API**: This API can be used in atomic services since API version 12. 3625 3626**System capability**: SystemCapability.Window.SessionManager 3627 3628**Parameters** 3629 3630| Name | Type | Mandatory| Description | 3631| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 3632| type | string | Yes | Event type. The value is fixed at **'windowStatusChange'**, indicating the window status change event.| 3633| 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. | 3634 3635**Error codes** 3636 3637For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3638 3639| ID| Error Message| 3640| ------- | ------------------------------ | 3641| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3642| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3643 3644**Example** 3645 3646```ts 3647const callback = (windowStatusType: window.WindowStatusType) => { 3648 // ... 3649} 3650try { 3651 windowClass.on('windowStatusChange', callback); 3652 windowClass.off('windowStatusChange', callback); 3653 // Unregister all the callbacks that have been registered through on(). 3654 windowClass.off('windowStatusChange'); 3655} catch (exception) { 3656 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3657} 3658``` 3659 3660### setWindowGrayScale<sup>12+</sup> 3661 3662setWindowGrayScale(grayScale: number): Promise<void> 3663 3664Sets 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. 3665 3666**Atomic service API**: This API can be used in atomic services since API version 12. 3667 3668**System capability**: SystemCapability.Window.SessionManager 3669 3670**Parameters** 3671 3672| Name| Type| Mandatory| Description | 3673| --------- | ------ | -- | ---------------------------------------- | 3674| 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.| 3675 3676**Return value** 3677 3678| Type| Description| 3679| ------------------- | ------------------------ | 3680| Promise<void> | Promise that returns no value.| 3681 3682**Error codes** 3683 3684For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3685 3686| ID| Error Message| 3687| ------- | --------------------------------------------- | 3688| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3689| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3690| 1300002 | This window state is abnormal. | 3691| 1300003 | This window manager service works abnormally. | 3692 3693**Example** 3694 3695```ts 3696import { BusinessError } from '@kit.BasicServicesKit'; 3697 3698windowClass?.setUIContent('pages/Index', (error: BusinessError) => { 3699 if (error.code) { 3700 console.error(`Failed to set the content. Cause code: ${error.code}`); 3701 return; 3702 } 3703 console.info('Succeeded in setting the content.'); 3704 let grayScale: number = 0.5; 3705 try { 3706 if (canIUse("SystemCapability.Window.SessionManager")) { 3707 let promise = windowClass?.setWindowGrayScale(grayScale); 3708 promise?.then(() => { 3709 console.info('Succeeded in setting the grayScale.'); 3710 }).catch((err: BusinessError) => { 3711 console.error(`Failed to set the grayScale. Cause code: ${err.code}, message: ${err.message}`); 3712 }); 3713 } 3714 } catch (exception) { 3715 console.error(`Failed to set the grayScale. Cause code: ${exception.code}, message: ${exception.message}`); 3716 } 3717}); 3718``` 3719 3720### on('windowTitleButtonRectChange')<sup>11+</sup> 3721 3722on(type: 'windowTitleButtonRectChange', callback: Callback<TitleButtonRect>): void 3723 3724Subscribes to the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 3725 3726**Atomic service API**: This API can be used in atomic services since API version 12. 3727 3728**System capability**: SystemCapability.Window.SessionManager 3729 3730**Parameters** 3731 3732| Name | Type | Mandatory| Description | 3733| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 3734| 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.| 3735| callback | Callback<[TitleButtonRect](#titlebuttonrect11)> | Yes | Callback used to return the new rectangle.| 3736 3737**Error codes** 3738 3739For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3740 3741| ID| Error Message | 3742| -------- | ------------------------------ | 3743| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3744| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3745| 1300002 | This window state is abnormal. | 3746 3747**Example** 3748 3749```ts 3750windowClass.setUIContent('pages/WindowPage').then(() => { 3751 try { 3752 windowClass?.on('windowTitleButtonRectChange', (titleButtonRect) => { 3753 console.info('Succeeded in enabling the listener for window title buttons area changes. Data: ' + JSON.stringify(titleButtonRect)); 3754 }); 3755 } catch (exception) { 3756 console.error(`Failed to enable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 3757 } 3758}) 3759``` 3760 3761### off('windowTitleButtonRectChange')<sup>11+</sup> 3762 3763off(type: 'windowTitleButtonRectChange', callback?: Callback<TitleButtonRect>): void 3764 3765Unsubscribes from the change event of the rectangle that holds the minimize, maximize, and close buttons on the title bar of the window. This API takes effect for the window that has a title bar or a three-button area on 2-in-1 devices. In the stage model, this API must be used after the call of [loadContent](#loadcontent9) or [setUIContent()](#setuicontent9) takes effect. 3766 3767**Atomic service API**: This API can be used in atomic services since API version 12. 3768 3769**System capability**: SystemCapability.Window.SessionManager 3770 3771**Parameters** 3772 3773| Name | Type | Mandatory| Description | 3774| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 3775| 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.| 3776| 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.| 3777 3778**Error codes** 3779 3780For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3781 3782| ID| Error Message | 3783| -------- | ------------------------------ | 3784| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3785| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3786| 1300002 | This window state is abnormal. | 3787 3788**Example** 3789 3790```ts 3791windowClass.setUIContent('pages/WindowPage').then(() => { 3792 const callback = (titleButtonRect: window.TitleButtonRect) => { 3793 // ... 3794 } 3795 try { 3796 // Enable listening through the on API. 3797 windowClass?.on('windowTitleButtonRectChange', callback); 3798 // Disable the listening of a specified callback. 3799 windowClass?.off('windowTitleButtonRectChange', callback); 3800 // Unregister all the callbacks that have been registered through on(). 3801 windowClass?.off('windowTitleButtonRectChange'); 3802 } catch (exception) { 3803 console.error(`Failed to disable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 3804 } 3805}) 3806``` 3807 3808### on('windowRectChange')<sup>12+</sup> 3809 3810on(type: 'windowRectChange', callback: Callback<RectChangeOptions>): void 3811 3812Subscribes to window rectangle (position and size) change events. 3813 3814**System capability**: SystemCapability.Window.SessionManager 3815 3816**Atomic service API**: This API can be used in atomic services since API version 12. 3817 3818**Parameters** 3819 3820| Name | Type | Mandatory| Description | 3821| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 3822| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event.| 3823| callback | Callback<[RectChangeOptions](#rectchangeoptions12)> | Yes | Callback used to return the value and reason of the window rectangle change. | 3824 3825**Error codes** 3826 3827For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3828 3829| ID| Error Message| 3830| ------- | -------------------------------------------- | 3831| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3832| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3833| 1300002 | This window state is abnormal. | 3834| 1300003 | This window manager service works abnormally. | 3835 3836**Example** 3837 3838```ts 3839windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 3840 console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data)); 3841}); 3842``` 3843 3844### off('windowRectChange')<sup>12+</sup> 3845 3846off(type: 'windowRectChange', callback?: Callback<RectChangeOptions>): void 3847 3848Unsubscribes from window rectangle (position and size) change events. 3849 3850**System capability**: SystemCapability.Window.SessionManager 3851 3852**Atomic service API**: This API can be used in atomic services since API version 12. 3853 3854**Parameters** 3855 3856| Name | Type | Mandatory| Description | 3857| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 3858| type | string | Yes | Event type. The value is fixed at **'windowRectChange'**, indicating the window rectangle change event. | 3859| 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.| 3860 3861**Error codes** 3862 3863For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3864 3865| ID| Error Message| 3866| ------- | -------------------------------------------- | 3867| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3868| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3869| 1300002 | This window state is abnormal. | 3870| 1300003 | This window manager service works abnormally. | 3871 3872**Example** 3873 3874```ts 3875const callback = (rectChangeOptions: window.RectChangeOptions) => { 3876 // ... 3877} 3878windowClass.on('windowRectChange', callback); 3879windowClass.off('windowRectChange', callback); 3880// Unregister all the callbacks that have been registered through on(). 3881windowClass.off('windowRectChange'); 3882``` 3883 3884### on('subWindowClose')<sup>12+</sup> 3885 3886on(type: 'subWindowClose', callback: Callback<void>): void 3887 3888Subscribes to the event indicating that the subwindow is closed. This event is triggered only when the user touches the close button in the upper right corner provided by the system to close the subwindow. It is not triggered when the subwindow is closed in other ways. 3889 3890**Atomic service API**: This API can be used in atomic services since API version 12. 3891 3892**System capability**: SystemCapability.Window.SessionManager 3893 3894**Parameters** 3895 3896| Name | Type | Mandatory| Description | 3897| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 3898| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the subwindow close event.| 3899| callback | Callback<void> | Yes | Callback invoked when the close button in the upper right corner of the subwindow is touched. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the subwindow. The value **true** means not to close the subwindow, and **false** means to continue to close the subwindow. | 3900 3901**Error codes** 3902 3903For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3904 3905| ID| Error Message| 3906| ------- | -------------------------------------------- | 3907| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3908| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3909| 1300002 | This window state is abnormal. | 3910| 1300004 | Unauthorized operation. | 3911 3912**Example** 3913 3914```ts 3915const callback = () => { 3916 // ... 3917 return true; 3918} 3919try { 3920 windowClass.on('subWindowClose', callback); 3921} catch (exception) { 3922 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3923} 3924``` 3925 3926### off('subWindowClose')<sup>12+</sup> 3927 3928off(type: 'subWindowClose', callback?: Callback<void>): void 3929 3930Unsubscribes from the event indicating that the subwindow is closed. 3931 3932**Atomic service API**: This API can be used in atomic services since API version 12. 3933 3934**System capability**: SystemCapability.Window.SessionManager 3935 3936**Parameters** 3937 3938| Name | Type | Mandatory| Description | 3939| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 3940| type | string | Yes | Event type. The value is fixed at **'subWindowClose'**, indicating the subwindow close event. | 3941| callback | Callback<void> | No | Callback invoked when the close button in the upper right corner of the subwindow is touched. It does not return any parameter. The internal logic of the callback function requires a return value of the Boolean type. The return value determines whether to continue to close the subwindow. The value **true** means not to close the subwindow, and **false** means to continue to close the subwindow. If a value is passed in, the corresponding subscription is canceled. If no value is passed in, all subscriptions to the specified event are canceled.| 3942 3943**Error codes** 3944 3945For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 3946 3947| ID| Error Message| 3948| ------- | -------------------------------------------- | 3949| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3950| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3951| 1300002 | This window state is abnormal. | 3952| 1300004 | Unauthorized operation. | 3953 3954**Example** 3955 3956```ts 3957const callback = () => { 3958 // ... 3959 return true; 3960} 3961try { 3962 windowClass.on('subWindowClose', callback); 3963 windowClass.off('subWindowClose', callback); 3964 // Unregister all the callbacks that have been registered through on(). 3965 windowClass.off('subWindowClose'); 3966} catch (exception) { 3967 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3968} 3969``` 3970 3971### isWindowSupportWideGamut<sup>9+</sup> 3972 3973isWindowSupportWideGamut(callback: AsyncCallback<boolean>): void 3974 3975Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 3976 3977**Atomic service API**: This API can be used in atomic services since API version 12. 3978 3979**System capability**: SystemCapability.WindowManager.WindowManager.Core 3980 3981**Parameters** 3982 3983| Name| Type| Mandatory| Description| 3984| -------- | ---------------------------- | -- | -------------------------------------------------------------------------------- | 3985| 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.| 3986 3987**Error codes** 3988 3989For details about the error codes, see [Window Error Codes](errorcode-window.md). 3990 3991| ID| Error Message| 3992| ------- | ------------------------------ | 3993| 1300002 | This window state is abnormal. | 3994 3995**Example** 3996 3997```ts 3998import { BusinessError } from '@kit.BasicServicesKit'; 3999 4000windowClass.isWindowSupportWideGamut((err: BusinessError, data) => { 4001 const errCode: number = err.code; 4002 if (errCode) { 4003 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 4004 return; 4005 } 4006 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 4007}); 4008``` 4009 4010### isWindowSupportWideGamut<sup>9+</sup> 4011 4012isWindowSupportWideGamut(): Promise<boolean> 4013 4014Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 4015 4016**Atomic service API**: This API can be used in atomic services since API version 12. 4017 4018**System capability**: SystemCapability.WindowManager.WindowManager.Core 4019 4020**Return value** 4021 4022| Type| Description| 4023| ---------------------- | ------------------------------------------------------------------------------------ | 4024| 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.| 4025 4026**Error codes** 4027 4028For details about the error codes, see [Window Error Codes](errorcode-window.md). 4029 4030| ID| Error Message| 4031| ------- | ------------------------------ | 4032| 1300002 | This window state is abnormal. | 4033 4034**Example** 4035 4036```ts 4037import { BusinessError } from '@kit.BasicServicesKit'; 4038 4039let promise = windowClass.isWindowSupportWideGamut(); 4040promise.then((data) => { 4041 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 4042}).catch((err: BusinessError) => { 4043 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 4044}); 4045``` 4046 4047### setWindowColorSpace<sup>9+</sup> 4048 4049setWindowColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 4050 4051Sets a color space for this window. This API uses an asynchronous callback to return the result. 4052 4053**Atomic service API**: This API can be used in atomic services since API version 12. 4054 4055**System capability**: SystemCapability.WindowManager.WindowManager.Core 4056 4057**Parameters** 4058 4059| Name| Type| Mandatory| Description| 4060| ---------- | ------------------------- | -- | ----------- | 4061| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 4062| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4063 4064**Error codes** 4065 4066For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4067 4068| ID| Error Message| 4069| ------- | ------------------------------ | 4070| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4071| 1300002 | This window state is abnormal. | 4072 4073**Example** 4074 4075```ts 4076import { BusinessError } from '@kit.BasicServicesKit'; 4077 4078try { 4079 windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 4080 const errCode: number = err.code; 4081 if (errCode) { 4082 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 4083 return; 4084 } 4085 console.info('Succeeded in setting window colorspace.'); 4086 }); 4087} catch (exception) { 4088 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 4089} 4090``` 4091 4092### setWindowColorSpace<sup>9+</sup> 4093 4094setWindowColorSpace(colorSpace:ColorSpace): Promise<void> 4095 4096Sets a color space for this window. This API uses a promise to return the result. 4097 4098**Atomic service API**: This API can be used in atomic services since API version 12. 4099 4100**System capability**: SystemCapability.WindowManager.WindowManager.Core 4101 4102**Parameters** 4103 4104| Name| Type| Mandatory| Description| 4105| ---------- | ------------------------- | -- | ------------- | 4106| colorSpace | [ColorSpace](#colorspace8) | Yes| Color space to set.| 4107 4108**Return value** 4109 4110| Type| Description| 4111| ------------------- | ------------------------ | 4112| Promise<void> | Promise that returns no value.| 4113 4114**Error codes** 4115 4116For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4117 4118| ID| Error Message| 4119| ------- | ------------------------------ | 4120| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4121| 1300002 | This window state is abnormal. | 4122 4123**Example** 4124 4125```ts 4126import { BusinessError } from '@kit.BasicServicesKit'; 4127 4128try { 4129 let promise = windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT); 4130 promise.then(() => { 4131 console.info('Succeeded in setting window colorspace.'); 4132 }).catch((err: BusinessError) => { 4133 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 4134 }); 4135} catch (exception) { 4136 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 4137} 4138``` 4139 4140### getWindowColorSpace<sup>9+</sup> 4141 4142getWindowColorSpace(): ColorSpace 4143 4144Obtains the color space of this window. 4145 4146**Atomic service API**: This API can be used in atomic services since API version 12. 4147 4148**System capability**: SystemCapability.WindowManager.WindowManager.Core 4149 4150**Return value** 4151 4152| Type| Description| 4153| ------------------------- | ------------- | 4154| [ColorSpace](#colorspace8) | Color space obtained.| 4155 4156**Error codes** 4157 4158For details about the error codes, see [Window Error Codes](errorcode-window.md). 4159 4160| ID| Error Message| 4161| ------- | ------------------------------ | 4162| 1300002 | This window state is abnormal. | 4163 4164**Example** 4165 4166```ts 4167let colorSpace = windowClass.getWindowColorSpace(); 4168``` 4169 4170### setWindowBackgroundColor<sup>9+</sup> 4171 4172setWindowBackgroundColor(color: string): void 4173 4174Sets 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. 4175 4176**System capability**: SystemCapability.WindowManager.WindowManager.Core 4177 4178**Atomic service API**: This API can be used in atomic services since API version 11. 4179 4180**Parameters** 4181 4182| Name| Type| Mandatory| Description| 4183| ----- | ------ | -- | ----------------------------------------------------------------------- | 4184| 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'**.| 4185 4186**Error codes** 4187 4188For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4189 4190| ID| Error Message| 4191| ------- | ------------------------------ | 4192| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4193| 1300002 | This window state is abnormal. | 4194 4195**Example** 4196 4197```ts 4198import { BusinessError } from '@kit.BasicServicesKit'; 4199 4200private SetUIContent(windowClass: window.Window) { 4201 windowClass.setUIContent("pages/ButtonWindow",(err: BusinessError) => { 4202 if (err.code) { 4203 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 4204 return; 4205 } 4206 console.info('Succeeded in loading the content.'); 4207 let color: string = '#00ff33'; 4208 try { 4209 windowClass.setWindowBackgroundColor(color); 4210 } catch (exception) { 4211 console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`); 4212 }; 4213 }); 4214} 4215``` 4216 4217### setWindowBrightness<sup>9+</sup> 4218 4219setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void 4220 4221Sets the screen brightness for the main window. This API uses an asynchronous callback to return the result. 4222 4223When 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. 4224 4225**System capability**: SystemCapability.WindowManager.WindowManager.Core 4226 4227**Atomic service API**: This API can be used in atomic services since API version 11. 4228 4229**Parameters** 4230 4231| Name| Type| Mandatory| Description | 4232| ---------- | ------------------------- | -- |-------------------------------------------| 4233| 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.| 4234| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4235 4236**Error codes** 4237 4238For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4239 4240| ID| Error Message| 4241| ------- | -------------------------------------------- | 4242| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4243| 1300002 | This window state is abnormal. | 4244| 1300003 | This window manager service works abnormally. | 4245 4246**Example** 4247 4248```ts 4249// EntryAbility.ets 4250import { UIAbility } from '@kit.AbilityKit'; 4251import { BusinessError } from '@kit.BasicServicesKit'; 4252 4253export default class EntryAbility extends UIAbility { 4254 // ... 4255 onWindowStageCreate(windowStage: window.WindowStage): void { 4256 console.info('onWindowStageCreate'); 4257 let windowClass: window.Window | undefined = undefined; 4258 windowStage.getMainWindow((err: BusinessError, data) => { 4259 const errCode: number = err.code; 4260 if (errCode) { 4261 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 4262 return; 4263 } 4264 windowClass = data; 4265 let brightness: number = 1; 4266 try { 4267 windowClass.setWindowBrightness(brightness, (err: BusinessError) => { 4268 const errCode: number = err.code; 4269 if (errCode) { 4270 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 4271 return; 4272 } 4273 console.info('Succeeded in setting the brightness.'); 4274 }); 4275 } catch (exception) { 4276 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 4277 } 4278 }); 4279 } 4280} 4281``` 4282 4283### setWindowBrightness<sup>9+</sup> 4284 4285setWindowBrightness(brightness: number): Promise<void> 4286 4287Sets the screen brightness for the main window. This API uses a promise to return the result. 4288 4289When 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. 4290 4291**System capability**: SystemCapability.WindowManager.WindowManager.Core 4292 4293**Atomic service API**: This API can be used in atomic services since API version 11. 4294 4295**Parameters** 4296 4297| Name| Type| Mandatory| Description | 4298| ---------- | ------ | -- |----------------------------------------| 4299| 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.| 4300 4301**Return value** 4302 4303| Type| Description| 4304| ------------------- | ------------------------ | 4305| Promise<void> | Promise that returns no value.| 4306 4307**Error codes** 4308 4309For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4310 4311| ID| Error Message| 4312| ------- | -------------------------------------------- | 4313| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4314| 1300002 | This window state is abnormal. | 4315| 1300003 | This window manager service works abnormally. | 4316 4317**Example** 4318 4319```ts 4320// EntryAbility.ets 4321import { UIAbility } from '@kit.AbilityKit'; 4322import { BusinessError } from '@kit.BasicServicesKit'; 4323 4324export default class EntryAbility extends UIAbility { 4325 // ... 4326 onWindowStageCreate(windowStage: window.WindowStage): void { 4327 console.info('onWindowStageCreate'); 4328 let windowClass: window.Window | undefined = undefined; 4329 windowStage.getMainWindow((err: BusinessError, data) => { 4330 const errCode: number = err.code; 4331 if (errCode) { 4332 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 4333 return; 4334 } 4335 windowClass = data; 4336 let brightness: number = 1; 4337 try { 4338 let promise = windowClass.setWindowBrightness(brightness); 4339 promise.then(() => { 4340 console.info('Succeeded in setting the brightness.'); 4341 }).catch((err: BusinessError) => { 4342 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 4343 }); 4344 } catch (exception) { 4345 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 4346 } 4347 }); 4348 } 4349} 4350``` 4351 4352### setWindowFocusable<sup>9+</sup> 4353 4354setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 4355 4356Sets 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. 4357 4358**Atomic service API**: This API can be used in atomic services since API version 12. 4359 4360**System capability**: SystemCapability.WindowManager.WindowManager.Core 4361 4362**Parameters** 4363 4364| Name| Type| Mandatory| Description| 4365| ----------- | ------------------------- | -- | ------------------------------------------------------- | 4366| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite.| 4367| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4368 4369**Error codes** 4370 4371For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4372 4373| ID| Error Message| 4374| ------- | -------------------------------------------- | 4375| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4376| 1300002 | This window state is abnormal. | 4377| 1300003 | This window manager service works abnormally. | 4378 4379**Example** 4380 4381```ts 4382import { BusinessError } from '@kit.BasicServicesKit'; 4383 4384let isFocusable: boolean = true; 4385try { 4386 windowClass.setWindowFocusable(isFocusable, (err: BusinessError) => { 4387 const errCode: number = err.code; 4388 if (errCode) { 4389 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 4390 return; 4391 } 4392 console.info('Succeeded in setting the window to be focusable.'); 4393 }); 4394} catch (exception) { 4395 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 4396} 4397``` 4398 4399### setWindowFocusable<sup>9+</sup> 4400 4401setWindowFocusable(isFocusable: boolean): Promise<void> 4402 4403Sets 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. 4404 4405**Atomic service API**: This API can be used in atomic services since API version 12. 4406 4407**System capability**: SystemCapability.WindowManager.WindowManager.Core 4408 4409**Parameters** 4410 4411| Name| Type| Mandatory| Description| 4412| ----------- | ------- | -- | -------------------------------------------------------- | 4413| isFocusable | boolean | Yes| Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 4414 4415**Return value** 4416 4417| Type| Description| 4418| ------------------- | ------------------------ | 4419| Promise<void> | Promise that returns no value.| 4420 4421**Error codes** 4422 4423For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4424 4425| ID| Error Message| 4426| ------- | -------------------------------------------- | 4427| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4428| 1300002 | This window state is abnormal. | 4429| 1300003 | This window manager service works abnormally. | 4430 4431**Example** 4432 4433```ts 4434import { BusinessError } from '@kit.BasicServicesKit'; 4435 4436let isFocusable: boolean = true; 4437try { 4438 let promise = windowClass.setWindowFocusable(isFocusable); 4439 promise.then(() => { 4440 console.info('Succeeded in setting the window to be focusable.'); 4441 }).catch((err: BusinessError) => { 4442 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 4443 }); 4444} catch (exception) { 4445 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 4446} 4447``` 4448 4449### setWindowKeepScreenOn<sup>9+</sup> 4450 4451setWindowKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 4452 4453Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 4454 4455Set **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. 4456 4457**System capability**: SystemCapability.WindowManager.WindowManager.Core 4458 4459**Atomic service API**: This API can be used in atomic services since API version 11. 4460 4461**Parameters** 4462 4463| Name| Type| Mandatory| Description| 4464| -------------- | ------------------------- | -- | ---------------------------------------------------- | 4465| 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. | 4466| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4467 4468**Error codes** 4469 4470For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4471 4472| ID| Error Message| 4473| ------- | -------------------------------------------- | 4474| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4475| 1300002 | This window state is abnormal. | 4476| 1300003 | This window manager service works abnormally. | 4477 4478**Example** 4479 4480```ts 4481import { BusinessError } from '@kit.BasicServicesKit'; 4482 4483let isKeepScreenOn: boolean = true; 4484try { 4485 windowClass.setWindowKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 4486 const errCode: number = err.code; 4487 if (errCode) { 4488 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 4489 return; 4490 } 4491 console.info('Succeeded in setting the screen to be always on.'); 4492 }); 4493} catch (exception) { 4494 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 4495} 4496``` 4497 4498### setWindowKeepScreenOn<sup>9+</sup> 4499 4500setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 4501 4502Sets whether to keep the screen always on. This API uses a promise to return the result. 4503 4504Set **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. 4505 4506**System capability**: SystemCapability.WindowManager.WindowManager.Core 4507 4508**Atomic service API**: This API can be used in atomic services since API version 11. 4509 4510**Parameters** 4511 4512| Name| Type| Mandatory| Description| 4513| -------------- | ------- | -- | --------------------------------------------------- | 4514| 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.| 4515 4516**Return value** 4517 4518| Type| Description| 4519| ------------------- | ------------------------ | 4520| Promise<void> | Promise that returns no value.| 4521 4522**Error codes** 4523 4524For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4525 4526| ID| Error Message| 4527| ------- | -------------------------------------------- | 4528| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4529| 1300002 | This window state is abnormal. | 4530| 1300003 | This window manager service works abnormally. | 4531 4532**Example** 4533 4534```ts 4535import { BusinessError } from '@kit.BasicServicesKit'; 4536 4537let isKeepScreenOn: boolean = true; 4538try { 4539 let promise = windowClass.setWindowKeepScreenOn(isKeepScreenOn); 4540 promise.then(() => { 4541 console.info('Succeeded in setting the screen to be always on.'); 4542 }).catch((err: BusinessError) => { 4543 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 4544 }); 4545} catch (exception) { 4546 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 4547} 4548``` 4549 4550### setWindowPrivacyMode<sup>9+</sup> 4551 4552setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 4553 4554Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 4555 4556A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 4557 4558**System capability**: SystemCapability.WindowManager.WindowManager.Core 4559 4560**Atomic service API**: This API can be used in atomic services since API version 12. 4561 4562**Required permissions**: ohos.permission.PRIVACY_WINDOW 4563 4564**Parameters** 4565 4566| Name| Type| Mandatory| Description| 4567| ------------- | ------------------------- | -- | ------------------------------------------------------ | 4568| 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. | 4569| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4570 4571**Error codes** 4572 4573For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4574 4575| ID| Error Message| 4576| ------- | ------------------------------ | 4577| 201 | Permission verification failed. The application does not have the permission required to call the API. | 4578| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4579| 1300002 | This window state is abnormal. | 4580 4581**Example** 4582 4583```ts 4584import { BusinessError } from '@kit.BasicServicesKit'; 4585 4586let isPrivacyMode: boolean = true; 4587try { 4588 windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => { 4589 const errCode: number = err.code; 4590 if (errCode) { 4591 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 4592 return; 4593 } 4594 console.info('Succeeded in setting the window to privacy mode.'); 4595 }); 4596} catch (exception) { 4597 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 4598} 4599``` 4600 4601### setWindowPrivacyMode<sup>9+</sup> 4602 4603setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 4604 4605Sets whether this window is in privacy mode. This API uses a promise to return the result. 4606 4607A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 4608 4609**System capability**: SystemCapability.WindowManager.WindowManager.Core 4610 4611**Atomic service API**: This API can be used in atomic services since API version 12. 4612 4613**Required permissions**: ohos.permission.PRIVACY_WINDOW 4614 4615**Parameters** 4616 4617| Name| Type| Mandatory| Description| 4618| ------------- | ------- | -- | ----------------------------------------------------- | 4619| 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.| 4620 4621**Return value** 4622 4623| Type| Description| 4624| ------------------- | ------------------------ | 4625| Promise<void> | Promise that returns no value.| 4626 4627**Error codes** 4628 4629For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4630 4631| ID| Error Message| 4632| ------- | ------------------------------ | 4633| 201 | Permission verification failed. The application does not have the permission required to call the API. | 4634| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4635| 1300002 | This window state is abnormal. | 4636 4637**Example** 4638 4639```ts 4640import { BusinessError } from '@kit.BasicServicesKit'; 4641 4642let isPrivacyMode: boolean = true; 4643try { 4644 let promise = windowClass.setWindowPrivacyMode(isPrivacyMode); 4645 promise.then(() => { 4646 console.info('Succeeded in setting the window to privacy mode.'); 4647 }).catch((err: BusinessError) => { 4648 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 4649 }); 4650} catch (exception) { 4651 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 4652} 4653``` 4654 4655### setWindowTouchable<sup>9+</sup> 4656 4657setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 4658 4659Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 4660 4661**Atomic service API**: This API can be used in atomic services since API version 12. 4662 4663**System capability**: SystemCapability.WindowManager.WindowManager.Core 4664 4665**Parameters** 4666 4667| Name| Type| Mandatory| Description| 4668| ----------- | ------------------------- | -- | ----------------------------------------------- | 4669| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 4670| callback | AsyncCallback<void> | Yes| Callback used to return the result. | 4671 4672**Error codes** 4673 4674For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4675 4676| ID| Error Message| 4677| ------- | -------------------------------------------- | 4678| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4679| 1300002 | This window state is abnormal. | 4680| 1300003 | This window manager service works abnormally. | 4681 4682**Example** 4683 4684```ts 4685import { BusinessError } from '@kit.BasicServicesKit'; 4686 4687let isTouchable = true; 4688try { 4689 windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => { 4690 const errCode: number = err.code; 4691 if (errCode) { 4692 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 4693 return; 4694 } 4695 console.info('Succeeded in setting the window to be touchable.'); 4696 }); 4697} catch (exception) { 4698 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 4699} 4700``` 4701 4702### setWindowTouchable<sup>9+</sup> 4703 4704setWindowTouchable(isTouchable: boolean): Promise<void> 4705 4706Sets whether this window is touchable. This API uses a promise to return the result. 4707 4708**Atomic service API**: This API can be used in atomic services since API version 12. 4709 4710**System capability**: SystemCapability.WindowManager.WindowManager.Core 4711 4712**Parameters** 4713 4714| Name| Type| Mandatory| Description| 4715| ----------- | ------- | -- | ----------------------------------------------- | 4716| isTouchable | boolean | Yes| Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite.| 4717 4718**Return value** 4719 4720| Type| Description| 4721| ------------------- | ------------------------- | 4722| Promise<void> | Promise that returns no value.| 4723 4724**Error codes** 4725 4726For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4727 4728| ID| Error Message| 4729| ------- | -------------------------------------------- | 4730| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 4731| 1300002 | This window state is abnormal. | 4732| 1300003 | This window manager service works abnormally. | 4733 4734**Example** 4735 4736```ts 4737import { BusinessError } from '@kit.BasicServicesKit'; 4738 4739let isTouchable: boolean = true; 4740try { 4741 let promise = windowClass.setWindowTouchable(isTouchable); 4742 promise.then(() => { 4743 console.info('Succeeded in setting the window to be touchable.'); 4744 }).catch((err: BusinessError) => { 4745 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 4746 }); 4747} catch (exception) { 4748 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 4749} 4750``` 4751 4752### snapshot<sup>9+</sup> 4753 4754snapshot(callback: AsyncCallback<image.PixelMap>): void 4755 4756Captures this window. This API uses an asynchronous callback to return the result. 4757 4758**Atomic service API**: This API can be used in atomic services since API version 12. 4759 4760**System capability**: SystemCapability.WindowManager.WindowManager.Core 4761 4762**Parameters** 4763 4764| Name | Type | Mandatory | Description | 4765| -------- | ------------------------------------------------------------ | --------- | ----------------------------------- | 4766| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Yes | Callback used to return the result. | 4767 4768**Error codes** 4769 4770For details about the error codes, see [Window Error Codes](errorcode-window.md). 4771 4772| ID | Error Message | 4773| ------- | ------------------------------ | 4774| 1300002 | This window state is abnormal. | 4775 4776**Example** 4777 4778```ts 4779import { BusinessError } from '@kit.BasicServicesKit'; 4780import { image } from '@kit.ImageKit'; 4781 4782windowClass.snapshot((err: BusinessError, pixelMap: image.PixelMap) => { 4783 const errCode: number = err.code; 4784 if (errCode) { 4785 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 4786 return; 4787 } 4788 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 4789 pixelMap.release(); // Release the memory in time after the PixelMap is used. 4790}); 4791``` 4792 4793### snapshot<sup>9+</sup> 4794 4795snapshot(): Promise<image.PixelMap> 4796 4797Captures this window. This API uses a promise to return the result. 4798 4799**Atomic service API**: This API can be used in atomic services since API version 12. 4800 4801**System capability**: SystemCapability.WindowManager.WindowManager.Core 4802 4803**Return value** 4804 4805| Type | Description | 4806| ------------------------------------------------------------ | --------------------------------------------- | 4807| Promise<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise used to return the window screenshot. | 4808 4809**Error codes** 4810 4811For details about the error codes, see [Window Error Codes](errorcode-window.md). 4812 4813| ID | Error Message | 4814| ------- | ------------------------------ | 4815| 1300002 | This window state is abnormal. | 4816 4817**Example** 4818 4819```ts 4820import { BusinessError } from '@kit.BasicServicesKit'; 4821import { image } from '@kit.ImageKit'; 4822 4823let promise = windowClass.snapshot(); 4824promise.then((pixelMap: image.PixelMap) => { 4825 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 4826 pixelMap.release(); // Release the memory in time after the PixelMap is used. 4827}).catch((err: BusinessError) => { 4828 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 4829}); 4830``` 4831 4832### setAspectRatio<sup>10+</sup> 4833 4834setAspectRatio(ratio: number): Promise<void> 4835 4836Sets the aspect ratio of the window content layout. This API uses a promise to return the result. 4837 4838This 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. 4839 4840**Atomic service API**: This API can be used in atomic services since API version 12. 4841 4842**System capability**: SystemCapability.WindowManager.WindowManager.Core 4843 4844**Parameters** 4845 4846| Name | Type | Mandatory | Description | 4847| ----- | ------ | --------- | ------------------------------------------------------------ | 4848| 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). | 4849 4850**Return value** 4851 4852| Type | Description | 4853| ------------------- | ------------------------------ | 4854| Promise<void> | Promise that returns no value. | 4855 4856**Error codes** 4857 4858For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4859 4860| ID | Error Message | 4861| ------- | ------------------------------------------------------------ | 4862| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4863| 1300002 | This window state is abnormal. | 4864| 1300004 | Unauthorized operation. | 4865 4866**Example** 4867<!--code_no_check--> 4868```ts 4869// EntryAbility.ets 4870import { UIAbility } from '@kit.AbilityKit'; 4871import { BusinessError } from '@kit.BasicServicesKit'; 4872 4873export default class EntryAbility extends UIAbility { 4874 4875 // ... 4876 onWindowStageCreate(windowStage: window.WindowStage) { 4877 console.info('onWindowStageCreate'); 4878 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 4879 if (!windowClass) { 4880 console.info('windowClass is null'); 4881 } 4882 try { 4883 let ratio = 1.0; 4884 let promise = windowClass.setAspectRatio(ratio); 4885 promise.then(() => { 4886 console.info('Succeeded in setting aspect ratio of window.'); 4887 }).catch((err: BusinessError) => { 4888 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 4889 }); 4890 } catch (exception) { 4891 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 4892 } 4893 } 4894} 4895``` 4896 4897### setAspectRatio<sup>10+</sup> 4898 4899setAspectRatio(ratio: number, callback: AsyncCallback<void>): void 4900 4901Sets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 4902 4903This 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. 4904 4905**Atomic service API**: This API can be used in atomic services since API version 12. 4906 4907**System capability**: SystemCapability.WindowManager.WindowManager.Core 4908 4909**Parameters** 4910 4911| Name | Type | Mandatory | Description | 4912| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 4913| 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). | 4914| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 4915 4916**Error codes** 4917 4918For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 4919 4920| ID | Error Message | 4921| ------- | ------------------------------------------------------------ | 4922| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4923| 1300002 | This window state is abnormal. | 4924| 1300004 | Unauthorized operation. | 4925 4926**Example** 4927<!--code_no_check--> 4928```ts 4929// EntryAbility.ets 4930import { UIAbility } from '@kit.AbilityKit'; 4931import { BusinessError } from '@kit.BasicServicesKit'; 4932 4933export default class EntryAbility extends UIAbility { 4934 4935 // ... 4936 onWindowStageCreate(windowStage: window.WindowStage) { 4937 console.info('onWindowStageCreate'); 4938 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 4939 if (!windowClass) { 4940 console.info('Failed to load the content. Cause: windowClass is null'); 4941 } 4942 try { 4943 let ratio = 1.0; 4944 windowClass.setAspectRatio(ratio, (err: BusinessError) => { 4945 const errCode: number = err.code; 4946 if (errCode) { 4947 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 4948 return; 4949 } 4950 console.info('Succeeded in setting the aspect ratio of window.'); 4951 }); 4952 } catch (exception) { 4953 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 4954 } 4955 } 4956} 4957 4958``` 4959 4960### resetAspectRatio<sup>10+</sup> 4961 4962resetAspectRatio(): Promise<void> 4963 4964Resets the aspect ratio of the window content layout. This API uses a promise to return the result. 4965 4966This 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. 4967 4968**Atomic service API**: This API can be used in atomic services since API version 12. 4969 4970**System capability**: SystemCapability.WindowManager.WindowManager.Core 4971 4972**Return value** 4973 4974| Type | Description | 4975| ------------------- | ------------------------------ | 4976| Promise<void> | Promise that returns no value. | 4977 4978**Error codes** 4979 4980For details about the error codes, see [Window Error Codes](errorcode-window.md). 4981 4982| ID | Error Message | 4983| ------- | ------------------------------ | 4984| 1300002 | This window state is abnormal. | 4985| 1300004 | Unauthorized operation. | 4986 4987**Example** 4988<!--code_no_check--> 4989```ts 4990// EntryAbility.ets 4991import { UIAbility } from '@kit.AbilityKit'; 4992import { BusinessError } from '@kit.BasicServicesKit'; 4993 4994export default class EntryAbility extends UIAbility { 4995 4996 // ... 4997 onWindowStageCreate(windowStage: window.WindowStage) { 4998 console.info('onWindowStageCreate'); 4999 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5000 if (!windowClass) { 5001 console.info('Failed to load the content. Cause: windowClass is null'); 5002 } 5003 try { 5004 let promise = windowClass.resetAspectRatio(); 5005 promise.then(() => { 5006 console.info('Succeeded in resetting aspect ratio of window.'); 5007 }).catch((err: BusinessError) => { 5008 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5009 }); 5010 } catch (exception) { 5011 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5012 } 5013 } 5014} 5015``` 5016 5017### resetAspectRatio<sup>10+</sup> 5018 5019resetAspectRatio(callback: AsyncCallback<void>): void 5020 5021Resets the aspect ratio of the window content layout. This API uses an asynchronous callback to return the result. 5022 5023This 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. 5024 5025**Atomic service API**: This API can be used in atomic services since API version 12. 5026 5027**System capability**: SystemCapability.WindowManager.WindowManager.Core 5028 5029**Parameters** 5030 5031| Name | Type | Mandatory | Description | 5032| -------- | ------------------------- | --------- | ----------------------------------- | 5033| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 5034 5035**Error codes** 5036 5037For details about the error codes, see [Window Error Codes](errorcode-window.md). 5038 5039| ID | Error Message | 5040| ------- | ------------------------------ | 5041| 1300002 | This window state is abnormal. | 5042| 1300004 | Unauthorized operation. | 5043 5044**Example** 5045<!--code_no_check--> 5046```ts 5047// EntryAbility.ets 5048import { UIAbility } from '@kit.AbilityKit'; 5049import { BusinessError } from '@kit.BasicServicesKit'; 5050 5051export default class EntryAbility extends UIAbility { 5052 5053 // ... 5054 onWindowStageCreate(windowStage: window.WindowStage) { 5055 console.info('onWindowStageCreate'); 5056 let windowClass: window.Window = windowStage.getMainWindowSync(); // Obtain the main window of the application. 5057 if (!windowClass) { 5058 console.info('Failed to load the content. Cause: windowClass is null'); 5059 } 5060 try { 5061 windowClass.resetAspectRatio((err: BusinessError) => { 5062 const errCode: number = err.code; 5063 if (errCode) { 5064 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 5065 return; 5066 } 5067 console.info('Succeeded in resetting aspect ratio of window.'); 5068 }); 5069 } catch (exception) { 5070 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 5071 } 5072 } 5073} 5074``` 5075 5076### minimize<sup>11+</sup> 5077 5078minimize(callback: AsyncCallback<void>): void 5079 5080Implements different functionalities based on the caller: 5081 5082Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. 5083 5084Hides the subwindow if the caller is a subwindow. The subwindow cannot be restored in the dock bar. 5085 5086This API uses an asynchronous callback to return the result. 5087 5088**Atomic service API**: This API can be used in atomic services since API version 12. 5089 5090**System capability**: SystemCapability.Window.SessionManager 5091 5092**Parameters** 5093 5094| Name | Type | Mandatory | Description | 5095| -------- | ------------------------- | --------- | ----------------------------------- | 5096| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 5097 5098**Error codes** 5099 5100For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5101 5102| ID | Error Message | 5103| ------- | ------------------------------------------------------------ | 5104| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5105| 1300002 | This window state is abnormal. | 5106| 1300003 | This window manager service works abnormally. | 5107 5108**Example** 5109 5110```ts 5111import { BusinessError } from '@kit.BasicServicesKit'; 5112 5113windowClass.minimize((err: BusinessError) => { 5114 const errCode: number = err.code; 5115 if (errCode) { 5116 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 5117 return; 5118 } 5119 console.info('Succeeded in minimizing the window.'); 5120}); 5121``` 5122 5123### minimize<sup>11+</sup> 5124 5125minimize(): Promise<void> 5126 5127Implements different functionalities based on the caller: 5128 5129Minimizes the main window if the caller is the main window. The main window can be restored in the dock bar. 5130 5131Hides the subwindow if the caller is a subwindow. The subwindow cannot be restored in the dock bar. 5132 5133This API uses a promise to return the result. 5134 5135**Atomic service API**: This API can be used in atomic services since API version 12. 5136 5137**System capability**: SystemCapability.Window.SessionManager 5138 5139**Return value** 5140 5141| Type | Description | 5142| ------------------- | ------------------------------ | 5143| Promise<void> | Promise that returns no value. | 5144 5145**Error codes** 5146 5147For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5148 5149| ID | Error Message | 5150| ------- | ------------------------------------------------------------ | 5151| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5152| 1300002 | This window state is abnormal. | 5153| 1300003 | This window manager service works abnormally. | 5154 5155**Example** 5156 5157```ts 5158import { BusinessError } from '@kit.BasicServicesKit'; 5159 5160let promise = windowClass.minimize(); 5161promise.then(() => { 5162 console.info('Succeeded in minimizing the window.'); 5163}).catch((err: BusinessError) => { 5164 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 5165}); 5166``` 5167 5168### maximize<sup>12+</sup> 5169maximize(presentation?: MaximizePresentation): Promise<void> 5170 5171Maximizes the main window. This API uses a promise to return the result. It can be used only on 2-in-1 devices. 5172 5173**Atomic service API**: This API can be used in atomic services since API version 12. 5174 5175**System capability**: SystemCapability.Window.SessionManager 5176 5177**Parameters** 5178 5179| Name | Type | Mandatory | Description | 5180| ------------ | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 5181| 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. | 5182 5183**Return value** 5184 5185| Type | Description | 5186| ------------------- | ------------------------------ | 5187| Promise<void> | Promise that returns no value. | 5188 5189**Error codes** 5190 5191For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5192 5193| ID | Error Message | 5194| ------- | ------------------------------------------------------------ | 5195| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5196| 1300002 | This window state is abnormal. | 5197| 1300003 | This window manager service works abnormally. | 5198| 1300004 | Unauthorized operation. | 5199| 1300005 | This window stage is abnormal. | 5200 5201**Example** 5202 5203```ts 5204// EntryAbility.ets 5205import { UIAbility } from '@kit.AbilityKit'; 5206import { BusinessError } from '@kit.BasicServicesKit'; 5207export default class EntryAbility extends UIAbility { 5208 // ... 5209 5210 onWindowStageCreate(windowStage: window.WindowStage) { 5211 console.info('onWindowStageCreate'); 5212 let windowClass: window.Window | undefined = undefined; 5213 windowStage.getMainWindow((err: BusinessError, data) => { 5214 const errCode: number = err.code; 5215 if (errCode) { 5216 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5217 return; 5218 } 5219 windowClass = data; 5220 let promise = windowClass.maximize(); 5221 // let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 5222 promise.then(() => { 5223 console.info('Succeeded in maximizing the window.'); 5224 }).catch((err: BusinessError) => { 5225 console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`); 5226 }); 5227 }); 5228 } 5229}; 5230``` 5231 5232### recover<sup>11+</sup> 5233 5234recover(): Promise<void> 5235 5236Restores 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 cascade layout. It can be used only on 2-in-1 devices. 5237 5238**Atomic service API**: This API can be used in atomic services since API version 12. 5239 5240**System capability**: SystemCapability.Window.SessionManager 5241 5242**Return value** 5243 5244| Type | Description | 5245| ------------------- | ------------------------------ | 5246| Promise<void> | Promise that returns no value. | 5247 5248**Error codes** 5249 5250For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5251 5252| ID | Error Message | 5253| ------- | ------------------------------------------------------------ | 5254| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5255| 1300001 | Repeated operation. | 5256| 1300002 | This window state is abnormal. | 5257 5258**Example** 5259 5260```ts 5261// EntryAbility.ets 5262import { UIAbility } from '@kit.AbilityKit'; 5263import { BusinessError } from '@kit.BasicServicesKit'; 5264 5265export default class EntryAbility extends UIAbility { 5266 // ... 5267 onWindowStageCreate(windowStage: window.WindowStage): void { 5268 console.info('onWindowStageCreate'); 5269 let windowClass: window.Window | undefined = undefined; 5270 windowStage.getMainWindow((err: BusinessError, data) => { 5271 const errCode: number = err.code; 5272 if (errCode) { 5273 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5274 return; 5275 } 5276 windowClass = data; 5277 let promise = windowClass.recover(); 5278 promise.then(() => { 5279 console.info('Succeeded in recovering the window.'); 5280 }).catch((err: BusinessError) => { 5281 console.error(`Failed to recover the window. Cause code: ${err.code}, message: ${err.message}`); 5282 }); 5283 }); 5284 } 5285} 5286``` 5287 5288### getWindowLimits<sup>11+</sup> 5289 5290getWindowLimits(): WindowLimits 5291 5292Obtains the size limits of this application window. 5293 5294**Atomic service API**: This API can be used in atomic services since API version 12. 5295 5296**System capability**: SystemCapability.Window.SessionManager 5297 5298**Return value** 5299 5300| Type | Description | 5301| ------------------------------- | ------------------- | 5302| [WindowLimits](#windowlimits11) | Window size limits. | 5303 5304**Error codes** 5305 5306For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5307 5308| ID | Error Message | 5309| :------ | :----------------------------------------------------------- | 5310| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5311| 1300002 | This window state is abnormal. | 5312 5313**Example** 5314 5315```ts 5316try { 5317 let windowLimits = windowClass.getWindowLimits(); 5318} catch (exception) { 5319 console.error(`Failed to obtain the window limits of window. Cause code: ${exception.code}, message: ${exception.message}`); 5320} 5321``` 5322 5323### setWindowLimits<sup>11+</sup> 5324 5325setWindowLimits(windowLimits: WindowLimits): Promise<WindowLimits> 5326 5327Sets the size limits for this application window. This API uses a promise to return the result. 5328By 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. 5329 5330**Atomic service API**: This API can be used in atomic services since API version 12. 5331 5332**System capability**: SystemCapability.Window.SessionManager 5333 5334**Parameters** 5335 5336| Name | Type | Mandatory | Description | 5337| :----------- | :------------------------------ | :-------- | :------------------------- | 5338| windowLimits | [WindowLimits](#windowlimits11) | Yes | Target size limits, in px. | 5339 5340**Return value** 5341 5342| Type | Description | 5343| :--------------------------------------------- | :----------------------------------------------------------- | 5344| 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. | 5345 5346**Error codes** 5347 5348For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5349 5350| ID | Error Message | 5351| :------ | :----------------------------------------------------------- | 5352| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5353| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5354| 1300002 | This window state is abnormal. | 5355| 1300003 | This window manager service works abnormally. | 5356| 1300004 | Unauthorized operation. | 5357 5358**Example** 5359 5360```ts 5361import { BusinessError } from '@kit.BasicServicesKit'; 5362try { 5363 let windowLimits: window.WindowLimits = { 5364 maxWidth: 1500, 5365 maxHeight: 1000, 5366 minWidth: 500, 5367 minHeight: 400 5368 }; 5369 let promise = windowClass.setWindowLimits(windowLimits); 5370 promise.then((data) => { 5371 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 5372 }).catch((err: BusinessError) => { 5373 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 5374 }); 5375} catch (exception) { 5376 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 5377} 5378``` 5379 5380### setWindowMask<sup>12+</sup> 5381 5382setWindowMask(windowMask: Array<Array<number>>): Promise<void>; 5383 5384Sets a mask for this window to get an irregularly shaped window. This API uses a promise to return the result. 5385 5386The mask is used to describe the shape of the irregularly shaped window. 5387 5388This API is available only for subwindows and global floating windows in 2-in-1 devices. 5389 5390**Atomic service API**: This API can be used in atomic services since API version 12. 5391 5392**System capability**: SystemCapability.Window.SessionManager 5393 5394**Parameters** 5395 5396| Name | Type | Mandatory | Description | 5397| :--------- | :------------------------------- | :-------- | :----------------------------------------------------------- | 5398| 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. | 5399 5400**Return value** 5401 5402| Type | Description | 5403| :------------------ | :----------------------------- | 5404| Promise<void> | Promise that returns no value. | 5405 5406**Error codes** 5407 5408For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5409 5410| ID | Error Message | 5411| :------ | :----------------------------------------------------------- | 5412| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5413| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5414| 1300002 | This window state is abnormal. | 5415| 1300003 | This window manager service works abnormally. | 5416| 1300004 | Unauthorized operation. | 5417 5418**Example** 5419 5420```ts 5421import { BusinessError } from '@kit.BasicServicesKit'; 5422try { 5423 let windowMask: Array<Array<number>> = [ 5424 [0, 0, 0, 1, 0, 0, 0], 5425 [0, 0, 1, 1, 1, 0, 0], 5426 [0, 1, 1, 0, 1, 1, 0], 5427 [1, 1, 0, 0, 0, 1, 1] 5428 ]; 5429 let promise = windowClass.setWindowMask(windowMask); 5430 promise.then(() => { 5431 console.info('Succeeded in setting the window mask.'); 5432 }).catch((err: BusinessError) => { 5433 console.error(`Failed to set the window mask. Cause code: ${err.code}, message: ${err.message}`); 5434 }); 5435} catch (exception) { 5436 console.error(`Failed to set the window mask. Cause code: ${exception.code}, message: ${exception.message}`); 5437} 5438``` 5439 5440### keepKeyboardOnFocus<sup>11+</sup> 5441 5442keepKeyboardOnFocus(keepKeyboardFlag: boolean): void 5443 5444Sets whether to keep the soft keyboard created by others when a window has focus. This API can be called only by a system window or an application subwindow. 5445 5446**Atomic service API**: This API can be used in atomic services since API version 12. 5447 5448**System capability**: SystemCapability.Window.SessionManager 5449 5450**Parameters** 5451 5452| Name | Type | Mandatory | Description | 5453| ---------------- | ------- | --------- | ------------------------------------------------------------ | 5454| 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. | 5455 5456**Error codes** 5457 5458For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5459 5460| ID | Error Message | 5461| ------- | ------------------------------------------------------------ | 5462| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5463| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5464| 1300002 | This window state is abnormal. | 5465| 1300004 | Unauthorized operation. | 5466 5467**Example** 5468 5469```ts 5470try { 5471 windowClass.keepKeyboardOnFocus(true); 5472} catch (exception) { 5473 console.error(`Failed to keep keyboard onFocus. Cause code: ${exception.code}, message: ${exception.message}`); 5474} 5475``` 5476 5477### setWindowDecorVisible<sup>11+</sup> 5478 5479setWindowDecorVisible(isVisible: boolean): void 5480 5481Sets 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. 5482 5483**Atomic service API**: This API can be used in atomic services since API version 12. 5484 5485**System capability**: SystemCapability.Window.SessionManager 5486 5487**Parameters** 5488 5489| Name | Type | Mandatory | Description | 5490| --------- | ------- | --------- | ------------------------------------------------------------ | 5491| isVisible | boolean | Yes | Whether the title bar is visible. The value **true** means that the title bar is visible and **false** means the opposite. | 5492 5493**Error codes** 5494 5495For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5496 5497| ID | Error Message | 5498| ------- | ------------------------------------------------------------ | 5499| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5500| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5501| 1300002 | This window state is abnormal. | 5502| 1300004 | Unauthorized operation. | 5503 5504**Example** 5505 5506```ts 5507import { BusinessError } from '@kit.BasicServicesKit'; 5508let storage: LocalStorage = new LocalStorage(); 5509storage.setOrCreate('storageSimpleProp', 121); 5510windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 5511 let errCode: number = err.code; 5512 if (errCode) { 5513 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 5514 return; 5515 } 5516 console.info('Succeeded in loading the content.'); 5517 let isVisible = false; 5518 // Call setWindowDecorVisible. 5519 try { 5520 windowClass?.setWindowDecorVisible(isVisible); 5521 } catch (exception) { 5522 console.error(`Failed to set the visibility of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 5523 } 5524}); 5525``` 5526 5527### setSubWindowModal<sup>12+</sup> 5528 5529setSubWindowModal(isModal: boolean): Promise<void> 5530 5531Enables the modal property of the subwindow. This API uses a promise to return the result. 5532 5533This API can be called only by a subwindow. Otherwise, an error is reported. 5534 5535After the modal property is enabled, the parent window cannot respond to user operations until the subwindow is closed or the modal property is disabled. 5536 5537**Atomic service API**: This API can be used in atomic services since API version 12. 5538 5539**System capability**: SystemCapability.Window.SessionManager 5540 5541**Parameters** 5542 5543| Name | Type | Mandatory | Description | 5544| ------- | ------- | --------- | ------------------------------------------------------------ | 5545| isModal | boolean | Yes | Whether to enable the modal property of the subwindow. The value **true** means to enable the modal property, and **false** means the opposite. | 5546 5547 5548**Return value** 5549 5550| Type | Description | 5551| ------------------- | ------------------------------ | 5552| Promise<void> | Promise that returns no value. | 5553 5554**Error codes** 5555 5556For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5557 5558| ID | Error Message | 5559| ------- | ------------------------------------------------------------ | 5560| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5561| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5562| 1300002 | This window state is abnormal. | 5563| 1300004 | Unauthorized operation. | 5564 5565**Example** 5566 5567```ts 5568// EntryAbility.ets 5569import { UIAbility } from '@kit.AbilityKit'; 5570import { BusinessError } from '@kit.BasicServicesKit'; 5571 5572export default class EntryAbility extends UIAbility { 5573 // ... 5574 onWindowStageCreate(windowStage: window.WindowStage): void { 5575 console.info('onWindowStageCreate'); 5576 let windowClass: window.Window | undefined = undefined; 5577 // Create a subwindow. 5578 try { 5579 let subWindow = windowStage.createSubWindow("testSubWindow"); 5580 subWindow.then((data) => { 5581 if (data == null) { 5582 console.error("Failed to create the subWindow. Cause: The data is empty"); 5583 return; 5584 } 5585 windowClass = data; 5586 let promise = windowClass.setSubWindowModal(true); 5587 promise.then(() => { 5588 console.info('Succeeded in setting subwindow modal'); 5589 }).catch((err: BusinessError) => { 5590 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 5591 }); 5592 }); 5593 } catch (exception) { 5594 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 5595 } 5596 } 5597} 5598``` 5599 5600### setWindowDecorHeight<sup>11+</sup> 5601 5602setWindowDecorHeight(height: number): void 5603 5604<!--RP1--> 5605Sets 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. 5606<!--RP1End--> 5607 5608**Atomic service API**: This API can be used in atomic services since API version 12. 5609 5610**System capability**: SystemCapability.Window.SessionManager 5611 5612**Parameters** 5613 5614| Name | Type | Mandatory | Description | 5615| ------ | ------ | --------- | ------------------------------------------------------------ | 5616| 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. | 5617 5618**Error codes** 5619 5620For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5621 5622| ID | Error Message | 5623| ------- | ------------------------------------------------------------ | 5624| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5625| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5626| 1300002 | This window state is abnormal. | 5627 5628**Example** 5629 5630```ts 5631windowClass.setUIContent('pages/WindowPage').then(() => { 5632 let height: number = 50; 5633 try { 5634 windowClass?.setWindowDecorHeight(height); 5635 console.info(`Succeeded in setting the height of window decor: ${height}`); 5636 } catch (exception) { 5637 console.error(`Failed to set the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 5638 } 5639}) 5640``` 5641 5642### getWindowDecorHeight<sup>11+</sup> 5643 5644getWindowDecorHeight(): number 5645 5646<!--RP2--> 5647Obtains 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. 5648<!--RP2End--> 5649 5650**Atomic service API**: This API can be used in atomic services since API version 12. 5651 5652**System capability**: SystemCapability.Window.SessionManager 5653 5654**Return value** 5655 5656| Type | Description | 5657| ------ | ------------------------------------------------------------ | 5658| number | Height of the title bar. The value is an integer in the range [37,112]. The unit is vp. | 5659 5660**Error codes** 5661 5662For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5663 5664| ID | Error Message | 5665| ------- | ------------------------------------------------------------ | 5666| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5667| 1300002 | This window state is abnormal. | 5668 5669**Example** 5670 5671```ts 5672windowClass.setUIContent('pages/WindowPage').then(() => { 5673 try { 5674 let height = windowClass?.getWindowDecorHeight(); 5675 console.info(`Succeeded in getting the height of window decor: ${height}`); 5676 } catch (exception) { 5677 console.error(`Failed to get the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 5678 } 5679}) 5680``` 5681 5682### getTitleButtonRect<sup>11+</sup> 5683 5684getTitleButtonRect(): TitleButtonRect 5685 5686<!--RP3-->Obtains the rectangle that holds the minimize, maximize, and close buttons on the title bar of the main window or the decorated subwindow. This API can be used only on 2-in-1 devices.<!--RP3End--> 5687 5688**Atomic service API**: This API can be used in atomic services since API version 12. 5689 5690**System capability**: SystemCapability.Window.SessionManager 5691 5692**Return value** 5693 5694| Type | Description | 5695| ------------------------------------- | ------------------------------------------------------------ | 5696| [TitleButtonRect](#titlebuttonrect11) | Rectangle obtained, which is located in the upper right corner of the window. | 5697 5698**Error codes** 5699 5700For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5701 5702| ID | Error Message | 5703| ------- | ------------------------------------------------------------ | 5704| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5705| 1300002 | This window state is abnormal. | 5706 5707**Example** 5708 5709```ts 5710// EntryAbility.ets 5711import { UIAbility } from '@kit.AbilityKit'; 5712import { BusinessError } from '@kit.BasicServicesKit'; 5713 5714export default class EntryAbility extends UIAbility { 5715 // ... 5716 onWindowStageCreate(windowStage: window.WindowStage): void { 5717 console.info('onWindowStageCreate'); 5718 let windowClass: window.Window | undefined = undefined; 5719 windowStage.getMainWindow((err: BusinessError, data) => { 5720 const errCode: number = err.code; 5721 if (errCode) { 5722 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5723 return; 5724 } 5725 windowClass = data; 5726 try { 5727 let titleButtonArea = windowClass.getTitleButtonRect(); 5728 console.info('Succeeded in obtaining the area of title buttons. Data: ' + JSON.stringify(titleButtonArea)); 5729 } catch (exception) { 5730 console.error(`Failed to get the area of title buttons. Cause code: ${exception.code}, message: ${exception.message}`); 5731 } 5732 }); 5733 } 5734} 5735``` 5736 5737### getWindowStatus<sup>12+</sup> 5738 5739getWindowStatus(): WindowStatusType 5740 5741Obtains the mode of this window. 5742 5743**Atomic service API**: This API can be used in atomic services since API version 12. 5744 5745**System capability**: SystemCapability.Window.SessionManager 5746 5747**Parameters** 5748 5749| Type | Description | 5750| --------------------------------------- | ------------ | 5751| [WindowStatusType](#windowstatustype11) | Window mode. | 5752 5753**Error codes** 5754 5755For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5756 5757| ID | Error Message | 5758| ------- | ------------------------------------------------------------ | 5759| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5760| 1300002 | This window state is abnormal. | 5761 5762**Example** 5763 5764```ts 5765try { 5766 let windowStatusType = windowClass.getWindowStatus(); 5767} catch (exception) { 5768 console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); 5769} 5770``` 5771 5772### isFocused<sup>12+</sup> 5773 5774isFocused(): boolean 5775 5776Checks whether this window is focused. 5777 5778**System capability**: SystemCapability.WindowManager.WindowManager.Core 5779 5780**Atomic service API**: This API can be used in atomic services since API version 12. 5781 5782**Return value** 5783 5784| Type | Description | 5785| ------- | ------------------------------------------------------------ | 5786| boolean | Result indicating whether the window is focused. The value **true** means that the window is focused, and **false** means the opposite. | 5787 5788**Error codes** 5789 5790For details about the error codes, see [Window Error Codes](errorcode-window.md). 5791 5792| ID | Error Message | 5793| ------- | ------------------------------ | 5794| 1300002 | This window state is abnormal. | 5795 5796**Example** 5797 5798```ts 5799try { 5800 let focus = windowClass.isFocused(); 5801 console.info('Succeeded in checking whether the window is focused. Data: ' + JSON.stringify(focus)); 5802} catch (exception) { 5803 console.error(`Failed to check whether the window is focused. Cause code: ${exception.code}, message: ${exception.message}`); 5804} 5805``` 5806 5807### createSubWindowWithOptions<sup>12+</sup> 5808 5809createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 5810 5811Creates a subwindow under the main window or another subwindow. This API uses a promise to return the result. It takes effect only on 2-in-1 devices. 5812 5813**Model restriction**: This API can be used only in the stage model. 5814 5815**System capability**: SystemCapability.Window.SessionManager 5816 5817**Atomic service API**: This API can be used in atomic services since API version 12. 5818 5819**Parameters** 5820 5821| Name | Type | Mandatory | Description | 5822| ------- | --------------------------------------- | --------- | ------------------------------------------- | 5823| name | string | Yes | Name of the subwindow. | 5824| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the subwindow. | 5825 5826**Return value** 5827 5828| Type | Description | 5829| -------------------------------- | ----------------------------------------------------- | 5830| Promise<[Window](#window)> | Promise used to used to return the subwindow created. | 5831 5832**Error codes** 5833 5834For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 5835 5836| ID | Error Message | 5837| ------- | ------------------------------------------------------------ | 5838| 401 | Parameter error. Possible cause: Incorrect parameter types. | 5839| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5840| 1300002 | This window state is abnormal. | 5841| 1300003 | This window manager service works abnormally. | 5842| 1300004 | Unauthorized operation. | 5843 5844**Example** 5845 5846```ts 5847import { BusinessError } from '@kit.BasicServicesKit'; 5848 5849try { 5850 let options : window.SubWindowOptions = { 5851 title: 'title', 5852 decorEnabled: true, 5853 isModal: true 5854 }; 5855 let promise = windowClass.createSubWindowWithOptions('mySubWindow', options); 5856 promise.then((data) => { 5857 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 5858 }).catch((err: BusinessError) => { 5859 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 5860 }); 5861} catch (exception) { 5862 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 5863} 5864``` 5865 5866### enableLandscapeMultiWindow<sup>12+</sup> 5867 5868enableLandscapeMultiWindow(): Promise<void> 5869 5870Enables 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. 5871 5872This 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. 5873 5874**Atomic service API**: This API can be used in atomic services since API version 12. 5875 5876**System capability**: SystemCapability.Window.SessionManager 5877 5878**Return value** 5879 5880| Type | Description | 5881| ------------------- | ------------------------------ | 5882| Promise<void> | Promise that returns no value. | 5883 5884**Error codes** 5885 5886For details about the error codes, see [Window Error Codes](errorcode-window.md). 5887 5888| ID | Error Message | 5889| ------- | --------------------------------------------- | 5890| 1300002 | This window state is abnormal. | 5891| 1300003 | This window manager service works abnormally. | 5892 5893**Example** 5894 5895```ts 5896// EntryAbility.ets 5897import { UIAbility } from '@kit.AbilityKit'; 5898import { BusinessError } from '@kit.BasicServicesKit'; 5899import { window } from '@kit.ArkUI'; 5900 5901export default class EntryAbility extends UIAbility { 5902 // ... 5903 onWindowStageCreate(windowStage: window.WindowStage): void { 5904 console.info('onWindowStageCreate'); 5905 let windowClass: window.Window | undefined = undefined; 5906 windowStage.getMainWindow((err: BusinessError, data) => { 5907 const errCode: number = err.code; 5908 if (errCode) { 5909 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5910 return; 5911 } 5912 windowClass = data; 5913 let promise = windowClass.enableLandscapeMultiWindow(); 5914 promise.then(() => { 5915 console.info('Succeeded in making multi-window become landscape.'); 5916 }).catch((err: BusinessError) => { 5917 console.error(`Failed to make multi-window become landscape. Cause code: ${err.code}, message: ${err.message}`); 5918 }); 5919 }); 5920 } 5921} 5922``` 5923 5924### disableLandscapeMultiWindow<sup>12+</sup> 5925 5926disableLandscapeMultiWindow(): Promise<void> 5927 5928Disables the landscape multi-window mode for the UI page that supports the horizontal layout. 5929 5930This 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. 5931 5932**Atomic service API**: This API can be used in atomic services since API version 12. 5933 5934**System capability**: SystemCapability.Window.SessionManager 5935 5936**Return value** 5937 5938| Type | Description | 5939| ------------------- | ------------------------------ | 5940| Promise<void> | Promise that returns no value. | 5941 5942**Error codes** 5943 5944For details about the error codes, see [Window Error Codes](errorcode-window.md). 5945 5946| ID | Error Message | 5947| ------- | --------------------------------------------- | 5948| 1300002 | This window state is abnormal. | 5949| 1300003 | This window manager service works abnormally. | 5950 5951**Example** 5952 5953```ts 5954// EntryAbility.ets 5955import { UIAbility } from '@kit.AbilityKit'; 5956import { BusinessError } from '@kit.BasicServicesKit'; 5957import { window } from '@kit.ArkUI'; 5958 5959export default class EntryAbility extends UIAbility { 5960 // ... 5961 onWindowStageCreate(windowStage: window.WindowStage): void { 5962 console.info('onWindowStageCreate'); 5963 let windowClass: window.Window | undefined = undefined; 5964 windowStage.getMainWindow((err: BusinessError, data) => { 5965 const errCode: number = err.code; 5966 if (errCode) { 5967 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5968 return; 5969 } 5970 windowClass = data; 5971 let promise = windowClass.disableLandscapeMultiWindow(); 5972 promise.then(() => { 5973 console.info('Succeeded in making multi-window become not landscape.'); 5974 }).catch((err: BusinessError) => { 5975 console.error(`Failed to make multi-window become not landscape. Cause code: ${err.code}, message: ${err.message}`); 5976 }); 5977 }); 5978 } 5979} 5980``` 5981 5982### setDialogBackGestureEnabled<sup>12+</sup> 5983 5984setDialogBackGestureEnabled(enabled: boolean): Promise<void> 5985 5986Sets 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. 5987 5988**System capability**: SystemCapability.Window.SessionManager 5989 5990**Atomic service API**: This API can be used in atomic services since API version 12. 5991 5992**Parameters** 5993 5994| Name | Type | Mandatory | Description | 5995| ------- | ------- | --------- | ------------------------------------------------------------ | 5996| 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. | 5997 5998**Return value** 5999 6000| Type | Description | 6001| ------------------- | ------------------------------ | 6002| Promise<void> | Promise that returns no value. | 6003 6004**Error codes** 6005 6006For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6007 6008| ID | Error Message | 6009| ------- | ------------------------------------------------------------ | 6010| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6011| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6012| 1300002 | This window state is abnormal. | 6013| 1300003 | This window manager service works abnormally. | 6014| 1300004 | Unauthorized operation. | 6015 6016**Example** 6017 6018```ts 6019// EntryAbility.ets 6020import { UIAbility } from '@kit.AbilityKit'; 6021import { BusinessError } from '@kit.BasicServicesKit'; 6022 6023export default class EntryAbility extends UIAbility { 6024 onWindowStageCreate(windowStage: window.WindowStage): void { 6025 console.info('onWindowStageCreate'); 6026 let windowClass: window.Window | undefined = undefined; 6027 let config: window.Configuration = { 6028 name: "test", 6029 windowType: window.WindowType.TYPE_DIALOG, 6030 ctx: this.context 6031 }; 6032 try { 6033 window.createWindow(config, (err: BusinessError, data) => { 6034 const errCode: number = err.code; 6035 if (errCode) { 6036 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 6037 return; 6038 } 6039 windowClass = data; 6040 windowClass.setUIContent("pages/Index"); 6041 let enabled = true; 6042 let promise = windowClass.setDialogBackGestureEnabled(enabled); 6043 promise.then(() => { 6044 console.info('Succeeded in setting dialog window to respond back gesture.'); 6045 }).catch((err: BusinessError) => { 6046 console.error(`Failed to set dialog window to respond back gesture. Cause code: ${err.code}, message: ${err.message}`); 6047 }); 6048 }); 6049 } catch (exception) { 6050 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 6051 } 6052 } 6053} 6054``` 6055 6056```ts 6057// ets/pages/Index.ets 6058@Entry 6059@Component 6060struct Index { 6061 @State message: string = 'Hello World' 6062 build() { 6063 RelativeContainer() { 6064 Text(this.message) 6065 .id('HelloWorld') 6066 .fontSize(50) 6067 .fontWeight(FontWeight.Bold) 6068 } 6069 .height('100%') 6070 .width('100%') 6071 } 6072 6073 onBackPress(): boolean | void { 6074 console.info('Succeeded in setting dialog window to respond back gesture.'); 6075 return true; 6076 } 6077} 6078``` 6079 6080### setWindowSystemBarProperties<sup>(deprecated)</sup> 6081 6082setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 6083 6084Sets 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--> 6085 6086This API does not take effect when it is called by a subwindow. 6087 6088> **NOTE** 6089> 6090> 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. 6091 6092**System capability**: SystemCapability.WindowManager.WindowManager.Core 6093 6094**Atomic service API**: This API can be used in atomic services since API version 12. 6095 6096**Parameters** 6097 6098| Name | Type | Mandatory | Description | 6099| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 6100| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar. | 6101| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6102 6103**Error codes** 6104 6105For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6106 6107| ID | Error Message | 6108| ------- | ------------------------------------------------------------ | 6109| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 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 6117// EntryAbility.ets 6118import { UIAbility } from '@kit.AbilityKit'; 6119import { BusinessError } from '@kit.BasicServicesKit'; 6120 6121export default class EntryAbility extends UIAbility { 6122 // ... 6123 onWindowStageCreate(windowStage: window.WindowStage): void { 6124 console.info('onWindowStageCreate'); 6125 let windowClass: window.Window | undefined = undefined; 6126 windowStage.getMainWindow((err: BusinessError, data) => { 6127 const errCode: number = err.code; 6128 if (errCode) { 6129 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6130 return; 6131 } 6132 windowClass = data; 6133 let SystemBarProperties: window.SystemBarProperties = { 6134 statusBarColor: '#ff00ff', 6135 navigationBarColor: '#00ff00', 6136 // The following properties are supported since API version 8. 6137 statusBarContentColor: '#ffffff', 6138 navigationBarContentColor: '#00ffff' 6139 }; 6140 try { 6141 windowClass.setWindowSystemBarProperties(SystemBarProperties, (err: BusinessError) => { 6142 const errCode: number = err.code; 6143 if (errCode) { 6144 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 6145 return; 6146 } 6147 console.info('Succeeded in setting the system bar properties.'); 6148 }); 6149 } catch (exception) { 6150 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 6151 } 6152 }); 6153 } 6154} 6155``` 6156 6157### setWindowSystemBarEnable<sup>(deprecated)</sup> 6158 6159setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 6160 6161Sets 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--> 6162 6163This API does not take effect when it is called by a subwindow. 6164 6165> **NOTE** 6166> 6167> 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. 6168 6169**Atomic service API**: This API can be used in atomic services since API version 12. 6170 6171**System capability**: SystemCapability.WindowManager.WindowManager.Core 6172 6173**Parameters** 6174 6175| Name | Type | Mandatory | Description | 6176| -------- | ----------------------------- | --------- | ------------------------------------------------------------ | 6177| 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 show all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed. | 6178| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6179 6180**Error codes** 6181 6182For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6183 6184| ID | Error Message | 6185| ------- | ------------------------------------------------------------ | 6186| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6187| 1300002 | This window state is abnormal. | 6188| 1300003 | This window manager service works abnormally. | 6189 6190**Example** 6191 6192```ts 6193// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 6194// EntryAbility.ets 6195import { UIAbility } from '@kit.AbilityKit'; 6196import { BusinessError } from '@kit.BasicServicesKit'; 6197 6198export default class EntryAbility extends UIAbility { 6199 // ... 6200 onWindowStageCreate(windowStage: window.WindowStage): void { 6201 console.info('onWindowStageCreate'); 6202 let windowClass: window.Window | undefined = undefined; 6203 windowStage.getMainWindow((err: BusinessError, data) => { 6204 const errCode: number = err.code; 6205 if (errCode) { 6206 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6207 return; 6208 } 6209 windowClass = data; 6210 let names: Array<'status' | 'navigation'> = []; 6211 try { 6212 windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => { 6213 const errCode: number = err.code; 6214 if (errCode) { 6215 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 6216 return; 6217 } 6218 console.info('Succeeded in setting the system bar to be invisible.'); 6219 }); 6220 } catch (exception) { 6221 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 6222 } 6223 }); 6224 } 6225} 6226``` 6227 6228### setWindowLayoutFullScreen<sup>(deprecated)</sup> 6229 6230setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 6231 6232Sets whether the main window layout or the subwindow layout is immersive. This API uses an asynchronous callback to return the result. 6233- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 6234- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 6235 6236> **NOTE** 6237> 6238> 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. 6239 6240**System capability**: SystemCapability.WindowManager.WindowManager.Core 6241 6242**Atomic service API**: This API can be used in atomic services since API version 12. 6243 6244**Parameters** 6245 6246| Name | Type | Mandatory | Description | 6247| ------------------ | ------------------------- | --------- | ------------------------------------------------------------ | 6248| 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. | 6249| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6250 6251**Error codes** 6252 6253For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 6254 6255| ID | Error Message | 6256| ------- | ------------------------------------------------------------ | 6257| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6258| 1300002 | This window state is abnormal. | 6259| 1300003 | This window manager service works abnormally. | 6260 6261**Example** 6262 6263```ts 6264// EntryAbility.ets 6265import { UIAbility } from '@kit.AbilityKit'; 6266import { BusinessError } from '@kit.BasicServicesKit'; 6267 6268export default class EntryAbility extends UIAbility { 6269 // ... 6270 onWindowStageCreate(windowStage: window.WindowStage): void { 6271 console.info('onWindowStageCreate'); 6272 let windowClass: window.Window | undefined = undefined; 6273 windowStage.getMainWindow((err: BusinessError, data) => { 6274 const errCode: number = err.code; 6275 if (errCode) { 6276 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6277 return; 6278 } 6279 windowClass = data; 6280 let isLayoutFullScreen = true; 6281 try { 6282 windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 6283 const errCode: number = err.code; 6284 if (errCode) { 6285 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 6286 return; 6287 } 6288 console.info('Succeeded in setting the window layout to full-screen mode.'); 6289 }); 6290 } catch (exception) { 6291 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 6292 } 6293 }); 6294 } 6295} 6296``` 6297 6298### show<sup>(deprecated)</sup> 6299 6300show(callback: AsyncCallback<void>): void 6301 6302Shows this window. This API uses an asynchronous callback to return the result. 6303 6304> **NOTE** 6305> 6306> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9) instead. 6307 6308**System capability**: SystemCapability.WindowManager.WindowManager.Core 6309 6310**Parameters** 6311 6312| Name | Type | Mandatory | Description | 6313| -------- | ------------------------- | --------- | ----------------------------------- | 6314| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6315 6316**Example** 6317 6318```ts 6319import { BusinessError } from '@kit.BasicServicesKit'; 6320 6321windowClass.show((err: BusinessError) => { 6322 const errCode: number = err.code; 6323 if (errCode) { 6324 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 6325 return; 6326 } 6327 console.info('Succeeded in showing the window.'); 6328}); 6329``` 6330 6331### show<sup>(deprecated)</sup> 6332 6333show(): Promise<void> 6334 6335Shows this window. This API uses a promise to return the result. 6336 6337> **NOTE** 6338> 6339> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [showWindow()](#showwindow9-1) instead. 6340 6341**System capability**: SystemCapability.WindowManager.WindowManager.Core 6342 6343**Return value** 6344 6345| Type | Description | 6346| ------------------- | ------------------------------ | 6347| Promise<void> | Promise that returns no value. | 6348 6349**Example** 6350 6351```ts 6352import { BusinessError } from '@kit.BasicServicesKit'; 6353 6354let promise = windowClass.show(); 6355promise.then(() => { 6356 console.info('Succeeded in showing the window.'); 6357}).catch((err: BusinessError) => { 6358 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 6359}); 6360``` 6361 6362### destroy<sup>(deprecated)</sup> 6363 6364destroy(callback: AsyncCallback<void>): void 6365 6366Destroys this window. This API uses an asynchronous callback to return the result. 6367 6368> **NOTE** 6369> 6370> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9) instead. 6371 6372**System capability**: SystemCapability.WindowManager.WindowManager.Core 6373 6374**Parameters** 6375 6376| Name | Type | Mandatory | Description | 6377| -------- | ------------------------- | --------- | ----------------------------------- | 6378| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6379 6380**Example** 6381 6382```ts 6383import { BusinessError } from '@kit.BasicServicesKit'; 6384 6385windowClass.destroy((err: BusinessError) => { 6386 const errCode: number = err.code; 6387 if (err.code) { 6388 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 6389 return; 6390 } 6391 console.info('Succeeded in destroying the window.'); 6392}); 6393``` 6394 6395### destroy<sup>(deprecated)</sup> 6396 6397destroy(): Promise<void> 6398 6399Destroys this window. This API uses a promise to return the result. 6400 6401> **NOTE** 6402> 6403> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [destroyWindow()](#destroywindow9-1) instead. 6404 6405**System capability**: SystemCapability.WindowManager.WindowManager.Core 6406 6407**Return value** 6408 6409| Type | Description | 6410| ------------------- | ------------------------------ | 6411| Promise<void> | Promise that returns no value. | 6412 6413**Example** 6414 6415```ts 6416import { BusinessError } from '@kit.BasicServicesKit'; 6417 6418let promise = windowClass.destroy(); 6419promise.then(() => { 6420 console.info('Succeeded in destroying the window.'); 6421}).catch((err: BusinessError) => { 6422 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 6423}); 6424``` 6425 6426### moveTo<sup>(deprecated)</sup> 6427 6428moveTo(x: number, y: number, callback: AsyncCallback<void>): void 6429 6430Moves this window. This API uses an asynchronous callback to return the result. 6431 6432This operation is not supported in a window in full-screen mode. 6433 6434> **NOTE** 6435> 6436> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9) instead. 6437 6438**System capability**: SystemCapability.WindowManager.WindowManager.Core 6439 6440**Parameters** 6441 6442| Name | Type | Mandatory | Description | 6443| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 6444| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down. | 6445| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down. | 6446| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6447 6448**Example** 6449 6450```ts 6451import { BusinessError } from '@kit.BasicServicesKit'; 6452 6453windowClass.moveTo(300, 300, (err: BusinessError) => { 6454 const errCode: number = err.code; 6455 if (errCode) { 6456 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 6457 return; 6458 } 6459 console.info('Succeeded in moving the window.'); 6460}); 6461``` 6462 6463### moveTo<sup>(deprecated)</sup> 6464 6465moveTo(x: number, y: number): Promise<void> 6466 6467Moves this window. This API uses a promise to return the result. 6468 6469This operation is not supported in a window in full-screen mode. 6470 6471> **NOTE** 6472> 6473> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [moveWindowTo()](#movewindowto9-1) instead. 6474 6475**System capability**: SystemCapability.WindowManager.WindowManager.Core 6476 6477**Parameters** 6478 6479| Name | Type | Mandatory | Description | 6480| ---- | ------ | --------- | ------------------------------------------------------------ | 6481| x | number | Yes | Distance that the window moves along the x-axis, in px. A positive value indicates that the window moves to the right. The value must be an integer. If a floating point number is passed in, the value is rounded down. | 6482| y | number | Yes | Distance that the window moves along the y-axis, in px. A positive value indicates that the window moves downwards. The value must be an integer. If a floating point number is passed in, the value is rounded down. | 6483 6484**Return value** 6485 6486| Type | Description | 6487| ------------------- | ------------------------------ | 6488| Promise<void> | Promise that returns no value. | 6489 6490**Example** 6491 6492```ts 6493import { BusinessError } from '@kit.BasicServicesKit'; 6494 6495let promise = windowClass.moveTo(300, 300); 6496promise.then(() => { 6497 console.info('Succeeded in moving the window.'); 6498}).catch((err: BusinessError) => { 6499 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 6500}); 6501``` 6502 6503### resetSize<sup>(deprecated)</sup> 6504 6505resetSize(width: number, height: number, callback: AsyncCallback<void>): void 6506 6507Changes the size of this window. This API uses an asynchronous callback to return the result. 6508 6509The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 6510The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 6511 6512The system window has the following size limits: [0, 1920] in width and [0, 1920] in height, both in units of vp. 6513 6514The window width and height you set must meet the limits. The rules are as follows: 6515- 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. 6516- 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. 6517 6518This operation is not supported in a window in full-screen mode. 6519 6520> **NOTE** 6521> 6522> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9) instead. 6523 6524**System capability**: SystemCapability.WindowManager.WindowManager.Core 6525 6526**Parameters** 6527 6528| Name | Type | Mandatory | Description | 6529| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 6530| 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. | 6531| 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. | 6532| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6533 6534**Example** 6535 6536```ts 6537import { BusinessError } from '@kit.BasicServicesKit'; 6538 6539windowClass.resetSize(500, 1000, (err: BusinessError) => { 6540 const errCode: number = err.code; 6541 if (errCode) { 6542 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 6543 return; 6544 } 6545 console.info('Succeeded in changing the window size.'); 6546}); 6547``` 6548 6549### resetSize<sup>(deprecated)</sup> 6550 6551resetSize(width: number, height: number): Promise<void> 6552 6553Changes the size of this window. This API uses a promise to return the result. 6554 6555The main window and subwindow have the following default size limits: [320, 1920] in width and [240, 1920] in height, both in units of vp. 6556The minimum width and height of the main window and subwindow of the application depends on the configuration on the product side. You can call [getWindowLimits](#getwindowlimits11) to obtain size limits. 6557 6558The system window has the following size limits: [0, 1920] in width and [0, 1920] in height, both in units of vp. 6559 6560The window width and height you set must meet the limits. The rules are as follows: 6561- 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. 6562- 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. 6563 6564This operation is not supported in a window in full-screen mode. 6565 6566> **NOTE** 6567> 6568> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [resize()](#resize9-1) instead. 6569 6570**System capability**: SystemCapability.WindowManager.WindowManager.Core 6571 6572**Parameters** 6573 6574| Name | Type | Mandatory | Description | 6575| ------ | ------ | --------- | ------------------------------------------------------------ | 6576| 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. | 6577| 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. | 6578 6579**Return value** 6580 6581| Type | Description | 6582| ------------------- | ------------------------------ | 6583| Promise<void> | Promise that returns no value. | 6584 6585**Example** 6586 6587```ts 6588import { BusinessError } from '@kit.BasicServicesKit'; 6589 6590let promise = windowClass.resetSize(500, 1000); 6591promise.then(() => { 6592 console.info('Succeeded in changing the window size.'); 6593}).catch((err: BusinessError) => { 6594 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 6595}); 6596``` 6597 6598### getProperties<sup>(deprecated)</sup> 6599 6600getProperties(callback: AsyncCallback<WindowProperties>): void 6601 6602Obtains the properties of this window. This API uses an asynchronous callback to return the result. 6603 6604> **NOTE** 6605> 6606> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 6607 6608**System capability**: SystemCapability.WindowManager.WindowManager.Core 6609 6610**Parameters** 6611 6612| Name | Type | Mandatory | Description | 6613| -------- | ---------------------------------------------------------- | --------- | ---------------------------------------------- | 6614| callback | AsyncCallback<[WindowProperties](#windowproperties)> | Yes | Callback used to return the window properties. | 6615 6616**Example** 6617 6618```ts 6619import { BusinessError } from '@kit.BasicServicesKit'; 6620 6621windowClass.getProperties((err: BusinessError, data) => { 6622 const errCode: number = err.code; 6623 if (errCode) { 6624 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 6625 return; 6626 } 6627 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 6628}); 6629``` 6630 6631### getProperties<sup>(deprecated)</sup> 6632 6633getProperties(): Promise<WindowProperties> 6634 6635Obtains the properties of this window. This API uses a promise to return the result. 6636 6637> **NOTE** 6638> 6639> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getWindowProperties()](#getwindowproperties9) instead. 6640 6641**System capability**: SystemCapability.WindowManager.WindowManager.Core 6642 6643**Return value** 6644 6645| Type | Description | 6646| ---------------------------------------------------- | --------------------------------------------- | 6647| Promise<[WindowProperties](#windowproperties)> | Promise used to return the window properties. | 6648 6649**Example** 6650 6651```ts 6652import { BusinessError } from '@kit.BasicServicesKit'; 6653 6654let promise = windowClass.getProperties(); 6655promise.then((data) => { 6656 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 6657}).catch((err: BusinessError) => { 6658 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 6659}); 6660``` 6661 6662### getAvoidArea<sup>(deprecated)</sup> 6663 6664getAvoidArea(type: [AvoidAreaType](#avoidareatype7), callback: AsyncCallback<[AvoidArea](#avoidarea7)>): void 6665 6666Obtains 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. 6667 6668> **NOTE** 6669> 6670> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 6671 6672**System capability**: SystemCapability.WindowManager.WindowManager.Core 6673 6674**Parameters** 6675 6676| Name | Type | Mandatory | Description | 6677| -------- | --------------------------------------------- | --------- | --------------------------------- | 6678| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. | 6679| callback | AsyncCallback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 6680 6681**Example** 6682 6683```ts 6684import { BusinessError } from '@kit.BasicServicesKit'; 6685 6686let type = window.AvoidAreaType.TYPE_SYSTEM; 6687windowClass.getAvoidArea(type, (err: BusinessError, data) => { 6688 const errCode: number = err.code; 6689 if (errCode) { 6690 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 6691 return; 6692 } 6693 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 6694}); 6695``` 6696 6697### getAvoidArea<sup>(deprecated)</sup> 6698 6699getAvoidArea(type: [AvoidAreaType](#avoidareatype7)): Promise<[AvoidArea](#avoidarea7)> 6700 6701Obtains 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. 6702 6703> **NOTE** 6704> 6705> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getWindowAvoidArea()](#getwindowavoidarea9) instead. 6706 6707**System capability**: SystemCapability.WindowManager.WindowManager.Core 6708 6709**Parameters** 6710 6711| Name | Type | Mandatory | Description | 6712| ---- | -------------------------------- | --------- | ----------------- | 6713| type | [AvoidAreaType](#avoidareatype7) | Yes | Type of the area. | 6714 6715**Return value** 6716 6717| Type | Description | 6718| --------------------------------------- | -------------------------------- | 6719| Promise<[AvoidArea](#avoidarea7)> | Promise used to return the area. | 6720 6721**Example** 6722 6723```ts 6724import { BusinessError } from '@kit.BasicServicesKit'; 6725 6726let type = window.AvoidAreaType.TYPE_SYSTEM; 6727let promise = windowClass.getAvoidArea(type); 6728promise.then((data) => { 6729 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 6730}).catch((err: BusinessError) => { 6731 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 6732}); 6733``` 6734 6735### setFullScreen<sup>(deprecated)</sup> 6736 6737setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void 6738 6739Sets whether the main window or the subwindow is in full-screen mode. This API uses an asynchronous callback to return the result. 6740- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them. 6741- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them. 6742 6743> **NOTE** 6744> 6745> 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. 6746 6747**System capability**: SystemCapability.WindowManager.WindowManager.Core 6748 6749**Parameters** 6750 6751| Name | Type | Mandatory | Description | 6752| ------------ | ------------------------- | --------- | ------------------------------------------------------------ | 6753| 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. | 6754| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6755 6756**Example** 6757 6758```ts 6759// EntryAbility.ets 6760import { UIAbility } from '@kit.AbilityKit'; 6761import { BusinessError } from '@kit.BasicServicesKit'; 6762 6763export default class EntryAbility extends UIAbility { 6764 // ... 6765 onWindowStageCreate(windowStage: window.WindowStage): void { 6766 console.info('onWindowStageCreate'); 6767 let windowClass: window.Window | undefined = undefined; 6768 windowStage.getMainWindow((err: BusinessError, data) => { 6769 const errCode: number = err.code; 6770 if (errCode) { 6771 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6772 return; 6773 } 6774 windowClass = data; 6775 let isFullScreen: boolean = true; 6776 windowClass.setFullScreen(isFullScreen, (err: BusinessError) => { 6777 const errCode: number = err.code; 6778 if (errCode) { 6779 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 6780 return; 6781 } 6782 console.info('Succeeded in enabling the full-screen mode.'); 6783 }); 6784 }); 6785 } 6786} 6787``` 6788 6789### setFullScreen<sup>(deprecated)</sup> 6790 6791setFullScreen(isFullScreen: boolean): Promise<void> 6792 6793Sets whether the main window or the subwindow is in full-screen mode. This API uses a promise to return the result. 6794- In full-screen mode, the layout does not avoid the status bar and navigation bar, and components may overlap with them. 6795- In non-full-screen mode, the layout avoids the status bar and navigation bar, and components do not overlap with them. 6796 6797> **NOTE** 6798> 6799> 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. 6800 6801**System capability**: SystemCapability.WindowManager.WindowManager.Core 6802 6803**Parameters** 6804 6805| Name | Type | Mandatory | Description | 6806| ------------ | ------- | --------- | ------------------------------------------------------------ | 6807| 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. | 6808 6809**Return value** 6810 6811| Type | Description | 6812| ------------------- | ------------------------------ | 6813| Promise<void> | Promise that returns no value. | 6814 6815**Example** 6816 6817```ts 6818// EntryAbility.ets 6819import { UIAbility } from '@kit.AbilityKit'; 6820import { BusinessError } from '@kit.BasicServicesKit'; 6821 6822export default class EntryAbility extends UIAbility { 6823 // ... 6824 onWindowStageCreate(windowStage: window.WindowStage): void { 6825 console.info('onWindowStageCreate'); 6826 let windowClass: window.Window | undefined = undefined; 6827 windowStage.getMainWindow((err: BusinessError, data) => { 6828 const errCode: number = err.code; 6829 if (errCode) { 6830 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6831 return; 6832 } 6833 windowClass = data; 6834 let isFullScreen: boolean = true; 6835 let promise = windowClass.setFullScreen(isFullScreen); 6836 promise.then(() => { 6837 console.info('Succeeded in enabling the full-screen mode.'); 6838 }).catch((err: BusinessError) => { 6839 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 6840 }); 6841 }); 6842 } 6843} 6844``` 6845 6846### setLayoutFullScreen<sup>(deprecated)</sup> 6847 6848setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 6849 6850Sets whether the main window layout or the subwindow layout is immersive. This API uses an asynchronous callback to return the result. 6851- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 6852- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 6853 6854> **NOTE** 6855> 6856> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9) instead. 6857 6858**System capability**: SystemCapability.WindowManager.WindowManager.Core 6859 6860**Parameters** 6861 6862| Name | Type | Mandatory | Description | 6863| ------------------ | ------------------------- | --------- | ------------------------------------------------------------ | 6864| 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. | 6865| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6866 6867**Example** 6868 6869```ts 6870// EntryAbility.ets 6871import { UIAbility } from '@kit.AbilityKit'; 6872import { BusinessError } from '@kit.BasicServicesKit'; 6873 6874export default class EntryAbility extends UIAbility { 6875 // ... 6876 onWindowStageCreate(windowStage: window.WindowStage): void { 6877 console.info('onWindowStageCreate'); 6878 let windowClass: window.Window | undefined = undefined; 6879 windowStage.getMainWindow((err: BusinessError, data) => { 6880 const errCode: number = err.code; 6881 if (errCode) { 6882 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6883 return; 6884 } 6885 windowClass = data; 6886 let isLayoutFullScreen: boolean = true; 6887 windowClass.setLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 6888 const errCode: number = err.code; 6889 if (errCode) { 6890 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 6891 return; 6892 } 6893 console.info('Succeeded in setting the window layout to full-screen mode.'); 6894 }); 6895 }); 6896 } 6897} 6898``` 6899 6900### setLayoutFullScreen<sup>(deprecated)</sup> 6901 6902setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 6903 6904Sets whether the main window layout or the subwindow layout is immersive. This API uses a promise to return the result. 6905- An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. 6906- A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. 6907 6908> **NOTE** 6909> 6910> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9-1) instead. 6911 6912**System capability**: SystemCapability.WindowManager.WindowManager.Core 6913 6914**Parameters** 6915 6916| Name | Type | Mandatory | Description | 6917| ------------------ | ------- | --------- | ------------------------------------------------------------ | 6918| 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. | 6919 6920**Return value** 6921 6922| Type | Description | 6923| ------------------- | ------------------------------ | 6924| Promise<void> | Promise that returns no value. | 6925 6926**Example** 6927 6928```ts 6929// EntryAbility.ets 6930import { UIAbility } from '@kit.AbilityKit'; 6931import { BusinessError } from '@kit.BasicServicesKit'; 6932 6933export default class EntryAbility extends UIAbility { 6934 // ... 6935 onWindowStageCreate(windowStage: window.WindowStage): void { 6936 console.info('onWindowStageCreate'); 6937 let windowClass: window.Window | undefined = undefined; 6938 windowStage.getMainWindow((err: BusinessError, data) => { 6939 const errCode: number = err.code; 6940 if (errCode) { 6941 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6942 return; 6943 } 6944 windowClass = data; 6945 let isLayoutFullScreen: boolean = true; 6946 let promise = windowClass.setLayoutFullScreen(isLayoutFullScreen); 6947 promise.then(() => { 6948 console.info('Succeeded in setting the window layout to full-screen mode.'); 6949 }).catch((err: BusinessError) => { 6950 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 6951 }); 6952 }); 6953 } 6954} 6955``` 6956 6957### setSystemBarEnable<sup>(deprecated)</sup> 6958 6959setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 6960 6961Sets 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--> 6962 6963This API does not take effect when it is called by a subwindow. 6964 6965> **NOTE** 6966> 6967> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9) instead. 6968 6969**System capability**: SystemCapability.WindowManager.WindowManager.Core 6970 6971**Parameters** 6972 6973| Name | Type | Mandatory | Description | 6974| -------- | ----------------------------- | --------- | ------------------------------------------------------------ | 6975| 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 show all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed. | 6976| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 6977 6978 6979**Example** 6980 6981```ts 6982// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 6983// EntryAbility.ets 6984import { UIAbility } from '@kit.AbilityKit'; 6985import { BusinessError } from '@kit.BasicServicesKit'; 6986 6987export default class EntryAbility extends UIAbility { 6988 // ... 6989 onWindowStageCreate(windowStage: window.WindowStage): void { 6990 console.info('onWindowStageCreate'); 6991 let windowClass: window.Window | undefined = undefined; 6992 windowStage.getMainWindow((err: BusinessError, data) => { 6993 const errCode: number = err.code; 6994 if (errCode) { 6995 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6996 return; 6997 } 6998 windowClass = data; 6999 let names: Array<'status' | 'navigation'> = []; 7000 windowClass.setSystemBarEnable(names, (err: BusinessError) => { 7001 const errCode: number = err.code; 7002 if (errCode) { 7003 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 7004 return; 7005 } 7006 console.info('Succeeded in setting the system bar to be invisible.'); 7007 }); 7008 }); 7009 } 7010} 7011``` 7012 7013### setSystemBarEnable<sup>(deprecated)</sup> 7014 7015setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 7016 7017Sets 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--> 7018 7019This API does not take effect when it is called by a subwindow. 7020 7021> **NOTE** 7022> 7023> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowSystemBarEnable()](#setwindowsystembarenable9-1) instead. 7024 7025**System capability**: SystemCapability.WindowManager.WindowManager.Core 7026 7027**Parameters** 7028 7029| Name | Type | Mandatory | Description | 7030| ----- | ----------------------------- | --------- | ------------------------------------------------------------ | 7031| 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 show all of them, set this parameter to **['status', 'navigation']**. By default, they are not displayed. | 7032 7033**Return value** 7034 7035| Type | Description | 7036| ------------------- | ------------------------------ | 7037| Promise<void> | Promise that returns no value. | 7038 7039 7040**Example** 7041 7042```ts 7043// In this example, the three-button navigation bar, status bar, and bottom navigation bar are not displayed. 7044// EntryAbility.ets 7045import { UIAbility } from '@kit.AbilityKit'; 7046import { BusinessError } from '@kit.BasicServicesKit'; 7047 7048export default class EntryAbility extends UIAbility { 7049 // ... 7050 onWindowStageCreate(windowStage: window.WindowStage): void { 7051 console.info('onWindowStageCreate'); 7052 let windowClass: window.Window | undefined = undefined; 7053 windowStage.getMainWindow((err: BusinessError, data) => { 7054 const errCode: number = err.code; 7055 if (errCode) { 7056 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7057 return; 7058 } 7059 windowClass = data; 7060 let names: Array<'status' | 'navigation'> = []; 7061 let promise = windowClass.setSystemBarEnable(names); 7062 promise.then(() => { 7063 console.info('Succeeded in setting the system bar to be invisible.'); 7064 }).catch((err: BusinessError) => { 7065 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 7066 }); 7067 }); 7068 } 7069} 7070``` 7071 7072### setSystemBarProperties<sup>(deprecated)</sup> 7073 7074setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 7075 7076Sets 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--> 7077 7078This API does not take effect when it is called by a subwindow. 7079 7080> **NOTE** 7081> 7082> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9) instead. 7083 7084**System capability**: SystemCapability.WindowManager.WindowManager.Core 7085 7086**Parameters** 7087 7088| Name | Type | Mandatory | Description | 7089| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 7090| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar. | 7091| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7092 7093**Example** 7094 7095```ts 7096// EntryAbility.ets 7097import { UIAbility } from '@kit.AbilityKit'; 7098import { BusinessError } from '@kit.BasicServicesKit'; 7099 7100export default class EntryAbility extends UIAbility { 7101 // ... 7102 onWindowStageCreate(windowStage: window.WindowStage): void { 7103 console.info('onWindowStageCreate'); 7104 let windowClass: window.Window | undefined = undefined; 7105 windowStage.getMainWindow((err: BusinessError, data) => { 7106 const errCode: number = err.code; 7107 if (errCode) { 7108 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7109 return; 7110 } 7111 windowClass = data; 7112 let SystemBarProperties: window.SystemBarProperties = { 7113 statusBarColor: '#ff00ff', 7114 navigationBarColor: '#00ff00', 7115 // The following properties are supported since API version 8. 7116 statusBarContentColor: '#ffffff', 7117 navigationBarContentColor: '#00ffff' 7118 }; 7119 windowClass.setSystemBarProperties(SystemBarProperties, (err) => { 7120 const errCode: number = err.code; 7121 if (errCode) { 7122 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 7123 return; 7124 } 7125 console.info('Succeeded in setting the system bar properties.'); 7126 }); 7127 }); 7128 } 7129} 7130``` 7131 7132### setSystemBarProperties<sup>(deprecated)</sup> 7133 7134setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 7135 7136Sets 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--> 7137 7138This API does not take effect when it is called by a subwindow. 7139 7140> **NOTE** 7141> 7142> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowSystemBarProperties()](#setwindowsystembarproperties9-1) instead. 7143 7144**System capability**: SystemCapability.WindowManager.WindowManager.Core 7145 7146**Parameters** 7147 7148| Name | Type | Mandatory | Description | 7149| ------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------ | 7150| systemBarProperties | [SystemBarProperties](#systembarproperties) | Yes | Properties of the three-button navigation bar and status bar. | 7151 7152**Return value** 7153 7154| Type | Description | 7155| ------------------- | ------------------------------ | 7156| Promise<void> | Promise that returns no value. | 7157 7158**Example** 7159 7160```ts 7161// EntryAbility.ets 7162import { UIAbility } from '@kit.AbilityKit'; 7163import { BusinessError } from '@kit.BasicServicesKit'; 7164 7165export default class EntryAbility extends UIAbility { 7166 // ... 7167 onWindowStageCreate(windowStage: window.WindowStage): void { 7168 console.info('onWindowStageCreate'); 7169 let windowClass: window.Window | undefined = undefined; 7170 windowStage.getMainWindow((err: BusinessError, data) => { 7171 const errCode: number = err.code; 7172 if (errCode) { 7173 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7174 return; 7175 } 7176 windowClass = data; 7177 let SystemBarProperties: window.SystemBarProperties = { 7178 statusBarColor: '#ff00ff', 7179 navigationBarColor: '#00ff00', 7180 // The following properties are supported since API version 8. 7181 statusBarContentColor: '#ffffff', 7182 navigationBarContentColor: '#00ffff' 7183 }; 7184 let promise = windowClass.setSystemBarProperties(SystemBarProperties); 7185 promise.then(() => { 7186 console.info('Succeeded in setting the system bar properties.'); 7187 }).catch((err: BusinessError) => { 7188 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 7189 }); 7190 }); 7191 } 7192} 7193``` 7194 7195### loadContent<sup>(deprecated)</sup> 7196 7197loadContent(path: string, callback: AsyncCallback<void>): void 7198 7199Loads content from a page to this window. This API uses an asynchronous callback to return the result. 7200 7201> **NOTE** 7202> 7203> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9) instead. 7204 7205**System capability**: SystemCapability.WindowManager.WindowManager.Core 7206 7207**Parameters** 7208 7209| Name | Type | Mandatory | Description | 7210| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 7211| 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. | 7212| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7213 7214**Example** 7215 7216```ts 7217import { BusinessError } from '@kit.BasicServicesKit'; 7218 7219windowClass.loadContent('pages/page2/page3', (err: BusinessError) => { 7220 const errCode: number = err.code; 7221 if (errCode) { 7222 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 7223 return; 7224 } 7225 console.info('Succeeded in loading the content.'); 7226}); 7227``` 7228 7229### loadContent<sup>(deprecated)</sup> 7230 7231loadContent(path: string): Promise<void> 7232 7233Loads content from a page to this window. This API uses a promise to return the result. 7234 7235> **NOTE** 7236> 7237> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setUIContent()](#setuicontent9-1) instead. 7238 7239**System capability**: SystemCapability.WindowManager.WindowManager.Core 7240 7241**Parameters** 7242 7243| Name | Type | Mandatory | Description | 7244| ---- | ------ | --------- | ------------------------------------------------------------ | 7245| 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. | 7246 7247**Return value** 7248 7249| Type | Description | 7250| ------------------- | ------------------------------ | 7251| Promise<void> | Promise that returns no value. | 7252 7253**Example** 7254 7255```ts 7256import { BusinessError } from '@kit.BasicServicesKit'; 7257 7258let promise = windowClass.loadContent('pages/page2/page3'); 7259promise.then(() => { 7260 console.info('Succeeded in loading the content.'); 7261}).catch((err: BusinessError) => { 7262 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 7263}); 7264``` 7265 7266### isShowing<sup>(deprecated)</sup> 7267 7268isShowing(callback: AsyncCallback<boolean>): void 7269 7270Checks whether this window is displayed. This API uses an asynchronous callback to return the result. 7271 7272> **NOTE** 7273> 7274> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 7275 7276**System capability**: SystemCapability.WindowManager.WindowManager.Core 7277 7278**Parameters** 7279 7280| Name | Type | Mandatory | Description | 7281| -------- | ---------------------------- | --------- | ------------------------------------------------------------ | 7282| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the window is displayed, and **false** means the opposite. | 7283 7284**Example** 7285 7286```ts 7287import { BusinessError } from '@kit.BasicServicesKit'; 7288 7289windowClass.isShowing((err: BusinessError, data) => { 7290 const errCode: number = err.code; 7291 if (errCode) { 7292 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 7293 return; 7294 } 7295 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 7296}); 7297``` 7298 7299### isShowing<sup>(deprecated)</sup> 7300 7301isShowing(): Promise<boolean> 7302 7303Checks whether this window is displayed. This API uses a promise to return the result. 7304 7305> **NOTE** 7306> 7307> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isWindowShowing()](#iswindowshowing9) instead. 7308 7309**System capability**: SystemCapability.WindowManager.WindowManager.Core 7310 7311**Return value** 7312 7313| Type | Description | 7314| ---------------------- | ------------------------------------------------------------ | 7315| Promise<boolean> | Promise used to return the result. The value **true** means that the window is displayed, and **false** means the opposite. | 7316 7317**Example** 7318 7319```ts 7320import { BusinessError } from '@kit.BasicServicesKit'; 7321 7322let promise = windowClass.isShowing(); 7323promise.then((data) => { 7324 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 7325}).catch((err: BusinessError) => { 7326 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 7327}); 7328``` 7329 7330### on('systemAvoidAreaChange')<sup>(deprecated)</sup> 7331 7332on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void 7333 7334Subscribes to the event indicating changes to the area where this window cannot be displayed. 7335 7336> **NOTE** 7337> 7338> This API is supported since API version 7 and deprecated since API version 9. Use [on('avoidAreaChange')](#onavoidareachange9) instead. 7339 7340**System capability**: SystemCapability.WindowManager.WindowManager.Core 7341 7342**Parameters** 7343 7344| Name | Type | Mandatory | Description | 7345| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------ | 7346| 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. | 7347| callback | Callback<[AvoidArea](#avoidarea7)> | Yes | Callback used to return the area. | 7348 7349 7350**Example** 7351 7352```ts 7353windowClass.on('systemAvoidAreaChange', (data) => { 7354 console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data)); 7355}); 7356``` 7357 7358### off('systemAvoidAreaChange')<sup>(deprecated)</sup> 7359 7360off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void 7361 7362Unsubscribes from the event indicating changes to the area where this window cannot be displayed. 7363 7364> **NOTE** 7365> 7366> This API is supported since API version 7 and deprecated since API version 9. Use [off('avoidAreaChange')](#offavoidareachange9) instead. 7367 7368**System capability**: SystemCapability.WindowManager.WindowManager.Core 7369 7370**Parameters** 7371 7372| Name | Type | Mandatory | Description | 7373| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------ | 7374| 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. | 7375| 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. | 7376 7377**Example** 7378 7379```ts 7380const callback = (avoidArea: window.AvoidArea) => { 7381 // ... 7382} 7383windowClass.on('systemAvoidAreaChange', callback); 7384windowClass.off('systemAvoidAreaChange', callback); 7385// Unregister all the callbacks that have been registered through on(). 7386windowClass.off('systemAvoidAreaChange'); 7387``` 7388 7389### isSupportWideGamut<sup>(deprecated)</sup> 7390 7391isSupportWideGamut(callback: AsyncCallback<boolean>): void 7392 7393Checks whether this window supports the wide-gamut color space. This API uses an asynchronous callback to return the result. 7394 7395> **NOTE** 7396> 7397> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9) instead. 7398 7399**System capability**: SystemCapability.WindowManager.WindowManager.Core 7400 7401**Parameters** 7402 7403| Name | Type | Mandatory | Description | 7404| -------- | ---------------------------- | --------- | ------------------------------------------------------------ | 7405| 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. | 7406 7407**Example** 7408 7409```ts 7410import { BusinessError } from '@kit.BasicServicesKit'; 7411 7412windowClass.isSupportWideGamut((err: BusinessError, data) => { 7413 const errCode: number = err.code; 7414 if (errCode) { 7415 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 7416 return; 7417 } 7418 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 7419}); 7420``` 7421 7422### isSupportWideGamut<sup>(deprecated)</sup> 7423 7424isSupportWideGamut(): Promise<boolean> 7425 7426Checks whether this window supports the wide-gamut color space. This API uses a promise to return the result. 7427 7428> **NOTE** 7429> 7430> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [isWindowSupportWideGamut()](#iswindowsupportwidegamut9-1) instead. 7431 7432**System capability**: SystemCapability.WindowManager.WindowManager.Core 7433 7434**Return value** 7435 7436| Type | Description | 7437| ---------------------- | ------------------------------------------------------------ | 7438| 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. | 7439 7440**Example** 7441 7442```ts 7443import { BusinessError } from '@kit.BasicServicesKit'; 7444 7445let promise = windowClass.isSupportWideGamut(); 7446promise.then((data) => { 7447 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 7448}).catch((err: BusinessError) => { 7449 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 7450}); 7451``` 7452 7453### setColorSpace<sup>(deprecated)</sup> 7454 7455setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 7456 7457Sets a color space for this window. This API uses an asynchronous callback to return the result. 7458 7459> **NOTE** 7460> 7461> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9) instead. 7462 7463**System capability**: SystemCapability.WindowManager.WindowManager.Core 7464 7465**Parameters** 7466 7467| Name | Type | Mandatory | Description | 7468| ---------- | -------------------------- | --------- | ----------------------------------- | 7469| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set. | 7470| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7471 7472 7473**Example** 7474 7475```ts 7476import { BusinessError } from '@kit.BasicServicesKit'; 7477 7478windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 7479 const errCode: number = err.code; 7480 if (errCode) { 7481 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 7482 return; 7483 } 7484 console.info('Succeeded in setting window colorspace.'); 7485}); 7486``` 7487 7488### setColorSpace<sup>(deprecated)</sup> 7489 7490setColorSpace(colorSpace:ColorSpace): Promise<void> 7491 7492Sets a color space for this window. This API uses a promise to return the result. 7493 7494> **NOTE** 7495> 7496> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setWindowColorSpace()](#setwindowcolorspace9-1) instead. 7497 7498**System capability**: SystemCapability.WindowManager.WindowManager.Core 7499 7500**Parameters** 7501 7502| Name | Type | Mandatory | Description | 7503| ---------- | -------------------------- | --------- | ------------------- | 7504| colorSpace | [ColorSpace](#colorspace8) | Yes | Color space to set. | 7505 7506**Return value** 7507 7508| Type | Description | 7509| ------------------- | ------------------------------ | 7510| Promise<void> | Promise that returns no value. | 7511 7512 7513**Example** 7514 7515```ts 7516import { BusinessError } from '@kit.BasicServicesKit'; 7517 7518let promise = windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT); 7519promise.then(() => { 7520 console.info('Succeeded in setting window colorspace.'); 7521}).catch((err: BusinessError) => { 7522 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 7523}); 7524``` 7525 7526### getColorSpace<sup>(deprecated)</sup> 7527 7528getColorSpace(callback: AsyncCallback<ColorSpace>): void 7529 7530Obtains the color space of this window. This API uses an asynchronous callback to return the result. 7531 7532> **NOTE** 7533> 7534> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 7535 7536**System capability**: SystemCapability.WindowManager.WindowManager.Core 7537 7538**Parameters** 7539 7540| Name | Type | Mandatory | Description | 7541| -------- | ----------------------------------------------- | --------- | ------------------------------------------------------------ | 7542| 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. | 7543 7544**Example** 7545 7546```ts 7547import { BusinessError } from '@kit.BasicServicesKit'; 7548 7549windowClass.getColorSpace((err: BusinessError, data) => { 7550 const errCode: number = err.code; 7551 if (errCode) { 7552 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 7553 return; 7554 } 7555 console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data)); 7556}); 7557``` 7558 7559### getColorSpace<sup>(deprecated)</sup> 7560 7561getColorSpace(): Promise<ColorSpace> 7562 7563Obtains the color space of this window. This API uses a promise to return the result. 7564 7565> **NOTE** 7566> 7567> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getWindowColorSpace()](#getwindowcolorspace9) instead. 7568 7569**System capability**: SystemCapability.WindowManager.WindowManager.Core 7570 7571**Return value** 7572 7573| Type | Description | 7574| ----------------------------------------- | ----------------------------------------------- | 7575| Promise<[ColorSpace](#colorspace8)> | Promise used to return the current color space. | 7576 7577**Example** 7578 7579```ts 7580import { BusinessError } from '@kit.BasicServicesKit'; 7581 7582let promise = windowClass.getColorSpace(); 7583promise.then((data) => { 7584 console.info('Succeeded in getting window color space. Cause:' + JSON.stringify(data)); 7585}).catch((err: BusinessError) => { 7586 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 7587}); 7588``` 7589 7590### setBackgroundColor<sup>(deprecated)</sup> 7591 7592setBackgroundColor(color: string, callback: AsyncCallback<void>): void 7593 7594Sets 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. 7595 7596> **NOTE** 7597> 7598> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 7599 7600**System capability**: SystemCapability.WindowManager.WindowManager.Core 7601 7602**Parameters** 7603 7604| Name | Type | Mandatory | Description | 7605| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 7606| 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'**. | 7607| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7608 7609 7610**Example** 7611 7612```ts 7613import { BusinessError } from '@kit.BasicServicesKit'; 7614 7615let color: string = '#00ff33'; 7616windowClass.setBackgroundColor(color, (err: BusinessError) => { 7617 const errCode: number = err.code; 7618 if (errCode) { 7619 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 7620 return; 7621 } 7622 console.info('Succeeded in setting the background color.'); 7623}); 7624``` 7625 7626### setBackgroundColor<sup>(deprecated)</sup> 7627 7628setBackgroundColor(color: string): Promise<void> 7629 7630Sets 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. 7631 7632> **NOTE** 7633> 7634> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBackgroundColor()](#setwindowbackgroundcolor9) instead. 7635 7636**System capability**: SystemCapability.WindowManager.WindowManager.Core 7637 7638**Parameters** 7639 7640| Name | Type | Mandatory | Description | 7641| ----- | ------ | --------- | ------------------------------------------------------------ | 7642| 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'**. | 7643 7644**Return value** 7645 7646| Type | Description | 7647| ------------------- | ------------------------------ | 7648| Promise<void> | Promise that returns no value. | 7649 7650 7651**Example** 7652 7653```ts 7654import { BusinessError } from '@kit.BasicServicesKit'; 7655 7656let color: string = '#00ff33'; 7657let promise = windowClass.setBackgroundColor(color); 7658promise.then(() => { 7659 console.info('Succeeded in setting the background color.'); 7660}).catch((err: BusinessError) => { 7661 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 7662}); 7663``` 7664 7665### setBrightness<sup>(deprecated)</sup> 7666 7667setBrightness(brightness: number, callback: AsyncCallback<void>): void 7668 7669Sets the screen brightness for this window. This API uses an asynchronous callback to return the result. 7670 7671When 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. 7672 7673> **NOTE** 7674> 7675> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9) instead. 7676 7677**System capability**: SystemCapability.WindowManager.WindowManager.Core 7678 7679**Parameters** 7680 7681| Name | Type | Mandatory | Description | 7682| ---------- | ------------------------- | --------- | ------------------------------------------------------------ | 7683| 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. | 7684| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7685 7686 7687**Example** 7688 7689```ts 7690import { BusinessError } from '@kit.BasicServicesKit'; 7691 7692let brightness: number = 1; 7693windowClass.setBrightness(brightness, (err: BusinessError) => { 7694 const errCode: number = err.code; 7695 if (errCode) { 7696 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 7697 return; 7698 } 7699 console.info('Succeeded in setting the brightness.'); 7700}); 7701``` 7702 7703### setBrightness<sup>(deprecated)</sup> 7704 7705setBrightness(brightness: number): Promise<void> 7706 7707Sets the screen brightness for this window. This API uses a promise to return the result. 7708 7709When 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. 7710 7711> **NOTE** 7712> 7713> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowBrightness()](#setwindowbrightness9-1) instead. 7714 7715**System capability**: SystemCapability.WindowManager.WindowManager.Core 7716 7717**Parameters** 7718 7719| Name | Type | Mandatory | Description | 7720| ---------- | ------ | --------- | ------------------------------------------------------------ | 7721| 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. | 7722 7723**Return value** 7724 7725| Type | Description | 7726| ------------------- | ------------------------------ | 7727| Promise<void> | Promise that returns no value. | 7728 7729 7730**Example** 7731 7732```ts 7733import { BusinessError } from '@kit.BasicServicesKit'; 7734 7735let brightness: number = 1; 7736let promise = windowClass.setBrightness(brightness); 7737promise.then(() => { 7738 console.info('Succeeded in setting the brightness.'); 7739}).catch((err: BusinessError) => { 7740 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 7741}); 7742``` 7743 7744### setDimBehind<sup>(deprecated)</sup> 7745 7746setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void 7747 7748Sets the dimness of the window that is not on top. This API uses an asynchronous callback to return the result. 7749 7750> **NOTE** 7751> 7752> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 7753 7754**System capability**: SystemCapability.WindowManager.WindowManager.Core 7755 7756**Parameters** 7757 7758| Name | Type | Mandatory | Description | 7759| -------------- | ------------------------- | --------- | ------------------------------------------------------------ | 7760| 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. | 7761| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7762 7763**Example** 7764 7765```ts 7766import { BusinessError } from '@kit.BasicServicesKit'; 7767 7768windowClass.setDimBehind(0.5, (err: BusinessError) => { 7769 const errCode: number = err.code; 7770 if (errCode) { 7771 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 7772 return; 7773 } 7774 console.info('Succeeded in setting the dimness.'); 7775}); 7776``` 7777 7778### setDimBehind<sup>(deprecated)</sup> 7779 7780setDimBehind(dimBehindValue: number): Promise<void> 7781 7782Sets the dimness of the window that is not on top. This API uses a promise to return the result. 7783 7784> **NOTE** 7785> 7786> This API cannot be used. This API is supported since API version 7 and deprecated since API version 9. 7787 7788**System capability**: SystemCapability.WindowManager.WindowManager.Core 7789 7790**Parameters** 7791 7792| Name | Type | Mandatory | Description | 7793| -------------- | ------ | --------- | ------------------------------------------------------------ | 7794| dimBehindValue | number | Yes | Dimness of the window to set. The value ranges from 0 to 1. The value **1** indicates the dimmest. | 7795 7796**Return value** 7797 7798| Type | Description | 7799| ------------------- | ------------------------------ | 7800| Promise<void> | Promise that returns no value. | 7801 7802**Example** 7803 7804```ts 7805import { BusinessError } from '@kit.BasicServicesKit'; 7806 7807let promise = windowClass.setDimBehind(0.5); 7808promise.then(() => { 7809 console.info('Succeeded in setting the dimness.'); 7810}).catch((err: BusinessError) => { 7811 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 7812}); 7813``` 7814 7815### setFocusable<sup>(deprecated)</sup> 7816 7817setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 7818 7819Sets 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. 7820 7821> **NOTE** 7822> 7823> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9) instead. 7824 7825**System capability**: SystemCapability.WindowManager.WindowManager.Core 7826 7827**Parameters** 7828 7829| Name | Type | Mandatory | Description | 7830| ----------- | ------------------------- | --------- | ------------------------------------------------------------ | 7831| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 7832| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7833 7834 7835**Example** 7836 7837```ts 7838import { BusinessError } from '@kit.BasicServicesKit'; 7839 7840let isFocusable: boolean = true; 7841windowClass.setFocusable(isFocusable, (err: BusinessError) => { 7842 const errCode: number = err.code; 7843 if (errCode) { 7844 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 7845 return; 7846 } 7847 console.info('Succeeded in setting the window to be focusable.'); 7848}); 7849``` 7850 7851### setFocusable<sup>(deprecated)</sup> 7852 7853setFocusable(isFocusable: boolean): Promise<void> 7854 7855Sets 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. 7856 7857> **NOTE** 7858> 7859> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowFocusable()](#setwindowfocusable9-1) instead. 7860 7861**System capability**: SystemCapability.WindowManager.WindowManager.Core 7862 7863**Parameters** 7864 7865| Name | Type | Mandatory | Description | 7866| ----------- | ------- | --------- | ------------------------------------------------------------ | 7867| isFocusable | boolean | Yes | Whether the window can gain focus. The value **true** means that the window can gain focus, and **false** means the opposite. | 7868 7869**Return value** 7870 7871| Type | Description | 7872| ------------------- | ------------------------------ | 7873| Promise<void> | Promise that returns no value. | 7874 7875 7876**Example** 7877 7878```ts 7879import { BusinessError } from '@kit.BasicServicesKit'; 7880 7881let isFocusable: boolean = true; 7882let promise = windowClass.setFocusable(isFocusable); 7883promise.then(() => { 7884 console.info('Succeeded in setting the window to be focusable.'); 7885}).catch((err: BusinessError) => { 7886 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 7887}); 7888``` 7889 7890### setKeepScreenOn<sup>(deprecated)</sup> 7891 7892setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 7893 7894Sets whether to keep the screen always on. This API uses an asynchronous callback to return the result. 7895 7896> **NOTE** 7897> 7898> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9) instead. 7899 7900**System capability**: SystemCapability.WindowManager.WindowManager.Core 7901 7902**Parameters** 7903 7904| Name | Type | Mandatory | Description | 7905| -------------- | ------------------------- | --------- | ------------------------------------------------------------ | 7906| 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. | 7907| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7908 7909 7910**Example** 7911 7912```ts 7913import { BusinessError } from '@kit.BasicServicesKit'; 7914 7915let isKeepScreenOn: boolean = true; 7916windowClass.setKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 7917 const errCode: number = err.code; 7918 if (errCode) { 7919 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 7920 return; 7921 } 7922 console.info('Succeeded in setting the screen to be always on.'); 7923}); 7924``` 7925 7926### setKeepScreenOn<sup>(deprecated)</sup> 7927 7928setKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 7929 7930Sets whether to keep the screen always on. This API uses a promise to return the result. 7931 7932> **NOTE** 7933> 7934> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setWindowKeepScreenOn()](#setwindowkeepscreenon9-1) instead. 7935 7936**System capability**: SystemCapability.WindowManager.WindowManager.Core 7937 7938**Parameters** 7939 7940| Name | Type | Mandatory | Description | 7941| -------------- | ------- | --------- | ------------------------------------------------------------ | 7942| 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. | 7943 7944**Return value** 7945 7946| Type | Description | 7947| ------------------- | ------------------------------ | 7948| Promise<void> | Promise that returns no value. | 7949 7950**Example** 7951 7952```ts 7953import { BusinessError } from '@kit.BasicServicesKit'; 7954 7955let isKeepScreenOn: boolean = true; 7956let promise = windowClass.setKeepScreenOn(isKeepScreenOn); 7957promise.then(() => { 7958 console.info('Succeeded in setting the screen to be always on.'); 7959}).catch((err: BusinessError) => { 7960 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 7961}); 7962``` 7963 7964### setOutsideTouchable<sup>(deprecated)</sup> 7965 7966setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): void 7967 7968Sets whether the area outside the subwindow is touchable. This API uses an asynchronous callback to return the result. 7969 7970> **NOTE** 7971> 7972> This API is supported since API version 7 and deprecated since API version 9. 7973> 7974> Since API version 9, the area outside the subwindow is touchable by default. This API is no longer supported and no substitute API is provided. 7975 7976**System capability**: SystemCapability.WindowManager.WindowManager.Core 7977 7978**Parameters** 7979 7980| Name | Type | Mandatory | Description | 7981| --------- | ------------------------- | --------- | ------------------------------------------------------------ | 7982| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means the area outside the subwindow is touchable, and **false** means the opposite. | 7983| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 7984 7985**Example** 7986 7987```ts 7988import { BusinessError } from '@kit.BasicServicesKit'; 7989 7990windowClass.setOutsideTouchable(true, (err: BusinessError) => { 7991 const errCode: number = err.code; 7992 if (errCode) { 7993 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 7994 return; 7995 } 7996 console.info('Succeeded in setting the area to be touchable.'); 7997}); 7998``` 7999 8000### setOutsideTouchable<sup>(deprecated)</sup> 8001 8002setOutsideTouchable(touchable: boolean): Promise<void> 8003 8004Sets whether the area outside the subwindow is touchable. This API uses a promise to return the result. 8005 8006> **NOTE** 8007> 8008> This API is supported since API version 7 and deprecated since API version 9. 8009> 8010> Since API version 9, the area outside the subwindow is touchable by default. This API is no longer supported and no substitute API is provided. 8011 8012**System capability**: SystemCapability.WindowManager.WindowManager.Core 8013 8014**Parameters** 8015 8016| Name | Type | Mandatory | Description | 8017| --------- | ------- | --------- | ------------------------------------------------------------ | 8018| touchable | boolean | Yes | Whether the area outside the subwindow is touchable. The value **true** means the area outside the subwindow is touchable, and **false** means the opposite. | 8019 8020**Return value** 8021 8022| Type | Description | 8023| ------------------- | ------------------------------ | 8024| Promise<void> | Promise that returns no value. | 8025 8026**Example** 8027 8028```ts 8029import { BusinessError } from '@kit.BasicServicesKit'; 8030 8031let promise = windowClass.setOutsideTouchable(true); 8032promise.then(() => { 8033 console.info('Succeeded in setting the area to be touchable.'); 8034}).catch((err: BusinessError) => { 8035 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 8036}); 8037``` 8038 8039### setPrivacyMode<sup>(deprecated)</sup> 8040 8041setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 8042 8043Sets whether this window is in privacy mode. This API uses an asynchronous callback to return the result. 8044 8045A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 8046 8047> **NOTE** 8048> 8049> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9) instead. 8050 8051**System capability**: SystemCapability.WindowManager.WindowManager.Core 8052 8053**Parameters** 8054 8055| Name | Type | Mandatory | Description | 8056| ------------- | ------------------------- | --------- | ------------------------------------------------------------ | 8057| 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. | 8058| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8059 8060**Example** 8061 8062```ts 8063import { BusinessError } from '@kit.BasicServicesKit'; 8064 8065let isPrivacyMode: boolean = true; 8066windowClass.setPrivacyMode(isPrivacyMode, (err: BusinessError) => { 8067 const errCode: number = err.code; 8068 if (errCode) { 8069 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 8070 return; 8071 } 8072 console.info('Succeeded in setting the window to privacy mode.'); 8073}); 8074``` 8075 8076### setPrivacyMode<sup>(deprecated)</sup> 8077 8078setPrivacyMode(isPrivacyMode: boolean): Promise<void> 8079 8080Sets whether this window is in privacy mode. This API uses a promise to return the result. 8081 8082A window in privacy mode cannot be captured or recorded. This API can be used in scenarios where screen capture or recording is disabled. 8083 8084> **NOTE** 8085> 8086> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowPrivacyMode()](#setwindowprivacymode9-1) instead. 8087 8088**System capability**: SystemCapability.WindowManager.WindowManager.Core 8089 8090**Parameters** 8091 8092| Name | Type | Mandatory | Description | 8093| ------------- | ------- | --------- | ------------------------------------------------------------ | 8094| 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. | 8095 8096**Return value** 8097 8098| Type | Description | 8099| ------------------- | ------------------------------ | 8100| Promise<void> | Promise that returns no value. | 8101 8102**Example** 8103 8104```ts 8105import { BusinessError } from '@kit.BasicServicesKit'; 8106 8107let isPrivacyMode: boolean = true; 8108let promise = windowClass.setPrivacyMode(isPrivacyMode); 8109promise.then(() => { 8110 console.info('Succeeded in setting the window to privacy mode.'); 8111}).catch((err: BusinessError) => { 8112 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 8113}); 8114``` 8115 8116### setTouchable<sup>(deprecated)</sup> 8117 8118setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 8119 8120Sets whether this window is touchable. This API uses an asynchronous callback to return the result. 8121 8122> **NOTE** 8123> 8124> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9) instead. 8125 8126**System capability**: SystemCapability.WindowManager.WindowManager.Core 8127 8128**Parameters** 8129 8130| Name | Type | Mandatory | Description | 8131| ----------- | ------------------------- | --------- | ------------------------------------------------------------ | 8132| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite. | 8133| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8134 8135 8136**Example** 8137 8138```ts 8139import { BusinessError } from '@kit.BasicServicesKit'; 8140 8141let isTouchable = true; 8142windowClass.setTouchable(isTouchable, (err: BusinessError) => { 8143 const errCode: number = err.code; 8144 if (errCode) { 8145 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 8146 return; 8147 } 8148 console.info('Succeeded in setting the window to be touchable.'); 8149}); 8150``` 8151 8152### setTouchable<sup>(deprecated)</sup> 8153 8154setTouchable(isTouchable: boolean): Promise<void> 8155 8156Sets whether this window is touchable. This API uses a promise to return the result. 8157 8158> **NOTE** 8159> 8160> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setWindowTouchable()](#setwindowtouchable9-1) instead. 8161 8162**System capability**: SystemCapability.WindowManager.WindowManager.Core 8163 8164**Parameters** 8165 8166| Name | Type | Mandatory | Description | 8167| ----------- | ------- | --------- | ------------------------------------------------------------ | 8168| isTouchable | boolean | Yes | Whether the window is touchable. The value **true** means that the window is touchable, and **false** means the opposite. | 8169 8170**Return value** 8171 8172| Type | Description | 8173| ------------------- | ------------------------------ | 8174| Promise<void> | Promise that returns no value. | 8175 8176 8177**Example** 8178 8179```ts 8180import { BusinessError } from '@kit.BasicServicesKit'; 8181 8182let isTouchable = true; 8183let promise = windowClass.setTouchable(isTouchable); 8184promise.then(() => { 8185 console.info('Succeeded in setting the window to be touchable.'); 8186}).catch((err: BusinessError) => { 8187 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 8188}); 8189``` 8190 8191## WindowStageEventType<sup>9+</sup> 8192 8193Describes the lifecycle of a window stage. 8194 8195**Model restriction**: This API can be used only in the stage model. 8196 8197**System capability**: SystemCapability.WindowManager.WindowManager.Core 8198 8199**Atomic service API**: This API can be used in atomic services since API version 11. 8200 8201| Name | Value | Description | 8202| --------------------- | ----- | ------------------------------------------------------------ | 8203| SHOWN | 1 | The window stage is running in the foreground. | 8204| ACTIVE | 2 | The window stage gains focus. | 8205| INACTIVE | 3 | The window stage loses focus. | 8206| HIDDEN | 4 | The window stage is running in the background. | 8207| RESUMED<sup>11+</sup> | 5 | The window stage is interactive in the foreground, for example, when the user touches the application icon on the recent tasks screen to open the application again. | 8208| PAUSED<sup>11+</sup> | 6 | The window stage is non-interactive in the foreground, for example, when the user swipes up from the bottom of the screen and hold to access the recent tasks screen. | 8209 8210## SubWindowOptions<sup>11+</sup> 8211 8212Describes the parameters used for creating a subwindow. 8213 8214**Atomic service API**: This API can be used in atomic services since API version 12. 8215 8216**System capability**: SystemCapability.Window.SessionManager 8217 8218| Name | Type | Read Only | Optional | Description | 8219| --------------------- | ------- | --------- | -------- | ------------------------------------------------------------ | 8220| title | string | No | No | Title of the subwindow. | 8221| decorEnabled | boolean | No | No | Whether decorations are displayed in the subwindow. The value **true** means that decorations are displayed, and **false** means the opposite. | 8222| isModal<sup>12+</sup> | boolean | No | Yes | Whether the modal property is enabled for the subwindow. The value **true** means that modal property is enabled, and **false** means the opposite. When the modal property is enabled, the parent window cannot respond to user operations. The default value is **false**. | 8223 8224## WindowStage<sup>9+</sup> 8225 8226Implements a window manager, which manages each basic window unit, that is, [Window](#window) instance. 8227 8228Before 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. 8229 8230### getMainWindow<sup>9+</sup> 8231 8232getMainWindow(callback: AsyncCallback<Window>): void 8233 8234Obtains the main window of this window stage. This API uses an asynchronous callback to return the result. 8235 8236**Model restriction**: This API can be used only in the stage model. 8237 8238**System capability**: SystemCapability.WindowManager.WindowManager.Core 8239 8240**Atomic service API**: This API can be used in atomic services since API version 11. 8241 8242**Parameters** 8243 8244| Name | Type | Mandatory | Description | 8245| -------- | -------------------------------------- | --------- | ---------------------------------------- | 8246| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the main window. | 8247 8248**Error codes** 8249 8250For details about the error codes, see [Window Error Codes](errorcode-window.md). 8251 8252| ID | Error Message | 8253| ------- | ------------------------------ | 8254| 1300002 | This window state is abnormal. | 8255| 1300005 | This window stage is abnormal. | 8256 8257**Example** 8258 8259```ts 8260// EntryAbility.ets 8261import { UIAbility } from '@kit.AbilityKit'; 8262import { BusinessError } from '@kit.BasicServicesKit'; 8263 8264export default class EntryAbility extends UIAbility { 8265 // ... 8266 8267 onWindowStageCreate(windowStage: window.WindowStage) { 8268 console.log('onWindowStageCreate'); 8269 let windowClass: window.Window | undefined = undefined; 8270 windowStage.getMainWindow((err: BusinessError, data) => { 8271 const errCode: number = err.code; 8272 if (errCode) { 8273 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8274 return; 8275 } 8276 windowClass = data; 8277 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 8278 }); 8279 } 8280}; 8281``` 8282 8283### getMainWindow<sup>9+</sup> 8284 8285getMainWindow(): Promise<Window> 8286 8287Obtains the main window of this window stage. This API uses a promise to return the result. 8288 8289**Model restriction**: This API can be used only in the stage model. 8290 8291**System capability**: SystemCapability.WindowManager.WindowManager.Core 8292 8293**Atomic service API**: This API can be used in atomic services since API version 11. 8294 8295**Return value** 8296 8297| Type | Description | 8298| -------------------------------- | --------------------------------------- | 8299| Promise<[Window](#window)> | Promise used to return the main window. | 8300 8301**Error codes** 8302 8303For details about the error codes, see [Window Error Codes](errorcode-window.md). 8304 8305| ID | Error Message | 8306| ------- | ------------------------------ | 8307| 1300002 | This window state is abnormal. | 8308| 1300005 | This window stage is abnormal. | 8309 8310**Example** 8311 8312```ts 8313// EntryAbility.ets 8314import { UIAbility } from '@kit.AbilityKit'; 8315import { BusinessError } from '@kit.BasicServicesKit'; 8316 8317export default class EntryAbility extends UIAbility { 8318 // ... 8319 8320 onWindowStageCreate(windowStage: window.WindowStage) { 8321 console.log('onWindowStageCreate'); 8322 let windowClass: window.Window | undefined = undefined; 8323 let promise = windowStage.getMainWindow(); 8324 promise.then((data) => { 8325 windowClass = data; 8326 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 8327 }).catch((err: BusinessError) => { 8328 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8329 }); 8330 } 8331}; 8332``` 8333 8334### getMainWindowSync<sup>9+</sup> 8335 8336getMainWindowSync(): Window 8337 8338Obtains the main window of this window stage. 8339 8340**Model restriction**: This API can be used only in the stage model. 8341 8342**System capability**: SystemCapability.WindowManager.WindowManager.Core 8343 8344**Atomic service API**: This API can be used in atomic services since API version 11. 8345 8346**Return value** 8347 8348| Type | Description | 8349| ----------------- | ------------ | 8350| [Window](#window) | Main window. | 8351 8352**Error codes** 8353 8354For details about the error codes, see [Window Error Codes](errorcode-window.md). 8355 8356| ID | Error Message | 8357| ------- | ------------------------------ | 8358| 1300002 | This window state is abnormal. | 8359| 1300005 | This window stage is abnormal. | 8360 8361**Example** 8362<!--code_no_check--> 8363```ts 8364// EntryAbility.ets 8365import { UIAbility } from '@kit.AbilityKit'; 8366 8367export default class EntryAbility extends UIAbility { 8368 // ... 8369 8370 onWindowStageCreate(windowStage: window.WindowStage) { 8371 console.log('onWindowStageCreate'); 8372 try { 8373 let windowClass = windowStage.getMainWindowSync(); 8374 } catch (exception) { 8375 console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`); 8376 } 8377 } 8378}; 8379``` 8380 8381### createSubWindow<sup>9+</sup> 8382 8383createSubWindow(name: string, callback: AsyncCallback<Window>): void 8384 8385Creates a subwindow for this window stage. This API uses an asynchronous callback to return the result. 8386 8387**Model restriction**: This API can be used only in the stage model. 8388 8389**System capability**: SystemCapability.WindowManager.WindowManager.Core 8390 8391**Atomic service API**: This API can be used in atomic services since API version 11. 8392 8393**Parameters** 8394 8395| Name | Type | Mandatory | Description | 8396| -------- | -------------------------------------- | --------- | -------------------------------------- | 8397| name | string | Yes | Name of the subwindow. | 8398| callback | AsyncCallback<[Window](#window)> | Yes | Callback used to return the subwindow. | 8399 8400**Error codes** 8401 8402For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8403 8404| ID | Error Message | 8405| ------- | ----------------------------------------------------------- | 8406| 401 | Parameter error. Possible cause: Incorrect parameter types. | 8407| 1300002 | This window state is abnormal. | 8408| 1300005 | This window stage is abnormal. | 8409 8410**Example** 8411 8412```ts 8413// EntryAbility.ets 8414import { UIAbility } from '@kit.AbilityKit'; 8415import { BusinessError } from '@kit.BasicServicesKit'; 8416 8417export default class EntryAbility extends UIAbility { 8418 // ... 8419 8420 onWindowStageCreate(windowStage: window.WindowStage) { 8421 console.log('onWindowStageCreate'); 8422 let windowClass: window.Window | undefined = undefined; 8423 try { 8424 windowStage.createSubWindow('mySubWindow', (err: BusinessError, data) => { 8425 const errCode: number = err.code; 8426 if (errCode) { 8427 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 8428 return; 8429 } 8430 windowClass = data; 8431 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 8432 if (!windowClass) { 8433 console.info('Failed to load the content. Cause: windowClass is null'); 8434 } 8435 else { 8436 (windowClass as window.Window).resize(500, 1000); 8437 } 8438 }); 8439 } catch (exception) { 8440 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 8441 } 8442 } 8443}; 8444``` 8445 8446### createSubWindow<sup>9+</sup> 8447 8448createSubWindow(name: string): Promise<Window> 8449 8450Creates a subwindow for this window stage. This API uses a promise to return the result. 8451 8452**Model restriction**: This API can be used only in the stage model. 8453 8454**System capability**: SystemCapability.WindowManager.WindowManager.Core 8455 8456**Atomic service API**: This API can be used in atomic services since API version 11. 8457 8458**Parameters** 8459 8460| Name | Type | Mandatory | Description | 8461| ---- | ------ | --------- | ---------------------- | 8462| name | string | Yes | Name of the subwindow. | 8463 8464**Return value** 8465 8466| Type | Description | 8467| -------------------------------- | ------------------------------------- | 8468| Promise<[Window](#window)> | Promise used to return the subwindow. | 8469 8470**Error codes** 8471 8472For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8473 8474| ID | Error Message | 8475| ------- | ----------------------------------------------------------- | 8476| 401 | Parameter error. Possible cause: Incorrect parameter types. | 8477| 1300002 | This window state is abnormal. | 8478| 1300005 | This window stage is abnormal. | 8479 8480**Example** 8481 8482```ts 8483// EntryAbility.ets 8484import { UIAbility } from '@kit.AbilityKit'; 8485import { BusinessError } from '@kit.BasicServicesKit'; 8486 8487export default class EntryAbility extends UIAbility { 8488 // ... 8489 8490 onWindowStageCreate(windowStage: window.WindowStage) { 8491 console.log('onWindowStageCreate'); 8492 let windowClass: window.Window | undefined = undefined; 8493 try { 8494 let promise = windowStage.createSubWindow('mySubWindow'); 8495 promise.then((data) => { 8496 windowClass = data; 8497 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 8498 }).catch((err: BusinessError) => { 8499 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 8500 }); 8501 } catch (exception) { 8502 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 8503 } 8504 } 8505}; 8506``` 8507 8508### createSubWindowWithOptions<sup>11+</sup> 8509 8510createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 8511 8512Creates a subwindow for this window stage. This API uses a promise to return the result. 8513 8514**Model restriction**: This API can be used only in the stage model. 8515 8516**Atomic service API**: This API can be used in atomic services since API version 12. 8517 8518**System capability**: SystemCapability.Window.SessionManager 8519 8520**Parameters** 8521 8522| Name | Type | Mandatory | Description | 8523| ------- | --------------------------------------- | --------- | ------------------------------------------- | 8524| name | string | Yes | Name of the subwindow. | 8525| options | [SubWindowOptions](#subwindowoptions11) | Yes | Parameters used for creating the subwindow. | 8526 8527**Return value** 8528 8529| Type | Description | 8530| -------------------------------- | --------------------------------------------- | 8531| Promise<[Window](#window)> | Promise used to return the subwindow created. | 8532 8533**Error codes** 8534 8535For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8536 8537| ID | Error Message | 8538| ------- | ------------------------------------------------------------ | 8539| 401 | Parameter error. Possible cause: Incorrect parameter types. | 8540| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8541| 1300002 | This window state is abnormal. | 8542| 1300005 | This window stage is abnormal. | 8543 8544**Example** 8545 8546```ts 8547// EntryAbility.ets 8548import { UIAbility } from '@kit.AbilityKit'; 8549import { BusinessError } from '@kit.BasicServicesKit'; 8550 8551export default class EntryAbility extends UIAbility { 8552 // ... 8553 8554 onWindowStageCreate(windowStage: window.WindowStage) { 8555 console.info('onWindowStageCreate'); 8556 let windowClass: window.Window | undefined = undefined; 8557 try { 8558 let options : window.SubWindowOptions = { 8559 title: 'title', 8560 decorEnabled: true 8561 }; 8562 let promise = windowStage.createSubWindowWithOptions('mySubWindow', options); 8563 promise.then((data) => { 8564 windowClass = data; 8565 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 8566 }).catch((err: BusinessError) => { 8567 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 8568 }); 8569 } catch (exception) { 8570 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 8571 } 8572 } 8573}; 8574``` 8575 8576### getSubWindow<sup>9+</sup> 8577 8578getSubWindow(callback: AsyncCallback<Array<Window>>): void 8579 8580Obtains all the subwindows of this window stage. This API uses an asynchronous callback to return the result. 8581 8582**Model restriction**: This API can be used only in the stage model. 8583 8584**System capability**: SystemCapability.WindowManager.WindowManager.Core 8585 8586**Atomic service API**: This API can be used in atomic services since API version 11. 8587 8588**Parameters** 8589 8590| Name | Type | Mandatory | Description | 8591| -------- | --------------------------------------------------- | --------- | ------------------------------------------- | 8592| callback | AsyncCallback<Array<[Window](#window)>> | Yes | Callback used to return all the subwindows. | 8593 8594**Error codes** 8595 8596For details about the error codes, see [Window Error Codes](errorcode-window.md). 8597 8598| ID | Error Message | 8599| ------- | ------------------------------ | 8600| 1300005 | This window stage is abnormal. | 8601 8602**Example** 8603<!--code_no_check--> 8604```ts 8605// EntryAbility.ets 8606import { UIAbility } from '@kit.AbilityKit'; 8607import { BusinessError } from '@kit.BasicServicesKit'; 8608 8609export default class EntryAbility extends UIAbility { 8610 // ... 8611 8612 onWindowStageCreate(windowStage: window.WindowStage) { 8613 console.log('onWindowStageCreate'); 8614 let windowClass: window.Window[] = []; 8615 windowStage.getSubWindow((err: BusinessError, data) => { 8616 const errCode: number = err.code; 8617 if (errCode) { 8618 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 8619 return; 8620 } 8621 windowClass = data; 8622 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 8623 }); 8624 } 8625}; 8626``` 8627 8628### getSubWindow<sup>9+</sup> 8629 8630getSubWindow(): Promise<Array<Window>> 8631 8632Obtains all the subwindows of this window stage. This API uses a promise to return the result. 8633 8634**Model restriction**: This API can be used only in the stage model. 8635 8636**System capability**: SystemCapability.WindowManager.WindowManager.Core 8637 8638**Atomic service API**: This API can be used in atomic services since API version 11. 8639 8640**Return value** 8641 8642| Type | Description | 8643| --------------------------------------------- | ------------------------------------------ | 8644| Promise<Array<[Window](#window)>> | Promise used to return all the subwindows. | 8645 8646**Error codes** 8647 8648For details about the error codes, see [Window Error Codes](errorcode-window.md). 8649 8650| ID | Error Message | 8651| ------- | ------------------------------ | 8652| 1300005 | This window stage is abnormal. | 8653 8654**Example** 8655<!--code_no_check--> 8656```ts 8657// EntryAbility.ets 8658import { UIAbility } from '@kit.AbilityKit'; 8659import { BusinessError } from '@kit.BasicServicesKit'; 8660 8661export default class EntryAbility extends UIAbility { 8662 // ... 8663 8664 onWindowStageCreate(windowStage: window.WindowStage) { 8665 console.log('onWindowStageCreate'); 8666 let windowClass: window.Window[] = []; 8667 let promise = windowStage.getSubWindow(); 8668 promise.then((data) => { 8669 windowClass = data; 8670 console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data)); 8671 }).catch((err: BusinessError) => { 8672 console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`); 8673 }); 8674 } 8675}; 8676``` 8677 8678### loadContent<sup>9+</sup> 8679 8680loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 8681 8682Loads 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. 8683 8684**Model restriction**: This API can be used only in the stage model. 8685 8686**System capability**: SystemCapability.WindowManager.WindowManager.Core 8687 8688**Atomic service API**: This API can be used in atomic services since API version 11. 8689 8690**Parameters** 8691 8692| Name | Type | Mandatory | Description | 8693| -------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | 8694| 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. | 8695| 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. | 8696| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8697 8698**Error codes** 8699 8700For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8701 8702| ID | Error Message | 8703| ------- | ------------------------------------------------------------ | 8704| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8705| 1300002 | This window state is abnormal. | 8706| 1300005 | This window stage is abnormal. | 8707 8708**Example** 8709 8710```ts 8711// EntryAbility.ets 8712import { UIAbility } from '@kit.AbilityKit'; 8713import { BusinessError } from '@kit.BasicServicesKit'; 8714 8715export default class EntryAbility extends UIAbility { 8716 // ... 8717 8718 storage: LocalStorage = new LocalStorage(); 8719 8720 onWindowStageCreate(windowStage: window.WindowStage) { 8721 this.storage.setOrCreate('storageSimpleProp', 121); 8722 console.log('onWindowStageCreate'); 8723 try { 8724 windowStage.loadContent('pages/page2', this.storage, (err: BusinessError) => { 8725 const errCode: number = err.code; 8726 if (errCode) { 8727 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8728 return; 8729 } 8730 console.info('Succeeded in loading the content.'); 8731 }); 8732 } catch (exception) { 8733 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 8734 } 8735 } 8736}; 8737``` 8738 8739### loadContent<sup>9+</sup> 8740 8741loadContent(path: string, storage?: LocalStorage): Promise<void> 8742 8743Loads 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. 8744 8745**Model restriction**: This API can be used only in the stage model. 8746 8747**System capability**: SystemCapability.WindowManager.WindowManager.Core 8748 8749**Atomic service API**: This API can be used in atomic services since API version 11. 8750 8751**Parameters** 8752 8753| Name | Type | Mandatory | Description | 8754| ------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | 8755| 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. | 8756| 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. | 8757 8758**Return value** 8759 8760| Type | Description | 8761| ------------------- | ------------------------------ | 8762| Promise<void> | Promise that returns no value. | 8763 8764**Error codes** 8765 8766For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8767 8768| ID | Error Message | 8769| ------- | ------------------------------------------------------------ | 8770| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8771| 1300002 | This window state is abnormal. | 8772| 1300005 | This window stage is abnormal. | 8773 8774**Example** 8775 8776```ts 8777// EntryAbility.ets 8778import { UIAbility } from '@kit.AbilityKit'; 8779import { BusinessError } from '@kit.BasicServicesKit'; 8780 8781export default class EntryAbility extends UIAbility { 8782 // ... 8783 8784 storage: LocalStorage = new LocalStorage(); 8785 8786 onWindowStageCreate(windowStage: window.WindowStage) { 8787 this.storage.setOrCreate('storageSimpleProp', 121); 8788 console.log('onWindowStageCreate'); 8789 try { 8790 let promise = windowStage.loadContent('pages/page2', this.storage); 8791 promise.then(() => { 8792 console.info('Succeeded in loading the content.'); 8793 }).catch((err: BusinessError) => { 8794 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8795 }); 8796 } catch (exception) { 8797 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 8798 } 8799 ; 8800 } 8801}; 8802``` 8803 8804### loadContent<sup>9+</sup> 8805 8806loadContent(path: string, callback: AsyncCallback<void>): void 8807 8808Loads content from a page to this window stage. This API uses an asynchronous callback to return the result. 8809 8810**Model restriction**: This API can be used only in the stage model. 8811 8812**System capability**: SystemCapability.WindowManager.WindowManager.Core 8813 8814**Atomic service API**: This API can be used in atomic services since API version 11. 8815 8816**Parameters** 8817 8818| Name | Type | Mandatory | Description | 8819| -------- | ------------------------- | --------- | ------------------------------------------------------------ | 8820| 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. | 8821| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8822 8823**Error codes** 8824 8825For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8826 8827| ID | Error Message | 8828| ------- | ------------------------------------------------------------ | 8829| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8830| 1300002 | This window state is abnormal. | 8831| 1300005 | This window stage is abnormal. | 8832 8833**Example** 8834 8835```ts 8836// EntryAbility.ets 8837import { UIAbility } from '@kit.AbilityKit'; 8838import { BusinessError } from '@kit.BasicServicesKit'; 8839 8840export default class EntryAbility extends UIAbility { 8841 // ... 8842 8843 onWindowStageCreate(windowStage: window.WindowStage) { 8844 console.log('onWindowStageCreate'); 8845 try { 8846 windowStage.loadContent('pages/page2', (err: BusinessError) => { 8847 const errCode: number = err.code; 8848 if (errCode) { 8849 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8850 return; 8851 } 8852 console.info('Succeeded in loading the content.'); 8853 }); 8854 } catch (exception) { 8855 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 8856 } 8857 } 8858}; 8859``` 8860 8861### loadContentByName<sup>11+</sup> 8862 8863loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 8864 8865Loads 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. 8866 8867**Model restriction**: This API can be used only in the stage model. 8868 8869**System capability**: SystemCapability.WindowManager.WindowManager.Core 8870 8871**Atomic service API**: This API can be used in atomic services since API version 11. 8872 8873**Parameters** 8874 8875| Name | Type | Mandatory | Description | 8876| -------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | 8877| name | string | Yes | Name of the named route page. | 8878| 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. | 8879| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8880 8881**Error codes** 8882 8883For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8884 8885| ID | Error Message | 8886| ------- | ------------------------------------------------------------ | 8887| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8888| 1300002 | This window state is abnormal. | 8889| 1300003 | This window manager service works abnormally. | 8890 8891**Example** 8892 8893<!--code_no_check--> 8894```ts 8895// EntryAbility.ets 8896import { UIAbility } from '@kit.AbilityKit'; 8897import { BusinessError } from '@kit.BasicServicesKit'; 8898import * as Index from '../pages/Index'; // Import the named route page. 8899 8900export default class EntryAbility extends UIAbility { 8901 // ... 8902 8903 storage: LocalStorage = new LocalStorage(); 8904 8905 onWindowStageCreate(windowStage: window.WindowStage) { 8906 console.log('onWindowStageCreate'); 8907 this.storage.setOrCreate('storageSimpleProp', 121); 8908 try { 8909 windowStage.loadContentByName(Index.entryName, this.storage, (err: BusinessError) => { 8910 const errCode: number = err.code; 8911 if (errCode) { 8912 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8913 return; 8914 } 8915 console.info('Succeeded in loading the content.'); 8916 }); 8917 } catch (exception) { 8918 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 8919 } 8920 } 8921}; 8922``` 8923<!--code_no_check--> 8924```ts 8925// ets/pages/Index.ets 8926export const entryName : string = 'Index'; 8927@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 8928@Component 8929export struct Index { 8930 @State message: string = 'Hello World' 8931 build() { 8932 Row() { 8933 Column() { 8934 Text(this.message) 8935 .fontSize(50) 8936 .fontWeight(FontWeight.Bold) 8937 } 8938 .width('100%') 8939 } 8940 .height('100%') 8941 } 8942} 8943``` 8944 8945### loadContentByName<sup>11+</sup> 8946 8947loadContentByName(name: string, callback: AsyncCallback<void>): void 8948 8949Loads 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. 8950 8951**Model restriction**: This API can be used only in the stage model. 8952 8953**System capability**: SystemCapability.WindowManager.WindowManager.Core 8954 8955**Atomic service API**: This API can be used in atomic services since API version 11. 8956 8957**Parameters** 8958 8959| Name | Type | Mandatory | Description | 8960| -------- | ------------------------- | --------- | ----------------------------------- | 8961| name | string | Yes | Name of the named route page. | 8962| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 8963 8964**Error codes** 8965 8966For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 8967 8968| ID | Error Message | 8969| ------- | ------------------------------------------------------------ | 8970| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8971| 1300002 | This window state is abnormal. | 8972| 1300003 | This window manager service works abnormally. | 8973 8974**Example** 8975 8976<!--code_no_check--> 8977```ts 8978// EntryAbility.ets 8979import { UIAbility } from '@kit.AbilityKit'; 8980import { BusinessError } from '@kit.BasicServicesKit'; 8981import * as Index from '../pages/Index'; // Import the named route page. 8982 8983export default class EntryAbility extends UIAbility { 8984 // ... 8985 8986 onWindowStageCreate(windowStage: window.WindowStage) { 8987 console.log('onWindowStageCreate'); 8988 try { 8989 windowStage.loadContentByName(Index.entryName, (err: BusinessError) => { 8990 const errCode: number = err.code; 8991 if (errCode) { 8992 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 8993 return; 8994 } 8995 console.info('Succeeded in loading the content.'); 8996 }); 8997 } catch (exception) { 8998 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 8999 } 9000 } 9001}; 9002``` 9003<!--code_no_check--> 9004```ts 9005// ets/pages/Index.ets 9006export const entryName : string = 'Index'; 9007@Entry({routeName: entryName}) 9008@Component 9009export struct Index { 9010 @State message: string = 'Hello World' 9011 build() { 9012 Row() { 9013 Column() { 9014 Text(this.message) 9015 .fontSize(50) 9016 .fontWeight(FontWeight.Bold) 9017 } 9018 .width('100%') 9019 } 9020 .height('100%') 9021 } 9022} 9023``` 9024 9025### loadContentByName<sup>11+</sup> 9026 9027loadContentByName(name: string, storage?: LocalStorage): Promise<void>; 9028 9029Loads 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. 9030 9031**Model restriction**: This API can be used only in the stage model. 9032 9033**System capability**: SystemCapability.WindowManager.WindowManager.Core 9034 9035**Atomic service API**: This API can be used in atomic services since API version 11. 9036 9037**Parameters** 9038 9039| Name | Type | Mandatory | Description | 9040| ------- | ------------ | --------- | ------------------------------------------------------------ | 9041| name | string | Yes | Name of the named route page. | 9042| storage | LocalStorage | No | Page-level UI state storage unit, which is used to transfer the state attribute for the page. | 9043 9044**Error codes** 9045 9046For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9047 9048| ID | Error Message | 9049| ------- | ------------------------------------------------------------ | 9050| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9051| 1300002 | This window state is abnormal. | 9052| 1300003 | This window manager service works abnormally. | 9053 9054**Example** 9055 9056<!--code_no_check--> 9057```ts 9058// EntryAbility.ets 9059import { UIAbility } from '@kit.AbilityKit'; 9060import { BusinessError } from '@kit.BasicServicesKit'; 9061import * as Index from '../pages/Index'; // Import the named route page. 9062 9063export default class EntryAbility extends UIAbility { 9064 // ... 9065 9066 storage: LocalStorage = new LocalStorage(); 9067 9068 onWindowStageCreate(windowStage: window.WindowStage) { 9069 console.log('onWindowStageCreate'); 9070 this.storage.setOrCreate('storageSimpleProp', 121); 9071 try { 9072 let promise = windowStage.loadContentByName(Index.entryName, this.storage); 9073 promise.then(() => { 9074 console.info('Succeeded in loading the content.'); 9075 }).catch((err: BusinessError) => { 9076 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 9077 }); 9078 } catch (exception) { 9079 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 9080 } 9081 } 9082}; 9083``` 9084<!--code_no_check--> 9085```ts 9086// ets/pages/Index.ets 9087export const entryName : string = 'Index'; 9088@Entry({routeName: entryName, storage : LocalStorage.getShared()}) 9089@Component 9090export struct Index { 9091 @State message: string = 'Hello World' 9092 build() { 9093 Row() { 9094 Column() { 9095 Text(this.message) 9096 .fontSize(50) 9097 .fontWeight(FontWeight.Bold) 9098 } 9099 .width('100%') 9100 } 9101 .height('100%') 9102 } 9103} 9104``` 9105 9106### on('windowStageEvent')<sup>9+</sup> 9107 9108on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void 9109 9110Subscribes to the window stage lifecycle change event. 9111 9112**Model restriction**: This API can be used only in the stage model. 9113 9114**System capability**: SystemCapability.WindowManager.WindowManager.Core 9115 9116**Atomic service API**: This API can be used in atomic services since API version 11. 9117 9118**Parameters** 9119 9120| Name | Type | Mandatory | Description | 9121| --------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 9122| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. | 9123| callback | Callback<[WindowStageEventType](#windowstageeventtype9)> | Yes | Callback used to return the window stage lifecycle state. | 9124 9125**Error codes** 9126 9127For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9128 9129| ID | Error Message | 9130| ------- | ------------------------------------------------------------ | 9131| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 9132| 1300002 | This window state is abnormal. | 9133| 1300005 | This window stage is abnormal. | 9134 9135**Example** 9136 9137```ts 9138// EntryAbility.ets 9139import { UIAbility } from '@kit.AbilityKit'; 9140 9141export default class EntryAbility extends UIAbility { 9142 // ... 9143 9144 onWindowStageCreate(windowStage: window.WindowStage) { 9145 console.log('onWindowStageCreate'); 9146 try { 9147 windowStage.on('windowStageEvent', (data) => { 9148 console.info('Succeeded in enabling the listener for window stage event changes. Data: ' + 9149 JSON.stringify(data)); 9150 }); 9151 } catch (exception) { 9152 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 9153 } 9154 } 9155}; 9156``` 9157 9158### off('windowStageEvent')<sup>9+</sup> 9159 9160off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType>): void 9161 9162Unsubscribes from the window stage lifecycle change event. 9163 9164**Model restriction**: This API can be used only in the stage model. 9165 9166**System capability**: SystemCapability.WindowManager.WindowManager.Core 9167 9168**Atomic service API**: This API can be used in atomic services since API version 11. 9169 9170**Parameters** 9171 9172| Name | Type | Mandatory | Description | 9173| --------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 9174| eventType | string | Yes | Event type. The value is fixed at **'windowStageEvent'**, indicating the window stage lifecycle change event. | 9175| 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. | 9176 9177**Error codes** 9178 9179For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9180 9181| ID | Error Message | 9182| ------- | ------------------------------------------------------------ | 9183| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 9184| 1300002 | This window state is abnormal. | 9185| 1300005 | This window stage is abnormal. | 9186 9187**Example** 9188 9189```ts 9190// EntryAbility.ets 9191import { UIAbility } from '@kit.AbilityKit'; 9192 9193export default class EntryAbility extends UIAbility { 9194 // ... 9195 9196 onWindowStageCreate(windowStage: window.WindowStage) { 9197 console.log('onWindowStageCreate'); 9198 const callback = (windowStageEventType: window.WindowStageEventType) => { 9199 // ... 9200 } 9201 try { 9202 windowStage.on('windowStageEvent', callback); 9203 } catch (exception) { 9204 console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 9205 } 9206 try { 9207 windowStage.off('windowStageEvent', callback); 9208 // Unregister all the callbacks that have been registered through on(). 9209 windowStage.off('windowStageEvent'); 9210 } catch (exception) { 9211 console.error(`Failed to disable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`); 9212 } 9213 } 9214}; 9215``` 9216 9217### setDefaultDensityEnabled<sup>12+</sup> 9218 9219setDefaultDensityEnabled(enabled: boolean): void 9220 9221Enables the system's default density. 9222 9223By default, the system's default density is not used, and the window layout changes with the system display size. 9224 9225**Model restriction**: This API can be used only in the stage model. 9226 9227**Atomic service API**: This API can be used in atomic services since API version 12. 9228 9229**System capability**: SystemCapability.Window.SessionManager 9230 9231**Parameters** 9232 9233| Name | Type | Mandatory | Description | 9234| ------- | ------- | --------- | ------------------------------------------------------------ | 9235| 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. | 9236 9237**Error codes** 9238 9239For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 9240 9241| ID | Error Message | 9242| ------- | ------------------------------------------------------------ | 9243| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9244| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9245| 1300002 | This window state is abnormal. | 9246| 1300005 | This window stage is abnormal. | 9247 9248**Example** 9249 9250```ts 9251// EntryAbility.ets 9252import { UIAbility } from '@kit.AbilityKit'; 9253 9254export default class EntryAbility extends UIAbility { 9255 // ... 9256 9257 onWindowStageCreate(windowStage: window.WindowStage) { 9258 console.log('onWindowStageCreate'); 9259 try { 9260 windowStage.setDefaultDensityEnabled(true); 9261 } catch (exception) { 9262 console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`); 9263 } 9264 } 9265}; 9266```