1# Application Window Development (FA Model)
2
3## Basic Concepts
4
5Immersive window: a window display mode where the system windows (generally the status bar and navigation bar) are hidden to allow users to fully engage with the content.
6
7The immersive window feature is applicable only to the main window of an application in full-screen mode. It does not apply to a main window in any other mode or a subwindow (for example, a dialog box or a floating window).
8
9> **NOTE**
10>
11> Currently, immersive UI development supports window-level configuration, but not page-level configuration. If page redirection is required, you can set the immersive mode at the beginning of the page lifecycle, for example, in the **onPageShow** callback, and then restore the default settings when the page exits, for example, in the **onPageHide** callback.
12
13## When to Use
14
15In the FA model, you can perform the following operations during application window development:
16
17- Setting the properties and content of the subwindow of an application
18
19- Experiencing the immersive window feature
20
21## Available APIs
22
23The table below lists the common APIs used for application window development. For details about more APIs, see [Window](../reference/apis-arkui/js-apis-window.md).
24
25| Instance        | API                                                      | Description                                                        |
26| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
27| Window static method| createWindow(config: Configuration, callback: AsyncCallback\<Window>): void | Creates a subwindow.<br>**config**: parameters used for creating the window.              |
28| Window static method| findWindow(name: string): Window                             | Finds a window based on the name.                                    |
29| Window         | setUIContent(path: string, callback: AsyncCallback&lt;void&gt;): void | Loads the content of a page, with its path in the current project specified, to this window.<br>**path**: path of the page from which the content will be loaded. The path is configured in the **config.json** file of the project in the FA model.                                |
30| Window         | moveWindowTo(x: number, y: number, callback: AsyncCallback&lt;void&gt;): void | Moves this window.                                              |
31| Window         | setWindowBrightness(brightness: number, callback: AsyncCallback&lt;void&gt;): void | Sets the brightness for this window.                                            |
32| Window         | resize(width: number, height: number, callback: AsyncCallback&lt;void&gt;): void | Changes the window size.                                          |
33| Window         | setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise&lt;void&gt; | Sets whether to enable the full-screen mode for the window layout.                                 |
34| Window         | setWindowSystemBarEnable(names: Array&lt;'status'\|'navigation'&gt;): Promise&lt;void&gt; | Sets whether to display the status bar and navigation bar in this window.                                |
35| Window         | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise&lt;void&gt; | Sets the properties of the status bar and navigation bar in this window.<br>**systemBarProperties**: properties of the status bar and navigation bar.|
36| Window         | showWindow(callback: AsyncCallback\<void>): void             | Shows this window.                                              |
37| Window         | on(type: 'touchOutside', callback: Callback&lt;void&gt;): void | Enables listening for touch events outside this window.                          |
38| Window         | destroyWindow(callback: AsyncCallback&lt;void&gt;): void     | Destroys this window.                                              |
39
40
41## Setting the Subwindow of an Application
42
43You can create a subwindow, such as a dialog box, and set its properties.
44
45> **NOTE**
46>
47> Due to the following limitations, using subwindows is not recommended in mobile device scenarios. Instead, you are advised to use the [overlay](../reference/apis-arkui/arkui-ts/ts-universal-attributes-overlay.md) capability of components.
48> - Subwindows on mobile devices are constrained within the main window's boundaries, mirroring the limitations of components.
49> - In split-screen or freeform window mode, components, when compared with subwindows, offer better real-time adaptability to changes in the main window's position and size.
50> - On certain platforms, system configurations may restrict subwindows to default system animations and rounded shadows, offering no customization options for applications and thereby limiting their versatility.
51
52### How to Develop
53
541. Create or obtain a subwindow.
55
56   - Call **window.createWindow** to create a subwindow.
57   - Call **window.findWindow** to find an available subwindow.
58
59   ```ts
60   import { window } from '@kit.ArkUI';
61   import { BusinessError } from '@kit.BasicServicesKit';
62
63   let windowClass: window.Window | null = null;
64   // Method 1: Create a subwindow.
65   let config: window.Configuration = { name: "subWindow", windowType: window.WindowType.TYPE_APP };
66   window.createWindow(config, (err: BusinessError, data) => {
67     let errCode: number = err.code;
68     if (errCode) {
69       console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err));
70       return;
71     }
72     console.info('Succeeded in creating subWindow. Data: ' + JSON.stringify(data));
73     windowClass = data;
74   });
75   // Method 2: Find a subwindow.
76   try {
77     windowClass = window.findWindow('subWindow');
78   } catch (exception) {
79     console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception));
80   }
81   ```
82
832. Set the properties of the subwindow.
84
85   After the subwindow is created, you can set its properties, such as the size, position, background color, and brightness.
86
87   ```ts
88   // Move the subwindow.
89   let windowClass: window.Window = window.findWindow("test");
90   windowClass.moveWindowTo(300, 300, (err: BusinessError) => {
91     let errCode: number = err.code;
92     if (errCode) {
93       console.error('Failed to move the window. Cause:' + JSON.stringify(err));
94       return;
95     }
96     console.info('Succeeded in moving the window.');
97   });
98   // Change the size of the subwindow.
99   windowClass.resize(500, 500, (err: BusinessError) => {
100     let errCode: number = err.code;
101     if (errCode) {
102       console.error('Failed to change the window size. Cause:' + JSON.stringify(err));
103       return;
104     }
105     console.info('Succeeded in changing the window size.');
106   });
107   ```
108
1093. Load content to and show the subwindow.
110
111   Call **setUIContent** to load content to the subwindow and **showWindow** to show the subwindow.
112
113   ```ts
114   // Load content to the subwindow.
115   let windowClass: window.Window = window.findWindow("test");
116   windowClass.setUIContent("pages/page2", (err: BusinessError) => {
117     let errCode: number = err.code;
118     if (errCode) {
119       console.error('Failed to load the content. Cause: ' + JSON.stringify(err));
120       return;
121     }
122     console.info('Succeeded in loading the content.');
123     // Show the subwindow.
124     windowClass.showWindow((err: BusinessError) => {
125       let errCode: number = err.code;
126       if (errCode) {
127         console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
128         return;
129       }
130       console.info('Succeeded in showing the window.');
131     });
132   });
133   ```
134
1354. Destroy the subwindow.
136
137   When the subwindow is no longer needed, you can call **destroyWindow** to destroy it.
138
139   ```ts
140   // Call destroy() to destroy the subwindow when it is no longer needed.
141   let windowClass: window.Window = window.findWindow("test");
142   windowClass.destroyWindow((err: BusinessError) => {
143     let errCode: number = err.code;
144     if (errCode) {
145       console.error('Failed to destroy the subwindow. Cause:' + JSON.stringify(err));
146       return;
147     }
148     console.info('Succeeded in destroying the subwindow.');
149   });
150   ```
151
152## Experiencing the Immersive Window Feature
153
154To create a better video watching and gaming experience, you can use the immersive window feature to hide the status bar and navigation bar. This feature is available only for the main window of an application. Since API version 10, the immersive window has the same size as the full screen by default; its layout is controlled by the component module; the background color of its status bar and navigation bar is transparent, and the text color is black. When an application window calls **setWindowLayoutFullScreen**, with **true** passed in, an immersive window layout is used. If **false** is passed in, a non-immersive window layout is used.
155
156
157### How to Develop
158
1591. Obtain the main window.
160
161   > **NOTE**
162   >
163   > The immersive window feature can be implemented only after the main window is obtained.
164   >
165   > Ensure that the top window of the application is the main window. You can use **window.getLastWindow** to obtain the main window.
166
167   ```ts
168   import { window } from '@kit.ArkUI';
169   import { BusinessError } from '@kit.BasicServicesKit';
170
171   let mainWindowClass: window.Window | null = null;
172
173   // Obtain the main window.
174   class BaseContext {
175     stageMode: boolean = false;
176   }
177
178   let context: BaseContext = { stageMode: false };
179   window.getLastWindow(context, (err: BusinessError, data) => {
180     let errCode: number = err.code;
181     if (errCode) {
182       console.error('Failed to get the subWindow. Cause: ' + JSON.stringify(err));
183       return;
184     }
185     console.info('Succeeded in getting subWindow. Data: ' + JSON.stringify(data));
186     mainWindowClass = data;
187   });
188   ```
189
1902. Implement the immersive effect. You can use either of the following methods:
191
192   - Method 1: When the main window of the application is a full-screen window, call **setWindowSystemBarEnable** to hide the status bar and navigation bar.
193   - Method 2: Call **setWindowLayoutFullScreen** to enable the full-screen mode for the main window layout. Call **setWindowSystemBarProperties** to set the opacity, background color, text color, and highlighted icon of the status bar and navigation bar to create a display effect consistent with that of the main window.
194
195   ```ts
196   // Implement the immersive effect by hiding the status bar and navigation bar.
197   let names: Array<'status' | 'navigation'> = [];
198   let mainWindowClass: window.Window = window.findWindow("test");
199   mainWindowClass.setWindowSystemBarEnable(names)
200    .then(() => {
201      console.info('Succeeded in setting the system bar to be visible.');
202    })
203    .catch((err: BusinessError) => {
204      console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err));
205    });
206   // Implement the immersive effect by setting the properties of the status bar and navigation bar.
207
208   let isLayoutFullScreen: boolean = true;
209   mainWindowClass.setWindowLayoutFullScreen(isLayoutFullScreen)
210    .then(() => {
211      console.info('Succeeded in setting the window layout to full-screen mode.');
212    })
213    .catch((err: BusinessError) => {
214      console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
215    });
216   let sysBarProps: window.SystemBarProperties = {
217     statusBarColor: '#ff00ff',
218     navigationBarColor: '#00ff00',
219     // The following properties are supported since API version 8.
220     statusBarContentColor: '#ffffff',
221     navigationBarContentColor: '#ffffff'
222   };
223   mainWindowClass.setWindowSystemBarProperties(sysBarProps)
224    .then(() => {
225      console.info('Succeeded in setting the system bar properties.');
226    })
227    .catch((err: BusinessError) => {
228      console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err));
229    });
230   ```
231
2323. Load content to and show the immersive window.
233
234   Call **setUIContent** to load content to the immersive window and **showWindow** to show the window.
235
236   ```ts
237   // Load content to the immersive window.
238   let mainWindowClass: window.Window = window.findWindow("test");
239   mainWindowClass.setUIContent("pages/page3", (err: BusinessError) => {
240     let errCode: number = err.code;
241     if (errCode) {
242       console.error('Failed to load the content. Cause: ' + JSON.stringify(err));
243       return;
244     }
245     console.info('Succeeded in loading the content.');
246     // Show the immersive window.
247     mainWindowClass.showWindow((err: BusinessError) => {
248       let errCode: number = err.code;
249       if (errCode) {
250         console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
251         return;
252       }
253       console.info('Succeeded in showing the window.');
254     });
255   });
256   ```
257