Window z-order (ZOrder) refers to the stacking order of multiple windows on the screen, which determines the front-to-back display relationship of windows.

The larger the z-order value, the closer the window is displayed to the front and can cover windows with smaller z-order values. Conversely, windows with smaller z-order values may be obscured by other windows.

For third-party apps, the z-order of a window cannot be directly modified, but the display z-order of subwindows can be indirectly affected by controlling the zLevel attribute.

The system controls the visibility and interaction priority of the user interface by managing ZOrder and zLevel.

This section systematically explains the window z-order management mechanism from five aspects: basic concepts, z-order rules, parent-child window relationships, the TopMost window mechanism, and related API examples.

Basic Concepts and Z-Order Rules

ZOrder and zLevel

ZOrder represents the window stacking order maintained internally by the system. The larger the value, the closer the window is to the front. Third-party apps cannot directly modify ZOrder.

zLevel represents the relative z-order between subwindows within an app that can be controlled by third-party apps, and is only effective for non-modal subwindows. The value range of zLevel is [-10000, 10000], and the default value is 0. The greater the zLevel value, the larger the corresponding ZOrder, and the closer the window is to the front.

Z-Order Rules for Window zLevel

Subwindows with different zLevels
- A window with a higher zLevel always covers a window with a lower zLevel. Even if a window with a lower zLevel is clicked, it will not be raised above the window with a higher zLevel.
Subwindows with the same zLevel
- By default, the window created later has a higher z-order.
- When the user taps a subwindow, its z-order is raised to the highest position within the same zLevel, implementing "tap-to-top."
- If setRaiseByClickEnabled() is called with false, the raise-on-tap feature is disabled, and the z-order remains unchanged when tapped.

Z-Order Rules for Window Types

Z-order adjustment for windows of the same type

For windows of the same type (multiple main windows, multiple regular subwindows), the z-order can be adjusted by tapping or using shortcuts (such as Alt+Tab).

Default z-order of in-app subwindow types

The system assigns default z-orders to different types of subwindows. The priorities from high to low are as follows:

Expand

Window Type	Creation Method
App-modal subwindow	Call the createSubWindowWithOptions() API and set isModal to true and modalityType to APPLICATION_MODALITY in the subwindow parameters SubWindowOptions.
Toast subwindow	Call the showToast() API and set showMode to TOP_MOST.
Text menu subwindow	Call the showActionMenu() API and set showInSubWindow to true.
Dialog subwindow	Call openCustomDialog() with dialogContent and options parameters, and set showInSubWindow to true. Call openCustomDialog() with the options parameter, and set showInSubWindow to true. Call openCustomDialogWithController(), and set showInSubWindow to true.
Modal subwindow	Call the createSubWindowWithOptions() API and set isModal to true and modalityType to WINDOW_MODALITY in the subwindow parameters SubWindowOptions.
Normal subwindow	The default subwindow created by calling the createSubWindowWithOptions() API.

Windows of different types cannot cross their z-order ranges by tapping or through APIs.

Z-Order Rules for Parent-Child Windows

When a parent window is raised, all its child windows are raised along with it; when a child window is raised, its parent window is also raised.
The z-order of a child window is always higher than that of its parent window.
A window can be raised by calling the raiseToAppTop() API or by tapping the window.

Z-Order Rules for TopMost Windows

In the freeform window state, an app's main window can call the setWindowTopmost() API with true to place itself above other app windows, achieving an always-on-top display effect that is not obscured. This should be used appropriately to avoid affecting the user experience.
Using this API requires the ohos.permission.WINDOW_TOPMOST permission.

Z-Order Control Mechanisms

Expand

Feature/Operation	Control Method	Effective Scope	Applicable Scenario
Z-order	System-managed	Effective across apps	Internal rendering order management
zLevel	setSubWindowZLevel()/Set when creating a window	Effective only within the same app	z-order management for subwindows
Window topmost	setWindowTopmost()	Effective across apps	Persistent windows such as video and navigation
Raise on tap	setRaiseByClickEnabled()	Effective across apps	Preventing accidental touches, fixed layouts

Expand

Feature	Typical Scenario	Corresponding API
Set main window to topmost	Used to place a window above other app windows without being obscured, such as in video calls, navigation, and other scenarios.	setWindowTopmost()
Raise a subwindow to the top	Used to raise a subwindow to the topmost position among subwindows of the same type within the current app. This only takes effect within the scope of subwindows that share the same parent window and the same zLevel value in the current app. For example, in a video conference with a floating toolbar, the main window displays the video feed, while subwindows include a chat box, a sharing control bar, and so on. When the chat box is tapped, raiseToAppTop() can be called to bring it to the top, preventing it from being obscured by other subwindows.	raiseToAppTop()
Disable/enable the subwindow raise-on-tap feature	Can be used for tool panels with fixed layouts to prevent z-order confusion caused by accidental user operations.	setRaiseByClickEnabled()
Get the topmost window in the current app	Can determine the currently displayed topmost window (which may be the main window or a subwindow), used for scenarios such as logging or state synchronization.	getLastWindow()

NOTE

Set zLevel appropriately to avoid z-order conflicts.
Use the TopMost feature with caution to avoid disrupting the system's multi-window experience.
For critical interfaces that require high-priority display, you can use raiseToAppTop() to ensure visibility. Before using this API, ensure that the window has called a showWindow() type API (showWindow()/showWindow(options: ShowWindowOptions)) and that the call has completed.
setWindowTopmost() takes effect only in the freeform window state. You can use isInFreeWindowMode() to check whether the current window is in freeform window mode, and combine it with the on('freeWindowModeChange') event listener to listen for window mode changes in real time, thereby accurately determining when it is safe to call setWindowTopmost().

Send feedback

Was this page helpful?

Send feedback

Reach out to us through the community for any other questions.

Community Q&A Intelligent Assistant