1# System Window Development (Stage Model Only) 2 3## Overview 4 5In the stage model, system applications are allowed to create and manage system windows, including the volume bar, wallpaper, notification panel, status bar, and navigation bar. For details about the supported system window types, see [WindowType in Window](../reference/apis/js-apis-window.md#windowtype7). 6 7When a window is displayed, hidden, or switched, an animation is usually used to smooth the interaction process. 8 9In OpenHarmony, the animation is the default behavior for application windows. You do not need to set or modify the code. 10 11However, you can customize an animation to be played during the display or hiding of a system window. 12 13> **NOTE** 14> 15> This document involves the use of system APIs. Use the full SDK for development. For details, see [Guide to Switching to Full SDK](../quick-start/full-sdk-switch-guide.md). 16 17 18## Available APIs 19 20For details, see [Window](../reference/apis/js-apis-window.md). 21 22| Instance | API | Description | 23| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 24| Window static method | createWindow(config: Configuration, callback: AsyncCallback\<Window>): void | Creates a subwindow or system window.<br>**config** specifies the parameters used for creating the window. | 25| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | Changes the window size. | 26| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | Moves this window. | 27| Window | SetUIContent(path: string, callback: AsyncCallback<void>): void | Loads the page content to this window. | 28| Window | showWindow(callback: AsyncCallback\<void>): void | Shows this window. | 29| Window | on(type: 'touchOutside', callback: Callback<void>): void | Enables listening for click events outside this window. | 30| Window | hide (callback: AsyncCallback\<void>): void | Hides this window. This is a system API. | 31| Window | destroyWindow(callback: AsyncCallback<void>): void | Destroys this window. | 32| Window | getTransitionController(): TransitionController | Obtains the transition animation controller. This is a system API. | 33| TransitionContext | completeTransition(isCompleted: boolean): void | Completes the transition. This API can be called only after [animateTo()](../reference/arkui-ts/ts-explicit-animation.md) is executed. This is a system API.| 34| Window | showWithAnimation(callback: AsyncCallback\<void>): void | Shows this window and plays an animation during the process. This is a system API. | 35| Window | hideWithAnimation(callback: AsyncCallback\<void>): void | Hides this window and plays an animation during the process. This is a system API. | 36 37## Developing a System Window 38 39This section uses the volume bar as an example to describe how to develop a system window. 40 41### How to Develop 42 43 441. Create a system window. 45 46 In the case of [ServiceExtensionContext](../reference/apis/js-apis-inner-application-serviceExtensionContext.md), call **window.createWindow** to create a system window of the volume bar type. 47 482. Set the properties of the system window. 49 50 After the volume bar window is created, you can change its size and position, and set its properties such as the background color and brightness. 51 523. Load content for the system window and show it. 53 54 You can call **SetUIContent** and **showWindow** to load and display the content in the volume bar window. 55 564. Hide or destroy the system window. 57 58 When the volume bar window is no longer needed, you can call **hide** or **destroyWindow** to hide or destroy it. 59 60```ts 61import ExtensionContext from '@ohos.app.ability.ServiceExtensionAbility'; 62import window from '@ohos.window'; 63 64export default class ServiceExtensionAbility1 extends ExtensionContext { 65 onCreate(want) { 66 globalThis.abilityWant = want; 67 // 1. Create a volume bar window. 68 let windowClass = null; 69 let config = {name: "volume", windowType: window.WindowType.TYPE_VOLUME_OVERLAY, ctx: this.context}; 70 window.createWindow(config, (err, data) => { 71 if (err.code) { 72 console.error('Failed to create the volume window. Cause:' + JSON.stringify(err)); 73 return; 74 } 75 console.info('Succeeded in creating the volume window.') 76 windowClass = data; 77 // 2. Change the size and position of the volume bar window, or set its properties such as the background color and brightness. 78 windowClass.moveWindowTo(300, 300, (err) => { 79 if (err.code) { 80 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 81 return; 82 } 83 console.info('Succeeded in moving the window.'); 84 }); 85 windowClass.resize(500, 500, (err) => { 86 if (err.code) { 87 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 88 return; 89 } 90 console.info('Succeeded in changing the window size.'); 91 }); 92 // 3. Load the page content to the volume bar window. 93 windowClass.setUIContent("pages/page_volume", (err) => { 94 if (err.code) { 95 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 96 return; 97 } 98 console.info('Succeeded in loading the content.'); 99 // 3. Show the volume bar window. 100 windowClass.showWindow((err) => { 101 if (err.code) { 102 console.error('Failed to show the window. Cause:' + JSON.stringify(err)); 103 return; 104 } 105 console.info('Succeeded in showing the window.'); 106 }); 107 }); 108 // 4. Hide or destroy the volume bar window. 109 // Hide the volume bar window when a click event outside the window is detected. 110 windowClass.on('touchOutside', () => { 111 console.info('touch outside'); 112 windowClass.hide((err) => { 113 if (err.code) { 114 console.error('Failed to hide the window. Cause: ' + JSON.stringify(err)); 115 return; 116 } 117 console.info('Succeeded in hidinging the window.'); 118 }); 119 }); 120 }); 121 } 122}; 123``` 124 125## Customizing an Animation to Be Played During the Display or Hiding of a System Window 126 127You can determine whether to play an animation when a system window is showing or hiding. 128 129### How to Develop 130 1311. Obtain the transition animation controller. 132 133 Call **getTransitionController** to obtain the controller, which completes subsequent animation operations. 134 1352. Configure the animation to be played. 136 137 Call [animateTo()](../reference/arkui-ts/ts-explicit-animation.md) to configure the animation attributes. 138 1393. Complete the transition. 140 141 Use **completeTransition(true)** to set the completion status of the transition. If **false** is passed in, the transition is canceled. 142 1434. Show or hide the system window and play the animation during the process. 144 145 Call **showWithAnimation** to show the window and play the animation. Call **hideWithAnimation** to hide the window and play the animation. 146 147```ts 148import ExtensionContext from '@ohos.app.ability.ServiceExtensionAbility'; 149import window from '@ohos.window'; 150 151export default class ServiceExtensionAbility1 extends ExtensionContext { 152 onCreate(want) { 153 globalThis.abilityWant = want; 154 // Create a volume bar window. 155 let windowClass = null; 156 let config = {name: "volume", windowType: window.WindowType.TYPE_VOLUME_OVERLAY, ctx: this.context}; 157 window.createWindow(config, (err, data) => { 158 if (err.code) { 159 console.error('Failed to create the volume window. Cause:' + JSON.stringify(err)); 160 return; 161 } 162 console.info('Succeeded in creating the volume window.') 163 windowClass = data; 164 // Customize an animation to be played during the display of the system window. 165 // 1. Obtain the transition animation controller. 166 let controller = windowClass.getTransitionController(); 167 // 2. Configure the animation to be played. 168 controller.animationForShown = (context : window.TransitionContext) => { 169 let toWindow = context.toWindow 170 // Set the animation attributes. 171 animateTo({ 172 duration: 1000, // Animation duration. 173 tempo: 0.5, // Playback speed. 174 curve: Curve.EaseInOut, // Animation curve. 175 delay: 0, // Animation delay. 176 iterations: 1, // Number of playback times. 177 playMode: PlayMode.Normal // Animation playback mode. 178 onFinish: ()=> { 179 // 3. Complete the transition. 180 context.completeTransition(true) 181 } 182 }, () => { 183 let obj : window.TranslateOptions = { 184 x : 100.0, 185 y : 0.0, 186 z : 0.0 187 } 188 toWindow.translate(obj); 189 console.info('toWindow translate end'); 190 }) 191 console.info('complete transition end'); 192 } 193 194 windowClass.loadContent("pages/page_volume", (err) => { 195 if (err.code) { 196 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 197 return; 198 } 199 console.info('Succeeded in loading the content.'); 200 // 4. Show the window and play the animation during the process. 201 windowClass.showWithAnimation((err) => { 202 if (err.code) { 203 console.error('Failed to show the window with animation. Cause: ' + JSON.stringify(err)); 204 return; 205 } 206 console.info('Succeeded in showing the window with animation.'); 207 }) 208 }); 209 }); 210 } 211 onDestroy() { 212 let windowClass = null; 213 try { 214 windowClass = window.findWindow('volume'); 215 } catch (exception) { 216 console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception)); 217 } 218 // Customize an animation to be played during the hiding of the system window. 219 // 1. Obtain the transition animation controller. 220 let controller = windowClass.getTransitionController(); 221 // 2. Configure the animation to be played. 222 controller.animationForHidden = (context : window.TransitionContext) => { 223 let toWindow = context.toWindow 224 // Set the animation attributes. 225 animateTo({ 226 duration: 1000, // Animation duration. 227 tempo: 0.5, // Playback speed. 228 curve: Curve.EaseInOut, // Animation curve. 229 delay: 0, // Animation delay. 230 iterations: 1, // Number of playback times. 231 playMode: PlayMode.Normal // Animation playback mode. 232 onFinish: ()=> { 233 // 3. Complete the transition. 234 context.completeTransition(true) 235 windowClass.destroyWindow((err) => { 236 if (err.code) { 237 console.error('Failed to destroy the window. Cause:' + JSON.stringify(err)); 238 return; 239 } 240 console.info('Succeeded in destroying the window.'); 241 }); 242 } 243 }, () => { 244 toWindow.opacity(0.0); 245 console.info('toWindow opacity end'); 246 }) 247 console.info('complete transition end'); 248 } 249 // 4. Hide the window and play the animation during the process. 250 windowClass.hideWithAnimation((err) => { 251 if (err.code) { 252 console.error('Failed to hide the window with animation. Cause: ' + JSON.stringify(err)); 253 return; 254 } 255 console.info('Succeeded in hiding the window with animation.'); 256 }); 257 } 258}; 259``` 260