1# @ohos.PiPWindow (PiP Window) 2 3The module provides basic APIs for manipulating Picture in Picture (PiP). For example, you can use the APIs to check whether the PiP feature is supported and create a PiP controller to start or stop a PiP window. PiP is mainly used in video playback, video calls, or video meetings. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import { PiPWindow } from '@kit.ArkUI'; 13``` 14 15## PiPWindow.isPiPEnabled 16 17isPiPEnabled(): boolean 18 19Checks whether the PiP feature is supported. 20 21**Atomic service API**: This API can be used in atomic services since API version 12. 22 23**System capability**: SystemCapability.Window.SessionManager 24 25**Return value** 26 27| Type | Description | 28|----------|-------------------------------------| 29| boolean | Check result for whether the PiP feature is supported. **true** if supported, **false** otherwise.| 30 31**Example** 32 33```ts 34let enable: boolean = PiPWindow.isPiPEnabled(); 35console.info('isPipEnabled:' + enable); 36``` 37 38## PiPWindow.create 39 40create(config: PiPConfiguration): Promise<PiPController> 41 42Creates a PiP controller. This API uses a promise to return the result. 43 44**Atomic service API**: This API can be used in atomic services since API version 12. 45 46**System capability**: SystemCapability.Window.SessionManager 47 48**Parameters** 49 50| Name | Type | Mandatory | Description | 51|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 52| config | [PiPConfiguration](#pipconfiguration) | Yes | Options for creating the PiP controller. This parameter cannot be empty, and **context** and **componentController** that are used to construct this parameter cannot be empty. When constructing this parameter, **templateType** (if specified) must be a value defined in [PiPTemplateType](#piptemplatetype), and **controlGroups** (if specified) must match the value of **templateType**. For details, see [PiPControlGroup](#pipcontrolgroup12).| 53 54**Return value** 55 56| Type | Description | 57|------------------------------------------------------------|--------------------------| 58| Promise<[PiPController](#pipcontroller)> | Promise used to return the PiP controller.| 59 60**Error codes** 61 62For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 63 64| ID| Error Message | 65|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 66| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 67| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 68 69**Example** 70 71```ts 72import { BusinessError } from '@kit.BasicServicesKit'; 73import { BuilderNode, FrameNode, NodeController, UIContext } from '@kit.ArkUI'; 74import { common } from '@kit.AbilityKit'; 75 76class Params { 77 text: string = ''; 78 constructor(text: string) { 79 this.text = text; 80 } 81} 82 83// You can use the @Builder decorator to construct layouts. 84@Builder 85function buildText(params: Params) { 86 Column() { 87 Text(params.text) 88 .fontSize(20) 89 .fontColor(Color.Red) 90 } 91 .width('100%') // The PiP window is displayed at full size in the width direction. 92 .height('100%') // The PiP window is displayed at full size in the height direction. 93} 94 95// You can extend NodeController to customize the UI controller. 96class TextNodeController extends NodeController { 97 private message: string; 98 private textNode: BuilderNode<[Params]> | null = null; 99 constructor(message: string) { 100 super(); 101 this.message = message; 102 } 103 104 // Use BuilderNode to load the custom layouts. 105 makeNode(context: UIContext): FrameNode | null { 106 this.textNode = new BuilderNode(context); 107 this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message)); 108 return this.textNode.getFrameNode(); 109 } 110 111 // You can customize this method to update layouts. 112 update(message: string) { 113 console.log(`update message: ${message}`); 114 if (this.textNode !== null) { 115 this.textNode.update(new Params(message)); 116 } 117 } 118} 119 120@Entry 121@Component 122struct Index { 123 private message: string = 'createPiP'; 124 private pipController: PiPWindow.PiPController | undefined = undefined; 125 private mXComponentController: XComponentController = new XComponentController(); // Use the mXComponentController to initialize the XComponent: XComponent( {id: 'video', type: 'surface', controller: mXComponentController} ). This ensures that the XComponent content can be migrated to the PiP window. 126 private nodeController: TextNodeController = new TextNodeController('this is custom UI'); 127 private navId: string = "page_1"; // The navigation ID of the current page is page_1. For details, see the definition of PiPConfiguration. The navigation name is customized. 128 private contentWidth: number = 800; // The content width is 800 px. 129 private contentHeight: number = 600; // The content height is 600 px. 130 private para: Record<string, number> = { 'PropA': 47 }; 131 private localStorage: LocalStorage = new LocalStorage(this.para); 132 private res: boolean = this.localStorage.setOrCreate('PropB', 121); 133 private defaultWindowSizeType: number = 1; // Set the window to be a small window when first pulled up in PiP. 134 private config: PiPWindow.PiPConfiguration = { 135 context: this.getUIContext().getHostContext() as Context, 136 componentController: this.mXComponentController, 137 navigationId: this.navId, 138 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 139 contentWidth: this.contentWidth, 140 contentHeight: this.contentHeight, 141 controlGroups: [PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT], 142 customUIController: this.nodeController, // Optional. Set this parameter if you want to display the custom UI at the top of the PiP window. 143 localStorage: this.localStorage, // Optional. Set this parameter if you want to track the main window instance. 144 defaultWindowSizeType: this.defaultWindowSizeType, // Optional. If you need to configure the default window size upon launch, set this parameter. 145 }; 146 147 createPiP() { 148 let promise: Promise<PiPWindow.PiPController> = PiPWindow.create(this.config); 149 promise.then((data: PiPWindow.PiPController) => { 150 this.pipController = data; 151 console.info(`Succeeded in creating pip controller. Data:${data}`); 152 }).catch((err: BusinessError) => { 153 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 154 }); 155 } 156 157 // This is for function testing only. In actual development, you should design components according to the service requirements. 158 build() { 159 RelativeContainer() { 160 Button(this.message) 161 .onClick(() => { 162 this.createPiP(); 163 }) 164 } 165 } 166} 167``` 168 169## PiPWindow.create<sup>12+</sup> 170 171create(config: PiPConfiguration, contentNode: typeNode.XComponent): Promise<PiPController> 172 173Creates a PiP controller through a type node. This API uses a promise to return the result. 174 175**Atomic service API**: This API can be used in atomic services since API version 12. 176 177**System capability**: SystemCapability.Window.SessionManager 178 179**Parameters** 180 181| Name | Type | Mandatory | Description | 182|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 183| config | [PiPConfiguration](#pipconfiguration) | Yes | Options for creating the PiP controller. This parameter cannot be empty, and **context** that is used to construct this parameter cannot be empty. When constructing this parameter, **templateType** (if specified) must be a value defined in [PiPTemplateType](#piptemplatetype), and **controlGroups** (if specified) must match the value of **templateType**. For details, see [PiPControlGroup](#pipcontrolgroup12).| 184| contentNode | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12) | Yes | Content to be rendered in the PiP window. The parameter value cannot be empty. | 185 186**Return value** 187 188| Type | Description | 189|------------------------------------------------------------|--------------------------| 190| Promise<[PiPController](#pipcontroller)> | Promise used to return the PiP controller.| 191 192**Error codes** 193 194For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 195 196| ID| Error Message | 197|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 198| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 199| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 200 201**Example** 202 203```ts 204import { BusinessError } from '@kit.BasicServicesKit'; 205import { PiPWindow, typeNode, UIContext } from '@kit.ArkUI'; 206import { common } from '@kit.AbilityKit'; 207 208@Entry 209@Component 210struct Index { 211 private message = 'createPiP' 212 private pipController: PiPWindow.PiPController | undefined = undefined; 213 private xComponentController: XComponentController = new XComponentController(); 214 private context: UIContext | undefined = this.getUIContext(); // You can pass UIContext or use this.getUIContext() in the layout to assign a valid value to context. 215 private contentWidth: number = 800; // The content width is 800 px. 216 private contentHeight: number = 600; // The content height is 600 px. 217 private config: PiPWindow.PiPConfiguration = { 218 context: this.getUIContext().getHostContext() as Context, 219 componentController: this.xComponentController, 220 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 221 contentWidth: this.contentWidth, 222 contentHeight: this.contentHeight, 223 }; 224 private options: XComponentOptions = { 225 type: XComponentType.SURFACE, 226 controller: this.xComponentController 227 } 228 private xComponent = typeNode.createNode(this.context, 'XComponent', this.options); 229 230 createPiP() { 231 let promise: Promise<PiPWindow.PiPController> = PiPWindow.create(this.config, this.xComponent); 232 promise.then((data: PiPWindow.PiPController) => { 233 this.pipController = data; 234 console.info(`Succeeded in creating pip controller. Data:${data}`); 235 }).catch((err: BusinessError) => { 236 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 237 }); 238 } 239 240 // This is for function testing only. In actual development, you should design components according to the service requirements. 241 build() { 242 RelativeContainer() { 243 Button(this.message) 244 .onClick(() => { 245 this.createPiP(); 246 }) 247 } 248 } 249} 250``` 251 252## PiPConfiguration 253 254Defines the parameters for creating a PiP controller. 255 256**System capability**: SystemCapability.Window.SessionManager 257 258| Name | Type | Mandatory | Description | 259|---------------------|----------------------------------------------------------------------------|-----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 260| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Context environment.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 261| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md#xcomponentcontroller) | Yes | Original [XComponent](arkui-ts/ts-basic-components-xcomponent.md) controller.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 262| navigationId | string | No | Navigation ID of the current page. If no value is passed, the page does not need to be cached.<br>1. When the UIAbility uses [Navigation](arkui-ts/ts-basic-components-navigation.md) to manage pages, set the ID of the **Navigation** component for the PiP controller. This ensures that the original page can be restored from the PiP window.<br>2. When the UIAbility uses [Router](js-apis-router.md) to manage pages, you do not need to set the ID of the **Navigation** component for the PiP controller.<br>3. If the UIAbility has only one page, you do not need to set the navigation ID. The original page can be restored from the PiP window.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 263| templateType | [PiPTemplateType](#piptemplatetype) | No | Template type, which is used to distinguish video playback, video call, and video meeting scenarios. If no value is passed, the video playback template is used.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 264| contentWidth | number | No | Width of the original content, in px. It is used to determine the aspect ratio of the PiP window. When the PiP controller is created in [typeNode mode](#pipwindowcreate12), the default value is 1920. When the PiP controller is created [not in typeNode mode](#pipwindowcreate), the default value is the width of the [XComponent](arkui-ts/ts-basic-components-xcomponent.md).<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 265| contentHeight | number | No | Height of the original content, in px. It is used to determine the aspect ratio of the PiP window. When the PiP controller is created in [typeNode mode](#pipwindowcreate12), the default value is 1080. When the PiP controller is created [not in typeNode mode](#pipwindowcreate), the default value is the height of the [XComponent](arkui-ts/ts-basic-components-xcomponent.md).<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 266| controlGroups<sup>12+</sup> | Array<[PiPControlGroup](#pipcontrolgroup12)> | No | A list of optional component groups of the PiP controller. An application can configure whether to display these optional components. If this parameter is not set for an application, the basic components (for example, play/pause of the video playback component group) are displayed. A maximum of three components can be configured in the list.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 267| customUIController<sup>12+</sup> | [NodeController](js-apis-arkui-nodeController.md) | No | Custom UI that can be displayed at the top of the PiP window. If no value is passed, custom UI is not used.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 268| localStorage<sup>17+</sup> | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | No | A page-level UI state storage unit. In multi-instance scenarios, it can be used to track the UI state storage object of the main window instance. If no value is passed, you cannot retrieve the main window's UI storage object through the PiP window.<br>**Atomic service API**: This API can be used in atomic services since API version 17. | 269| defaultWindowSizeType<sup>19+</sup>| number | No | Initial PiP window size.<br>The value **0** means that no size is set, and the window will launch at the size it was before being closed in the previous PiP session.<br>The value **1** means a small window,<br>and **2** means a large window.<br>If no value is passed, **0** is used.<br>**Atomic service API**: This API can be used in atomic services since API version 19. | 270 271## PiPWindowSize<sup>15+</sup> 272 273Describes the size of a PiP window. 274 275**Atomic service API**: This API can be used in atomic services since API version 15. 276 277**System capability**: SystemCapability.Window.SessionManager 278 279| Name | Type| Read-Only| Optional| Description | 280| ------ | -------- | ---- | ---- | ---------- | 281| width | number | Yes | No | Window width, in px. The value must be a positive integer and cannot be greater than the screen width.| 282| height | number | Yes | No | Window height, in px. The value must be a positive integer and cannot be greater than the screen height.| 283| scale | number | Yes | No | Scale factor of the window, representing the display size relative to the width and height. The value is a floating-point number in the range (0.0, 1.0]. The value **1** means that the window matches the specified width and height.| 284 285## PiPWindowInfo<sup>15+</sup> 286 287Describes the PiP window information. 288 289**Atomic service API**: This API can be used in atomic services since API version 15. 290 291**System capability**: SystemCapability.Window.SessionManager 292 293| Name | Type| Read-Only| Optional| Description | 294| ------ | -------- | ---- | ---- | ---------- | 295| windowId | number | Yes | No | ID of the PiP window.| 296| size | [PiPWindowSize](#pipwindowsize15) | Yes | No | Size of the PiP window.| 297 298## PiPTemplateType 299 300Enumerates the PIP template types. 301 302**Atomic service API**: This API can be used in atomic services since API version 12. 303 304**System capability**: SystemCapability.Window.SessionManager 305 306| Name | Value | Description | 307|---------------|-----|--------------------------------------| 308| VIDEO_PLAY | 0 | Video playback template. A PiP window will be started during video playback, and the video playback template is loaded. | 309| VIDEO_CALL | 1 | Video call template. A PiP window will be started during a video call, and the video call template will be loaded.| 310| VIDEO_MEETING | 2 | Video meeting template. A PiP window will be started during a video meeting, and the video meeting template will be loaded.| 311| VIDEO_LIVE | 3 | Live template. A PiP window will be started during a live, and the live template is loaded. | 312 313## PiPState 314 315Enumerates the PiP states. 316 317**Atomic service API**: This API can be used in atomic services since API version 12. 318 319**System capability**: SystemCapability.Window.SessionManager 320 321| Name | Value | Description | 322|----------------------|-----|-----------------------| 323| ABOUT_TO_START | 1 | PiP is about to start. | 324| STARTED | 2 | PiP is started. | 325| ABOUT_TO_STOP | 3 | PiP is about to stop. | 326| STOPPED | 4 | PiP is stopped. | 327| ABOUT_TO_RESTORE | 5 | The original page is about to restore.| 328| ERROR | 6 | An error occurs during the execution of the PiP lifecycle. | 329 330## PiPControlGroup<sup>12+</sup> 331 332type PiPControlGroup = VideoPlayControlGroup | VideoCallControlGroup | VideoMeetingControlGroup | VideoLiveControlGroup 333 334Describes the optional component groups of the PiP controller. An application can configure whether to display these optional components. By default, the controller displays only basic components (such as the play/pause component of the video playback component group). 335 336**Atomic service API**: This API can be used in atomic services since API version 12. 337 338**System capability**: SystemCapability.Window.SessionManager 339 340| Type | Description | 341|-------------------------------------------------|-------------| 342| [VideoPlayControlGroup](#videoplaycontrolgroup12) | Video playback component group.| 343| [VideoCallControlGroup](#videocallcontrolgroup12) | Video call component group.| 344| [VideoMeetingControlGroup](#videomeetingcontrolgroup12) | Video meeting component group.| 345| [VideoLiveControlGroup](#videolivecontrolgroup12) | Live video component group.| 346 347 348## VideoPlayControlGroup<sup>12+</sup> 349 350Enumerates the video playback component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_PLAY**. 351 352**Atomic service API**: This API can be used in atomic services since API version 12. 353 354**System capability**: SystemCapability.Window.SessionManager 355 356| Name | Value | Description | 357|----------------------|-----|-----------------------| 358| VIDEO_PREVIOUS_NEXT | 101 | Previous/Next component group for video playback.<br>This component group is mutually exclusive with the fast-forward/rewind component group. It cannot be added if the fast-forward/rewind component group is added. | 359| FAST_FORWARD_BACKWARD | 102 | Fast-forward/Rewind component group for video playback.<br>This component group is mutually exclusive with the previous/next component group. It cannot be added if the previous/next component group is added. | 360 361## VideoCallControlGroup<sup>12+</sup> 362 363Enumerates the video call component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_CALL**. 364 365**Atomic service API**: This API can be used in atomic services since API version 12. 366 367**System capability**: SystemCapability.Window.SessionManager 368 369| Name | Value | Description | 370|----------------------|-----|-----------------------| 371| MICROPHONE_SWITCH | 201 | Microphone on/off component group. | 372| HANG_UP_BUTTON | 202 | Hang-up component group. | 373| CAMERA_SWITCH | 203 | Camera on/off component group. | 374| MUTE_SWITCH | 204 | Mute/Unmute component group. | 375 376## VideoMeetingControlGroup<sup>12+</sup> 377 378Enumerates the video meeting component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_MEETING**. 379 380**Atomic service API**: This API can be used in atomic services since API version 12. 381 382**System capability**: SystemCapability.Window.SessionManager 383 384| Name | Value | Description | 385|----------------------|-----|-----------------------| 386| HANG_UP_BUTTON | 301 | Hang-up component group. | 387| CAMERA_SWITCH | 302 | Camera on/off component group. | 388| MUTE_SWITCH | 303 | Mute/Unmute component group. | 389| MICROPHONE_SWITCH | 304 | Microphone on/off component group. | 390 391## VideoLiveControlGroup<sup>12+</sup> 392 393Enumerates the live video component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_LIVE**. 394 395**Atomic service API**: This API can be used in atomic services since API version 12. 396 397**System capability**: SystemCapability.Window.SessionManager 398 399| Name | Value | Description | 400|----------------------|-----|-----------------------| 401| VIDEO_PLAY_PAUSE | 401 | Play/Pause component group for live video.| 402| MUTE_SWITCH | 402 | Mute/Unmute component group. | 403 404## PiPActionEventType 405 406type PiPActionEventType = PiPVideoActionEvent | PiPCallActionEvent | PiPMeetingActionEvent | PiPLiveActionEvent 407 408Enumerates the types of action events of the PiP controller. 409 410**Atomic service API**: This API can be used in atomic services since API version 12. 411 412**System capability**: SystemCapability.Window.SessionManager 413 414| Type | Description | 415|-------------------------------------------------|-------------| 416| [PiPVideoActionEvent](#pipvideoactionevent) | Action event for components displayed on the video playback controller.| 417| [PiPCallActionEvent](#pipcallactionevent) | Action event for components displayed on the video call controller.| 418| [PiPMeetingActionEvent](#pipmeetingactionevent) | Action event for components displayed on the video meeting controller.| 419| [PiPLiveActionEvent](#pipliveactionevent) | Action event for components displayed on the live video controller. | 420 421## PiPVideoActionEvent 422 423type PiPVideoActionEvent = 'playbackStateChanged' | 'nextVideo' | 'previousVideo' | 'fastForward' | 'fastBackward' 424 425Defines the PiP action event during video playback. 426 427**Atomic service API**: This API can be used in atomic services since API version 12. 428 429**System capability**: SystemCapability.Window.SessionManager 430 431| Type | Description | 432| ---------------------------- | ----------------------------------------- | 433| 'playbackStateChanged' | The playback status changes. | 434| 'nextVideo' | Plays the next video. | 435| 'previousVideo' | Plays the previous video. | 436| 'fastForward'<sup>12+</sup> | Fast forwards the video. This value is supported since API version 12.| 437| 'fastBackward'<sup>12+</sup> | Rewinds the video. This value is supported since API version 12.| 438 439## PiPCallActionEvent 440 441type PiPCallActionEvent = 'hangUp' | 'micStateChanged' | 'videoStateChanged' | 'voiceStateChanged' 442 443Defines the PiP action event in a video call. 444 445**Atomic service API**: This API can be used in atomic services since API version 12. 446 447**System capability**: SystemCapability.Window.SessionManager 448 449| Type | Description | 450| ------------------- | ------------------ | 451| 'hangUp' | The video call is hung up. | 452| 'micStateChanged' | The microphone is muted or unmuted.| 453| 'videoStateChanged' | The camera is turned on or off.| 454| 'voiceStateChanged'<sup>12+</sup> | The speaker is muted or unmuted. | 455 456 457## PiPMeetingActionEvent 458 459type PiPMeetingActionEvent = 'hangUp' | 'voiceStateChanged' | 'videoStateChanged' | 'micStateChanged' 460 461Defines the PiP action event in a video meeting. 462 463**Atomic service API**: This API can be used in atomic services since API version 12. 464 465**System capability**: SystemCapability.Window.SessionManager 466 467| Type | Description | 468| ------------------- | ------------------ | 469| 'hangUp' | The video meeting is hung up. | 470| 'voiceStateChanged' | The speaker is muted or unmuted. | 471| 'videoStateChanged' | The camera is turned on or off.| 472| 'micStateChanged'<sup>12+</sup> | The microphone is muted or unmuted.| 473 474 475## PiPLiveActionEvent 476 477type PiPLiveActionEvent = 'playbackStateChanged' | 'voiceStateChanged' 478 479Defines the PiP action event in a live. 480 481**Atomic service API**: This API can be used in atomic services since API version 12. 482 483**System capability**: SystemCapability.Window.SessionManager 484 485| Type | Description | 486| ---------------------- | ---------------- | 487| 'playbackStateChanged' | The live is played or paused.| 488| 'voiceStateChanged'<sup>12+</sup> | The speaker is muted or unmuted. | 489 490 491## PiPControlStatus<sup>12+</sup> 492 493Enumerates the statuses of components displayed on the PiP controller. 494 495**Atomic service API**: This API can be used in atomic services since API version 12. 496 497**System capability**: SystemCapability.Window.SessionManager 498 499| Name | Value | Description | 500|----------------------|-----|-----------------------| 501| PLAY | 1 | Play. | 502| PAUSE | 0 | Pause. | 503| OPEN | 1 | Open. | 504| CLOSE | 0 | Close. | 505 506## PiPControlType<sup>12+</sup> 507 508Enumerates the types of components displayed on the PiP controller. 509 510**Atomic service API**: This API can be used in atomic services since API version 12. 511 512**System capability**: SystemCapability.Window.SessionManager 513 514| Name | Value | Description | 515|-------------------|-----|--------------------------------------| 516| VIDEO_PLAY_PAUSE | 0 | Play/Pause component. | 517| VIDEO_PREVIOUS | 1 | Previous component in video scenarios.| 518| VIDEO_NEXT | 2 | Next component in video scenarios.| 519| FAST_FORWARD | 3 | Fast-forward component in video scenarios. | 520| FAST_BACKWARD | 4 | Rewind component in video scenarios. | 521| HANG_UP_BUTTON | 5 | Hang-up component.| 522| MICROPHONE_SWITCH | 6 | Microphone on/off component.| 523| CAMERA_SWITCH | 7 | Camera on/off component. | 524| MUTE_SWITCH | 8 | Mute/Unmute component. | 525 526 527## ControlPanelActionEventCallback<sup>12+</sup> 528 529type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void 530 531Describes the action event callback of the PiP controller. 532 533**Atomic service API**: This API can be used in atomic services since API version 12. 534 535**System capability**: SystemCapability.Window.SessionManager 536 537**Parameters** 538 539| Name | Type | Mandatory | Description | 540|--------------------------|--------------|--------------|-----------------------------------| 541| event | [PiPActionEventType](#pipactioneventtype) | Yes| Type of the action event of the PiP controller.<br>The application performs processing based on the action event. For example, if the **'playbackStateChanged'** event is triggered, the application starts or stops the video.| 542| status | number | No| Status of a component that can be switched. For example, for a microphone on/off component group, a camera on/off component group, and a mute/unmute component group, the value **1** means that the component is enabled and **0** means that the component is disabled. For other components, the default value **-1** is used.| 543 544## ControlEventParam<sup>12+</sup> 545 546Describes the parameters in the callback of the action event of the PiP controller. 547 548**Atomic service API**: This API can be used in atomic services since API version 12. 549 550**System capability**: SystemCapability.Window.SessionManager 551 552| Name | Type | Mandatory | Description | 553|--------------------------|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------| 554| controlType | [PiPControlType](#pipcontroltype12) | Yes| Type of the action event of the PiP controller. The application performs processing based on the component type. For example, if the video play/pause component is touched, the application starts or stops the video. | 555| status | [PiPControlStatus](#pipcontrolstatus12) | No| Status of a component that can be switched. For example, for a microphone on/off component group, a camera on/off component group, and a mute/unmute component group, the value **PiPControlStatus.PLAY** means that the component is enabled and **PiPControlStatus.PAUSE** means that the component is disabled. For the hang-up component, the default value is **-1**.| 556 557## PiPController 558 559Implements a PiP controller that starts, stops, or updates a PiP window and registers callbacks. 560 561Before calling any of the following APIs, you must use [PiPWindow.create()](#pipwindowcreate) to create a PiPController instance. 562 563**System capability**: SystemCapability.Window.SessionManager 564 565### startPiP 566 567startPiP(): Promise<void> 568 569Starts a PiP window. This API uses a promise to return the result. 570 571**Atomic service API**: This API can be used in atomic services since API version 12. 572 573**System capability**: SystemCapability.Window.SessionManager 574 575**Return value** 576 577| Type | Description | 578|------------------------|--------------------| 579| Promise<void> | Promise that returns no value. | 580 581**Error codes** 582 583For details about the error codes, see [Window Error Codes](errorcode-window.md). 584 585| ID | Error Message | 586|------------|--------------------------------------------------------| 587| 1300012 | The PiP window state is abnormal. | 588| 1300013 | Failed to create the PiP window. | 589| 1300014 | PiP internal error. | 590| 1300015 | Repeated PiP operation. | 591 592**Example** 593 594```ts 595// You can call pipController according to the pipController definition. 596let promise : Promise<void> = this.pipController.startPiP(); 597promise.then(() => { 598 console.info(`Succeeded in starting pip.`); 599}).catch((err: BusinessError) => { 600 console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`); 601}); 602``` 603 604### stopPiP 605 606stopPiP(): Promise<void> 607 608Stops a PiP window. This API uses a promise to return the result. 609 610**Atomic service API**: This API can be used in atomic services since API version 12. 611 612**System capability**: SystemCapability.Window.SessionManager 613 614**Return value** 615 616| Type | Description | 617|----------------------|---------------------| 618| Promise<void> | Promise that returns no value. | 619 620**Error codes** 621 622For details about the error codes, see [Window Error Codes](errorcode-window.md). 623 624| ID | Error Message | 625|---------|-----------------------------------| 626| 1300011 | Failed to destroy the PiP window. | 627| 1300012 | The PiP window state is abnormal. | 628| 1300015 | Repeated PiP operation. | 629 630**Example** 631 632```ts 633let promise : Promise<void> = this.pipController.stopPiP(); 634promise.then(() => { 635 console.info(`Succeeded in stopping pip.`); 636}).catch((err: BusinessError) => { 637 console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`); 638}); 639``` 640 641### setAutoStartEnabled 642 643setAutoStartEnabled(enable: boolean): void 644 645Sets whether to automatically start a PiP window when the user returns to the home screen. By default, no PiP window is started. 646 647If the XComponent approach is used to implement PiP and the **Navigation** component is used for route management, the system caches the top stack information with the specified navigation ID upon the first call of **setAutoStartEnabled(true)**. 648 649**Atomic service API**: This API can be used in atomic services since API version 12. 650 651**System capability**: SystemCapability.Window.SessionManager 652 653**Parameters** 654 655| Name | Type | Mandatory | Description | 656|----------|-----------|-------|---------------------------------| 657| enable | boolean | Yes | Whether to automatically start a PiP window when the user returns to the home screen. **true** to start, **false** otherwise. If the automatic PiP startup feature is disabled in Settings, a PiP window will not be automatically started in such a case even if this parameter is set to **true**. | 658 659**Example** 660 661```ts 662let enable: boolean = true; 663this.pipController.setAutoStartEnabled(enable); 664``` 665 666### updateContentSize 667 668updateContentSize(width: number, height: number): void 669 670Updates the media content size when the media content changes. 671 672**Atomic service API**: This API can be used in atomic services since API version 12. 673 674**System capability**: SystemCapability.Window.SessionManager 675 676**Parameters** 677 678| Name | Type | Mandatory | Description | 679|--------|--------|-----|----------------------------------------| 680| width | number | Yes | Width of the media content, in px. The value must be a number greater than 0. It is used to update the aspect ratio of the PiP window. | 681| height | number | Yes | Height of the media content, in px. The value must be a number greater than 0. It is used to update the aspect ratio of the PiP window. | 682 683**Error codes** 684 685For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 686 687| ID| Error Message | 688|-------|-------------------------------------------------------------------------------------------------------------| 689| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 690 691**Example** 692 693```ts 694let width: number = 540; // The content width changes to 540 px. 695let height: number = 960; // The content height changes to 960 px. 696this.pipController.updateContentSize(width, height); 697``` 698 699### updatePiPControlStatus<sup>12+</sup> 700updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void 701 702Updates the PiP component status. 703 704**Atomic service API**: This API can be used in atomic services since API version 12. 705 706**System capability**: SystemCapability.Window.SessionManager 707 708**Parameters** 709 710| Name | Type | Mandatory | Description | 711|--------|--------|-----|----------------------------------------------------------------------------------------------------| 712| controlType | [PiPControlType](#pipcontroltype12) | Yes | Type of the component displayed on the PiP controller. Currently, only **VIDEO_PLAY_PAUSE**, **MICROPHONE_SWITCH**, **CAMERA_SWITCH**, and **MUTE_SWITCH** are supported.| 713| status | [PiPControlStatus](#pipcontrolstatus12) | Yes | Status of the component displayed on the PiP controller. | 714 715**Error codes** 716 717For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 718 719| ID| Error Message | 720|-------|-------------------------------------------------------------------------------------------------------------| 721| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 722 723**Example** 724 725```ts 726let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // Play/Pause component displayed on the video playback control panel. 727let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // The Play/Pause component displayed on the video playback control panel is in the playing state. 728this.pipController.updatePiPControlStatus(controlType, status); 729``` 730 731### updateContentNode<sup>18+</sup> 732updateContentNode(contentNode: typeNode.XComponent): Promise<void> 733 734Updates the PiP node content. 735 736**Atomic service API**: This API can be used in atomic services since API version 18. 737 738**System capability**: SystemCapability.Window.SessionManager 739 740**Parameters** 741 742| Name | Type | Mandatory | Description | 743|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 744| contentNode | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12) | Yes | Content to be rendered in the PiP window. The parameter value cannot be empty. | 745 746**Return value** 747 748| Type | Description | 749|----------------------|---------------------| 750| Promise<void> | Promise that returns no value. | 751 752**Error codes** 753 754For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 755 756| ID| Error Message | 757|-------|-------------------------------------------------------------------------------------------------------------| 758| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 759| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 760| 1300014 | PiP internal error. | 761 762**Example** 763 764```ts 765import { typeNode, UIContext } from '@kit.ArkUI'; 766 767let context: UIContext | undefined = undefined; // You can pass UIContext or use this.getUIContext() in the layout to assign a valid value to context. 768 769try { 770 let contentNode = typeNode.createNode(context, "XComponent"); 771 this.pipController.updateContentNode(contentNode); 772} catch (exception) { 773 console.error(`Failed to update content node. Cause: ${exception.code}, message: ${exception.message}`); 774} 775``` 776 777### setPiPControlEnabled<sup>12+</sup> 778setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void 779 780Sets the enabled status for a component displayed on the PiP controller. 781 782**Atomic service API**: This API can be used in atomic services since API version 12. 783 784**System capability**: SystemCapability.Window.SessionManager 785 786**Parameters** 787 788| Name | Type | Mandatory | Description | 789|-------------|--------|-----|----------------------------------------| 790| controlType | [PiPControlType](#pipcontroltype12) | Yes | Type of the component displayed on the PiP controller. | 791| enabled | boolean | Yes | Enabled status of the component displayed on the PiP controller. **true** if enabled, **false** otherwise. | 792 793**Error codes** 794 795For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 796 797| ID| Error Message | 798|-------|-------------------------------------------------------------------------------------------------------------| 799| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 800 801**Example** 802 803```ts 804let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // Play/Pause component displayed on the video playback control panel. 805let enabled: boolean = false; // The Play/Pause component displayed on the video playback control panel is in the disabled state. 806this.pipController.setPiPControlEnabled(controlType, enabled); 807``` 808### getPiPWindowInfo<sup>15+</sup> 809getPiPWindowInfo(): Promise<[PiPWindowInfo](#pipwindowinfo15)> 810 811Obtains the PIP window information. 812 813**Atomic service API**: This API can be used in atomic services since API version 15. 814 815**System capability**: SystemCapability.Window.SessionManager 816 817**Return value** 818 819| Type | Description | 820|----------------------|---------------------| 821| Promise<[PiPWindowInfo](#pipwindowinfo15)> | Promise used to return the information about the current PIP window.| 822 823**Error codes** 824 825For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 826 827| ID| Error Message | 828|-------|-------------------------------------------------------------------------------------------------------------| 829| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 830| 1300014 | PiP internal error. | 831 832**Example** 833 834```ts 835let pipWindowInfo: PiPWindow.PiPWindowInfo | undefined = undefined; 836try { 837 let promise : Promise<PiPWindow.PiPWindowInfo> = this.pipController.getPiPWindowInfo(); 838 promise.then((data) => { 839 pipWindowInfo = data; 840 console.info('Success in get pip window info. Info: ' + JSON.stringify(data)); 841 }).catch((err: BusinessError) => { 842 console.error(`Failed to get pip window info. Cause code: ${err.code}, message: ${err.message}`); 843 }); 844} catch (exception) { 845 console.error(`Failed to get pip window info. Cause code: ${exception.code}, message: ${exception.message}`); 846} 847``` 848 849### getPiPSettingSwitch<sup>20+</sup> 850getPiPSettingSwitch(): Promise<boolean> 851 852Obtains the status of the auto-start PiP switch in Settings. This API works only for phones and tablets. 853 854**Atomic service API**: This API can be used in atomic services since API version 20. 855 856**System capability**: SystemCapability.Window.SessionManager 857 858**Return value** 859 860| Type | Description | 861|----------------------|---------------------| 862| Promise<boolean> | Promise used to return the auto-start PiP switch status. **true** if enabled, **false** otherwise.| 863 864**Error codes** 865 866For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 867 868| ID| Error Message | 869|-------|-------------------------------------------------------------------------------------------------------------| 870| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 871| 1300014 | PiP internal error. | 872 873**Example** 874 875```ts 876let pipSwitchStatus: boolean | undefined = undefined; 877try { 878 let promise : Promise<boolean> = this.pipController.getPiPSettingSwitch(); 879 promise.then((data) => { 880 pipSwitchStatus = data; 881 console.info('Succeeded in getting pip switch status. switchStatus: ' + JSON.stringify(data)); 882 }).catch((err: BusinessError) => { 883 console.error(`Failed to get pip switch status. Cause code: ${err.code}, message: ${err.message}`); 884 }); 885} catch (exception) { 886 console.error(`Failed to get pip switch status. Cause code: ${exception.code}, message: ${exception.message}`); 887} 888``` 889 890### on('stateChange') 891 892on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 893 894Subscribes to PiP state events. To avoid potential memory leaks, you are advised to stop listening when it is no longer needed. 895 896**Atomic service API**: This API can be used in atomic services since API version 12. 897 898**System capability**: SystemCapability.Window.SessionManager 899 900**Parameters** 901 902| Name | Type | Mandatory | Description | 903|------------|-----------|------|---------------------------------------------------------------------------------------------------| 904| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 905| callback | function | Yes | Callback used to return the result, which includes the following information:<br>- **state**: [PiPState](#pipstate), indicating the new PiP state.<br>- **reason**: a string indicating the reason for the state change. | 906 907**Example** 908 909```ts 910this.pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => { 911 let curState: string = ''; 912 switch (state) { 913 case PiPWindow.PiPState.ABOUT_TO_START: 914 curState = 'ABOUT_TO_START'; 915 break; 916 case PiPWindow.PiPState.STARTED: 917 curState = 'STARTED'; 918 break; 919 case PiPWindow.PiPState.ABOUT_TO_STOP: 920 curState = 'ABOUT_TO_STOP'; 921 break; 922 case PiPWindow.PiPState.STOPPED: 923 curState = 'STOPPED'; 924 break; 925 case PiPWindow.PiPState.ABOUT_TO_RESTORE: 926 curState = 'ABOUT_TO_RESTORE'; 927 break; 928 case PiPWindow.PiPState.ERROR: 929 curState = 'ERROR'; 930 break; 931 default: 932 break; 933 } 934 console.info('stateChange:' + curState + ' reason:' + reason); 935}); 936``` 937 938### off('stateChange') 939 940off(type: 'stateChange'): void 941 942Unsubscribes from PiP state events. 943 944**Atomic service API**: This API can be used in atomic services since API version 12. 945 946**System capability**: SystemCapability.Window.SessionManager 947 948**Parameters** 949 950| Name | Type | Mandatory | Description | 951|-----------|---------------|-------|----------------------------------------| 952| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 953 954**Example** 955 956```ts 957this.pipController.off('stateChange'); 958``` 959 960### on('controlPanelActionEvent') 961 962on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void 963 964Subscribes to PiP action events. To avoid potential memory leaks, you are advised to stop listening when it is no longer needed. The [on('controlEvent')](#oncontrolevent12) API is preferred. 965 966**Atomic service API**: This API can be used in atomic services since API version 12. 967 968**System capability**: SystemCapability.Window.SessionManager 969 970**Parameters** 971 972| Name | Type | Mandatory | Description | 973|----------|------------|-------|---------------------------------------------------| 974| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event.| 975| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12) | Yes | Action event callback of the PiP controller. | 976 977**Example** 978 979```ts 980this.pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => { 981 switch (event) { 982 case 'playbackStateChanged': 983 if (status === 0) { 984 // Stop the video. 985 } else if (status === 1) { 986 // Play the video. 987 } 988 break; 989 case 'nextVideo': 990 // Switch to the next video. 991 break; 992 case 'previousVideo': 993 // Switch to the previous video. 994 break; 995 case 'fastForward': 996 // Fast forward the video. 997 break; 998 case 'fastBackward': 999 // Rewind the video. 1000 break; 1001 default: 1002 break; 1003 } 1004 console.info('registerActionEventCallback, event:' + event); 1005}); 1006``` 1007 1008### on('controlEvent')<sup>12+</sup> 1009 1010on(type: 'controlEvent', callback: Callback<ControlEventParam>): void 1011 1012Subscribes to PiP action events. To avoid potential memory leaks, you are advised to stop listening when it is no longer needed. 1013 1014**Atomic service API**: This API can be used in atomic services since API version 12. 1015 1016**System capability**: SystemCapability.Window.SessionManager 1017 1018**Parameters** 1019 1020| Name | Type | Mandatory | Description | 1021|----------|-----------------------------------------------------|-------|----------------------------------------| 1022| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event.| 1023| callback | Callback<[ControlEventParam](#controleventparam12)> | Yes | Action event callback of the PiP controller. | 1024 1025**Example** 1026 1027```ts 1028this.pipController.on('controlEvent', (control) => { 1029 switch (control.controlType) { 1030 case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE: 1031 if (control.status === PiPWindow.PiPControlStatus.PAUSE) { 1032 // Stop the video. 1033 } else if (control.status === PiPWindow.PiPControlStatus.PLAY) { 1034 // Play the video. 1035 } 1036 break; 1037 case PiPWindow.PiPControlType.VIDEO_NEXT: 1038 // Switch to the next video. 1039 break; 1040 case PiPWindow.PiPControlType.VIDEO_PREVIOUS: 1041 // Switch to the previous video. 1042 break; 1043 case PiPWindow.PiPControlType.FAST_FORWARD: 1044 // Fast forward the video. 1045 break; 1046 case PiPWindow.PiPControlType.FAST_BACKWARD: 1047 // Rewind the video. 1048 break; 1049 default: 1050 break; 1051 } 1052 console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status); 1053}); 1054``` 1055 1056### off('controlPanelActionEvent') 1057 1058off(type: 'controlPanelActionEvent'): void 1059 1060Unsubscribes from PiP action events. The **[off('controlEvent')](#offcontrolevent12)** API is preferred. 1061 1062**Atomic service API**: This API can be used in atomic services since API version 12. 1063 1064**System capability**: SystemCapability.Window.SessionManager 1065 1066**Parameters** 1067 1068| Name | Type | Mandatory | Description | 1069|------------|------------------------------|------|-----------------------------------------------| 1070| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event. | 1071 1072**Example** 1073 1074```ts 1075this.pipController.off('controlPanelActionEvent'); 1076``` 1077 1078### off('controlEvent')<sup>12+</sup> 1079 1080off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void 1081 1082Unsubscribes from PiP action events. 1083 1084**Atomic service API**: This API can be used in atomic services since API version 12. 1085 1086**System capability**: SystemCapability.Window.SessionManager 1087 1088**Parameters** 1089 1090| Name | Type | Mandatory| Description | 1091|------------|-----------------------------------------------------|----|--------------------------------------------------------| 1092| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event. | 1093| callback | Callback<[ControlEventParam](#controleventparam12)> | No | Action event callback of the PiP controller. If no value is passed in, all subscriptions to the specified event are canceled.| 1094 1095**Example** 1096 1097```ts 1098this.pipController.off('controlEvent', () => {}); 1099``` 1100 1101### on('pipWindowSizeChange')<sup>15+</sup> 1102 1103on(type: 'pipWindowSizeChange', callback: Callback<PiPWindowSize>): void 1104 1105Subscribes to PiP window size change events. To avoid potential memory leaks, you are advised to stop listening when it is no longer needed. 1106 1107**Atomic service API**: This API can be used in atomic services since API version 15. 1108 1109**System capability**: SystemCapability.Window.SessionManager 1110 1111**Parameters** 1112 1113| Name | Type | Mandatory | Description | 1114|----------|---------------------------------------------|-------|---------------------------------------------------| 1115| type | string | Yes | Event type. The value is fixed at **'pipWindowSizeChange'**, indicating the PiP window size change event.| 1116| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | Yes | Callback used to return the size of the current PiP window.| 1117 1118**Error codes** 1119 1120For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1121 1122| ID| Error Message| 1123| ------- | -------------------------------------------- | 1124| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1125| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1126| 1300014 | PiP internal error. | 1127 1128**Example** 1129 1130```ts 1131try { 1132 this.pipController.on('pipWindowSizeChange', (size: PiPWindow.PiPWindowSize) => { 1133 console.info('Succeeded in enabling the listener for pip window size changes. size: ' + JSON.stringify(size)); 1134 }); 1135} catch (exception) { 1136 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1137} 1138``` 1139 1140### off('pipWindowSizeChange')<sup>15+</sup> 1141 1142off(type: 'pipWindowSizeChange', callback?: Callback<PiPWindowSize>): void 1143 1144Unsubscribes from the PiP window size change event. 1145 1146**Atomic service API**: This API can be used in atomic services since API version 15. 1147 1148**System capability**: SystemCapability.Window.SessionManager 1149 1150**Parameters** 1151 1152| Name | Type | Mandatory| Description | 1153|----------|------------|----|---------------------------------------------------------------------| 1154| type | string | Yes | Event type. The value is fixed at **'pipWindowSizeChange'**, indicating the PiP window size change event. | 1155| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | No | Callback used to return the size of the current PiP window. 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.| 1156 1157**Error codes** 1158 1159For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1160 1161| ID| Error Message| 1162| ------- | -------------------------------------------- | 1163| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1164| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1165 1166**Example** 1167 1168```ts 1169const callback = (size: PiPWindow.PiPWindowSize) => { 1170 // ... 1171} 1172try { 1173 // Enable listening through the on API. 1174 this.pipController.on('pipWindowSizeChange', callback); 1175} catch (exception) { 1176 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1177} 1178 1179try { 1180 // Disable the listening of a specified callback. 1181 this.pipController.off('pipWindowSizeChange', callback); 1182 // Unregister all the callbacks that have been registered through on(). 1183 this.pipController.off('pipWindowSizeChange'); 1184} catch (exception) { 1185 console.error(`Failed to disable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1186} 1187``` 1188