294d8479创建于 17 天前历史提交

@ohos.window (Window) (System API)

The 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.

This module provides the following common window-related functions:

Window: window instance, which is the basic unit managed by the window manager.
WindowStage: window manager that manages windows.

NOTE

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.

This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.window (Window).

For the system capability SystemCapability.Window.SessionManager, use canIUse() to check whether the device supports this system capability and the corresponding APIs.

Modules to Import

import { window } from '@kit.ArkUI';

WindowType⁷⁺

Enumerates the window types.

Name	Value	Description
TYPE_INPUT_METHOD^(deprecated)	2	Input method window. Model restriction: This API can be used only in the stage model. System API: This is a system API. Note: This API is supported since API version 9 and deprecated since API version 13. There is no alternative window type. To control the input method, call Input method framework APIs. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_STATUS_BAR⁹⁺	3	Status bar. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_PANEL⁹⁺	4	Notification panel. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_KEYGUARD⁹⁺	5	Lock screen. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_VOLUME_OVERLAY⁹⁺	6	Volume bar. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_NAVIGATION_BAR⁹⁺	7	Navigation bar. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_WALLPAPER⁹⁺	9	Wallpaper. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_DESKTOP⁹⁺	10	Home screen. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_LAUNCHER_RECENT⁹⁺	11	Recent tasks screen. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_LAUNCHER_DOCK⁹⁺	12	Dock bar on the home screen. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_VOICE_INTERACTION⁹⁺	13	Voice assistant. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_POINTER⁹⁺	14	Mouse. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_FLOAT_CAMERA⁹⁺	15	Floating camera window. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_SCREENSHOT⁹⁺	17	Screenshot window. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_SYSTEM_TOAST¹¹⁺	18	Toast displayed at the top. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_DIVIDER¹¹⁺	19	Divider. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_GLOBAL_SEARCH¹¹⁺	20	Window used for global search. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.WindowManager.WindowManager.Core
TYPE_HANDWRITE¹²⁺	21	Stylus window. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.Window.SessionManager
TYPE_WALLET_SWIPE_CARD¹⁵⁺	22	Wallet swipe card window. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.Window.SessionManager
TYPE_SCREEN_CONTROL¹⁵⁺	23	Top-level window used for locking touch input, which intercepts screen touch and click events. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.Window.SessionManager
TYPE_FLOAT_NAVIGATION¹⁷⁺	24	Floating window with a three-button navigation bar. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.Window.SessionManager
TYPE_DYNAMIC²⁰⁺	25	System window that allows for adjustable z-levels. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.Window.SessionManager
TYPE_MUTISCREEN_COLLABORATION²⁰⁺	26	Window for multi-screen collaboration. Model restriction: This API can be used only in the stage model. System API: This is a system API. System capability: SystemCapability.Window.SessionManager

Configuration⁹⁺

Defines the parameters for creating a child window or system window.

System API: This is a system API.

Name	Type	Read-Only	Optional	Description
zIndex²⁰⁺	number	No	Yes	Z-level of the system window. This parameter is valid only when WindowType is set to TYPE_DYNAMIC. System capability: SystemCapability.Window.SessionManager
defaultDensityEnabled²⁰⁺	boolean	No	Yes	Whether the window should use the default density of the system. If the default density is used, the window does not re-layout when the system display size changes. If this parameter is set to true for a system window, the window uses the default density and is not affected by setDefaultDensityEnabled() or setCustomDensity() settings for the main window or setDefaultDensityEnabled() settings for the current window. If this parameter is set to false, the window does not use the default density and is affected by those settings. The default value is false. System capability: SystemCapability.Window.SessionManager

WindowMode⁷⁺

Enumerates the window modes.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Value	Description
UNDEFINED	1	The window mode is not defined by the application.
FULLSCREEN	2	The application is displayed in full screen.
PRIMARY	3	The application is displayed in the primary window in split-screen mode. In top-bottom splits, the top screen is primary; in left-right splits, the left screen is primary.
SECONDARY	4	The application is displayed in the secondary window in split-screen mode. In top-bottom splits, the bottom screen is secondary; in left-right splits, the right screen is secondary.
FLOATING	5	The application is displayed in a floating window.

BlurStyle⁹⁺

Enumerates the window blur styles.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Value	Description
OFF	0	Blur disabled.
THIN	1	Thin blur.
REGULAR	2	Regular blur.
THICK	3	Thick blur.

AnimationType²⁰⁺

Enumerates the types of window animations.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Name	Value	Description
FADE_IN	1	Fade-in animation, which takes effect during window display.

SystemBarRegionTint⁸⁺

Describes the callback for a single system bar.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Read-Only	Optional	Description
type	WindowType	No	No	Type of the system bar whose properties are changed. Only the status bar and navigation bar are supported.
isEnable	boolean	No	Yes	Whether the system bar is displayed. true if displayed, false otherwise. The default value is true.
region	Rect	No	Yes	Current position and size of the system bar. The default value is {0,0,0,0}.
backgroundColor	string	No	Yes	Background color of the system 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'.
contentColor	string	No	Yes	Color of the text on the system bar. The default value is '0xE5FFFFFF'.

SystemBarTintState⁸⁺

Describes the callback for the current system bar.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Read-Only	Optional	Description
displayId	number	No	No	ID of the screen where the window is located. The value must be an integer.
regionTint	Array<SystemBarRegionTint>	No	No	All system bar information that has been changed.

ScaleOptions⁹⁺

Describes the scale parameters.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Read-Only	Optional	Description
x	number	No	Yes	Scale factor along the x-axis. The value is a floating-point number, and the default value is 1.0.
y	number	No	Yes	Scale factor along the y-axis. The value is a floating-point number, and the default value is 1.0.
pivotX	number	No	Yes	X coordinate of the scale center. The value is a floating-point number in the range [0.0, 1.0], and the default value is 0.5.
pivotY	number	No	Yes	Y coordinate of the scale center. The value is a floating-point number in the range [0.0, 1.0], and the default value is 0.5.

RotateOptions⁹⁺

Describes the rotation parameters.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Read-Only	Optional	Description
x	number	No	Yes	Rotation angle around the x-axis. The value is a floating-point number, and the default value is 0.0.
y	number	No	Yes	Rotation angle around the y-axis. The value is a floating-point number, and the default value is 0.0.
z	number	No	Yes	Rotation angle around the z-axis. The value is a floating-point number, and the default value is 0.0.
pivotX	number	No	Yes	X coordinate of the rotation center. The value is a floating-point number in the range [0.0, 1.0], and the default value is 0.5.
pivotY	number	No	Yes	Y coordinate of the rotation center. The value is a floating-point number in the range [0.0, 1.0], and the default value is 0.5.

TranslateOptions⁹⁺

Describes the translation parameters.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Read-Only	Optional	Description
x	number	No	Yes	Distance to translate along the x-axis. The value is a floating-point number, the default value is 0.0, and the unit is px.
y	number	No	Yes	Distance to translate along the y-axis. The value is a floating-point number, the default value is 0.0, and the unit is px.
z	number	No	Yes	Distance to translate along the z-axis. The value is a floating-point number, the default value is 0.0, and the unit is px.

StartAnimationSystemParams²⁰⁺

Describes the start animation configuration. This API works only for full-screen applications.

The configuration does not take effect for inter-application transitions, where the default animation of the system is used.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Device behavior differences: This API can be properly called on tablets in non-free windows mode and phones. If it is called on other device types, it has no effect and does not report errors.

Name	Type	Read-Only	Optional	Description
type	AnimationType	No	No	Type of the window animation.
animationConfig	WindowAnimationConfig	No	Yes	Configuration for the window animation. The default animation curve is WindowAnimationCurve.LINEAR, and the duration is 0.

WindowCreateParams²⁰⁺

Describes the window parameters during application startup.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Name	Type	Read-Only	Optional	Description
systemAnimationParams	StartAnimationSystemParams	No	Yes	Parameters for the startup animation. The default value is undefined. If this parameter is not set, the default animation of the system is used.
isWindowLimitsForcible	boolean	No	Yes	Whether the dimensions of the main window of an application can exceed the default system limit. This parameter takes effect only when the started application is a system application. Otherwise, this parameter does not take effect and no error is reported. - true: The default system limit can be exceeded. During the calculation of the window dimensions limit, the default system limit is ignored. The final effective result is still calculated based on the intersection of each source, and the priority remains unchanged. For details, see WindowLimits. - false: The default system limit cannot be exceeded. The window dimensions limit is calculated based on the default rules (including the default system limit). The default value is false. Since: 26.0.0 Model restriction: This API can be used only in the stage model.

WindowAnchorInfo²⁴⁺

Describes the anchor point information used to maintain the relative position between the level-1 child window and the main window.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name	Type	Read-Only	Optional	Description
anchorType	WindowAnchor	No	No	Type of the anchor point used to maintain the relative position.
offsetX	number	No	Yes	X-axis offset between the anchor points of the child window and the main window, in px. The value must be an integer. Floating-point numbers are rounded down. The default value is 0.
offsetY	number	No	Yes	Y-axis offset between the anchor points of the child window and the main window, in px. The value must be an integer. Floating-point numbers are rounded down. The default value is 0.

SubWindowAttachOptions²⁴⁺

Describes the parameters used to maintain the relative position between the child window and the main window.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Name	Type	Read-Only	Optional	Description
currentLayoutMode	string	No	Yes	Current layout mode of the child window, which is used to control the UI effect customized by the application. If this parameter is not passed, the default value is an empty string.
parentWindowSizeChangeCallback	Callback<Size>	No	Yes	Callback triggered when the parent window size changes. The callback is triggered immediately after the binding, and notifications are sent when the parent window size changes. By default, this parameter is not passed, and notifications about the parent window size changes cannot be received.
parentWindowStatusChangeCallback	Callback<WindowStatusType>	No	Yes	Callback triggered when the parent window mode changes. The callback is triggered immediately after the binding, and notifications are sent when the parent window mode changes. By default, this parameter is not passed, and notifications about the parent window mode changes cannot be received.
isIntersectedWidthLimit	boolean	No	Yes	Whether the width of the child window is mutually restricted with that of the bound main window. The value true indicates that the width of the child window and that of the bound main window cannot exceed the intersection of the width limits of the two windows. If there is no intersection between the width limits of the two windows, they do not restrict each other. When this parameter is set to true for multiple child windows at the same time, the width of all windows (including the main window) involved in mutual restriction is restricted by the intersection of the width limits of all windows. The value false indicates that the width of the child window is not mutually restricted with that of the bound main window. The default value is false. Since: 26.0.0
isIntersectedHeightLimit	boolean	No	Yes	Whether the height of the child window is mutually restricted with that of the bound main window. The value true indicates that the height of the child window and that of the bound main window cannot exceed the intersection of the height limits of the two windows. If there is no intersection between the height limits of the two windows, they do not restrict each other. When this parameter is set to true for multiple child windows at the same time, the height of all windows (including the main window) involved in mutual restriction is restricted by the intersection of the height limits of all windows. The value false indicates that the height of the child window is not mutually restricted with that of the bound main window. The default value is false. Since: 26.0.0

WindowLayoutMode^(deprecated)

Enumerates the window layout modes.

NOTE
This API is supported since API version 9 and deprecated since API version 26.0.0. No substitute is provided.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Value	Description
WINDOW_LAYOUT_MODE_CASCADE^(deprecated)	0	Cascade mode. In this mode, freeform windows are stacked with Z-order arrangement. Note: This enumerated value is supported since API version 9 and deprecated since API version 26.0.0. No substitute is provided.
WINDOW_LAYOUT_MODE_TILE^(deprecated)	1	Tile mode. In this mode, newly opened application windows appear on the rightmost. Note: This enumerated value is supported since API version 9 and deprecated since API version 26.0.0. No substitute is provided.

window.minimizeAll⁹⁺

minimizeAll(id: number, callback: AsyncCallback<void>): void

Minimizes all main windows on a display.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Device behavior differences: This API can be properly called on phones. If it is called on other device types, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
id	number	Yes	ID of the display. The value must be an integer.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300003	This window manager service works abnormally.

Example

import { display } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let displayClass: display.Display | null = null;
displayClass = display.getDefaultDisplaySync();

try {
  if (!displayClass) {
    console.error('displayClass is null');
  } else {
    window.minimizeAll(displayClass.id, (err: BusinessError) => {
      const errCode: number = err?.code;
      if (errCode) {
        console.error(`Failed to minimize all windows. Cause code: ${err?.code}, message: ${err?.message}`);
        return;
      }
      console.info('Succeeded in minimizing all windows.');
    });
  }
} catch (exception) {
  console.error(`Failed to minimize all windows. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.minimizeAll⁹⁺

minimizeAll(id: number): Promise<void>

Minimizes all main windows on a display. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Device behavior differences: This API can be properly called on phones. If it is called on other device types, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
id	number	Yes	ID of the display. The value must be an integer.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300003	This window manager service works abnormally.

Example

import { display } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let displayClass: display.Display | null = null;
displayClass = display.getDefaultDisplaySync();

try {
  let promise = window.minimizeAll(displayClass.id);
  promise.then(() => {
    console.info('Succeeded in minimizing all windows.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to minimize all windows. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to minimize all windows. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.minimizeAllWithExclusion²³⁺

minimizeAllWithExclusion(displayId: number, excludeWindowId: number): Promise<void>

Minimizes all main windows on a display while keeping one window open. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Device behavior differences: This API can be properly called on phones. If it is called on other device types, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID. The value must be an integer. Non-integer values are rounded down.
excludeWindowId	number	Yes	Window ID. You can call getWindowProperties to obtain the window properties, in which id is the window ID. If the window ID is less than or equal to 0, or the window ID is null or undefined, error code 401 is thrown. If the window ID is greater than 0 but the window does not exist, error code 1300002 is thrown. If the window ID is greater than 0 but the window exists on another display, all main windows on the specified display are minimized. The value must be an integer. Floating-point numbers are rounded down.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal. Possible cause: 1.Window is nullptr; 2. Failed to find specified window by id.
1300003	This window manager service works abnormally.

Example

import { display, window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let displayClass: display.Display | null = null;
displayClass = display.getDefaultDisplaySync();
let excludeWindowId = 1;

try {
  let promise = window.minimizeAllWithExclusion(displayClass.id, excludeWindowId);
  promise.then(() => {
    console.info('Succeeded in minimizing all windows.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to minimize all windows. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to minimize all windows. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.toggleShownStateForAllAppWindows⁹⁺

toggleShownStateForAllAppWindows(callback: AsyncCallback<void>): void

Hides or restores the application's windows during quick multi-window switching. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

window.toggleShownStateForAllAppWindows((err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to toggle shown state for all app windows. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in toggling shown state for all app windows.');
});

window.toggleShownStateForAllAppWindows⁹⁺

toggleShownStateForAllAppWindows(): Promise<void>

Hides or restores the application's windows during quick multi-window switching. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = window.toggleShownStateForAllAppWindows();
promise.then(() => {
  console.info('Succeeded in toggling shown state for all app windows.');
}).catch((err: BusinessError) => {
  console.error(`Failed to toggle shown state for all app windows. Cause code: ${err.code}, message: ${err.message}`);
});

window.on('systemBarTintChange')⁸⁺

on(type: 'systemBarTintChange', callback: Callback<SystemBarTintState>): void

Subscribes to the property change event of the status bar and navigation bar.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'systemBarTintChange', indicating the property change event of the status bar and navigation bar.
callback	Callback<SystemBarTintState>	Yes	Callback used to return the properties of the status bar and navigation bar.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

try {
  window.on('systemBarTintChange', (data) => {
    console.info('Succeeded in enabling the listener for systemBarTint changes. Data: ' + JSON.stringify(data));
  });
} catch (exception) {
  console.error(`Failed to enable the listener for systemBarTint changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.off('systemBarTintChange')⁸⁺

off(type: 'systemBarTintChange', callback?: Callback<SystemBarTintState >): void

Unsubscribes from the property change event of the status bar and navigation bar.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'systemBarTintChange', indicating the property change event of the status bar and navigation bar.
callback	Callback<SystemBarTintState>	No	Callback used to return the properties of the status bar and navigation bar. 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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

Example

const callback = (systemBarTintState: window.SystemBarTintState) => {
  // ...
}
try {
  window.on('systemBarTintChange', callback);

  window.off('systemBarTintChange', callback);
  // Unregister all the callbacks that have been registered through on().
  window.off('systemBarTintChange');
} catch (exception) {
  console.error(`Failed to enable or disable the listener for systemBarTint changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.on('gestureNavigationEnabledChange')¹⁰⁺

on(type: 'gestureNavigationEnabledChange', callback: Callback<boolean>): void

Subscribes to the gesture navigation status change event.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'gestureNavigationEnabledChange', indicating the gesture navigation status change event.
callback	Callback<boolean>	Yes	Callback used to return the gesture navigation status. true if enabled, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

try {
  window.on('gestureNavigationEnabledChange', (data) => {
    console.info(`Succeeded in enabling the listener for gesture navigation status changes. Data: ${data}`);
  });
} catch (exception) {
  console.error(`Failed to enable the listener for gesture navigation status changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.off('gestureNavigationEnabledChange')¹⁰⁺

off(type: 'gestureNavigationEnabledChange', callback?: Callback<boolean>): void

Unsubscribes from the gesture navigation status change event.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'gestureNavigationEnabledChange', indicating the gesture navigation status change event.
callback	Callback<boolean>	No	Callback function that has been used for the subscription. 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.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

const callback = (bool: boolean) => {
  // ...
}
try {
  window.on('gestureNavigationEnabledChange', callback);
  window.off('gestureNavigationEnabledChange', callback);
  // Unregister all the callbacks that have been registered through on().
  window.off('gestureNavigationEnabledChange');
} catch (exception) {
  console.error(`Failed to enable or disable the listener for gesture navigation status changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.on('waterMarkFlagChange')¹⁰⁺

on(type: 'waterMarkFlagChange', callback: Callback<boolean>): void

Subscribes to the watermark status change event.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'waterMarkFlagChange', indicating the watermark status change event.
callback	Callback<boolean>	Yes	Callback used to return the watermark status. true if enabled, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

try {
  window.on('waterMarkFlagChange', (data) => {
    console.info(`Succeeded in enabling the listener for watermark flag changes. Data: ${data}`);
  });
} catch (exception) {
  console.error(`Failed to enable the listener for watermark flag changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.off('waterMarkFlagChange')¹⁰⁺

off(type: 'waterMarkFlagChange', callback?: Callback<boolean>): void

Unsubscribes from the watermark status change event.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'waterMarkFlagChange', indicating the watermark status change event.
callback	Callback<boolean>	No	Callback function that has been used for the subscription. 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.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

const callback = (bool: boolean) => {
  // ...
}
try {
  window.on('waterMarkFlagChange', callback);
  window.off('waterMarkFlagChange', callback);
  // Unregister all the callbacks that have been registered through on().
  window.off('waterMarkFlagChange');
} catch (exception) {
  console.error(`Failed to enable or disable the listener for watermark flag changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setGestureNavigationEnabled¹⁰⁺

setGestureNavigationEnabled(enable: boolean, callback: AsyncCallback<void>): void

Enables or disables gesture navigation. This API uses an asynchronous callback to return the result. For security purposes, the system does not interfere with the disabling and enabling of gesture navigation. If an application exits abnormally after it disables gesture navigation and wants to restore gesture navigation, it must implement automatic launch and call this API again to enable gesture navigation.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to enable gesture navigation. true to enable, false otherwise. Currently, only the pull-down gesture is disabled. Other gestures remain enabled.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  window.setGestureNavigationEnabled(true, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set gesture navigation enabled. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in setting gesture navigation enabled.');
  });
} catch (exception) {
  console.error(`Failed to set gesture navigation enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setGestureNavigationEnabled¹⁰⁺

setGestureNavigationEnabled(enable: boolean): Promise<void>

Enables or disables gesture navigation. This API uses a promise to return the result. For security purposes, the system does not interfere with the disabling and enabling of gesture navigation. If an application exits abnormally after it disables gesture navigation and wants to restore gesture navigation, it must implement automatic launch and call this API again to enable gesture navigation.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to enable gesture navigation. true to enable, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let promise = window.setGestureNavigationEnabled(true);
  promise.then(() => {
    console.info('Succeeded in setting gesture navigation enabled.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set gesture navigation enabled. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set gesture navigation enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setWaterMarkImage¹⁰⁺

setWaterMarkImage(pixelMap: image.PixelMap, enable: boolean, callback: AsyncCallback<void>): void

Controls whether a watermark image is displayed on the screen. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
pixelMap	image.PixelMap	Yes	Watermark image, which can be obtained by calling createPixelMap.
enable	boolean	Yes	Whether to display the watermark image. true to display, false otherwise. After the watermark image is displayed, you need to set this parameter to false to disable the watermark display.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300003	This window manager service works abnormally.

Example

import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

let enable: boolean = true;
let color: ArrayBuffer = new ArrayBuffer(40000);
let initializationOptions: image.InitializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions).then((pixelMap: image.PixelMap) => {
  console.info('Succeeded in creating pixelmap.');
  try {
    window.setWaterMarkImage(pixelMap, enable, (err: BusinessError) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error(`Failed to show watermark image. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info('Succeeded in showing watermark image.');
    });
  } catch (exception) {
    console.error(`Failed to show watermark image. Cause code: ${exception.code}, message: ${exception.message}`);
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to create PixelMap. Cause code: ${err.code}, message: ${err.message}`);
});

window.setWaterMarkImage¹⁰⁺

setWaterMarkImage(pixelMap: image.PixelMap, enable: boolean): Promise<void>

Controls whether a watermark image is displayed on the screen. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
pixelMap	image.PixelMap	Yes	Watermark image, which can be obtained by calling createPixelMap.
enable	boolean	Yes	Whether to display the watermark image. true to display, false otherwise. After the watermark image is displayed, you need to set this parameter to false to disable the watermark display.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300003	This window manager service works abnormally.

Example

import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

let enable: boolean = true;
let color: ArrayBuffer = new ArrayBuffer(40000);
let initializationOptions: image.InitializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions).then((pixelMap: image.PixelMap) => {
  console.info('Succeeded in creating pixelmap.');
  try {
    let promise = window.setWaterMarkImage(pixelMap, enable);
    promise.then(() => {
      console.info('Succeeded in showing watermark image.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to show watermark image. Cause code: ${err.code}, message: ${err.message}`);
    });
  } catch (exception) {
    console.error(`Failed to show watermark image. Cause code: ${exception.code}, message: ${exception.message}`);
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to create PixelMap. Cause code: ${err.code}, message: ${err.message}`);
});

window.setWaterMarkImage

setWaterMarkImage(pixelMap: image.PixelMap, enable: boolean, priority: number): Promise<void>

Sets the display status of a watermark image on the screen and the watermark priority. This API uses a promise to return the result. When priority is set to 0, this API is equivalent to setWaterMarkImage.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
pixelMap	image.PixelMap	Yes	Watermark image, which can be obtained by calling createPixelMap.
enable	boolean	Yes	Whether to display the watermark image. true means that the watermark image is displayed, and false means the opposite. After the watermark image is displayed, you need to set this parameter to false to disable the watermark display.
priority	number	Yes	Watermark priority. A smaller value indicates a higher priority. The value must be greater than or equal to 0. If the value is less than 0, error code 1300016 is returned. If the input priority in this watermark setting is lower than the previous setting, the current setting does not take effect.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300003	This window manager service works abnormally.
1300016	Parameter error. Possible cause: Invalid parameter range.

Example

import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

let enable: boolean = true;
let color: ArrayBuffer = new ArrayBuffer(40000);
let initializationOptions: image.InitializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions).then((pixelMap: image.PixelMap) => {
  console.info('Succeeded in creating pixelmap.');
  try {
    window.setWaterMarkImage(pixelMap, enable, 0).then(() => {
      console.info('Succeeded in showing watermark image.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to show watermark image. Cause code: ${err.code}, message: ${err.message}`);
    });
  } catch (exception) {
    console.error(`Failed to show watermark image. Cause code: ${exception.code}, message: ${exception.message}`);
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to create PixelMap. Cause code: ${err.code}, message: ${err.message}`);
});

window.getSnapshot¹²⁺

getSnapshot(windowId: number): Promise<image.PixelMap>

Obtains a snapshot of the same size as the specified window. This API uses a promise to return the result. If privacy mode is enabled for the current window (using setWindowPrivacyMode), taking a screenshot will result in a blank screen.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
windowId	number	Yes	Window ID. You can call getWindowProperties to obtain the window properties, in which id is the window ID.

Return value

Type	Description
Promise<image.PixelMap>	Promise used to return the window screenshot.

Error codes For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
1300002	This window state is abnormal. Possible cause: Internal task error.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

try {
  // This is only an example. Use getWindowProperties to obtain the window ID.
  let windowId: number = 40;
  let promise = window.getSnapshot(windowId);
  promise.then((pixelMap: image.PixelMap) => {
    console.info('Succeeded in getting snapshot window. Pixel bytes number:' + pixelMap.getPixelBytesNumber());
    pixelMap.release();
  }).catch((err: BusinessError) =>{
    console.error(`Failed to get snapshot. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to get snapshot. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.notifyScreenshotEvent²⁰⁺

notifyScreenshotEvent(eventType: ScreenshotEventType): Promise<void>

Notifies a screenshot event. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
eventType	ScreenshotEventType	Yes	Type of the screenshot event.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300003	This window manager service works abnormally.
1300016	Parameter error. Possible cause: 1. Invalid parameter range.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let eventType: window.ScreenshotEventType = window.ScreenshotEventType.SYSTEM_SCREENSHOT;
  let promise = window.notifyScreenshotEvent(eventType);
  promise.then(() => {
    console.info(`Succeeded in notifying screenshot event type.`);
  }).catch((err: BusinessError) =>{
    console.error(`Failed to notify screenshot event type. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to notify screenshot event type. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.getTopNavDestinationName²⁰⁺

getTopNavDestinationName(windowId: number): Promise<string>

Obtains the name of NavDestination in the current top-level Navigation component of the specified foreground window. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
windowId	number	Yes	ID of the window to query. This parameter must be an integer greater than 0. If it is less than or equal to 0, error code 1300016 is returned. If the specified window does not exist or is not in the foreground, error code 1300002 is returned.

Return value

Type	Description
Promise<string>	Promise used to return the NavDestination name obtained. If there are nested Navigation components or multiple Navigation components on the current page, the information of the most recently created Navigation component is queried. If the page does not have the Navigation component or the Navigation component does not have NavDestination, an empty string is returned.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed, non-system application uses system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300016	Parameter error. Possible cause: 1. Invalid parameter range.

Example

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let windowId = 10;
  let promise = window.getTopNavDestinationName(windowId);
  promise.then((data) => {
    console.info(`Succeeded, data: ${data}`);
  }).catch((err: BusinessError) => {
    console.error(`Failed, cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed, exception code: ${exception.code}, message: ${exception.message}`);
}

window.setSpecificSystemWindowZIndex²³⁺

setSpecificSystemWindowZIndex(windowType: WindowType, zIndex: number): Promise<void>

Sets the z-level of a system window. This API uses a promise to return the result.

Adjusts the zIndex of all system windows of the specified type to the configured value. Before and after the adjustment, the relative z-level of these windows remains unchanged, and the focus window does not change. After the application is closed, the z-level of specified windows is restored to the default value.

You are advised to set different zIndex values for different types of windows. If there are windows with the same zIndex, the relative z-level of windows remains unchanged before and after the setting.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
windowType	WindowType	Yes	Window type. Only the following types are supported: TYPE_WALLET_SWIPE_CARD, TYPE_VOICE_INTERACTION, TYPE_SCREENSHOT, TYPE_SCREEN_CONTROL, TYPE_FLOAT_NAVIGATION, and TYPE_MUTISCREEN_COLLABORATION.
zIndex	number	Yes	Z-level of the system window. The value must be an integer. Floating-point numbers are rounded down. The value 0 or a negative number will place the window below the home screen.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed, non-system application uses system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: Invalid window type. Possible cause: Invalid window type.

Example

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
try {
  window.setSpecificSystemWindowZIndex(window.WindowType.TYPE_WALLET_SWIPE_CARD, 200).then(() => {
    console.info('Succeeded in setting zIndex');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set zIndex. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set zIndex. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.createSubWindowAndBindParent

createSubWindowAndBindParent(name: string, parentId: number, ctx: BaseContext, parentWindowEventListener: WindowEventListener): Promise<Window>

Creates a subwindow and binds it to the parent window. This API uses a promise to return the result.

Only the main window can be bound as the parent window.

The subwindow is displayed or hidden along with the parent window, but is not destroyed when the parent window is destroyed. The subwindow listens to the lifecycle changes of the parent window through a callback function.

It is recommended that you destroy the created subwindow after the parent window is destroyed.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Window name.
parentId	number	Yes	Parent window ID. You are advised to call getWindowProperties() to obtain the window ID.
ctx	BaseContext	Yes	Current application context.
parentWindowEventListener	WindowEventListener	Yes	Callback used to return the lifecycle changes of the bound parent window.

Return value

Type	Description
Promise<Window>	Promise used to return the child window created.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. This can not work correctly due to limited device capabilities.
1300001	Repeated operation. Possible cause: The window has been created and can not be created again.
1300002	This window state is abnormal. Possible cause: 1. Internal task error. 2. The number of windows has reached the limit.
1300003	This window manager service works abnormally.
1300009	The parent window is invalid. Possible cause: 1. The parent window does not exist or has been destroyed. 2. Invalid window type. Only main windows are supported.

Example

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    let windowClass: window.Window | undefined = undefined;
    const parentWindowEventListener = (windowId: number, event: window.WindowEventType) => {
      // ...
    }
    try {
      let promise = window.createSubWindowAndBindParent('test', 100, this.context, parentWindowEventListener);
      promise.then((data) => {
        console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
        windowClass = data;
      }).catch((err: BusinessError) => {
        console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

window.moveMainWindowToTargetDisplay

moveMainWindowToTargetDisplay(displayId: number, windowId: number): Promise<void>

Moves the specified main window to the specified display. This API uses a promise to return the result.

For window movement between the displays of a main screen or an extended screen and a virtual screen, or of virtual screens, only the main window and its child windows are moved to the corresponding display and raised. If there are child windows, the topmost child window that can obtain focus will obtain the focus; otherwise, the main window will obtain the focus.
For window movement between the displays of a main screen and an extended screen, only the main window is moved to the corresponding display, and is raised and obtains focus.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	ID of the display to which the window is moved. The value must be a non-negative integer. You can obtain the value by calling getWindowProperties to obtain properties and then using properties.displayId. You can also obtain the value by using id of the Display object.
windowId	number	Yes	ID of the window to be moved. The value must be an integer greater than 0. You can obtain the value by calling getWindowProperties to obtain properties and then using properties.id.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed, non-system application uses system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.
1300008	The display device is abnormal.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { display, window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    windowStage.loadContent('pages/Index', (err: BusinessError) => {
      if (err.code) {
        console.error(`Failed to load content for main window. Cause code: ${err.code}, message: ${err.message}`);
      }
      let displayClass: display.Display | null = null;
      displayClass = display.getDefaultDisplaySync();
      let mainWindow = windowStage.getMainWindowSync();
      try {
        window.moveMainWindowToTargetDisplay(displayClass.id, mainWindow.getWindowProperties().id).then(() => {
          console.info(`Succeeded in moving window id: ${mainWindow.getWindowProperties().id} to target display id: ${mainWindow.getWindowProperties().displayId}`);
        }).catch((err: BusinessError) => {
          console.error(`Failed to move window to target display. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to move window to target display. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

window.setWindowLayoutMode^(deprecated)

setWindowLayoutMode(mode: WindowLayoutMode, callback: AsyncCallback<void>): void

Sets the window layout mode. This API uses an asynchronous callback to return the result.

NOTE
This API is supported since API version 9 and deprecated since API version 26.0.0. No substitute is provided.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
mode	WindowLayoutMode	Yes	Window layout mode to set.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  window.setWindowLayoutMode(window.WindowLayoutMode.WINDOW_LAYOUT_MODE_CASCADE, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set window layout mode. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in setting window layout mode.');
  });
} catch (exception) {
  console.error(`Failed to set window layout mode. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setWindowLayoutMode^(deprecated)

setWindowLayoutMode(mode: WindowLayoutMode): Promise<void>

Sets the window layout mode. This API uses a promise to return the result.

NOTE
This API is supported since API version 9 and deprecated since API version 26.0.0. No substitute is provided.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
mode	WindowLayoutMode	Yes	Window layout mode to set.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let promise = window.setWindowLayoutMode(window.WindowLayoutMode.WINDOW_LAYOUT_MODE_CASCADE);
  promise.then(() => {
    console.info('Succeeded in setting window layout mode.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set window layout mode. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set window layout mode. Cause code: ${exception.code}, message: ${exception.message}`);
}

Window

Represents a window instance, which is the basic unit managed by the window manager.

In the following API examples, you must use getLastWindow(), createWindow(), or findWindow() to obtain a Window instance (named windowClass in this example) and then call a method in this instance.

hide⁷⁺

hide (callback: AsyncCallback<void>): void

Hides this window. This API uses an asynchronous callback to return the result. This API takes effect only for a system window or an application child window.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal.

Example

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.hide((err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to hide the window. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in hiding the window.');
});

hide⁷⁺

hide(): Promise<void>

Hides this window. This API uses a promise to return the result. This API takes effect only for a system window or an application child window.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.hide();
promise.then(() => {
  console.info('Succeeded in hiding the window.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide the window. Cause code: ${err.code}, message: ${err.message}`);
});

hideWithAnimation⁹⁺

hideWithAnimation(callback: AsyncCallback<void>): void

Hides this window and plays an animation during the process. This API uses an asynchronous callback to return the result. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

Example

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.hideWithAnimation((err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to hide the window with animation. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in hiding the window with animation.');
});

hideWithAnimation⁹⁺

hideWithAnimation(): Promise<void>

Hides this window and plays an animation during the process. This API uses a promise to return the result. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.hideWithAnimation();
promise.then(() => {
  console.info('Succeeded in hiding the window with animation.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide the window with animation. Cause code: ${err.code}, message: ${err.message}`);
});

showWithAnimation⁹⁺

showWithAnimation(callback: AsyncCallback<void>): void

Shows this window and plays an animation during the process. This API uses an asynchronous callback to return the result. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

Example

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.showWithAnimation((err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to show the window with animation. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in showing the window with animation.');
});

showWithAnimation⁹⁺

showWithAnimation(): Promise<void>

Shows this window and plays an animation during the process. This API uses a promise to return the result. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.showWithAnimation();
promise.then(() => {
  console.info('Succeeded in showing the window with animation.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show the window with animation. Cause code: ${err.code}, message: ${err.message}`);
});

setWindowMode⁹⁺

setWindowMode(mode: WindowMode, callback: AsyncCallback<void>): void

Sets the mode of the main window. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
mode	WindowMode	Yes	Window mode to set.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    windowStage.getMainWindow((err: BusinessError, data) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      windowClass = data;
      let mode = window.WindowMode.FULLSCREEN;
      try {
        windowClass.setWindowMode(mode, (err: BusinessError) => {
          const errCode: number = err.code;
          if (errCode) {
            console.error(`Failed to set the window mode. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in setting the window mode.');
        });
      } catch (exception) {
        console.error(`Failed to set the window mode. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

setWindowMode⁹⁺

setWindowMode(mode: WindowMode): Promise<void>

Sets the mode of the main window. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
mode	WindowMode	Yes	Window mode to set.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    windowStage.getMainWindow((err: BusinessError, data) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      windowClass = data;
      let mode = window.WindowMode.FULLSCREEN;
      try {
        let promise = windowClass.setWindowMode(mode);
        promise.then(() => {
          console.info('Succeeded in setting the window mode.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to set the window mode. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to set the window mode. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

attachLayoutToParentWindow²⁴⁺

attachLayoutToParentWindow(anchorInfo?: WindowAnchorInfo, attachOptions?: SubWindowAttachOptions): Promise<void>

Attaches a first-level child window to the main window to maintain a fixed relative position. This API uses a promise to return the result.

The relative position is represented by the anchor point offset between the child window and the parent window. The child window and the parent window use the same window anchor point.

This API can be called by non-independent child windows. When this API is called by independent child windows, result code 1300004 will be returned.

NOTE

Only first-level child windows can call this API. The child window must be in floating window mode (that is, the window mode is window.WindowStatusType.FLOATING).

After the child window calls this API, the display position of the child window immediately follows the main window and the relative position remains unchanged. In addition, the size and mode changes of the main window can be listened to. The effect will persist unless the detachLayoutToParentWindow() API is called for detaching.

After the child window calls this API, calling APIs such as moveWindowTo(), maximize(), and setFollowParentWindowLayoutEnabled() to change the window position, or dragging and moving or dragging and resizing the child window through mouse or touch operations will not take effect.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Device behavior differences: This API can be called properly on a device that supports freeform windows and is in the freeform window state. If the device supports freeform windows but is not in the freeform window state, no error is thrown and this API does not take effect until the device is in the freeform window state. If the device does not support freeform windows, this API does not take effect and no error is reported.

Parameters

Name	Type	Mandatory	Description
anchorInfo	WindowAnchorInfo	No	Anchor point information used to attach the first-level child window to the main window to maintain the fixed relative position. If this parameter is not passed, the default logic is the same as that of WindowAnchorInfo.
attachOptions	SubWindowAttachOptions	No	Additional parameters for setting the child window layout. If this parameter is not passed, the default logic is the same as that of SubWindowAttachOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
801	Capability not supported. Function attachLayoutToParentWindow can not work correctly due to limited device capabilities.
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: 1. Invalid window type. Only subwindows are supported; 2. The current window's parent window is not a main window; 3. Only level-1 subwindows are supported.
1300010	The operation in the current window status is invalid. Possible cause: 1. The subwindow is following its parent window's layout. 2. The subwindow is maximized.

Example

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (loadError: BusinessError) => {
      if (loadError.code) {
        console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`);
        return;
      }
      console.info("Succeeded in loading the content.");
      windowStage.createSubWindow("subWindow").then((subWindow: window.Window) => {
        if (subWindow == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        let anchorInfo : window.WindowAnchorInfo = {
          anchorType: window.WindowAnchor.TOP_START,
          offsetX: 0,
          offsetY: 0
        };
        let attachOptions: window.SubWindowAttachOptions = {
          parentWindowSizeChangeCallback:(data: window.Size) => {
            console.info(`Successfully accepted parentWindow size change, width: ${data.width}, height: ${data.height}`);
          },
          parentWindowStatusChangeCallback:(type: window.WindowStatusType) => {
            console.info(`Successfully accepted parentWindow status change, statusType: ${type}`);
          },
          isIntersectedWidthLimit: true,
          isIntersectedHeightLimit: true
        }
        subWindow.attachLayoutToParentWindow(anchorInfo, attachOptions).then(() => {
          console.info("Succeeded in attaching to the main window");
        }).catch((error: BusinessError) => {
          console.error(`attachLayoutToParentWindow failed. ${error.code} ${error.message}`);
        })
      }).catch((error: BusinessError) => {
        console.error(`createSubWindow failed. ${error.code} ${error.message}`);
      })
    });
  }
}

detachLayoutToParentWindow²⁴⁺

detachLayoutToParentWindow(): Promise<void>

Detach a first-level child window from the main window to cancel a fixed relative position. This API uses a promise to return the result.

This API can be called by non-independent child windows. When this API is called by independent child windows, result code 1300004 will be returned.

NOTE

When the child window calls this API, the child window must be in the attached state.

After detached by calling this API, the child window retains its position during attaching. You can drag the child window to change its size and position.

After the detaching, calling APIs such as moveWindowTo(), maximize(), and setFollowParentWindowLayoutEnabled() to change the window position, or dragging and moving or dragging and resizing the child window through mouse or touch operations will take effect.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
801	Capability not supported. Function detachLayoutToParentWindow can not work correctly due to limited device capabilities.
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: 1. Invalid window type. Only subwindows are supported; 2. Only level-1 subwindows are supported.
1300010	The operation in the current window status is invalid. Possible cause: The subwindow is not attached to the main window.

Example

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (loadError: BusinessError) => {
      if (loadError.code) {
        console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`);
        return;
      }
      console.info("Succeeded in loading the content.");
      windowStage.createSubWindow("subWindow").then((subWindow: window.Window) => {
        if (subWindow == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        subWindow.detachLayoutToParentWindow().then(() => {
          console.info("Succeeded in detaching to the main window");
        }).catch((error: BusinessError) => {
          console.error(`detachLayoutToParentWindow failed. ${error.code} ${error.message}`);
        })
      }).catch((error: BusinessError) => {
        console.error(`createSubWindow failed. ${error.code} ${error.message}`);
      })
    });
  }
}

bindDialogTarget⁹⁺

bindDialogTarget(token: rpc.RemoteObject, deathCallback: Callback<void>, callback: AsyncCallback<void>): void

Binds the modal window to the target window. After the binding is successful, the target window cannot respond to user operations. In addition, a callback used to listen for modal window destruction events is added. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
token	rpc.RemoteObject	Yes	Token of the target window.
deathCallback	Callback<void>	Yes	Callback used to listen for modal window destruction events.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { rpc } from '@kit.IPCKit';
import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class Property {
  public value: Object

  constructor(value: Object) {
    this.value = value
  }
}

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    let config: window.Configuration = {
      name: "test",
      windowType: window.WindowType.TYPE_DIALOG,
      ctx: this.context
    };
    try {
      window.createWindow(config, (err: BusinessError, data) => {
        let errCode: number = err?.code;
        if (errCode) {
          console.error(`Failed to create the window. Cause code: ${err?.code}, message: ${err?.message}`);
          return;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let token = want.parameters?.['ohos.ability.params.request.token'] as Property;
        let value = token.value as rpc.RemoteObject;
        data.bindDialogTarget(value, () => {
          console.info('Dialog Window Need Destroy.');
          }, (err: BusinessError) => {
          let errCode: number = err?.code;
          if (errCode) {
            console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
            return;
          }
          console.info('Succeeded in binding dialog target.');
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

bindDialogTarget⁹⁺

bindDialogTarget(token: rpc.RemoteObject, deathCallback: Callback<void>): Promise<void>

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
token	rpc.RemoteObject	Yes	Token of the target window.
deathCallback	Callback<void>	Yes	Callback used to listen for modal window destruction events.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { rpc } from '@kit.IPCKit';
import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class Property {
  public value: Object

  constructor(value: Object) {
    this.value = value
  }
}

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    let config: window.Configuration = {
      name: "test",
      windowType: window.WindowType.TYPE_DIALOG,
      ctx: this.context
    };
    try {
      window.createWindow(config, (err: BusinessError, data) => {
        const errCode: number = err?.code;
        if (errCode) {
          console.error(`Failed to create the window. Cause code: ${err?.code}, message: ${err?.message}`);
          return;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let token = want.parameters?.['ohos.ability.params.request.token'] as Property;
        let value = token.value as rpc.RemoteObject;
        let promise = data.bindDialogTarget(value, () => {
          console.info('Dialog Window Need Destroy.');
        });
        promise.then(() => {
          console.info('Succeeded in binding dialog target.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

bindDialogTarget⁹⁺

bindDialogTarget(requestInfo: dialogRequest.RequestInfo, deathCallback: Callback<void>, callback: AsyncCallback<void>): void

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
requestInfo	dialogRequest.RequestInfo	Yes	RequestInfo of the target window.
deathCallback	Callback<void>	Yes	Callback used to listen for modal window destruction events.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    let config: window.Configuration = {
      name: "test", windowType: window.WindowType.TYPE_DIALOG, ctx: this.context
    };
    try {
      window.createWindow(config, (err: BusinessError, data) => {
        let errCode: number = err?.code;
        if (errCode) {
          console.error(`Failed to create the window. Cause code: ${err?.code}, message: ${err?.message}`);
          return;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let requestInfo = dialogRequest.getRequestInfo(want);
        data.bindDialogTarget(requestInfo, () => {
          console.info('Dialog Window Need Destroy.');
          }, (err: BusinessError) => {
          let errCode: number = err?.code;
          if (errCode) {
            console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
            return;
          }
          console.info('Succeeded in binding dialog target.');
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

bindDialogTarget⁹⁺

bindDialogTarget(requestInfo: dialogRequest.RequestInfo, deathCallback: Callback<void>): Promise<void>

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
requestInfo	dialogRequest.RequestInfo	Yes	RequestInfo of the target window.
deathCallback	Callback<void>	Yes	Callback used to listen for modal window destruction events.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    let config: window.Configuration = {
      name: "test", windowType: window.WindowType.TYPE_DIALOG, ctx: this.context
    };
    try {
      window.createWindow(config, (err: BusinessError, data) => {
        const errCode: number = err?.code;
        if (errCode) {
          console.error(`Failed to create the window. Cause code: ${err?.code}, message: ${err?.message}`);
          return;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let requestInfo = dialogRequest.getRequestInfo(want);
        let promise = data.bindDialogTarget(requestInfo, () => {
          console.info('Dialog Window Need Destroy.');
        });
        promise.then(() => {
          console.info('Succeeded in binding dialog target.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

setWakeUpScreen⁹⁺

setWakeUpScreen(wakeUp: boolean): void

Wakes up the screen.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
wakeUp	boolean	Yes	Whether to wake up the screen. true to wake up, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

let wakeUp: boolean = true;
try {
  windowClass.setWakeUpScreen(wakeUp);
} catch (exception) {
  console.error(`Failed to wake up the screen. Cause code: ${exception.code}, message: ${exception.message}`);
}

setSnapshotSkip⁹⁺

setSnapshotSkip(isSkip: boolean): void

Sets whether to ignore this window during screen capture, recording, or casting. This API is typically used in situations where you want to prevent screen capture, recording, or casting.

If you want the window to always be ignored during screen capture, recording, or casting while it is in the foreground, listen for window lifecycle changes using on('windowEvent'). Set isSkip to false when the window is in the background and true when it is in the foreground.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
isSkip	boolean	Yes	Whether to ignore the window. The default value is false. true to ignore, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002	This window state is abnormal.

Example

let isSkip: boolean = true;
try {
  windowClass.setSnapshotSkip(isSkip);
} catch (exception) {
  console.error(`Failed to Skip. Cause code: ${exception.code}, message: ${exception.message}`);
}

opacity⁹⁺

opacity(opacity: number): void

Sets the opacity for this window. This API can be used only when you customize an animation to be played during the display or hiding of a system window, global floating window, and modal window.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
opacity	number	Yes	Opacity. The value is a floating-point number in the range [0.0, 1.0]. The value 0.0 means completely transparent, and 1.0 means completely opaque.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

try {
  windowClass.opacity(0.5);
} catch (exception) {
  console.error(`Failed to opacity. Cause code: ${exception.code}, message: ${exception.message}`);
}

scale⁹⁺

scale(scaleOptions: ScaleOptions): void

Sets the scale parameters for this window. This API can be used only when you customize an animation to be played during the display or hiding of a system window, global floating window, and modal window.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
scaleOptions	ScaleOptions	Yes	Scale parameters to set.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

let obj: window.ScaleOptions = {
  x: 2.0,
  y: 1.0,
  pivotX: 0.5,
  pivotY: 0.5
};
try {
  windowClass.scale(obj);
} catch (exception) {
  console.error(`Failed to scale. Cause code: ${exception.code}, message: ${exception.message}`);
}

rotate⁹⁺

rotate(rotateOptions: RotateOptions): void

Sets the rotation parameters for this window. This API can be used only when you customize an animation to be played during the display or hiding of a system window, global floating window, and modal window.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
rotateOptions	RotateOptions	Yes	Rotation parameters to set.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

let obj: window.RotateOptions = {
  x: 1.0,
  y: 1.0,
  z: 45.0,
  pivotX: 0.5,
  pivotY: 0.5
};
try {
  windowClass.rotate(obj);
} catch (exception) {
  console.error(`Failed to rotate. Cause code: ${exception.code}, message: ${exception.message}`);
}

translate⁹⁺

translate(translateOptions: TranslateOptions): void

Sets the translation parameters for this window. This API can be used only when you customize an animation to be played during the display or hiding of a system window, global floating window, and modal window.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
translateOptions	TranslateOptions	Yes	Translation parameters. The unit is px.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

let obj: window.TranslateOptions = {
  x: 100.0,
  y: 0.0,
  z: 0.0
};
try {
  windowClass.translate(obj);
} catch (exception) {
  console.error(`Failed to translate. Cause code: ${exception.code}, message: ${exception.message}`);
}

getTransitionController⁹⁺

getTransitionController(): TransitionController

Obtains the transition animation controller. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Return value

Type	Description
TransitionController	Transition animation controller.

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

let controller = windowClass.getTransitionController(); // Obtain the transition animation controller.

setBlur⁹⁺

setBlur(radius: number): void

Blurs this window. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
radius	number	Yes	Radius of the blur. The value is a floating-point number greater than or equal to 0.0, in px. The value 0.0 means that the blur is disabled for the window.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

try {
  windowClass.setBlur(4.0);
} catch (exception) {
  console.error(`Failed to set blur. Cause code: ${exception.code}, message: ${exception.message}`);
}

setBackdropBlur⁹⁺

setBackdropBlur(radius: number): void

Blurs the background of this window. This API can be used only for system windows, global floating windows, and modal windows.

The window background refers to the lower-layer area covered by the window, which is the same as the window size.

To make the blur effect visible, you must set the window background transparent by calling setWindowBackgroundColor.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
radius	number	Yes	Radius of the blur. The value is a floating-point number greater than or equal to 0.0, in px. The value 0.0 means that the blur is disabled for the background of the window.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

try {
  windowClass.setWindowBackgroundColor('#00FFFFFF');
  windowClass.setBackdropBlur(4.0);
} catch (exception) {
  console.error(`Failed to set backdrop blur. Cause code: ${exception.code}, message: ${exception.message}`);
}

setBackdropBlurStyle⁹⁺

setBackdropBlurStyle(blurStyle: BlurStyle): void

Sets the blur style for the background of this window. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
blurStyle	BlurStyle	Yes	Blur style to set for the background of the window.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

try {
  windowClass.setBackdropBlurStyle(window.BlurStyle.THIN);
} catch (exception) {
  console.error(`Failed to set backdrop blur style. Cause code: ${exception.code}, message: ${exception.message}`);
}

setShadow⁹⁺

setShadow(radius: number, color?: string, offsetX?: number, offsetY?: number): void

Sets the shadow for the window borders. This API can be used only for system windows, application subwindows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
radius	number	Yes	Radius of the shadow. The value is a floating-point number greater than or equal to 0.0, in px. The value 0.0 means that the shadow is disabled for the window borders.
color	string	No	Color of the shadow. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, #00FF00 or #FF00FF00. The default value is '#000000'.
offsetX	number	No	Offset of the shadow along the x-axis, in px. The value is a floating-point number, in px. The default value is 0.0.
offsetY	number	No	Offset of the shadow along the y-axis, in px. The value is a floating-point number, in px. The default value is 0.0.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

try {
  windowClass.setShadow(4.0, '#FF00FF00', 2, 3);
} catch (exception) {
  console.error(`Failed to set shadow. Cause code: ${exception.code}, message: ${exception.message}`);
}

setCornerRadius⁹⁺

setCornerRadius(cornerRadius: number): void

Sets the radius of the rounded corners for this window. This API can be used only for system windows, global floating windows, and modal windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
cornerRadius	number	Yes	Radius of the rounded corners. The value is a floating-point number greater than or equal to 0.0, in px. The value 0.0 means that the window does not use rounded corners.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

try {
  windowClass.setCornerRadius(4.0);
} catch (exception) {
  console.error(`Failed to set corner radius. Cause code: ${exception.code}, message: ${exception.message}`);
}

raiseToAppTop¹⁰⁺

raiseToAppTop(callback: AsyncCallback<void>): void

Raises the application child window to the top layer of the application. This API uses an asynchronous callback to return the result.

Before calling this API, ensure that the child window has been created and showWindow() has been successfully executed.

This API can be called by non-independent child windows. This API does not take effect and no error is reported when it is called by independent child windows.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.
1300009	The parent window is invalid.

Example

// EntryAbility.ets
import { window } from '@kit.ArkUI';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    // Create a child window.
    windowStage.createSubWindow('testSubWindow').then((subWindow) => {
      if (subWindow == null) {
        console.error('Failed to create the subWindow. Cause: The data is empty');
        return;
      }
      subWindow.showWindow().then(() => {
        subWindow.raiseToAppTop((err: BusinessError) => {
          const errCode: number = err.code;
          if (errCode) {
            console.error(`Failed to raise the window to app top. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in raising the window to app top.');
        });
      });
    });
  }
}

setWaterMarkFlag¹⁰⁺

setWaterMarkFlag(enable: boolean): Promise<void>

Adds or deletes the watermark flag for this window. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to add or delete the flag. true to add, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300008	The display device is abnormal.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let enable = true;
  let promise = windowClass.setWaterMarkFlag(enable);
  promise.then(() => {
    console.info('Succeeded in setting water mark flag of window.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set water mark flag of window. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set water mark flag of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

setWaterMarkFlag¹⁰⁺

setWaterMarkFlag(enable: boolean, callback: AsyncCallback<void>): void

Adds or deletes the watermark flag for this window. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to add or delete the flag. true to add, false otherwise.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300008	The display device is abnormal.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let enable: boolean = true;
  windowClass.setWaterMarkFlag(enable, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set water mark flag of window. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in setting water mark flag of window.');
  });
} catch (exception) {
  console.error(`Failed to set water mark flag of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

setHandwritingFlag¹²⁺

setHandwritingFlag(enable: boolean): Promise<void>

Adds or deletes the handwriting flag for this window. After this flag is added, the window responds to stylus events but not touch events. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to add or delete the flag. true to add, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let enable = true;
  let promise = windowClass.setHandwritingFlag(enable);
  promise.then(() => {
    console.info('Succeeded in setting handwriting flag of window.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set handwriting flag of window. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set handwriting flag of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

raiseAboveTarget¹⁰⁺

raiseAboveTarget(windowId: number, callback: AsyncCallback<void>): void

Raises a child window above a target child window. This API uses an asynchronous callback to return the result.

Before calling this API, ensure that the child window to raise and the target child window have been created and showWindow() has been successfully executed for each.

This API can be called by non-independent child windows. This API does not take effect and no error is reported when it is called by independent child windows.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
windowId	number	Yes	ID of the target child window, which is the value of properties.id in properties obtained through getWindowProperties.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: Mandatory parameters are left unspecified.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.
1300009	The parent window is invalid.

Example

// EntryAbility.ets
import { window } from '@kit.ArkUI';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window;
    // Create a child window.
    try {
      windowStage.createSubWindow("testSubWindow").then((data) => {
        if (data == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        windowClass = data;
        windowClass.showWindow().then(() => {
          // The windowClass must be obtained above the targetWindow.
          let targetWindow: window.Window = windowClass;
          let properties = targetWindow.getWindowProperties();
          let targetId = properties.id;
          windowClass.raiseAboveTarget(targetId, (err: BusinessError) => {
            if (err.code) {
              console.error(`Failed to raise the subWindow to target subWindow top. Cause code: ${err.code}, message: ${err.message}`);
              return;
            }
            console.info('Succeeded in raising the subWindow to target subWindow top.');
          });
        });
      });
    } catch (exception) {
      console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

raiseAboveTarget¹⁰⁺

raiseAboveTarget(windowId: number): Promise<void>

Raises a child window above a target child window. This API uses a promise to return the result.

Before calling this API, ensure that the child window to raise and the target child window have been created and showWindow() has been successfully executed for each.

This API can be called by non-independent child windows. This API does not take effect and no error is reported when it is called by independent child windows.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
windowId	number	Yes	ID of the target child window, which is the value of properties.id in properties obtained through getWindowProperties.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: Mandatory parameters are left unspecified.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.
1300009	The parent window is invalid.

Example

// EntryAbility.ets
import { window } from '@kit.ArkUI';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window;
    // Create a child window.
    try {
      windowStage.createSubWindow("testSubWindow").then((data) => {
        if (data == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        windowClass = data;
        windowClass.showWindow().then(() => {
          // The windowClass must be obtained above the targetWindow.
          let targetWindow: window.Window = windowClass;
          let properties = targetWindow.getWindowProperties();
          let targetId = properties.id;
          windowClass.raiseAboveTarget(targetId).then(()=> {
            console.info('Succeeded in raising the subWindow to target subWindow top.');
          }).catch((err: BusinessError)=>{
            console.error(`Failed to raise the subWindow to target subWindow top. Cause code: ${err.code}, message: ${err.message}`);
          });
        });
      });
    } catch (exception) {
      console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

raiseMainWindowAboveTarget²⁰⁺

raiseMainWindowAboveTarget(windowId: number): Promise<void>

Moves the main window above another main window within the same application, with child windows following their parents' layer change. This API uses a promise to return the result.

This API can be called only by the main window of a system application.

You need to pass the ID of the target main window. Both the calling window and the target window must be in the same application process, displayed on the same physical screen, below the lock screen layer, not topmost, not modal, and have no application-modal child windows.

If the application's main window or its child windows currently have focus, calling this API to lower the layer will cause the window to lose focus automatically, and the highest-layered application window will gain focus.
If the main window calls this API to move above the current focused window, the highest-layered window among the raised main window and its child windows will gain focus. If the main window calls this API without moving above the current focused window, the focus remains unchanged.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Device behavior differences: This API can be called on a device that supports freeform windows and is in the freeform window state. If the device does not support freeform windows, or if the device supports freeform windows but is not in the freeform window state, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
windowId	number	Yes	ID of the target main window. The value is an integer. It is the value of properties.id in properties obtained through getWindowProperties.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.
1300016	Parameter error. Possible cause: 1. Invalid Parameter range. 2. Invalid parameter length.

Example

// EntryAbility.ets
import { UIAbility, Want, StartOptions, AbilityConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}.`);
        return;
      }
      console.info('Succeeded in loading the content.');
      try {
        let want: Want = {
          abilityName: "RaiseMainWindowAbility",
          bundleName: "com.example.myapplication"
        };
        let options: StartOptions = {
          windowMode: AbilityConstant.WindowMode.WINDOW_MODE_FLOATING
        };
        this.context.startAbility(want, options);
      } catch (err) {
        console.error(`Failed to start the ability. Cause code: ${err.code}, message: ${err.message}.`);
      }
      setTimeout(async () => {
        let mainWindow: window.Window | null | undefined = windowStage.getMainWindowSync();
        let targetId: number | null | undefined = AppStorage.get('higher_window_id');
        mainWindow.raiseMainWindowAboveTarget(targetId).then(() => {
          console.info('Succeeded in raising main window above target.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to raise main window above target. Cause code: ${err.code}, message: ${err.message}.`)
        });
      }, 3000)
    });
  }
}

// Create the RaiseMainWindowAbility.ets file in src/main/ets/raisemainwindowability.
import { UIAbility } from '@kit.AbilityKit';

export default class RaiseMainWindowAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    AppStorage.setOrCreate('higher_window_id', windowStage.getMainWindowSync().getWindowProperties().id);
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}.`);
        return;
      }
      console.info('Succeeded in loading the content.');
    });
  }
}

// module.json5
{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      },
      {
        "name": "RaiseMainWindowAbility",
        "launchType": "multiton",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}

setRaiseByClickEnabled¹⁰⁺

setRaiseByClickEnabled(enable: boolean, callback: AsyncCallback<void>): void

Sets whether to enable a child window to raise itself by click. This API uses an asynchronous callback to return the result.

Generally, when a user clicks a child window, the child window is displayed on the top. If the enable parameter is set to false, the child window is not displayed on the top when being clicked.

Before calling this API, ensure that the child window has been created and showWindow() has been successfully executed.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to enable a child window to raise itself by click. true to enable, false otherwise.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.
1300009	The parent window is invalid.

Example

// EntryAbility.ets
import { window } from '@kit.ArkUI';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    // Create a child window.
    windowStage.createSubWindow("testSubWindow").then((subWindow) => {
      if (subWindow == null) {
        console.error('Failed to create the subWindow. Cause: The data is empty');
        return;
      }
      subWindow.showWindow().then(() => {
        try {
          let enabled = false;
          subWindow.setRaiseByClickEnabled(enabled, (err) => {
          if (err.code) {
            console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in disabling the raise-by-click function.');
          });
        } catch (err) {
          console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`);
        }
      });
    });
  }
}

setMainWindowRaiseByClickEnabled²³⁺

setMainWindowRaiseByClickEnabled(enable: boolean): Promise<void>

Sets whether to enable the main window to raise itself by click. This API uses a promise to return the result.

By default, clicking the main window raises both the main window and its associated child windows. Disabling this feature (by passing false) prevents the main window and its child windows from being raised when the main window is clicked, preserving their current state. However, clicking on a child window still raises both the child window and the main window together.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to enable the main window to raise itself by click. true to enable, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.getMainWindow().then((window: window.Window) => {
      // Load the page corresponding to the main window.
      windowStage.loadContent('pages/Index', (err) => {
        if (err.code) {
          console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        console.info('Succeeded in loading the content.');
        try {
          let raiseEnabled: boolean = false;
          let promise = window.setMainWindowRaiseByClickEnabled(raiseEnabled);
          promise.then(() => {
            console.info('Succeeded in disabling the raise-by-click function.');
          })
        } catch(err) {
          console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`);
        };
      });
    });
  }
}

hideNonSystemFloatingWindows¹¹⁺

hideNonSystemFloatingWindows(shouldHide: boolean, callback: AsyncCallback<void>): void

Sets whether to hide non-system floating windows (where windowType is TYPE_FLOAT). This API uses an asynchronous callback to return the result.

A non-system floating window is a floating window created by a non-system application. By default, the main window of a system application can be displayed together with a non-system floating window. This means that the main window may be blocked by an upper-layer non-system floating window. If the shouldHide parameter is set to true, all non-system floating windows are hidden, so that the main window will never be blocked by a non-system floating window.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Device behavior differences: This API has no effect and does not report errors when being called in 2-in-1 devices and other devices in Desktop mode. For other devices and modes, this API can be called properly.

Parameters

Name	Type	Mandatory	Description
shouldHide	boolean	Yes	Whether to hide non-system floating windows. true to hide, false otherwise.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.

Example

// EntryAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // Load the page corresponding to the main window.
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info('Succeeded in loading the content.');
    });

    // Obtain the main window.
    let mainWindow: window.Window | undefined = undefined;
    windowStage.getMainWindow((err, data) => {
      if (err.code) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      mainWindow = data;
      console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));

      let shouldHide = true;
      try {
        // Call hideNonSystemFloatingWindows with the callback parameter.
        mainWindow.hideNonSystemFloatingWindows(shouldHide, (err) => {
          if (err.code) {
            console.error(`Failed to hide the non-system floating windows. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in hiding the non-system floating windows.');
        });
      } catch (exception) {
        console.error(`Failed to hide the non-system floating windows. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

hideNonSystemFloatingWindows¹¹⁺

hideNonSystemFloatingWindows(shouldHide: boolean): Promise<void>

Sets whether to hide non-system floating windows (where windowType is TYPE_FLOAT). This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
shouldHide	boolean	Yes	Whether to hide non-system floating windows. true to hide, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.

Example

// EntryAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // Load the page corresponding to the main window.
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info('Succeeded in loading the content.');
    });

    // Obtain the main window.
    let mainWindow: window.Window | undefined = undefined;
    windowStage.getMainWindow((err, data) => {
      if (err.code) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      mainWindow = data;
      console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));

      let shouldHide = true;
      try {
        // Call hideNonSystemFloatingWindows to obtain a promise object.
        let promise = mainWindow.hideNonSystemFloatingWindows(shouldHide);
        promise.then(()=> {
          console.info('Succeeded in hiding the non-system floating windows.');
        }).catch((err: BusinessError)=>{
          console.error(`Failed to hide the non-system floating windows. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to hide the non-system floating windows. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

setDefaultDensityEnabled²⁰⁺

setDefaultDensityEnabled(enabled: boolean): void

Sets whether the window uses the default density of the current screen. In the stage model, you need to call this API after loadContent() or setUIContent().

If this API is not called, the default density is not used.

If this API, setDefaultDensityEnabled(), and setCustomDensity are all called, the setting from the last called API will be applied.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
enabled	boolean	Yes	Whether to use the default density of the system. true to enable, false otherwise. When the default density is enabled, the window layout does not change with the system display size.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal. Possible cause: The window is not created or destroyed.

Example

try {
  windowClass.setDefaultDensityEnabled(true);
  console.info(`Succeeded in setting default density enabled`);
} catch (exception) {
  console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}

isMainWindowFullScreenAcrossDisplays²⁰⁺

isMainWindowFullScreenAcrossDisplays(): Promise<boolean>

Checks whether the main window is in full-screen mode across multiple displays. This API uses a promise to return the result. It takes effect only for the main window and child windows.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Return value

Type	Description
Promise<boolean>	Promise used to return the result indicating whether the main window is in full-screen mode across multiple displays. true if yes, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let promise = windowClass.isMainWindowFullScreenAcrossDisplays();
  promise.then((data: boolean)=> {
      console.info(`Succeeded in using isMainWindowFullScreenAcrossDisplays function. Data: ${data}`);
  }).catch((err: BusinessError)=>{
      console.error(`Failed to use isMainWindowFullScreenAcrossDisplays function. code:${err.code}, message:${err.message}.`);
  });
} catch (exception) {
  console.error(`Failed to use isMainWindowFullScreenAcrossDisplays function. Cause code: ${exception.code}, message: ${exception.message}.`);
}

on('mainWindowFullScreenAcrossDisplaysChanged')²⁰⁺

on(type: 'mainWindowFullScreenAcrossDisplaysChanged', callback: Callback<boolean>): void

Subscribes to events indicating whether the main window is in full-screen mode across multiple displays.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'mainWindowFullScreenAcrossDisplaysChanged', indicating changes in whether the main window is in full-screen mode across multiple displays.
callback	Callback<boolean>	Yes	Callback used to return the result indicating whether the main window is in full-screen mode across multiple displays. true if yes, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: Invalid window type. Only main windows and subwindows are supported.

Example

const callback = (mainWindowFullScreenAcrossDisplaysChanged: boolean) => {
  console.info(`main window across displays changed. Data: ${mainWindowFullScreenAcrossDisplaysChanged}`);
}
try {
  windowClass.on('mainWindowFullScreenAcrossDisplaysChanged', callback);
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

off('mainWindowFullScreenAcrossDisplaysChanged')²⁰⁺

off(type: 'mainWindowFullScreenAcrossDisplaysChanged', callback?: Callback<boolean>): void

Unsubscribes from events indicating whether the main window is in full-screen mode across multiple displays.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at 'mainWindowFullScreenAcrossDisplaysChanged', indicating changes in whether the main window is in full-screen mode across multiple displays.
callback	Callback<boolean>	No	Callback used to return the result indicating whether the main window is in full-screen mode across multiple displays. 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.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation. Possible cause: Invalid window type. Only main windows and subwindows are supported.

Example

const callback = (mainWindowFullScreenAcrossDisplaysChanged: boolean) => {
  // ...
}
try {
  // Enable listening through the on API.
  windowClass.on('mainWindowFullScreenAcrossDisplaysChanged', callback);
  // Disable the listening of a specified callback.
  windowClass.off('mainWindowFullScreenAcrossDisplaysChanged', callback);
  // Unregister all the callbacks that have been registered through on().
  windowClass.off('mainWindowFullScreenAcrossDisplaysChanged');
} catch (exception) {
  console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

setTopmost¹²⁺

setTopmost(isTopmost: boolean): Promise<void>

Called by the main window to place the window above all the other windows. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Device behavior differences

In versions earlier than OpenHarmony 6.1, this API can be called properly on 2-in-1 devices but returns error code 801 on other devices.

Since OpenHarmony 6.1, this API can be called properly on a device that supports freeform windows and is in the freeform window state. If the device supports freeform windows but is not in the freeform window state, or if the device does not support freeform windows, this API returns error code 801 when called.

Parameters

Name	Type	Mandatory	Description
isTopmost	boolean	Yes	Whether to pin the main window on top. true to pin, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300004	Unauthorized operation.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    // ...
    windowStage.getMainWindow().then((mainWindow) => {
      let isTopmost: boolean = true;
      mainWindow.setTopmost(isTopmost).then(() => {
        console.info('Succeeded in setting the main window to be topmost.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to set the main window to be topmost. Cause code: ${err.code}, message: ${err.message}`);
      });
    });
  }
}

setSingleFrameComposerEnabled¹¹⁺

setSingleFrameComposerEnabled(enable: boolean): Promise<void>

Enables or disables the single-frame composer. This API uses a promise to return the result.

The single-frame composer is mainly used in scenarios that require extremely low interaction latency. It reduces the screen display latency of the rendering node.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to enable the single-frame composer. true to enable, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let enable = true;
try {
  let promise = windowClass.setSingleFrameComposerEnabled(enable);
  promise.then(()=> {
      console.info('Succeeded in enabling the single-frame-composer function.');
  }).catch((err: BusinessError)=>{
      console.error(`Failed to enable the single-frame-composer function. code:${err.code}, message:${err.message}.`);
  });
} catch (exception) {
  console.error(`Failed to enable the single-frame-composer function. Cause code: ${exception.code}, message: ${exception.message}`);
}

setTitleButtonVisible¹²⁺

setTitleButtonVisible(isMaximizeVisible: boolean, isMinimizeVisible: boolean, isSplitVisible: boolean): void

Shows or hides the maximize, minimize, and split-screen buttons on the title bar.

This API can be called only by the main window and independent child windows. When this API is called by other windows, result code 1300004 will be returned.

This API takes effect only for the title bar buttons (maximize, minimize, and split-screen) that are available in the current scenario.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
isMaximizeVisible	boolean	Yes	Whether to show the maximize button. true to show, false otherwise.
isMinimizeVisible	boolean	Yes	Whether to show the minimize button. true to show, false otherwise.
isSplitVisible	boolean	Yes	Whether to show the split-screen button. true to show, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300004	Unauthorized operation.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    // Load the page corresponding to the main window.
    windowStage.loadContent('pages/Index', (err) => {
      if (err?.code) {
        console.error(`Failed to load content. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      let mainWindow: window.Window | undefined = undefined;
      // Obtain the main window.
      windowStage.getMainWindow().then(
        data => {
          if (!data) {
            console.error('Failed to get main window.');
            return;
          }
          mainWindow = data;
          console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
          // Call setTitleButtonVisible to hide the maximize, minimize, and split-screen buttons on the title bar of the main window.
          mainWindow.setTitleButtonVisible(false, false, false);
        }
      ).catch((err: BusinessError) => {
          if(err.code){
            console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
          }
      });
    });
  }
}

setRotationLocked²²⁺

setRotationLocked(locked: boolean): Promise<void>

Allows a system window to lock or unlock its own screen-rotation behavior. When locked, the window's orientation remains unchanged. When unlocked, the window's orientation follows the main window's orientation, the system rotation-lock button, and the device's physical rotation sensor. If this API is called by a non-system window, error code 1300029 is thrown. This API uses a promise to return the result.

NOTE

If the main window sets the display orientation via setPreferredOrientation() while rotation is locked, the window restores the last orientation request when brought to the foreground after unlocking.

If the system window sets the display orientation via setPreferredOrientation() while rotation is locked, the window restores the last orientation request when brought to the foreground with the highest level after unlocking. The rotation lock set by a lower-level window using setRotationLocked does not hinder the system window at a higher level to set the display orientation by calling setPreferredOrientation().

If the sensor orientation changes while rotation is locked, the last sensor orientation is restored after unlocking.

If the application calls setOrientation() to set the screen orientation while rotation is locked, that screen‑orientation setting is ignored.

When rotation is unlocked, the application's display orientation is determined based on the main window's display orientation set via setPreferredOrientation(), the sensor orientation, and more. For details, see Window Rotation Overview.

The API does not affect the launch orientation set by the orientation under abilities in the module.json5 file of the application.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Device behavior differences: This API can be properly called on phones, tablets, and 2-in-1 devices. If it is called on other device types, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
locked	boolean	Yes	Whether to lock the rotation. true to lock, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed, non-system application uses system API.
801	Capability not supported. Function setRotationLocked can not work correctly due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300029	This window type is invalid.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let locked: boolean = true;
let promise = windowClass.setRotationLocked(locked);
promise.then(() => {
  console.info('set rotation locked success.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set rotation locked. Cause code: ${err.code}, message: ${err.message}`);
});

getRotationLocked²²⁺

getRotationLocked(): boolean

Checks whether the system window has its screen rotation locked. If this API is called by a non-system window, error code 1300029 is thrown.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Device behavior differences: This API can be properly called on phones, tablets, and 2-in-1 devices. If it is called on other device types, error code 801 is returned.

Return value

Type	Description
boolean	Check result for whether rotation is currently locked for this system window. true if locked, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed, non-system application uses system API.
801	Capability not supported. Function setRotationLocked can not work correctly due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300029	This window type is invalid.

Example

try {
  let locked = windowClass.getRotationLocked();
  console.info('Succeeded in getting rotation locked.');
} catch (exception) {
  console.error(`Failed to get rotation locked. Cause code: ${exception.code}, message: ${exception.message}`);
};

requestFocus¹³⁺

requestFocus(isFocused: boolean): Promise<void>

Allows this window to proactively request to gain or lose focus. This API uses a promise to return the result. A value is returned as long as the API is successfully called. The return value does not indicate that the window has gained or lost focus. You can use on('windowEvent') to listen for the focus status of the window.

When a focus request is sent, whether the window can successfully gain focus depends on its capability of being focused and its current visibility. To gain focus, the window must be capable of receiving focus and in a visible state (actively displayed and not hidden or destroyed).

Conversely, once a blur request is sent, the window will lose focus without any conditions.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
isFocused	boolean	Yes	Whether to gain or lose focus. true to gain focus, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed, non-system application uses system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let isFocused: boolean = true;
let promise = windowClass.requestFocus(isFocused);
promise.then(() => {
  console.info('Succeeded in requesting focus.');
}).catch((err: BusinessError) => {
  console.error(`Failed to request focus. Cause code: ${err.code}, message: ${err.message}`);
});

setWindowType^(deprecated)

setWindowType(type: WindowType, callback: AsyncCallback<void>): void

Sets the type of this window. This API uses an asynchronous callback to return the result.

System API: This is a system API.

NOTE

This API is supported since API version 7 and deprecated since API version 9.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	WindowType	Yes	Window type.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let type = window.WindowType.TYPE_SYSTEM_ALERT;
windowClass.setWindowType(type, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to set the window type. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the window type.');
});

setWindowType^(deprecated)

setWindowType(type: WindowType): Promise<void>

Sets the type of this window. This API uses a promise to return the result.

System API: This is a system API.

NOTE

This API is supported since API version 7 and deprecated since API version 9.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
type	WindowType	Yes	Window type.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let type = window.WindowType.TYPE_SYSTEM_ALERT;
let promise = windowClass.setWindowType(type);
promise.then(() => {
  console.info('Succeeded in setting the window type.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set the window type. Cause code: ${err.code}, message: ${err.message}`);
});

setForbidSplitMove^(deprecated)

setForbidSplitMove(isForbidSplitMove: boolean, callback: AsyncCallback<void>): void

Sets whether the main window is forbidden to move in split-screen mode. This API uses an asynchronous callback to return the result.

NOTE
This API is supported since API version 9 and deprecated since API version 26.0.0. No substitute is provided.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
isForbidSplitMove	boolean	Yes	Whether the window is forbidden to move in split-screen mode. true if forbidden, false otherwise.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    windowStage.getMainWindow((err: BusinessError, data) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      windowClass = data;
      let isForbidSplitMove: boolean = true;
      try {
        windowClass.setForbidSplitMove(isForbidSplitMove, (err: BusinessError) => {
          const errCode: number = err.code;
          if (errCode) {
            console.error(`Failed to forbid window moving in split screen mode. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in forbidding window moving in split screen mode.');
        });
      } catch (exception) {
        console.error(`Failed to forbid window moving in split screen mode. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

setForbidSplitMove^(deprecated)

setForbidSplitMove(isForbidSplitMove: boolean): Promise<void>

Sets whether the main window is forbidden to move in split-screen mode. This API uses a promise to return the result.

NOTE
This API is supported since API version 9 and deprecated since API version 26.0.0. No substitute is provided.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
isForbidSplitMove	boolean	Yes	Whether the window is forbidden to move in split-screen mode. true if forbidden, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    windowStage.getMainWindow((err: BusinessError, data) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      windowClass = data;
      let isForbidSplitMove: boolean = true;
      try {
        let promise = windowClass.setForbidSplitMove(isForbidSplitMove);
        promise.then(() => {
          console.info('Succeeded in forbidding window moving in split screen mode.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to forbid window moving in split screen mode. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to forbid window moving in split screen mode. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

SubWindowOptions¹¹⁺

Describes the parameters used for creating a child window.

Name	Type	Read-Only	Optional	Description
isTopmost¹²⁺	boolean	No	Yes	Whether the child window is topmost. true if topmost, false otherwise. The default value is false. System API: This is a system API. System capability: SystemCapability.Window.SessionManager

WindowStage⁹⁺

Implements a window manager, which manages each basic window unit, that is, Window instance.

Before calling any of the following APIs, you must use onWindowStageCreate() to create a WindowStage instance.

disableWindowDecor⁹⁺

disableWindowDecor(): void

Disables window decorators.

When window decorators are disabled and the main window transitions into full-screen mode, hovering the cursor over the hot zone of the top window's title bar will cause a floating title bar to appear. To prevent the floating title bar from appearing, call setTitleAndDockHoverShown().

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Error codes

For details about the error codes, see Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
1300002	This window state is abnormal.
1300005	This window stage is abnormal.

Example

// EntryAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('disableWindowDecor');
    windowStage.disableWindowDecor();
  }
};

setShowOnLockScreen⁹⁺

setShowOnLockScreen(showOnLockScreen: boolean): void

Sets whether to display the window of the application on the lock screen.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
showOnLockScreen	boolean	Yes	Whether to display the window on the lock screen. true to display, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002	This window state is abnormal.
1300005	This window stage is abnormal.

Example

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    try {
      windowStage.setShowOnLockScreen(true);
    } catch (exception) {
      console.error(`Failed to show on lockscreen. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

setImageForRecent¹⁹⁺

setImageForRecent(imgResourceId: number, value: ImageFit): Promise<void>

Sets the image displayed in the multitasking view. This API uses a promise to return the result.

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Window.SessionManager

Parameters

Name	Type	Mandatory	Description
imgResourceId	number	Yes	Resource ID of the custom image. The image must be stored in the resources/base/media directory and its resource ID can be obtained using the $r resource access mode. For example, to obtain the resource ID of the startIcon image, use the following: $r("app.media.startIcon").id.
value	ImageFit	Yes	Fill mode of the custom image.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Window Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1300002	This window state is abnormal.
1300003	This window manager service works abnormally.
1300016	Parameter error. Possible cause: 1. Invalid parameter range. 2. Invalid parameter length. 3. Incorrect parameter format.

Example

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    let imgResourceId = $r("app.media.startIcon").id
    try {
      let promise = windowStage.setImageForRecent(imgResourceId, ImageFit.Fill);
      promise.then(() => {
        console.info(`Succeeded in setting image for recent`);
      }).catch((err: BusinessError) => {
        console.error(`Failed to set image for recent. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to set image for recent.`);
    }
  }
};

TransitionContext⁹⁺

Provides the context for the transition animation.

System API: This is a system API.

Attributes

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Name	Type	Read-Only	Optional	Description
toWindow	Window	No	No	Target window to display the animation.

completeTransition⁹⁺

completeTransition(isCompleted: boolean): void

Completes the transition. This API can be called only after animateTo() is executed.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
isCompleted	boolean	Yes	Whether the transition is complete. true if complete, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

(context: window.TransitionContext) => {
  let toWindow: window.Window = context.toWindow;
  this.getUIContext()?.animateTo({
    duration: 1000, // Animation duration.
    tempo: 0.5, // Playback speed.
    curve: Curve.EaseInOut, // Animation curve.
    delay: 0, // Animation delay.
    iterations: 1, // Number of playback times.
    playMode: PlayMode.Normal // Animation playback mode.
  }, () => {
    let obj: window.TranslateOptions = {
      x: 100.0,
      y: 0.0,
      z: 0.0
    };
    toWindow?.translate(obj);
    console.info('toWindow translate end');
  }
  );
  try {
    context.completeTransition(true)
  } catch (exception) {
    console.error(`toWindow translate fail. Cause code: ${exception.code}, message: ${exception.message}`);
  }
  console.info('complete transition end');
};

TransitionController⁹⁺

Implements the transition animation controller. Before calling any API, you must create a system window. For details, see the sample code.

System API: This is a system API.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
let config: window.Configuration = {
  name: "systemTypeWindow",
  windowType: window.WindowType.TYPE_PANEL, // Select a system window type as required.
  ctx: this.context
};
let promise = window.createWindow(config);
promise.then((data) => {
  windowClass = data;
  console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`);
});

animationForShown⁹⁺

animationForShown(context: TransitionContext): void

Customizes the animation for the scenario when the window is shown.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
context	TransitionContext	Yes	Context of the transition animation.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

// xxx.ts
export class AnimationConfig {
  private animationForShownCallFunc_: ((context : window.TransitionContext) => void) | undefined = undefined;
  ShowWindowWithCustomAnimation(windowClass: window.Window, callback: (context : window.TransitionContext) => void) {
    if (!windowClass) {
      console.error('windowClass is undefined');
      return false;
    }
    this.animationForShownCallFunc_ = callback;
    let controller: window.TransitionController = windowClass.getTransitionController();
    controller.animationForShown = (context : window.TransitionContext)=> {
      this.animationForShownCallFunc_(context);
    };
    windowClass.showWithAnimation(()=>{
      console.info('Show with animation success');
    });
  }
}

// xxx.ets
let animationConfig = new AnimationConfig();
let systemTypeWindow = window.findWindow("systemTypeWindow"); // Obtain a system window.
try {
  animationConfig?.ShowWindowWithCustomAnimation(systemTypeWindow, (context : window.TransitionContext)=>{
    console.info('complete transition end');
    let toWindow = context.toWindow;
    this.getUIContext()?.animateTo({
      duration: 1000, // Animation duration.
      tempo: 0.5, // Playback speed.
      curve: Curve.EaseInOut, // Animation curve.
      delay: 0, // Animation delay.
      iterations: 1, // Number of playback times.
      playMode: PlayMode.Normal // Animation playback mode.
      onFinish: () => {
        console.info('onFinish in animation');
        context.completeTransition(true)
      }
    }, () => {
      let obj : window.TranslateOptions = {
        x : 100.0,
        y : 0.0,
        z : 0.0
      };
      toWindow?.translate(obj); // Set the transition animation.
      console.info('toWindow translate end in animation');
    });
    console.info('complete transition end');
  });
} catch (error) {
  console.error(`ShowWindowWithCustomAnimation error code: ${error.code}, message: ${error.message}`);
}

animationForHidden⁹⁺

animationForHidden(context: TransitionContext): void

Customizes the animation for the scenario when the window is hidden.

System API: This is a system API.

System capability: SystemCapability.WindowManager.WindowManager.Core

Parameters

Name	Type	Mandatory	Description
context	TransitionContext	Yes	Context of the transition animation.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

// xxx.ts
export class AnimationConfig {
  private animationForHiddenCallFunc_: ((context : window.TransitionContext) => void) | undefined = undefined;
  HideWindowWithCustomAnimation(windowClass: window.Window, callback: (context : window.TransitionContext) => void) {
    if (!windowClass) {
      console.error('windowClass is undefined');
      return false;
    }
    this.animationForHiddenCallFunc_ = callback;
    let controller: window.TransitionController = windowClass.getTransitionController();
    controller.animationForHidden = (context : window.TransitionContext)=> {
      this.animationForHiddenCallFunc_(context);
    };
    windowClass.hideWithAnimation(()=>{
      console.info('hide with animation success');
    });
  }
}

// xxx.ets
let animationConfig = new AnimationConfig();
let systemTypeWindow = window.findWindow("systemTypeWindow"); // Obtain a system window.
try {
  animationConfig?.HideWindowWithCustomAnimation(systemTypeWindow, (context : window.TransitionContext)=>{
    console.info('complete transition end');
    let toWindow = context.toWindow;
    this.getUIContext()?.animateTo({
      duration: 1000, // Animation duration.
      tempo: 0.5, // Playback speed.
      curve: Curve.EaseInOut, // Animation curve.
      delay: 0, // Animation delay.
      iterations: 1, // Number of playback times.
      playMode: PlayMode.Normal // Animation playback mode.
      onFinish: () => {
        console.info('onFinish in animation');
        context.completeTransition(true)
      }
    }, () => {
      let obj : window.TranslateOptions = {
        x : 100.0,
        y : 0.0,
        z : 0.0
      };
      toWindow?.translate(obj); // Set the transition animation.
      console.info('toWindow translate end in animation');
    });
    console.info('complete transition end');
  });
} catch (error) {
  console.error(`HideWindowWithCustomAnimation error code: ${error.code}, message: ${error.message}` );
}

ExtensionWindowAttribute¹⁴⁺

Enumerates the attributes of a window for a UI ServiceExtensionAbility.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Name	Value	Description
SYSTEM_WINDOW	0	System window
SUB_WINDOW	1	child window.

SystemWindowOptions¹⁴⁺

Describes the parameters for creating a system window.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Name	Type	Read-Only	Optional	Description
windowType	WindowType	No	No	Window type. There is no default value. If null is passed in, the window fails to be created. TYPE_DIALOG is not supported.

ExtensionWindowConfig¹⁴⁺

Describes the parameters for creating a window for a UI ServiceExtensionAbility.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Window.SessionManager

Name	Type	Read-Only	Optional	Description
windowName	string	No	No	Window name.
windowAttribute	ExtensionWindowAttribute	No	No	Window attribute. It specifies whether the created window is a child window or a system window. When windowAttribute is set to SUB_WINDOW, subWindowOptions is mandatory. When windowAttribute is set to SYSTEM_WINDOW, systemWindowOptions is mandatory. Otherwise, the window fails to be created.
windowRect	Rect	No	No	Rectangular area of the window.
subWindowOptions	SubWindowOptions	No	Yes	Parameters used for creating a child window. There is no default value. This parameter is mandatory when windowAttribute is set to SUB_WINDOW. Otherwise, the window fails to be created.
systemWindowOptions	SystemWindowOptions	No	Yes	Parameters for creating a system window. There is no default value. This parameter is mandatory when windowAttribute is set to SYSTEM_WINDOW. Otherwise, the window fails to be created.

@ohos.window (Window) (System API)

Modules to Import

WindowType7+

Configuration9+

WindowMode7+

BlurStyle9+

AnimationType20+

SystemBarRegionTint8+

SystemBarTintState8+

ScaleOptions9+

RotateOptions9+

TranslateOptions9+

StartAnimationSystemParams20+

WindowCreateParams20+

WindowAnchorInfo24+

SubWindowAttachOptions24+

WindowLayoutMode(deprecated)

window.minimizeAll9+

window.minimizeAll9+

window.minimizeAllWithExclusion23+

window.toggleShownStateForAllAppWindows9+

window.toggleShownStateForAllAppWindows9+

window.on('systemBarTintChange')8+

window.off('systemBarTintChange')8+

window.on('gestureNavigationEnabledChange')10+

window.off('gestureNavigationEnabledChange')10+

window.on('waterMarkFlagChange')10+

window.off('waterMarkFlagChange')10+

window.setGestureNavigationEnabled10+

window.setGestureNavigationEnabled10+

window.setWaterMarkImage10+

window.setWaterMarkImage10+

window.setWaterMarkImage

window.getSnapshot12+

window.notifyScreenshotEvent20+

window.getTopNavDestinationName20+

window.setSpecificSystemWindowZIndex23+

window.createSubWindowAndBindParent

window.moveMainWindowToTargetDisplay

window.setWindowLayoutMode(deprecated)

window.setWindowLayoutMode(deprecated)

Window

hide7+

hide7+

hideWithAnimation9+

hideWithAnimation9+

showWithAnimation9+

showWithAnimation9+

setWindowMode9+

setWindowMode9+

attachLayoutToParentWindow24+

detachLayoutToParentWindow24+

bindDialogTarget9+

bindDialogTarget9+

bindDialogTarget9+

bindDialogTarget9+

setWakeUpScreen9+

setSnapshotSkip9+

opacity9+

scale9+

rotate9+

translate9+

getTransitionController9+

setBlur9+

setBackdropBlur9+

setBackdropBlurStyle9+

setShadow9+

setCornerRadius9+

raiseToAppTop10+

setWaterMarkFlag10+

setWaterMarkFlag10+

setHandwritingFlag12+

raiseAboveTarget10+

raiseAboveTarget10+

raiseMainWindowAboveTarget20+

setRaiseByClickEnabled10+

setMainWindowRaiseByClickEnabled23+

hideNonSystemFloatingWindows11+

hideNonSystemFloatingWindows11+

setDefaultDensityEnabled20+

WindowType⁷⁺

Configuration⁹⁺

WindowMode⁷⁺

BlurStyle⁹⁺

AnimationType²⁰⁺

SystemBarRegionTint⁸⁺

SystemBarTintState⁸⁺

ScaleOptions⁹⁺

RotateOptions⁹⁺

TranslateOptions⁹⁺

StartAnimationSystemParams²⁰⁺

WindowCreateParams²⁰⁺

WindowAnchorInfo²⁴⁺

SubWindowAttachOptions²⁴⁺

WindowLayoutMode^(deprecated)

window.minimizeAll⁹⁺

window.minimizeAll⁹⁺

window.minimizeAllWithExclusion²³⁺

window.toggleShownStateForAllAppWindows⁹⁺

window.toggleShownStateForAllAppWindows⁹⁺

window.on('systemBarTintChange')⁸⁺

window.off('systemBarTintChange')⁸⁺

window.on('gestureNavigationEnabledChange')¹⁰⁺

window.off('gestureNavigationEnabledChange')¹⁰⁺

window.on('waterMarkFlagChange')¹⁰⁺

window.off('waterMarkFlagChange')¹⁰⁺

window.setGestureNavigationEnabled¹⁰⁺

window.setGestureNavigationEnabled¹⁰⁺

window.setWaterMarkImage¹⁰⁺

window.setWaterMarkImage¹⁰⁺

window.getSnapshot¹²⁺

window.notifyScreenshotEvent²⁰⁺

window.getTopNavDestinationName²⁰⁺

window.setSpecificSystemWindowZIndex²³⁺

window.setWindowLayoutMode^(deprecated)

window.setWindowLayoutMode^(deprecated)

hide⁷⁺

hide⁷⁺

hideWithAnimation⁹⁺

hideWithAnimation⁹⁺

showWithAnimation⁹⁺

showWithAnimation⁹⁺

setWindowMode⁹⁺

setWindowMode⁹⁺

attachLayoutToParentWindow²⁴⁺

detachLayoutToParentWindow²⁴⁺

bindDialogTarget⁹⁺

bindDialogTarget⁹⁺

bindDialogTarget⁹⁺

bindDialogTarget⁹⁺

setWakeUpScreen⁹⁺

setSnapshotSkip⁹⁺

opacity⁹⁺

scale⁹⁺

rotate⁹⁺

translate⁹⁺

getTransitionController⁹⁺

setBlur⁹⁺

setBackdropBlur⁹⁺

setBackdropBlurStyle⁹⁺

setShadow⁹⁺

setCornerRadius⁹⁺

raiseToAppTop¹⁰⁺

setWaterMarkFlag¹⁰⁺

setWaterMarkFlag¹⁰⁺

setHandwritingFlag¹²⁺

raiseAboveTarget¹⁰⁺

raiseAboveTarget¹⁰⁺

raiseMainWindowAboveTarget²⁰⁺

setRaiseByClickEnabled¹⁰⁺

setMainWindowRaiseByClickEnabled²³⁺

hideNonSystemFloatingWindows¹¹⁺

hideNonSystemFloatingWindows¹¹⁺

setDefaultDensityEnabled²⁰⁺

isMainWindowFullScreenAcrossDisplays²⁰⁺

on('mainWindowFullScreenAcrossDisplaysChanged')²⁰⁺

off('mainWindowFullScreenAcrossDisplaysChanged')²⁰⁺

setTopmost¹²⁺

setSingleFrameComposerEnabled¹¹⁺

setTitleButtonVisible¹²⁺