1# Window Overview 2 3<!--Kit: ArkUI--> 4<!--Subsystem: Window--> 5<!--Owner: @Pakoo007--> 6<!--Designer: @ki_ja--> 7<!--Tester: @qinliwen0417--> 8<!--Adviser: @ge-yafang--> 9 10## Introduction 11 12The Window module provides a mechanism for displaying multiple application UIs and allowing the end user to interact with them on the same physical screen. 13 14- For application developers, the Window module provides APIs for UI display and user interaction. 15 16- For end users, the Window module provides a way to control application UIs. 17 18- For the entire operating system, the Window module provides logic for application UI management. 19 20 21## Features 22 23The Window module has the following features: 24 25- **Provides a Window object to hold application and system UIs.** You can load your application UIs through the window to display them to the end user. 26 27- **Maintains the window relationship (overlay layers and positions).** Different types of application and system windows have different default positions and overlay layers (z-index). End users can adjust the position and overlay layer of a window within a certain range. 28 29- **Provides window decoration.** Window decoration refers to the title bar and border of a window. The title bar usually provides the Maximize, Minimize, and Close buttons and has the default click behavior. The border can be dragged to relocate or resize the window. Window decoration is a system-level default behavior. You can enable or disable window decoration without paying attention to the implementation at the UI code layer. 30 31- **Provides window animations.** When a window is displayed, hidden, or switched, an animation is usually used to smooth the interaction process. This is the default behavior for application windows. You do not need to set or modify the code. 32 33- **Provides guidance for input event distribution.** Events are distributed based on the window status and focus. Touch and mouse events are distributed based on the window position and size, and keyboard events are distributed to the focused window. You can call APIs provided by the Window module to set whether a window is touchable and can gain focus. 34 35 36## Basic Concepts 37 38 39### Window Type 40 41The Window module provides system windows and application windows. 42- A **system window** implements specific functionalities of the system. Examples include the volume bar, wallpaper, notification panel, status bar, and navigation bar. 43- An **application window** is related to the application display. Based on the displayed content, application windows are further classified into main windows and child windows. 44 - A main window shows the application UI and appears on the task management page. 45 - A child window is an auxiliary window of an application, such as a dialog box and floating window. It is not displayed on the task management page. Its lifecycle follows that of the main window. 46 47 48 49 50### Application Window Mode 51 52The application window mode refers to the display mode of the main window when it is started. Currently, there are three application window modes: full-screen, split-screen, and freeform window. This support for multiple window modes is known as the multi-window capability. 53 54 55- In **full-screen** mode, the main window is displayed on the entire screen when it is started. 56- In **split-screen** mode, the main window occupies part of the screen when it is started, and the other part of the screen is occupied by another window. You can resize the two windows by dragging the split line between them. 57- In **freeform window** mode, the main window may come in any size or position as needed. Multiple freeform windows can be simultaneously displayed on the screen. These freeform windows are arranged on the z-axis in the sequence that they are opened or gain the focus. When a freeform window is clicked or touched, its z-index is incremented and it gains the focus. 58 59 60 61 62 63## Working Principles 64 65The window implementation and development vary according to the application development model, which can be FA model or stage model. 66 67For details about the overall architecture and design ideas of the two models, see [Application Models](../application-models/application-models.md). 68 69You are advised to use the stage model for window development. 70 71## Main Window Lifecycle 72 73### Lifecycle Overview 74 75In the stage model, each UIAbility corresponds to a WindowStage, and each WindowStage corresponds to an application's main window. The relationship between the UIAbility, the WindowStage, and the application's main window is shown in the figure below. 76 77 78 79Each UIAbility instance is bound to an instance of the WindowStage class, which functions as the window manager within the application process. It contains a main window, meaning that the UIAbility instance holds a main window through the WindowStage. This main window provides a drawing area for ArkUI and can load different ArkUI pages. 80 81In the stage model, the main window is managed and its lifecycle is maintained by the UIAbility through WindowStage. Notifications for the creation and destruction of the main window can be received via [onWindowStageCreate](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#onwindowstagecreate) and [onWindowStageDestroy](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#onwindowstagedestroy). For details, see [UIAbility Lifecycle](../application-models/uiability-lifecycle.md). 82 83### Lifecycle States 84 85The lifecycle state of a window changes when it enters the foreground, switches between the foreground and background, or moves to the background. 86 87In the stage model, the lifecycle states of the main window include: 88- **SHOWN**: The window enters the foreground. The SHOWN event is triggered when an application switches from the background to the foreground. 89 90- **RESUMED**: The window becomes interactive. The RESUMED event is triggered when the window moves to the foreground. It is also triggered when the window is restored. 91 92- **PAUSED**: The window becomes non-interactive. The PAUSED event is triggered when the window is visible in the foreground but not interactive. The window remains in this state until it is restored or moves to the background. If the window is restored, the RESUMED event is triggered, and the window becomes interactive again. 93 94- **HIDDEN**: The window moves to the background. The HIDDEN event is triggered when the application switches from the foreground to the background. 95 96> **NOTE** 97> 98> The RESUMED and PAUSED events are triggered when the window switches to the foreground and background, respectively. However, in some scenarios, the triggering of these events may differ. 99> - For example, in some system-controlled scenarios, such as application management, when an application window switches to the foreground and enters an authentication screen, the PAUSED event is triggered. After authentication is successful, the RESUMED event is triggered. 100 101|**Lifecycle State**|**Example Triggers**| 102|---------------|---------------| 103|SHOWN |Occurs when the application is launched in full-screen mode or a floating window opens.| 104|RESUMED |Occurs when the application is launched in full-screen mode, a floating window opens, or the application is resumed after being swiped up into hover mode.| 105|PAUSED |Occurs when the application exits to the home screen, the user swipes up in full-screen mode to enter multitasking mode, or the application is under system control in full-screen mode.| 106|HIDDEN |Occurs when an application is swiped up (in full-screen mode) and exits to the home screen, or it is moved to the background or is destroyed.| 107 108The flow of lifecycle events for the application's main window is shown in the figure below. 109 110 111 112**Special scenario**: If the application is system-controlled, it enters the PAUSED state and triggers a callback notification during the startup process or while in the RESUMED state. 113 114### Listening for Lifecycle State Changes 115 116If you need to detect changes in the lifecycle of the application's main window, you can use the following registration APIs to listen for these changes. 117 118- Before API version 20, you can call [on('windowStageEvent')](../reference/apis-arkui/arkts-apis-window-WindowStage.md#onwindowstageevent9) to register a listener for the WindowStage lifecycle changes and call [off('windowStageEvent')](../reference/apis-arkui/arkts-apis-window-WindowStage.md#offwindowstageevent9) to unregister the listener. This registration API does not ensure the order of lifecycle state transitions and is not recommended for use when the order of states matters. 119- From API version 20 onwards, you can call [on('windowStageLifecycleEvent')](../reference/apis-arkui/arkts-apis-window-WindowStage.md#onwindowstagelifecycleevent20) to register a listener for the WindowStage lifecycle changes and call [off('windowStageLifecycleEvent')](../reference/apis-arkui/arkts-apis-window-WindowStage.md#offwindowstagelifecycleevent20) to unregister the listener. This registration API does not support listening for focus gain/loss states of the WindowStage. For such requirements, use [on('windowEvent')](arkts-apis-window-Window.md#onwindowevent10). For applications requiring a specific order of lifecycle states, this API is recommended. 120 121### Differentiated Lifecycle Behaviors Across Different Devices 122 123In the stage model, when the main window of an application moves from the foreground to the background, it also triggers the UIAbility lifecycle transition. You need to pay special attention to the differences in behavior across different types of products. 124 125- **On phones**: When a window moves from the foreground to the background, it triggers the UIAbility to transition to the background. 126 127- **On tablets**: 128 129 - For applications that do not support running on 2-in-1 devices, or that can run on both phones and 2-in-1 devices, moving a window from the foreground to the background will trigger the UIAbility to transition to the background. 130 131 - For applications that do not support running on phones but do support running on 2-in-1 devices, moving a window from the foreground to the background will not trigger the UIAbility to transition to the background. 132 133- **On 2-in-1 devices**: 134 135 - For applications that support running on phones, moving a window from the foreground to the background will trigger the UIAbility to transition to the background. 136 137 - For applications that do not support running on phones, moving a window from the foreground to the background will not trigger the UIAbility to transition to the background. 138 139## Constraints 140 141- You cannot develop system windows in the FA model. 142 143- The application main window and child window have the following size limits: [320, 2560] in width and [240, 2560] in height, both in units of vp. 144 145- The system window has the following size limits: (0, 2560] in width and (0, 2560] in height, both in units of vp. 146
