1# oh_window.h 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @waterwin--> 5<!--Designer: @nyankomiya--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9## Overview 10 11The file declares the window management APIs. You can use the APIs to set and obtain the properties of a window, and set its status bar style and navigation bar style. 12 13**File to include**: <window_manager/oh_window.h> 14 15**Library**: libnative_window_manager.so 16 17**System capability**: SystemCapability.Window.SessionManager 18 19**Since**: 15 20 21**Related module**: [WindowManager](capi-windowmanager.md) 22 23## Summary 24 25### Functions 26 27| Name| Description| 28| -- | -- | 29| [int32_t OH_WindowManager_SetWindowStatusBarEnabled(int32_t windowId, bool enabled, bool enableAnimation)](#oh_windowmanager_setwindowstatusbarenabled) | Sets whether to display the status bar in a window.| 30| [int32_t OH_WindowManager_SetWindowStatusBarColor(int32_t windowId, int32_t color)](#oh_windowmanager_setwindowstatusbarcolor) | Sets the color of the status bar in a window.| 31| [int32_t OH_WindowManager_SetWindowNavigationBarEnabled(int32_t windowId, bool enabled, bool enableAnimation)](#oh_windowmanager_setwindownavigationbarenabled) | Sets whether to display the navigation bar in a window.| 32| [int32_t OH_WindowManager_GetWindowAvoidArea(int32_t windowId, WindowManager_AvoidAreaType type, WindowManager_AvoidArea* avoidArea)](#oh_windowmanager_getwindowavoidarea) | Obtains the avoid area of a window.| 33| [int32_t OH_WindowManager_IsWindowShown(int32_t windowId, bool* isShow)](#oh_windowmanager_iswindowshown) | Checks whether a window is displayed.| 34| [int32_t OH_WindowManager_ShowWindow(int32_t windowId)](#oh_windowmanager_showwindow) | Shows a window.| 35| [int32_t OH_WindowManager_SetWindowTouchable(int32_t windowId, bool isTouchable)](#oh_windowmanager_setwindowtouchable) | Sets whether a window is touchable.| 36| [int32_t OH_WindowManager_SetWindowFocusable(int32_t windowId, bool isFocusable)](#oh_windowmanager_setwindowfocusable) | Sets whether a window is focusable.| 37| [int32_t OH_WindowManager_SetWindowBackgroundColor(int32_t windowId, const char* color)](#oh_windowmanager_setwindowbackgroundcolor) | Sets the background color of a window.| 38| [int32_t OH_WindowManager_SetWindowBrightness(int32_t windowId, float brightness)](#oh_windowmanager_setwindowbrightness) | Sets the screen brightness of a window.| 39| [int32_t OH_WindowManager_SetWindowKeepScreenOn(int32_t windowId, bool isKeepScreenOn)](#oh_windowmanager_setwindowkeepscreenon) | Sets whether to always keep the screen on for a window.| 40| [int32_t OH_WindowManager_SetWindowPrivacyMode(int32_t windowId, bool isPrivacy)](#oh_windowmanager_setwindowprivacymode) | Sets whether to enable privacy mode for a window.| 41| [int32_t OH_WindowManager_GetWindowProperties(int32_t windowId, WindowManager_WindowProperties* windowProperties)](#oh_windowmanager_getwindowproperties) | Obtains the properties of a window.| 42| [int32_t OH_WindowManager_Snapshot(int32_t windowId, OH_PixelmapNative* pixelMap)](#oh_windowmanager_snapshot) | Obtains the snapshot of a window.| 43| [int32_t OH_WindowManager_GetAllWindowLayoutInfoList(int64_t displayId,WindowManager_Rect** windowLayoutInfoList, size_t* windowLayoutInfoSize)](#oh_windowmanager_getallwindowlayoutinfolist) | Obtains the layout information array of all windows visible on a display. The layout information is arranged based on the current window stacking order, and the topmost window in the hierarchy is at index 0 of the array.| 44| [void OH_WindowManager_ReleaseAllWindowLayoutInfoList(WindowManager_Rect* windowLayoutInfoList)](#oh_windowmanager_releaseallwindowlayoutinfolist) | Releases the memory occupied by a window layout information array.| 45| [int32_t OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* touchEvent, int32_t windowX, int32_t windowY)](#oh_windowmanager_injecttouchevent) | Injects a multimodal touch event into the target window. This function is limited to injecting events into windows that belong to the same process. The injection does not affect window focus or stacking order, nor does it start window dragging. The event is forwarded directly to ArkUI. This function must be called after the target window has completed its UI loading.| 46 47## Function Description 48 49### OH_WindowManager_SetWindowStatusBarEnabled() 50 51``` 52int32_t OH_WindowManager_SetWindowStatusBarEnabled(int32_t windowId, bool enabled, bool enableAnimation) 53``` 54 55**Description** 56 57Sets whether to display the status bar in a window. 58 59**Since**: 15 60 61 62**Parameters** 63 64| Parameter| Description| 65| -- | -- | 66| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 67| bool enabled | Whether to display the status bar. **true** to display, **false** otherwise.| 68| bool enableAnimation | Whether to enable the show/hide animation of the status bar. **true** to enable, **false** otherwise.| 69 70**Return value** 71 72| Type| Description| 73| -- | -- | 74| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_DEVICE_NOT_SUPPORTED**: The feature is not supported by the device.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 75 76### OH_WindowManager_SetWindowStatusBarColor() 77 78``` 79int32_t OH_WindowManager_SetWindowStatusBarColor(int32_t windowId, int32_t color) 80``` 81 82**Description** 83 84Sets the color of the status bar in a window. 85 86**Since**: 15 87 88 89**Parameters** 90 91| Parameter| Description| 92| -- | -- | 93| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 94| int32_t color | Color to set, in ARGB format.| 95 96**Return value** 97 98| Type| Description| 99| -- | -- | 100| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_DEVICE_NOT_SUPPORTED**: The feature is not supported by the device.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 101 102### OH_WindowManager_SetWindowNavigationBarEnabled() 103 104``` 105int32_t OH_WindowManager_SetWindowNavigationBarEnabled(int32_t windowId, bool enabled, bool enableAnimation) 106``` 107 108**Description** 109 110Sets whether to display the navigation bar in a window. 111 112**Since**: 15 113 114 115**Parameters** 116 117| Parameter| Description| 118| -- | -- | 119| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 120| bool enabled | Whether to display the navigation bar. **true** to display, **false** otherwise.| 121| bool enableAnimation | Whether to enable the show/hide animation of the navigation bar. **true** to enable, **false** otherwise.| 122 123**Return value** 124 125| Type| Description| 126| -- | -- | 127| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_DEVICE_NOT_SUPPORTED**: The feature is not supported by the device.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 128 129### OH_WindowManager_GetWindowAvoidArea() 130 131``` 132int32_t OH_WindowManager_GetWindowAvoidArea(int32_t windowId, WindowManager_AvoidAreaType type, WindowManager_AvoidArea* avoidArea) 133``` 134 135**Description** 136 137Obtains the avoid area of a window. 138 139**Since**: 15 140 141 142**Parameters** 143 144| Parameter| Description| 145| -- | -- | 146| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 147| [WindowManager_AvoidAreaType](capi-oh-window-comm-h.md#windowmanager_avoidareatype) type | Type of the avoid area.| 148| [WindowManager_AvoidArea](capi-windowmanager-avoidarea.md)* avoidArea | Pointer to the avoid area.| 149 150**Return value** 151 152| Type| Description| 153| -- | -- | 154| int32_t | One of the following result codes:<br> **OK**: The function is successfully called, and the pointer to the avoid area is returned.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 155 156### OH_WindowManager_IsWindowShown() 157 158``` 159int32_t OH_WindowManager_IsWindowShown(int32_t windowId, bool* isShow) 160``` 161 162**Description** 163 164Checks whether a window is displayed. 165 166**Since**: 15 167 168 169**Parameters** 170 171| Parameter| Description| 172| -- | -- | 173| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 174| bool* isShow | Pointer to the check result for whether the window is displayed. **true** if displayed, **false** otherwise.| 175 176**Return value** 177 178| Type| Description| 179| -- | -- | 180| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 181 182### OH_WindowManager_ShowWindow() 183 184``` 185int32_t OH_WindowManager_ShowWindow(int32_t windowId) 186``` 187 188**Description** 189 190Shows a window. 191 192**Since**: 15 193 194 195**Parameters** 196 197| Parameter| Description| 198| -- | -- | 199| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 200 201**Return value** 202 203| Type| Description| 204| -- | -- | 205| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 206 207### OH_WindowManager_SetWindowTouchable() 208 209``` 210int32_t OH_WindowManager_SetWindowTouchable(int32_t windowId, bool isTouchable) 211``` 212 213**Description** 214 215Sets whether a window is touchable. 216 217**Since**: 15 218 219 220**Parameters** 221 222| Parameter| Description| 223| -- | -- | 224| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 225| bool isTouchable | Whether the window is touchable. **true** if touchable, **false** otherwise.| 226 227**Return value** 228 229| Type| Description| 230| -- | -- | 231| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 232 233### OH_WindowManager_SetWindowFocusable() 234 235``` 236int32_t OH_WindowManager_SetWindowFocusable(int32_t windowId, bool isFocusable) 237``` 238 239**Description** 240 241Sets whether a window is focusable. 242 243**Since**: 15 244 245 246**Parameters** 247 248| Parameter| Description| 249| -- | -- | 250| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 251| bool isFocusable | Whether the window is focusable. **true** if focusable, **false** otherwise.| 252 253**Return value** 254 255| Type| Description| 256| -- | -- | 257| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 258 259### OH_WindowManager_SetWindowBackgroundColor() 260 261``` 262int32_t OH_WindowManager_SetWindowBackgroundColor(int32_t windowId, const char* color) 263``` 264 265**Description** 266 267Sets the background color of a window. 268 269**Since**: 15 270 271 272**Parameters** 273 274| Parameter| Description| 275| -- | -- | 276| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 277| const char* color | Pointer to the background color. The value is a string in hexadecimal RGB or ARGB color format.| 278 279**Return value** 280 281| Type| Description| 282| -- | -- | 283| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.| 284 285### OH_WindowManager_SetWindowBrightness() 286 287``` 288int32_t OH_WindowManager_SetWindowBrightness(int32_t windowId, float brightness) 289``` 290 291**Description** 292 293Sets the screen brightness of a window. 294 295**Since**: 15 296 297 298**Parameters** 299 300| Parameter| Description| 301| -- | -- | 302| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 303| float brightness | Screen brightness. The value is a floating-point number in the range [0.0, 1.0] or is set to **-1.0**, where **1.0** indicates the brightest, and **-1.0** is the default brightness.| 304 305**Return value** 306 307| Type| Description| 308| -- | -- | 309| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 310 311### OH_WindowManager_SetWindowKeepScreenOn() 312 313``` 314int32_t OH_WindowManager_SetWindowKeepScreenOn(int32_t windowId, bool isKeepScreenOn) 315``` 316 317**Description** 318 319Sets whether to always keep the screen on for a window. 320 321**Since**: 15 322 323 324**Parameters** 325 326| Parameter| Description| 327| -- | -- | 328| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 329| bool isKeepScreenOn | Whether to always keep the screen on. **true** to always keep the screen on, **false** otherwise.| 330 331**Return value** 332 333| Type| Description| 334| -- | -- | 335| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 336 337### OH_WindowManager_SetWindowPrivacyMode() 338 339``` 340int32_t OH_WindowManager_SetWindowPrivacyMode(int32_t windowId, bool isPrivacy) 341``` 342 343**Description** 344 345Sets whether to enable privacy mode for a window. 346 347**Required permissions**: ohos.permission.PRIVACY_WINDOW 348 349**Since**: 15 350 351 352**Parameters** 353 354| Parameter| Description| 355| -- | -- | 356| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 357| bool isPrivacy | Whether to enable privacy mode. **true** to enable, **false** otherwise.| 358 359**Return value** 360 361| Type| Description| 362| -- | -- | 363| int32_t | One of the following result codes:<br> **OK**: The function is successfully called.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PERMISSION**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_NO_PERMISSION**: The permission verification fails.| 364 365### OH_WindowManager_GetWindowProperties() 366 367``` 368int32_t OH_WindowManager_GetWindowProperties(int32_t windowId, WindowManager_WindowProperties* windowProperties) 369``` 370 371**Description** 372 373Obtains the properties of a window. 374 375**Since**: 15 376 377 378**Parameters** 379 380| Parameter| Description| 381| -- | -- | 382| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 383| [WindowManager_WindowProperties](capi-windowmanager-windowproperties.md)* windowProperties | Pointer to the properties.| 384 385**Return value** 386 387| Type| Description| 388| -- | -- | 389| int32_t | One of the following result codes:<br> **OK**: The function is successfully called, and the pointer to the window properties is returned.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 390 391### OH_WindowManager_Snapshot() 392 393``` 394int32_t OH_WindowManager_Snapshot(int32_t windowId, OH_PixelmapNative* pixelMap) 395``` 396 397**Description** 398 399Obtains the snapshot of a window. 400 401**Since**: 15 402 403 404**Parameters** 405 406| Parameter| Description| 407| -- | -- | 408| int32_t windowId | Window ID. The default value is **0**. The value is an integer.<br>If the window ID is invalid or the window has been destroyed, you cannot obtain the window snapshot. To successfully obtain a snapshot, a valid window ID is required.<br>You can obtain a valid window ID by calling the ArkTS API **getWindowProperties** on the window object.| 409| [OH_PixelmapNative](capi-struct.md)* pixelMap | Pointer to the snapshot.| 410 411**Return value** 412 413| Type| Description| 414| -- | -- | 415| int32_t | One of the following result codes:<br> **OK**: The function is successfully called, and the pointer to the pixelMap is returned.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.| 416 417### OH_WindowManager_GetAllWindowLayoutInfoList() 418 419``` 420int32_t OH_WindowManager_GetAllWindowLayoutInfoList(int64_t displayId,WindowManager_Rect** windowLayoutInfoList, size_t* windowLayoutInfoSize) 421``` 422 423**Description** 424 425Obtains the layout information array of all windows visible on a display. The layout information is arranged based on the current window stacking order, and the topmost window in the hierarchy is at index 0 of the array. 426 427**Since**: 17 428 429 430**Parameters** 431 432| Parameter| Description| 433| -- | -- | 434| int64_t displayId | ID of the display. You can obtain a valid display ID by calling the ArkTS API **getWindowProperties** on the window object.| 435| [WindowManager_Rect](capi-windowmanager-rect.md)** windowLayoutInfoList | Double pointer to the layout information array of all windows visible.| 436| size_t* windowLayoutInfoSize | Pointer to the length of the layout information array.| 437 438**Return value** 439 440| Type| Description| 441| -- | -- | 442| int32_t | One of the following result codes:<br> **OK**: The function is successfully called, and the double pointer to the array and the pointer to the array length are returned.<br> **WINDOW_MANAGER_ERRORCODE_INVALID_PARAM**: A parameter is incorrect.<br> **WINDOW_MANAGER_ERRORCODE_DEVICE_NOT_SUPPORTED**: The feature is not supported by the device.<br> **WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 443 444### OH_WindowManager_ReleaseAllWindowLayoutInfoList() 445 446``` 447void OH_WindowManager_ReleaseAllWindowLayoutInfoList(WindowManager_Rect* windowLayoutInfoList) 448``` 449 450**Description** 451 452Releases the memory occupied by a window layout information array. 453 454**Since**: 17 455 456 457**Parameters** 458 459| Parameter| Description| 460| -- | -- | 461| [WindowManager_Rect](capi-windowmanager-rect.md)* windowLayoutInfoList | Pointer to the layout information array of all windows visible on the display. You can obtain the array pointer by calling [OH_WindowManager_GetAllWindowLayoutInfoList](capi-oh-window-h.md#oh_windowmanager_getallwindowlayoutinfolist).| 462 463### OH_WindowManager_InjectTouchEvent() 464 465``` 466int32_t OH_WindowManager_InjectTouchEvent(int32_t windowId, Input_TouchEvent* touchEvent, int32_t windowX, int32_t windowY) 467``` 468 469**Description** 470 471Injects a multimodal touch event into the target window. This function is limited to injecting events into windows that belong to the same process. The injection does not affect window focus or stacking order, nor does it start window dragging. The event is forwarded directly to ArkUI. This function must be called after the target window has completed its UI loading. 472 473**Since**: 20 474 475**Parameters** 476 477| Parameter| Description| 478| -- | -- | 479| int32_t windowId | Window ID. The default value is **0**. The value is an integer.| 480| [Input_TouchEvent](../apis-input-kit/capi-input-input-touchevent.md)* touchEvent | Pointer to the multimodal touch event. For details, see [Input_TouchEvent](../apis-input-kit/capi-input-input-touchevent.md). The event is defined in **oh_input_manager.h**. Certain fields in this parameter have specific constraints. Specifically, **action** should be an integer in the range [0, 3]; **id**, **displayX**, **displayY**, and **actionTime** should be an integer greater than or equal to 0. If these constraints are not met, the function returns **WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**, indicating that the window manager service is abnormal.| 481| int32_t windowX | X coordinate of the event relative to the target window. The value is an integer.| 482| int32_t windowY | Y coordinate of the event relative to the target window. The value is an integer.| 483 484**Return value** 485 486| Type| Description| 487| -- | -- | 488| int32_t | One of the following result codes:<br>**OK**: The function is successfully called.<br>**WINDOW_MANAGER_ERRORCODE_STATE_ABNORMAL**: The window status is abnormal.<br>**WINDOW_MANAGER_ERRORCODE_SYSTEM_ABNORMAL**: The window manager service is abnormal.| 489