1# Application Window Development (Stage Mode) 2 3 4## Basic Concepts 5 6- Immersive window: System windows such as the status bar and navigation bar are controlled in such a way that they are unobtrusive on the entire screen, thereby engaging users more deeply with the content displayed. 7 The immersive window feature is valid only when the main window of an application is displayed in full-screen mode. It does not apply to a main window in free window mode or a subwindow (for example, a dialog box or a floating window). 8 9- Floating window: a special application window that can still be displayed in the foreground when the main window and corresponding ability are running the background. 10 The floating window can be used to continue playing a video in a small window after the application returns to the background, or offer a quick entry (for example, bubbles) to a specific application. Before creating a floating window, an application must apply for the required permission. 11 12 13## When to Use 14 15In the stage model, you can perform the following operations during application window development: 16 17- Setting the properties and content of the main window of an application 18 19- Setting the properties and content of the subwindow of an application 20 21- Experiencing the immersive window feature 22 23- Setting a floating window 24 25 26## Available APIs 27 28The table below lists the common APIs used for application window development. For details about more APIs, see [Window](../reference/apis/js-apis-window.md). 29 30| Instance| API| Description| 31| -------- | -------- | -------- | 32| WindowStage | getMainWindow(callback: AsyncCallback<Window>): void | Obtains the main window of this window stage.<br>This API can be used only in the stage model.| 33| WindowStage | loadContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to the main window in this window stage.<br>This API can be used only in the stage model.| 34| WindowStage | createSubWindow(name: string, callback: AsyncCallback<Window>): void | Creates a subwindow.<br>This API can be used only in the stage model.| 35| Window static method| createWindow(config: Configuration, callback: AsyncCallback\<Window>): void | Creates a system window.<br>**config** specifies the parameters used for creating the window.| 36| Window | setUIContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to this window.| 37| Window | setWindowBackgroundColor(color: string, callback: AsyncCallback<void>): void | Sets the background color for this window.| 38| Window | setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void | Sets the brightness for this window.| 39| Window | setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void | Sets whether this window is touchable.| 40| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | Moves this window.| 41| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | Changes the window size.| 42| Window | setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void | Sets whether to enable the full-screen mode for the window layout. | 43| Window | setWindowSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | Sets whether to display the status bar and navigation bar in this window.| 44| Window | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void | Sets the properties of the status bar and navigation bar in this window.<br>**systemBarProperties**: properties of the status bar and navigation bar.| 45| Window | showWindow(callback: AsyncCallback\<void>): void | Shows this window.| 46| Window | on(type: 'touchOutside', callback: Callback<void>): void | Enables listening for click events outside this window.| 47| Window | destroyWindow(callback: AsyncCallback<void>): void | Destroys this window.| 48 49 50## Setting the Main Window of an Application 51 52In the stage model, the main window of an application is created and maintained by a **UIAbility** instance. In the **onWindowStageCreate** callback of the **UIAbility** instance, use **WindowStage** to obtain the main window of the application and set its properties. You can also set the properties (for example, **maxWindowWidth**) in the [module.json5 file](../quick-start/module-configuration-file.md#abilities). 53 54 55### How to Develop 56 571. Obtain the main window. 58 59 Call **getMainWindow** to obtain the main window of the application. 60 612. Set the properties of the main window. 62 63 You can set multiple properties of the main window, such as the background color, brightness, and whether the main window is touchable. The code snippet below uses the **touchable** property as an example. 64 653. Load content for the main window. 66 67 Call **loadContent** to load the page content to the main window. 68 69 ```ts 70 import UIAbility from '@ohos.app.ability.UIAbility'; 71 72 export default class EntryAbility extends UIAbility { 73 onWindowStageCreate(windowStage) { 74 // 1. Obtain the main window of the application. 75 let windowClass = null; 76 windowStage.getMainWindow((err, data) => { 77 if (err.code) { 78 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 79 return; 80 } 81 windowClass = data; 82 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 83 // 2. Set the touchable property of the main window. 84 let isTouchable = true; 85 windowClass.setWindowTouchable(isTouchable, (err) => { 86 if (err.code) { 87 console.error('Failed to set the window to be touchable. Cause:' + JSON.stringify(err)); 88 return; 89 } 90 console.info('Succeeded in setting the window to be touchable.'); 91 }) 92 }) 93 // 3. Load the page content to the main window. 94 windowStage.loadContent("pages/page2", (err) => { 95 if (err.code) { 96 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 97 return; 98 } 99 console.info('Succeeded in loading the content.'); 100 }); 101 } 102 }; 103 ``` 104 105 106## Setting a Subwindow of an Application 107 108You can create an application subwindow, such as a dialog box, and set its properties. 109 110 111### How to Develop 112 1131. Create a subwindow. 114 115 Call **createSubWindow** to create a subwindow. 116 1172. Set the properties of the subwindow. 118 119 After the subwindow is created, you can set its properties, such as the size, position, background color, and brightness. 120 1213. Load content for the subwindow and show it. 122 123 Call **setUIContent** and **showWindow** to load and display the content in the subwindow. 124 1254. Destroy the subwindow. 126 127 When the subwindow is no longer needed, you can call **destroyWindow** to destroy it. 128 129 ```ts 130 import UIAbility from '@ohos.app.ability.UIAbility'; 131 132 let windowStage_ = null; 133 let sub_windowClass = null; 134 export default class EntryAbility extends UIAbility { 135 showSubWindow() { 136 // 1. Create a subwindow. 137 windowStage_.createSubWindow("mySubWindow", (err, data) => { 138 if (err.code) { 139 console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err)); 140 return; 141 } 142 sub_windowClass = data; 143 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 144 // 2. Set the position, size, and other properties of the subwindow. 145 sub_windowClass.moveWindowTo(300, 300, (err) => { 146 if (err.code) { 147 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 148 return; 149 } 150 console.info('Succeeded in moving the window.'); 151 }); 152 sub_windowClass.resize(500, 500, (err) => { 153 if (err.code) { 154 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 155 return; 156 } 157 console.info('Succeeded in changing the window size.'); 158 }); 159 // 3. Load the page content to the subwindow. 160 sub_windowClass.setUIContent("pages/page3", (err) => { 161 if (err.code) { 162 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 163 return; 164 } 165 console.info('Succeeded in loading the content.'); 166 // 3. Show the subwindow. 167 sub_windowClass.showWindow((err) => { 168 if (err.code) { 169 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 170 return; 171 } 172 console.info('Succeeded in showing the window.'); 173 }); 174 }); 175 }) 176 } 177 178 destroySubWindow() { 179 // 4. Destroy the subwindow when it is no longer needed (depending on the service logic). 180 sub_windowClass.destroyWindow((err) => { 181 if (err.code) { 182 console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err)); 183 return; 184 } 185 console.info('Succeeded in destroying the window.'); 186 }); 187 } 188 189 onWindowStageCreate(windowStage) { 190 windowStage_ = windowStage; 191 // Create a subwindow when it is needed, for example, when a click event occurs in the main window. Calling onWindowStageCreate is not always necessary. The code here is for reference only. 192 this.showSubWindow(); 193 } 194 195 onWindowStageDestroy() { 196 // Destroy the subwindow when it is no longer needed, for example, when the Close button in the subwindow is clicked. Calling onWindowStageDestroy is not always necessary. The code here is for reference only. 197 this.destroySubWindow(); 198 } 199 }; 200 ``` 201 202 203## Experiencing the Immersive Window Feature 204 205To create a better video watching and gaming experience, you can use the immersive window feature to hide the system windows, including the status bar and navigation bar. To achieve this effect, you can use the immersive window feature, which is available only for the main window of an application. 206 207 208### How to Develop 209 2101. Obtain the main window. 211 212 Call **getMainWindow** to obtain the main window of the application. 213 2142. Implement the immersive effect. You can use either of the following methods: 215 - Method 1: Call **setWindowSystemBarEnable** to hide the navigation bar and status bar. 216 - 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 navigation bar and status bar to ensure that their display effect is consistent with that of the main window. 217 2183. Load content for the immersive window and show it. 219 220 Call **loadContent** to load the content to the immersive window. 221 222 ```ts 223 import UIAbility from '@ohos.app.ability.UIAbility'; 224 225 export default class EntryAbility extends UIAbility { 226 onWindowStageCreate(windowStage) { 227 // 1. Obtain the main window of the application. 228 let windowClass = null; 229 windowStage.getMainWindow((err, data) => { 230 if (err.code) { 231 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 232 return; 233 } 234 windowClass = data; 235 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 236 237 // 2. Use method 1 to implement the immersive effect. 238 let names = []; 239 windowClass.setWindowSystemBarEnable(names, (err) => { 240 if (err.code) { 241 console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); 242 return; 243 } 244 console.info('Succeeded in setting the system bar to be visible.'); 245 }); 246 // 2. Use method 2 to implement the immersive effect. 247 let isLayoutFullScreen = true; 248 windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err) => { 249 if (err.code) { 250 console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err)); 251 return; 252 } 253 console.info('Succeeded in setting the window layout to full-screen mode.'); 254 }); 255 let sysBarProps = { 256 statusBarColor: '#ff00ff', 257 navigationBarColor: '#00ff00', 258 // The following properties are supported since API version 8. 259 statusBarContentColor: '#ffffff', 260 navigationBarContentColor: '#ffffff' 261 }; 262 windowClass.setWindowSystemBarProperties(sysBarProps, (err) => { 263 if (err.code) { 264 console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err)); 265 return; 266 } 267 console.info('Succeeded in setting the system bar properties.'); 268 }); 269 }) 270 // 3. Load the page content to the immersive window. 271 windowStage.loadContent("pages/page2", (err) => { 272 if (err.code) { 273 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 274 return; 275 } 276 console.info('Succeeded in loading the content.'); 277 }); 278 } 279 }; 280 ``` 281 282 283## Setting a Floating Window 284 285A floating window is created based on an existing task. It is always displayed in the foreground, even if the task used for creating the floating window is switched to the background. Generally, the floating window is above all application windows. You can create a floating window and set its properties. 286 287 288### How to Develop 289 2901. Apply for permissions. 291 292 To create a floating window (of the **WindowType.TYPE_FLOAT** type), you must configure the **ohos.permission.SYSTEM_FLOAT_WINDOW** permission in the **requestPermissions** field of the **module.json5** file. For more configuration information, see [module.json5 Configuration File](../quick-start/module-configuration-file.md). 293 294 > **NOTE** 295 > 296 > If the task for creating the floating window is reclaimed by the system, the floating window will no longer be displayed. If you want the floating window to be displayed in such a case, apply for a [continuous task](../task-management/background-task-overview.md). 297 298 ```json 299 { 300 "module": { 301 "requestPermissions":[ 302 { 303 "name" : "ohos.permission.SYSTEM_FLOAT_WINDOW", 304 "usedScene": { 305 "abilities": [ 306 "EntryAbility" 307 ], 308 "when":"inuse" 309 } 310 } 311 ] 312 } 313 } 314 ``` 315 3162. Create a floating window. 317 318 Call **window.createWindow** to create a floating window. 319 3203. Set properties for the floating window. 321 322 After the floating window is created, you can set its properties, such as the size, position, background color, and brightness. 323 3244. Load content for the floating window and show it. 325 326 Call **setUIContent** and **showWindow** to load and display the content in the floating window. 327 3285. Destroy the floating window. 329 330 When the floating window is no longer needed, you can call **destroyWindow** to destroy it. 331 332 ```ts 333 import UIAbility from '@ohos.app.ability.UIAbility'; 334 import window from '@ohos.window'; 335 336 export default class EntryAbility extends UIAbility { 337 onWindowStageCreate(windowStage) { 338 // 2. Create a floating window. 339 let windowClass = null; 340 let config = {name: "floatWindow", windowType: window.WindowType.TYPE_FLOAT, ctx: this.context}; 341 window.createWindow(config, (err, data) => { 342 if (err.code) { 343 console.error('Failed to create the floatWindow. Cause: ' + JSON.stringify(err)); 344 return; 345 } 346 console.info('Succeeded in creating the floatWindow. Data: ' + JSON.stringify(data)); 347 windowClass = data; 348 // 3. Set the position, size, and properties of the floating window. 349 windowClass.moveWindowTo(300, 300, (err) => { 350 if (err.code) { 351 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 352 return; 353 } 354 console.info('Succeeded in moving the window.'); 355 }); 356 windowClass.resize(500, 500, (err) => { 357 if (err.code) { 358 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 359 return; 360 } 361 console.info('Succeeded in changing the window size.'); 362 }); 363 // 4. Load the page content to the floating window. 364 windowClass.setUIContent("pages/page4", (err) => { 365 if (err.code) { 366 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 367 return; 368 } 369 console.info('Succeeded in loading the content.'); 370 // 4. Show the floating window. 371 windowClass.showWindow((err) => { 372 if (err.code) { 373 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 374 return; 375 } 376 console.info('Succeeded in showing the window.'); 377 }); 378 }); 379 // 5. Destroy the floating window when it is no longer needed (depending on the service logic). 380 windowClass.destroyWindow((err) => { 381 if (err.code) { 382 console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err)); 383 return; 384 } 385 console.info('Succeeded in destroying the window.'); 386 }); 387 }); 388 } 389 }; 390 ```