1# @ohos.PiPWindow (PiP Window) 2 3The **PiPWindow** module provides basic APIs for manipulating Picture in Picture (PiP). For example, you can use the APIs to check whether the PiP feature is enabled and create a PiP controller to start or stop a PiP window. PiP is mainly used in video playback, video call, or video meeting scenarios. 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> This module must be used on the device that supports the **SystemCapability.Window.SessionManager** capability.<!--RP1--> For details, see [SystemCapability](../syscap.md).<!--RP1End--> 10 11## Modules to Import 12 13```ts 14import { PiPWindow } from '@kit.ArkUI'; 15``` 16 17## PiPWindow.isPiPEnabled 18 19isPiPEnabled(): boolean 20 21Checks whether the PiP feature is enabled. 22 23**Atomic service API**: This API can be used in atomic services since API version 12. 24 25**System capability**: SystemCapability.Window.SessionManager 26 27**Return value** 28 29| Type | Description | 30|----------|-------------------------------------| 31| boolean | Status of the PiP feature. The value **true** means that the PiP feature is enabled, and **false** means the opposite.| 32 33**Example** 34 35```ts 36let enable: boolean = PiPWindow.isPiPEnabled(); 37console.info('isPipEnabled:' + enable); 38``` 39 40## PiPWindow.create 41 42create(config: PiPConfiguration): Promise<PiPController> 43 44Creates a PiP controller. This API uses a promise to return the result. 45 46**Atomic service API**: This API can be used in atomic services since API version 12. 47 48**System capability**: SystemCapability.Window.SessionManager 49 50**Parameters** 51 52| Name | Type | Mandatory | Description | 53|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 54| 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).| 55 56**Return value** 57 58| Type | Description | 59|------------------------------------------------------------|--------------------------| 60| Promise<[PiPController](#pipcontroller)> | Promise used to return the PiP controller.| 61 62**Error codes** 63 64For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 65 66| ID| Error Message | 67|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 68| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 69| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 70 71**Example** 72 73```ts 74import { BusinessError } from '@kit.BasicServicesKit'; 75import { BuilderNode, FrameNode, NodeController, Size, UIContext } from '@kit.ArkUI'; 76 77class Params { 78 text: string = ''; 79 constructor(text: string) { 80 this.text = text; 81 } 82} 83 84// You can use the @Builder decorator to construct layouts. 85@Builder 86function buildText(params: Params) { 87 Column() { 88 Text(params.text) 89 .fontSize(20) 90 .fontColor(Color.Red) 91 } 92 .width('100%') // The PiP window is displayed at full size in the width direction. 93 .height('100%') // The PiP window is displayed at full size in the height direction. 94} 95 96// You can extend NodeController to customize the UI controller. 97class TextNodeController extends NodeController { 98 private message: string; 99 private textNode: BuilderNode<[Params]> | null = null; 100 constructor(message: string) { 101 super(); 102 this.message = message; 103 } 104 105 // Use BuilderNode to load the custom layouts. 106 makeNode(context: UIContext): FrameNode | null { 107 this.textNode = new BuilderNode(context); 108 this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message)); 109 return this.textNode.getFrameNode(); 110 } 111 112 // You can customize this method to update layouts. 113 update(message: string) { 114 console.log(`update message: ${message}`); 115 if (this.textNode !== null) { 116 this.textNode.update(new Params(message)); 117 } 118 } 119} 120 121let pipController: PiPWindow.PiPController | undefined = undefined; 122let 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. 123let nodeController: TextNodeController = new TextNodeController('this is custom UI'); 124let 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. 125let contentWidth: number = 800; // The content width is 800 px. 126let contentHeight: number = 600; // The content height is 600 px. 127let config: PiPWindow.PiPConfiguration = { 128 context: getContext(this), 129 componentController: mXComponentController, 130 navigationId: navId, 131 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 132 contentWidth: contentWidth, 133 contentHeight: contentHeight, 134 controlGroups: [PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT], 135 customUIController: nodeController, // Optional. Set this parameter if you want to display the custom UI at the top of the PiP window. 136}; 137 138let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config); 139promise.then((data : PiPWindow.PiPController) => { 140 pipController = data; 141 console.info(`Succeeded in creating pip controller. Data:${data}`); 142}).catch((err: BusinessError) => { 143 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 144}); 145``` 146 147## PiPWindow.create<sup>12+</sup> 148 149create(config: PiPConfiguration, contentNode: typeNode.XComponent): Promise<PiPController> 150 151Creates a PiP controller through a type node. This API uses a promise to return the result. 152 153**Atomic service API**: This API can be used in atomic services since API version 12. 154 155**System capability**: SystemCapability.Window.SessionManager 156 157**Parameters** 158 159| Name | Type | Mandatory | Description | 160|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 161| 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).| 162| contentNode | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12) | Yes | Content to be rendered in the PiP window. The parameter value cannot be empty. | 163 164**Return value** 165 166| Type | Description | 167|------------------------------------------------------------|--------------------------| 168| Promise<[PiPController](#pipcontroller)> | Promise used to return the PiP controller.| 169 170**Error codes** 171 172For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 173 174| ID| Error Message | 175|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 176| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 177| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 178 179**Example** 180 181```ts 182import { BusinessError } from '@kit.BasicServicesKit'; 183import { PiPWindow } from '@kit.ArkUI'; 184import { typeNode } from '@ohos.arkui.node'; 185 186let pipController: PiPWindow.PiPController | undefined = undefined; 187let xComponentController: XComponentController = new XComponentController(); 188let xComponent = typeNode.createNode(this.getUIContext(), "XComponent"); 189xComponent.initialize({ 190 id:'xcomponent', 191 type:XComponentType.SURFACE, 192 controller:xComponentController 193}); 194let contentWidth: number = 800; // The content width is 800 px. 195let contentHeight: number = 600; // The content height is 600 px. 196let config: PiPWindow.PiPConfiguration = { 197 context: getContext(this), 198 componentController: xComponentController, 199 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 200 contentWidth: contentWidth, 201 contentHeight: contentHeight 202}; 203 204let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config, xComponent); 205promise.then((data : PiPWindow.PiPController) => { 206 pipController = data; 207 console.info(`Succeeded in creating pip controller. Data:${data}`); 208}).catch((err: BusinessError) => { 209 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 210}); 211``` 212 213## PiPConfiguration 214 215Defines the parameters for creating a PiP controller. 216 217**Atomic service API**: This API can be used in atomic services since API version 12. 218 219**System capability**: SystemCapability.Window.SessionManager 220 221| Name | Type | Mandatory | Description | 222|---------------------|----------------------------------------------------------------------------|-----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 223| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Context environment. | 224| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md) | Yes | Original [XComponent](arkui-ts/ts-basic-components-xcomponent.md) controller. | 225| navigationId | string | No | Navigation ID of the current page.<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.| 226| templateType | [PiPTemplateType](#piptemplatetype) | No | Template type, which is used to distinguish video playback, video call, and video meeting scenarios. | 227| 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). | 228| contentHeight | number | No | Height of the original content, in px. It is used to determine the aspect ratio of the PiP window. 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). | 229| 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. | 230| customUIController<sup>12+</sup> | [NodeController](js-apis-arkui-nodeController.md) | No | Custom UI that can be displayed at the top of the PiP window. | 231 232## PiPTemplateType 233 234Enumerates the PIP template types. 235 236**Atomic service API**: This API can be used in atomic services since API version 12. 237 238**System capability**: SystemCapability.Window.SessionManager 239 240| Name | Value | Description | 241|---------------|-----|--------------------------------------| 242| VIDEO_PLAY | 0 | Video playback template. A PiP window will be started during video playback, and the video playback template is loaded. | 243| VIDEO_CALL | 1 | Video call template. A PiP window will be started during a video call, and the video call template will be loaded.| 244| VIDEO_MEETING | 2 | Video meeting template. A PiP window will be started during a video meeting, and the video meeting template will be loaded.| 245| VIDEO_LIVE | 3 | Live template. A PiP window will be started during a live, and the live template is loaded. | 246 247## PiPState 248 249Enumerates the PiP states. 250 251**Atomic service API**: This API can be used in atomic services since API version 12. 252 253**System capability**: SystemCapability.Window.SessionManager 254 255| Name | Value | Description | 256|----------------------|-----|-----------------------| 257| ABOUT_TO_START | 1 | PiP is about to start. | 258| STARTED | 2 | PiP is started. | 259| ABOUT_TO_STOP | 3 | PiP is about to stop. | 260| STOPPED | 4 | PiP is stopped. | 261| ABOUT_TO_RESTORE | 5 | The original page is about to restore.| 262| ERROR | 6 | An error occurs during the execution of the PiP lifecycle. | 263 264## PiPControlGroup<sup>12+</sup> 265 266type PiPControlGroup = VideoPlayControlGroup | VideoCallControlGroup | VideoMeetingControlGroup | VideoLiveControlGroup 267 268Describes 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). 269 270**Atomic service API**: This API can be used in atomic services since API version 12. 271 272**System capability**: SystemCapability.Window.SessionManager 273 274| Type | Description | 275|-------------------------------------------------|-------------| 276| [VideoPlayControlGroup](#videoplaycontrolgroup12) | Video playback component group.| 277| [VideoCallControlGroup](#videocallcontrolgroup12) | Video call component group.| 278| [VideoMeetingControlGroup](#videomeetingcontrolgroup12) | Video meeting component group.| 279| [VideoLiveControlGroup](#videolivecontrolgroup12) | Live video component group.| 280 281 282## VideoPlayControlGroup<sup>12+</sup> 283 284Enumerates the video playback component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_PLAY**. 285 286**Atomic service API**: This API can be used in atomic services since API version 12. 287 288**System capability**: SystemCapability.Window.SessionManager 289 290| Name | Value | Description | 291|----------------------|-----|-----------------------| 292| 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. | 293| 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 control component group is added. | 294 295## VideoCallControlGroup<sup>12+</sup> 296 297Enumerates the video call component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_CALL**. 298 299**Atomic service API**: This API can be used in atomic services since API version 12. 300 301**System capability**: SystemCapability.Window.SessionManager 302 303| Name | Value | Description | 304|----------------------|-----|-----------------------| 305| MICROPHONE_SWITCH | 201 | Microphone on/off component group. | 306| HANG_UP_BUTTON | 202 | Hang-up component group. | 307| CAMERA_SWITCH | 203 | Camera on/off component group. | 308| MUTE_SWITCH | 204 | Mute/Unmute component group. | 309 310## VideoMeetingControlGroup<sup>12+</sup> 311 312Enumerates the video meeting component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_MEETING**. 313 314**Atomic service API**: This API can be used in atomic services since API version 12. 315 316**System capability**: SystemCapability.Window.SessionManager 317 318| Name | Value | Description | 319|----------------------|-----|-----------------------| 320| HANG_UP_BUTTON | 301 | Hang-up component group. | 321| CAMERA_SWITCH | 302 | Camera on/off component group. | 322| MUTE_SWITCH | 303 | Mute/Unmute component group. | 323| MICROPHONE_SWITCH | 304 | Microphone on/off component group. | 324 325## VideoLiveControlGroup<sup>12+</sup> 326 327Enumerates the live video component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_LIVE**. 328 329**Atomic service API**: This API can be used in atomic services since API version 12. 330 331**System capability**: SystemCapability.Window.SessionManager 332 333| Name | Value | Description | 334|----------------------|-----|-----------------------| 335| VIDEO_PLAY_PAUSE | 401 | Play/Pause component group for live video. | 336| MUTE_SWITCH | 402 | Mute/Unmute component group. | 337 338## PiPActionEventType 339 340type PiPActionEventType = PiPVideoActionEvent | PiPCallActionEvent | PiPMeetingActionEvent | PiPLiveActionEvent 341 342Enumerates the types of action events of the PiP controller. 343 344**Atomic service API**: This API can be used in atomic services since API version 12. 345 346**System capability**: SystemCapability.Window.SessionManager 347 348| Type | Description | 349|-------------------------------------------------|-------------| 350| [PiPVideoActionEvent](#pipvideoactionevent) | Action event for components displayed on the video playback controller.| 351| [PiPCallActionEvent](#pipcallactionevent) | Action event for components displayed on the video call controller.| 352| [PiPMeetingActionEvent](#pipmeetingactionevent) | Action event for components displayed on the video meeting controller.| 353| [PiPLiveActionEvent](#pipliveactionevent) | Action event for components displayed on the live video controller. | 354 355## PiPVideoActionEvent 356 357type PiPVideoActionEvent = 'playbackStateChanged' | 'nextVideo' | 'previousVideo' | 'fastForward' | 'fastBackward' 358 359Defines the PiP action event during video playback. 360 361**Atomic service API**: This API can be used in atomic services since API version 12. 362 363**System capability**: SystemCapability.Window.SessionManager 364 365| Type | Description | 366| ---------------------------- | ----------------------------------------- | 367| 'playbackStateChanged' | The playback status changes. | 368| 'nextVideo' | Plays the next video. | 369| 'previousVideo' | Plays the previous video. | 370| 'fastForward'<sup>12+</sup> | Fast forwards the video. This value is supported since API version 12.| 371| 'fastBackward'<sup>12+</sup> | Rewinds the video. This value is supported since API version 12.| 372 373## PiPCallActionEvent 374 375type PiPCallActionEvent = 'hangUp' | 'micStateChanged' | 'videoStateChanged' | 'voiceStateChanged' 376 377Defines the PiP action event in a video call. 378 379**Atomic service API**: This API can be used in atomic services since API version 12. 380 381**System capability**: SystemCapability.Window.SessionManager 382 383| Type | Description | 384| ------------------- | ------------------ | 385| 'hangUp' | The video call is hung up. | 386| 'micStateChanged' | The microphone is muted or unmuted.| 387| 'videoStateChanged' | The camera is turned on or off.| 388| 'voiceStateChanged'<sup>12+</sup> | The speaker is muted or unmuted. | 389 390 391## PiPMeetingActionEvent 392 393type PiPMeetingActionEvent = 'hangUp' | 'voiceStateChanged' | 'videoStateChanged' | 'micStateChanged' 394 395Defines the PiP action event in a video meeting. 396 397**Atomic service API**: This API can be used in atomic services since API version 12. 398 399**System capability**: SystemCapability.Window.SessionManager 400 401| Type | Description | 402| ------------------- | ------------------ | 403| 'hangUp' | The video meeting is hung up. | 404| 'voiceStateChanged' | The speaker is muted or unmuted. | 405| 'videoStateChanged' | The camera is turned on or off.| 406| 'micStateChanged'<sup>12+</sup> | The microphone is muted or unmuted.| 407 408 409## PiPLiveActionEvent 410 411type PiPLiveActionEvent = 'playbackStateChanged' | 'voiceStateChanged' 412 413Defines the PiP action event in a live. 414 415**Atomic service API**: This API can be used in atomic services since API version 12. 416 417**System capability**: SystemCapability.Window.SessionManager 418 419| Type | Description | 420| ---------------------- | ---------------- | 421| 'playbackStateChanged' | The live is played or paused.| 422| 'voiceStateChanged'<sup>12+</sup> | The speaker is muted or unmuted. | 423 424 425## PiPControlStatus<sup>12+</sup> 426 427Enumerates the statuses of components displayed on the PiP controller. 428 429**Atomic service API**: This API can be used in atomic services since API version 12. 430 431**System capability**: SystemCapability.Window.SessionManager 432 433| Name | Value | Description | 434|----------------------|-----|-----------------------| 435| PLAY | 1 | Play. | 436| PAUSE | 0 | Pause. | 437| OPEN | 1 | Open. | 438| CLOSE | 0 | Close. | 439 440## PiPControlType<sup>12+</sup> 441 442Enumerates the types of components displayed on the PiP controller. 443 444**Atomic service API**: This API can be used in atomic services since API version 12. 445 446**System capability**: SystemCapability.Window.SessionManager 447 448| Name | Value | Description | 449|-------------------|-----|--------------------------------------| 450| VIDEO_PLAY_PAUSE | 0 | Play/Pause component. | 451| VIDEO_PREVIOUS | 1 | Previous component in video scenarios.| 452| VIDEO_NEXT | 2 | Next component in video scenarios.| 453| FAST_FORWARD | 3 | Fast-forward component in video scenarios. | 454| FAST_BACKWARD | 4 | Rewind component in video scenarios. | 455| HANG_UP_BUTTON | 5 | Hang-up component.| 456| MICROPHONE_SWITCH | 6 | Microphone on/off component.| 457| CAMERA_SWITCH | 7 | Camera on/off component. | 458| MUTE_SWITCH | 8 | Mute/Unmute component. | 459 460 461## ControlPanelActionEventCallback<sup>12+</sup> 462 463type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void 464 465Describes the action event callback of the PiP controller. 466 467**Atomic service API**: This API can be used in atomic services since API version 12. 468 469**System capability**: SystemCapability.Window.SessionManager 470 471**Parameters** 472 473| Name | Type | Mandatory | Description | 474|--------------------------|--------------|--------------|-----------------------------------| 475| 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.| 476| 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.| 477 478## ControlEventParam<sup>12+</sup> 479 480Describes the parameters in the callback of the action event of the PiP controller. 481 482**Atomic service API**: This API can be used in atomic services since API version 12. 483 484**System capability**: SystemCapability.Window.SessionManager 485 486| Name | Type | Mandatory | Description | 487|--------------------------|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------| 488| 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. | 489| 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**.| 490 491## PiPController 492 493Implements a PiP controller that starts, stops, or updates a PiP window and registers callbacks. 494 495Before calling any of the following APIs, you must use [PiPWindow.create()](#pipwindowcreate) to create a **PiPController** instance. 496 497**System capability**: SystemCapability.Window.SessionManager 498 499### startPiP 500 501startPiP(): Promise<void> 502 503Starts a PiP window. This API uses a promise to return the result. 504 505**Atomic service API**: This API can be used in atomic services since API version 12. 506 507**System capability**: SystemCapability.Window.SessionManager 508 509**Return value** 510 511| Type | Description | 512|------------------------|--------------------| 513| Promise<void> | Promise that returns no value. | 514 515**Error codes** 516 517For details about the error codes, see [Window Error Codes](errorcode-window.md). 518 519| ID | Error Message | 520|------------|--------------------------------------------------------| 521| 1300012 | The PiP window state is abnormal. | 522| 1300013 | Failed to create the PiP window. | 523| 1300014 | PiP internal error. | 524| 1300015 | Repeated PiP operation. | 525 526**Example** 527 528```ts 529let promise : Promise<void> = pipController.startPiP(); 530promise.then(() => { 531 console.info(`Succeeded in starting pip.`); 532}).catch((err: BusinessError) => { 533 console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`); 534}); 535``` 536 537### stopPiP 538 539stopPiP(): Promise<void> 540 541Stops a PiP window. This API uses a promise to return the result. 542 543**Atomic service API**: This API can be used in atomic services since API version 12. 544 545**System capability**: SystemCapability.Window.SessionManager 546 547**Return value** 548 549| Type | Description | 550|----------------------|---------------------| 551| Promise<void> | Promise that returns no value. | 552 553**Error codes** 554 555For details about the error codes, see [Window Error Codes](errorcode-window.md). 556 557| ID | Error Message | 558|---------|-----------------------------------| 559| 1300011 | Failed to destroy the PiP window. | 560| 1300012 | The PiP window state is abnormal. | 561| 1300015 | Repeated PiP operation. | 562 563**Example** 564 565```ts 566let promise : Promise<void> = pipController.stopPiP(); 567promise.then(() => { 568 console.info(`Succeeded in stopping pip.`); 569}).catch((err: BusinessError) => { 570 console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`); 571}); 572``` 573 574### setAutoStartEnabled 575 576setAutoStartEnabled(enable: boolean): void 577 578Sets whether to automatically start a PiP window when the user returns to the home screen. 579 580**Atomic service API**: This API can be used in atomic services since API version 12. 581 582**System capability**: SystemCapability.Window.SessionManager 583 584**Parameters** 585 586| Name | Type | Mandatory | Description | 587|----------|-----------|-------|---------------------------------| 588| enable | boolean | Yes | Whether to automatically start a PiP window when the user returns to the home screen. The value **true** means to automatically start a PiP window in such a case, and **false** means the opposite. 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**. | 589 590**Example** 591 592```ts 593let enable: boolean = true; 594pipController.setAutoStartEnabled(enable); 595``` 596 597### updateContentSize 598 599updateContentSize(width: number, height: number): void 600 601Updates the media content size when the media content is switched. 602 603**Atomic service API**: This API can be used in atomic services since API version 12. 604 605**System capability**: SystemCapability.Window.SessionManager 606 607**Parameters** 608 609| Name | Type | Mandatory | Description | 610|--------|--------|-----|----------------------------------------| 611| 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. | 612| 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. | 613 614**Error codes** 615 616For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 617 618| ID| Error Message | 619|-------|-------------------------------------------------------------------------------------------------------------| 620| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 621 622**Example** 623 624```ts 625let width: number = 540; // The content width changes to 540 px. 626let height: number = 960; // The content height changes to 960 px. 627pipController.updateContentSize(width, height); 628``` 629 630### updatePiPControlStatus<sup>12+</sup> 631updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void 632 633Updates the enabled status of a component displayed on the PiP controller. 634 635**Atomic service API**: This API can be used in atomic services since API version 12. 636 637**System capability**: SystemCapability.Window.SessionManager 638 639**Parameters** 640 641| Name | Type | Mandatory | Description | 642|--------|--------|-----|----------------------------------------------------------------------------------------------------| 643| 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.| 644| status | [PiPControlStatus](#pipcontrolstatus12) | Yes | Status of the component displayed on the PiP controller. | 645 646**Error codes** 647 648For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 649 650| ID| Error Message | 651|-------|-------------------------------------------------------------------------------------------------------------| 652| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 653 654**Example** 655 656```ts 657let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // Play/Pause component displayed on the video playback control panel. 658let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // The Play/Pause component displayed on the video playback control panel is in the playing state. 659pipController.updatePiPControlStatus(controlType, status); 660``` 661 662### setPiPControlEnabled<sup>12+</sup> 663setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void 664 665Sets the enabled status for a component displayed on the PiP controller. 666 667**Atomic service API**: This API can be used in atomic services since API version 12. 668 669**System capability**: SystemCapability.Window.SessionManager 670 671**Parameters** 672 673| Name | Type | Mandatory | Description | 674|-------------|--------|-----|----------------------------------------| 675| controlType | [PiPControlType](#pipcontroltype12) | Yes | Type of the component displayed on the PiP controller. | 676| enabled | boolean | Yes | Enabled status of the component displayed on the PiP controller. The value **true** means that the component is enabled, and **false** means the opposite. | 677 678**Error codes** 679 680For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 681 682| ID| Error Message | 683|-------|-------------------------------------------------------------------------------------------------------------| 684| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 685 686**Example** 687 688```ts 689let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // Play/Pause component displayed on the video playback control panel. 690let enabled: boolean = false; // The Play/Pause component displayed on the video playback control panel is in the disabled state. 691pipController.setPiPControlEnabled(controlType, enabled); 692``` 693 694### on('stateChange') 695 696on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 697 698Subscribes to PiP state events. 699 700**Atomic service API**: This API can be used in atomic services since API version 12. 701 702**System capability**: SystemCapability.Window.SessionManager 703 704**Parameters** 705 706| Name | Type | Mandatory | Description | 707|------------|-----------|------|---------------------------------------------------------------------------------------------------| 708| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 709| 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. | 710 711**Example** 712 713```ts 714pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => { 715 let curState: string = ''; 716 switch (state) { 717 case PiPWindow.PiPState.ABOUT_TO_START: 718 curState = 'ABOUT_TO_START'; 719 break; 720 case PiPWindow.PiPState.STARTED: 721 curState = 'STARTED'; 722 break; 723 case PiPWindow.PiPState.ABOUT_TO_STOP: 724 curState = 'ABOUT_TO_STOP'; 725 break; 726 case PiPWindow.PiPState.STOPPED: 727 curState = 'STOPPED'; 728 break; 729 case PiPWindow.PiPState.ABOUT_TO_RESTORE: 730 curState = 'ABOUT_TO_RESTORE'; 731 break; 732 case PiPWindow.PiPState.ERROR: 733 curState = 'ERROR'; 734 break; 735 default: 736 break; 737 } 738 console.info('stateChange:' + curState + ' reason:' + reason); 739}); 740``` 741 742### off('stateChange') 743 744off(type: 'stateChange'): void 745 746Unsubscribes from PiP state events. 747 748**Atomic service API**: This API can be used in atomic services since API version 12. 749 750**System capability**: SystemCapability.Window.SessionManager 751 752**Parameters** 753 754| Name | Type | Mandatory | Description | 755|-----------|---------------|-------|----------------------------------------| 756| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 757 758**Example** 759 760```ts 761pipController.off('stateChange'); 762``` 763 764### on('controlPanelActionEvent') 765 766on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void 767 768Subscribes to PiP action events. The [on('controlEvent')](#oncontrolevent12) API is preferred. 769 770**Atomic service API**: This API can be used in atomic services since API version 12. 771 772**System capability**: SystemCapability.Window.SessionManager 773 774**Parameters** 775 776| Name | Type | Mandatory | Description | 777|----------|------------|-------|---------------------------------------------------| 778| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event.| 779| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12) | Yes | Action event callback of the PiP controller. | 780 781**Example** 782 783```ts 784pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => { 785 switch (event) { 786 case 'playbackStateChanged': 787 if (status === 0) { 788 // Stop the video. 789 } else if (status === 1) { 790 // Play the video. 791 } 792 break; 793 case 'nextVideo': 794 // Switch to the next video. 795 break; 796 case 'previousVideo': 797 // Switch to the previous video. 798 break; 799 case 'fastForward': 800 // Fast forward the video. 801 break; 802 case 'fastBackward': 803 // Rewind the video. 804 break; 805 default: 806 break; 807 } 808 console.info('registerActionEventCallback, event:' + event); 809}); 810``` 811 812### on('controlEvent')<sup>12+</sup> 813 814on(type: 'controlEvent', callback: Callback<ControlEventParam>): void 815 816Subscribes to PiP action events. 817 818**Atomic service API**: This API can be used in atomic services since API version 12. 819 820**System capability**: SystemCapability.Window.SessionManager 821 822**Parameters** 823 824| Name | Type | Mandatory | Description | 825|----------|-----------------------------------------------------|-------|----------------------------------------| 826| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event.| 827| callback | Callback<[ControlEventParam](#controleventparam12)> | Yes | Action event callback of the PiP controller. | 828 829**Example** 830 831```ts 832pipController.on('controlEvent', (control) => { 833 switch (control.controlType) { 834 case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE: 835 if (control.status === PiPWindow.PiPControlStatus.PAUSE) { 836 // Stop the video. 837 } else if (control.status === PiPWindow.PiPControlStatus.PLAY) { 838 // Play the video. 839 } 840 break; 841 case PiPWindow.PiPControlType.VIDEO_NEXT: 842 // Switch to the next video. 843 break; 844 case PiPWindow.PiPControlType.VIDEO_PREVIOUS: 845 // Switch to the previous video. 846 break; 847 case PiPWindow.PiPControlType.FAST_FORWARD: 848 // Fast forward the video. 849 break; 850 case PiPWindow.PiPControlType.FAST_BACKWARD: 851 // Rewind the video. 852 break; 853 default: 854 break; 855 } 856 console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status); 857}); 858``` 859 860### off('controlPanelActionEvent') 861 862off(type: 'controlPanelActionEvent'): void 863 864Unsubscribes from PiP action events. The **[off('controlEvent')](#offcontrolevent12)** API is preferred. 865 866**Atomic service API**: This API can be used in atomic services since API version 12. 867 868**System capability**: SystemCapability.Window.SessionManager 869 870**Parameters** 871 872| Name | Type | Mandatory | Description | 873|------------|------------------------------|------|-----------------------------------------------| 874| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event. | 875 876**Example** 877 878```ts 879pipController.off('controlPanelActionEvent'); 880``` 881 882### off('controlEvent')<sup>12+</sup> 883 884off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void 885 886Unsubscribes from PiP action events. 887 888**Atomic service API**: This API can be used in atomic services since API version 12. 889 890**System capability**: SystemCapability.Window.SessionManager 891 892**Parameters** 893 894| Name | Type | Mandatory| Description | 895|------------|-----------------------------------------------------|----|--------------------------------------------------------| 896| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event. | 897| 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.| 898 899**Example** 900 901```ts 902pipController.off('controlEvent', () => {}); 903``` 904