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 supported. 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 supported, 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, UIContext } from '@kit.ArkUI'; 184import { typeNode } from '@ohos.arkui.node'; 185 186let pipController: PiPWindow.PiPController | undefined = undefined; 187let xComponentController: XComponentController = new XComponentController(); 188let context: UIContext | undefined = undefined; // You can pass UIContext or use this.getUIContext() in the layout to assign a valid value to context. 189let xComponent = typeNode.createNode(context, 'XComponent'); 190xComponent.initialize({ 191 id:'xcomponent', 192 type:XComponentType.SURFACE, 193 controller:xComponentController 194}); 195let contentWidth: number = 800; // The content width is 800 px. 196let contentHeight: number = 600; // The content height is 600 px. 197let config: PiPWindow.PiPConfiguration = { 198 context: getContext(this), 199 componentController: xComponentController, 200 templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, 201 contentWidth: contentWidth, 202 contentHeight: contentHeight 203}; 204 205let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config, xComponent); 206promise.then((data : PiPWindow.PiPController) => { 207 pipController = data; 208 console.info(`Succeeded in creating pip controller. Data:${data}`); 209}).catch((err: BusinessError) => { 210 console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`); 211}); 212``` 213 214## PiPConfiguration 215 216Defines the parameters for creating a PiP controller. 217 218**Atomic service API**: This API can be used in atomic services since API version 12. 219 220**System capability**: SystemCapability.Window.SessionManager 221 222| Name | Type | Mandatory | Description | 223|---------------------|----------------------------------------------------------------------------|-----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 224| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | Yes | Context environment. | 225| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md#xcomponentcontroller) | Yes | Original [XComponent](arkui-ts/ts-basic-components-xcomponent.md) controller. | 226| 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.| 227| templateType | [PiPTemplateType](#piptemplatetype) | No | Template type, which is used to distinguish video playback, video call, and video meeting scenarios. | 228| 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). | 229| 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). | 230| 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. | 231| customUIController<sup>12+</sup> | [NodeController](js-apis-arkui-nodeController.md) | No | Custom UI that can be displayed at the top of the PiP window. | 232 233## PiPWindowSize<sup>15+</sup> 234 235Describes the size of a PiP window. 236 237**Atomic service API**: This API can be used in atomic services since API version 15. 238 239**System capability**: SystemCapability.Window.SessionManager 240 241| Name | Type| Readable| Writable| Description | 242| ------ | -------- | ---- | ---- | ---------- | 243| width | number | Yes | No | Window width, in px. The value must be a positive integer and cannot be greater than the screen width.| 244| height | number | Yes | No | Window height, in px. The value must be a positive integer and cannot be greater than the screen height.| 245| 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 ranging from 0.0 to 1.0. The value **1** means that the window matches the specified width and height.| 246 247## PiPWindowInfo<sup>15+</sup> 248 249Describes the PiP window information. 250 251**Atomic service API**: This API can be used in atomic services since API version 15. 252 253**System capability**: SystemCapability.Window.SessionManager 254 255| Name | Type| Readable| Writable| Description | 256| ------ | -------- | ---- | ---- | ---------- | 257| windowId | number | Yes | No | ID of the PiP window.| 258| size | [PiPWindowSize](#pipwindowsize15) | Yes | No | Size of the PiP window.| 259 260## PiPTemplateType 261 262Enumerates the PIP template types. 263 264**Atomic service API**: This API can be used in atomic services since API version 12. 265 266**System capability**: SystemCapability.Window.SessionManager 267 268| Name | Value | Description | 269|---------------|-----|--------------------------------------| 270| VIDEO_PLAY | 0 | Video playback template. A PiP window will be started during video playback, and the video playback template is loaded. | 271| VIDEO_CALL | 1 | Video call template. A PiP window will be started during a video call, and the video call template will be loaded.| 272| VIDEO_MEETING | 2 | Video meeting template. A PiP window will be started during a video meeting, and the video meeting template will be loaded.| 273| VIDEO_LIVE | 3 | Live template. A PiP window will be started during a live, and the live template is loaded. | 274 275## PiPState 276 277Enumerates the PiP states. 278 279**Atomic service API**: This API can be used in atomic services since API version 12. 280 281**System capability**: SystemCapability.Window.SessionManager 282 283| Name | Value | Description | 284|----------------------|-----|-----------------------| 285| ABOUT_TO_START | 1 | PiP is about to start. | 286| STARTED | 2 | PiP is started. | 287| ABOUT_TO_STOP | 3 | PiP is about to stop. | 288| STOPPED | 4 | PiP is stopped. | 289| ABOUT_TO_RESTORE | 5 | The original page is about to restore.| 290| ERROR | 6 | An error occurs during the execution of the PiP lifecycle. | 291 292## PiPControlGroup<sup>12+</sup> 293 294type PiPControlGroup = VideoPlayControlGroup | VideoCallControlGroup | VideoMeetingControlGroup | VideoLiveControlGroup 295 296Describes 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). 297 298**Atomic service API**: This API can be used in atomic services since API version 12. 299 300**System capability**: SystemCapability.Window.SessionManager 301 302| Type | Description | 303|-------------------------------------------------|-------------| 304| [VideoPlayControlGroup](#videoplaycontrolgroup12) | Video playback component group.| 305| [VideoCallControlGroup](#videocallcontrolgroup12) | Video call component group.| 306| [VideoMeetingControlGroup](#videomeetingcontrolgroup12) | Video meeting component group.| 307| [VideoLiveControlGroup](#videolivecontrolgroup12) | Live video component group.| 308 309 310## VideoPlayControlGroup<sup>12+</sup> 311 312Enumerates the video playback component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_PLAY**. 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| 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. | 321| 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. | 322 323## VideoCallControlGroup<sup>12+</sup> 324 325Enumerates the video call component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_CALL**. 326 327**Atomic service API**: This API can be used in atomic services since API version 12. 328 329**System capability**: SystemCapability.Window.SessionManager 330 331| Name | Value | Description | 332|----------------------|-----|-----------------------| 333| MICROPHONE_SWITCH | 201 | Microphone on/off component group. | 334| HANG_UP_BUTTON | 202 | Hang-up component group. | 335| CAMERA_SWITCH | 203 | Camera on/off component group. | 336| MUTE_SWITCH | 204 | Mute/Unmute component group. | 337 338## VideoMeetingControlGroup<sup>12+</sup> 339 340Enumerates the video meeting component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_MEETING**. 341 342**Atomic service API**: This API can be used in atomic services since API version 12. 343 344**System capability**: SystemCapability.Window.SessionManager 345 346| Name | Value | Description | 347|----------------------|-----|-----------------------| 348| HANG_UP_BUTTON | 301 | Hang-up component group. | 349| CAMERA_SWITCH | 302 | Camera on/off component group. | 350| MUTE_SWITCH | 303 | Mute/Unmute component group. | 351| MICROPHONE_SWITCH | 304 | Microphone on/off component group. | 352 353## VideoLiveControlGroup<sup>12+</sup> 354 355Enumerates the live video component groups. They are used only when [PiPTemplateType](#piptemplatetype) is set to **VIDEO_LIVE**. 356 357**Atomic service API**: This API can be used in atomic services since API version 12. 358 359**System capability**: SystemCapability.Window.SessionManager 360 361| Name | Value | Description | 362|----------------------|-----|-----------------------| 363| VIDEO_PLAY_PAUSE | 401 | Play/Pause component group for live video.| 364| MUTE_SWITCH | 402 | Mute/Unmute component group. | 365 366## PiPActionEventType 367 368type PiPActionEventType = PiPVideoActionEvent | PiPCallActionEvent | PiPMeetingActionEvent | PiPLiveActionEvent 369 370Enumerates the types of action events of the PiP controller. 371 372**Atomic service API**: This API can be used in atomic services since API version 12. 373 374**System capability**: SystemCapability.Window.SessionManager 375 376| Type | Description | 377|-------------------------------------------------|-------------| 378| [PiPVideoActionEvent](#pipvideoactionevent) | Action event for components displayed on the video playback controller.| 379| [PiPCallActionEvent](#pipcallactionevent) | Action event for components displayed on the video call controller.| 380| [PiPMeetingActionEvent](#pipmeetingactionevent) | Action event for components displayed on the video meeting controller.| 381| [PiPLiveActionEvent](#pipliveactionevent) | Action event for components displayed on the live video controller. | 382 383## PiPVideoActionEvent 384 385type PiPVideoActionEvent = 'playbackStateChanged' | 'nextVideo' | 'previousVideo' | 'fastForward' | 'fastBackward' 386 387Defines the PiP action event during video playback. 388 389**Atomic service API**: This API can be used in atomic services since API version 12. 390 391**System capability**: SystemCapability.Window.SessionManager 392 393| Type | Description | 394| ---------------------------- | ----------------------------------------- | 395| 'playbackStateChanged' | The playback status changes. | 396| 'nextVideo' | Plays the next video. | 397| 'previousVideo' | Plays the previous video. | 398| 'fastForward'<sup>12+</sup> | Fast forwards the video. This value is supported since API version 12.| 399| 'fastBackward'<sup>12+</sup> | Rewinds the video. This value is supported since API version 12.| 400 401## PiPCallActionEvent 402 403type PiPCallActionEvent = 'hangUp' | 'micStateChanged' | 'videoStateChanged' | 'voiceStateChanged' 404 405Defines the PiP action event in a video call. 406 407**Atomic service API**: This API can be used in atomic services since API version 12. 408 409**System capability**: SystemCapability.Window.SessionManager 410 411| Type | Description | 412| ------------------- | ------------------ | 413| 'hangUp' | The video call is hung up. | 414| 'micStateChanged' | The microphone is muted or unmuted.| 415| 'videoStateChanged' | The camera is turned on or off.| 416| 'voiceStateChanged'<sup>12+</sup> | The speaker is muted or unmuted. | 417 418 419## PiPMeetingActionEvent 420 421type PiPMeetingActionEvent = 'hangUp' | 'voiceStateChanged' | 'videoStateChanged' | 'micStateChanged' 422 423Defines the PiP action event in a video meeting. 424 425**Atomic service API**: This API can be used in atomic services since API version 12. 426 427**System capability**: SystemCapability.Window.SessionManager 428 429| Type | Description | 430| ------------------- | ------------------ | 431| 'hangUp' | The video meeting is hung up. | 432| 'voiceStateChanged' | The speaker is muted or unmuted. | 433| 'videoStateChanged' | The camera is turned on or off.| 434| 'micStateChanged'<sup>12+</sup> | The microphone is muted or unmuted.| 435 436 437## PiPLiveActionEvent 438 439type PiPLiveActionEvent = 'playbackStateChanged' | 'voiceStateChanged' 440 441Defines the PiP action event in a live. 442 443**Atomic service API**: This API can be used in atomic services since API version 12. 444 445**System capability**: SystemCapability.Window.SessionManager 446 447| Type | Description | 448| ---------------------- | ---------------- | 449| 'playbackStateChanged' | The live is played or paused.| 450| 'voiceStateChanged'<sup>12+</sup> | The speaker is muted or unmuted. | 451 452 453## PiPControlStatus<sup>12+</sup> 454 455Enumerates the statuses of components displayed on the PiP controller. 456 457**Atomic service API**: This API can be used in atomic services since API version 12. 458 459**System capability**: SystemCapability.Window.SessionManager 460 461| Name | Value | Description | 462|----------------------|-----|-----------------------| 463| PLAY | 1 | Play. | 464| PAUSE | 0 | Pause. | 465| OPEN | 1 | Open. | 466| CLOSE | 0 | Close. | 467 468## PiPControlType<sup>12+</sup> 469 470Enumerates the types of components displayed on the PiP controller. 471 472**Atomic service API**: This API can be used in atomic services since API version 12. 473 474**System capability**: SystemCapability.Window.SessionManager 475 476| Name | Value | Description | 477|-------------------|-----|--------------------------------------| 478| VIDEO_PLAY_PAUSE | 0 | Play/Pause component. | 479| VIDEO_PREVIOUS | 1 | Previous component in video scenarios.| 480| VIDEO_NEXT | 2 | Next component in video scenarios.| 481| FAST_FORWARD | 3 | Fast-forward component in video scenarios. | 482| FAST_BACKWARD | 4 | Rewind component in video scenarios. | 483| HANG_UP_BUTTON | 5 | Hang-up component.| 484| MICROPHONE_SWITCH | 6 | Microphone on/off component.| 485| CAMERA_SWITCH | 7 | Camera on/off component. | 486| MUTE_SWITCH | 8 | Mute/Unmute component. | 487 488 489## ControlPanelActionEventCallback<sup>12+</sup> 490 491type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void 492 493Describes the action event callback of 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**Parameters** 500 501| Name | Type | Mandatory | Description | 502|--------------------------|--------------|--------------|-----------------------------------| 503| 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.| 504| 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.| 505 506## ControlEventParam<sup>12+</sup> 507 508Describes the parameters in the callback of the action event of 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 | Type | Mandatory | Description | 515|--------------------------|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------| 516| 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. | 517| 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**.| 518 519## PiPController 520 521Implements a PiP controller that starts, stops, or updates a PiP window and registers callbacks. 522 523Before calling any of the following APIs, you must use [PiPWindow.create()](#pipwindowcreate) to create a **PiPController** instance. 524 525**System capability**: SystemCapability.Window.SessionManager 526 527### startPiP 528 529startPiP(): Promise<void> 530 531Starts a PiP window. This API uses a promise to return the result. 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**Return value** 538 539| Type | Description | 540|------------------------|--------------------| 541| Promise<void> | Promise that returns no value. | 542 543**Error codes** 544 545For details about the error codes, see [Window Error Codes](errorcode-window.md). 546 547| ID | Error Message | 548|------------|--------------------------------------------------------| 549| 1300012 | The PiP window state is abnormal. | 550| 1300013 | Failed to create the PiP window. | 551| 1300014 | PiP internal error. | 552| 1300015 | Repeated PiP operation. | 553 554**Example** 555 556```ts 557let promise : Promise<void> = pipController.startPiP(); 558promise.then(() => { 559 console.info(`Succeeded in starting pip.`); 560}).catch((err: BusinessError) => { 561 console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`); 562}); 563``` 564 565### stopPiP 566 567stopPiP(): Promise<void> 568 569Stops 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| 1300011 | Failed to destroy the PiP window. | 588| 1300012 | The PiP window state is abnormal. | 589| 1300015 | Repeated PiP operation. | 590 591**Example** 592 593```ts 594let promise : Promise<void> = pipController.stopPiP(); 595promise.then(() => { 596 console.info(`Succeeded in stopping pip.`); 597}).catch((err: BusinessError) => { 598 console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`); 599}); 600``` 601 602### setAutoStartEnabled 603 604setAutoStartEnabled(enable: boolean): void 605 606Sets whether to automatically start a PiP window when the user returns to the home screen. 607 608**Atomic service API**: This API can be used in atomic services since API version 12. 609 610**System capability**: SystemCapability.Window.SessionManager 611 612**Parameters** 613 614| Name | Type | Mandatory | Description | 615|----------|-----------|-------|---------------------------------| 616| 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**. | 617 618**Example** 619 620```ts 621let enable: boolean = true; 622pipController.setAutoStartEnabled(enable); 623``` 624 625### updateContentSize 626 627updateContentSize(width: number, height: number): void 628 629Updates the media content size when the media content is switched. 630 631**Atomic service API**: This API can be used in atomic services since API version 12. 632 633**System capability**: SystemCapability.Window.SessionManager 634 635**Parameters** 636 637| Name | Type | Mandatory | Description | 638|--------|--------|-----|----------------------------------------| 639| 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. | 640| 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. | 641 642**Error codes** 643 644For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 645 646| ID| Error Message | 647|-------|-------------------------------------------------------------------------------------------------------------| 648| 401 | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 649 650**Example** 651 652```ts 653let width: number = 540; // The content width changes to 540 px. 654let height: number = 960; // The content height changes to 960 px. 655pipController.updateContentSize(width, height); 656``` 657 658### updatePiPControlStatus<sup>12+</sup> 659updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void 660 661Updates the enabled status of a component displayed on the PiP controller. 662 663**Atomic service API**: This API can be used in atomic services since API version 12. 664 665**System capability**: SystemCapability.Window.SessionManager 666 667**Parameters** 668 669| Name | Type | Mandatory | Description | 670|--------|--------|-----|----------------------------------------------------------------------------------------------------| 671| 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.| 672| status | [PiPControlStatus](#pipcontrolstatus12) | Yes | Status of the component displayed on the PiP controller. | 673 674**Error codes** 675 676For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 677 678| ID| Error Message | 679|-------|-------------------------------------------------------------------------------------------------------------| 680| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 681 682**Example** 683 684```ts 685let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // Play/Pause component displayed on the video playback control panel. 686let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // The Play/Pause component displayed on the video playback control panel is in the playing state. 687pipController.updatePiPControlStatus(controlType, status); 688``` 689 690### setPiPControlEnabled<sup>12+</sup> 691setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void 692 693Sets the enabled status for a component displayed on the PiP controller. 694 695**Atomic service API**: This API can be used in atomic services since API version 12. 696 697**System capability**: SystemCapability.Window.SessionManager 698 699**Parameters** 700 701| Name | Type | Mandatory | Description | 702|-------------|--------|-----|----------------------------------------| 703| controlType | [PiPControlType](#pipcontroltype12) | Yes | Type of the component displayed on the PiP controller. | 704| 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. | 705 706**Error codes** 707 708For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 709 710| ID| Error Message | 711|-------|-------------------------------------------------------------------------------------------------------------| 712| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 713 714**Example** 715 716```ts 717let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // Play/Pause component displayed on the video playback control panel. 718let enabled: boolean = false; // The Play/Pause component displayed on the video playback control panel is in the disabled state. 719pipController.setPiPControlEnabled(controlType, enabled); 720``` 721### getPiPWindowInfo<sup>15+</sup> 722getPiPWindowInfo(): Promise<[PiPWindowInfo](#pipwindowinfo15)> 723 724Obtains the PIP window information. 725 726**Atomic service API**: This API can be used in atomic services since API version 15. 727 728**System capability**: SystemCapability.Window.SessionManager 729 730**Return value** 731 732| Type | Description | 733|----------------------|---------------------| 734| Promise<[PiPWindowInfo](#pipwindowinfo15)> | Promise used to return the information about the current PIP window.| 735 736**Error codes** 737 738For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 739 740| ID| Error Message | 741|-------|-------------------------------------------------------------------------------------------------------------| 742| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 743| 1300014 | PiP internal error. | 744 745**Example** 746 747```ts 748let pipWindowInfo: PiPWindow.PiPWindowInfo | undefined = undefined; 749try { 750 let promise : Promise<PiPWindow.PiPWindowInfo> = pipController.getPiPWindowInfo(); 751 promise.then((data) => { 752 pipWindowInfo = data; 753 console.info('Success in get pip window info. Info: ' + JSON.stringify(data)); 754 }).catch((err: BusinessError) => { 755 console.error(`Failed to get pip window info. Cause code: ${err.code}, message: ${err.message}`); 756 }); 757} catch (exception) { 758 console.error(`Failed to get pip window info. Cause code: ${exception.code}, message: ${exception.message}`); 759} 760``` 761 762### on('stateChange') 763 764on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 765 766Subscribes to PiP state events. 767 768**Atomic service API**: This API can be used in atomic services since API version 12. 769 770**System capability**: SystemCapability.Window.SessionManager 771 772**Parameters** 773 774| Name | Type | Mandatory | Description | 775|------------|-----------|------|---------------------------------------------------------------------------------------------------| 776| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 777| 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. | 778 779**Example** 780 781```ts 782pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => { 783 let curState: string = ''; 784 switch (state) { 785 case PiPWindow.PiPState.ABOUT_TO_START: 786 curState = 'ABOUT_TO_START'; 787 break; 788 case PiPWindow.PiPState.STARTED: 789 curState = 'STARTED'; 790 break; 791 case PiPWindow.PiPState.ABOUT_TO_STOP: 792 curState = 'ABOUT_TO_STOP'; 793 break; 794 case PiPWindow.PiPState.STOPPED: 795 curState = 'STOPPED'; 796 break; 797 case PiPWindow.PiPState.ABOUT_TO_RESTORE: 798 curState = 'ABOUT_TO_RESTORE'; 799 break; 800 case PiPWindow.PiPState.ERROR: 801 curState = 'ERROR'; 802 break; 803 default: 804 break; 805 } 806 console.info('stateChange:' + curState + ' reason:' + reason); 807}); 808``` 809 810### off('stateChange') 811 812off(type: 'stateChange'): void 813 814Unsubscribes from PiP state events. 815 816**Atomic service API**: This API can be used in atomic services since API version 12. 817 818**System capability**: SystemCapability.Window.SessionManager 819 820**Parameters** 821 822| Name | Type | Mandatory | Description | 823|-----------|---------------|-------|----------------------------------------| 824| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 825 826**Example** 827 828```ts 829pipController.off('stateChange'); 830``` 831 832### on('controlPanelActionEvent') 833 834on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void 835 836Subscribes to PiP action events. The [on('controlEvent')](#oncontrolevent12) API is preferred. 837 838**Atomic service API**: This API can be used in atomic services since API version 12. 839 840**System capability**: SystemCapability.Window.SessionManager 841 842**Parameters** 843 844| Name | Type | Mandatory | Description | 845|----------|------------|-------|---------------------------------------------------| 846| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event.| 847| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12) | Yes | Action event callback of the PiP controller. | 848 849**Example** 850 851```ts 852pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => { 853 switch (event) { 854 case 'playbackStateChanged': 855 if (status === 0) { 856 // Stop the video. 857 } else if (status === 1) { 858 // Play the video. 859 } 860 break; 861 case 'nextVideo': 862 // Switch to the next video. 863 break; 864 case 'previousVideo': 865 // Switch to the previous video. 866 break; 867 case 'fastForward': 868 // Fast forward the video. 869 break; 870 case 'fastBackward': 871 // Rewind the video. 872 break; 873 default: 874 break; 875 } 876 console.info('registerActionEventCallback, event:' + event); 877}); 878``` 879 880### on('controlEvent')<sup>12+</sup> 881 882on(type: 'controlEvent', callback: Callback<ControlEventParam>): void 883 884Subscribes to PiP action events. 885 886**Atomic service API**: This API can be used in atomic services since API version 12. 887 888**System capability**: SystemCapability.Window.SessionManager 889 890**Parameters** 891 892| Name | Type | Mandatory | Description | 893|----------|-----------------------------------------------------|-------|----------------------------------------| 894| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event.| 895| callback | Callback<[ControlEventParam](#controleventparam12)> | Yes | Action event callback of the PiP controller. | 896 897**Example** 898 899```ts 900pipController.on('controlEvent', (control) => { 901 switch (control.controlType) { 902 case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE: 903 if (control.status === PiPWindow.PiPControlStatus.PAUSE) { 904 // Stop the video. 905 } else if (control.status === PiPWindow.PiPControlStatus.PLAY) { 906 // Play the video. 907 } 908 break; 909 case PiPWindow.PiPControlType.VIDEO_NEXT: 910 // Switch to the next video. 911 break; 912 case PiPWindow.PiPControlType.VIDEO_PREVIOUS: 913 // Switch to the previous video. 914 break; 915 case PiPWindow.PiPControlType.FAST_FORWARD: 916 // Fast forward the video. 917 break; 918 case PiPWindow.PiPControlType.FAST_BACKWARD: 919 // Rewind the video. 920 break; 921 default: 922 break; 923 } 924 console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status); 925}); 926``` 927 928### off('controlPanelActionEvent') 929 930off(type: 'controlPanelActionEvent'): void 931 932Unsubscribes from PiP action events. The **[off('controlEvent')](#offcontrolevent12)** API is preferred. 933 934**Atomic service API**: This API can be used in atomic services since API version 12. 935 936**System capability**: SystemCapability.Window.SessionManager 937 938**Parameters** 939 940| Name | Type | Mandatory | Description | 941|------------|------------------------------|------|-----------------------------------------------| 942| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event. | 943 944**Example** 945 946```ts 947pipController.off('controlPanelActionEvent'); 948``` 949 950### off('controlEvent')<sup>12+</sup> 951 952off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void 953 954Unsubscribes from PiP action events. 955 956**Atomic service API**: This API can be used in atomic services since API version 12. 957 958**System capability**: SystemCapability.Window.SessionManager 959 960**Parameters** 961 962| Name | Type | Mandatory| Description | 963|------------|-----------------------------------------------------|----|--------------------------------------------------------| 964| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event. | 965| 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.| 966 967**Example** 968 969```ts 970pipController.off('controlEvent', () => {}); 971``` 972 973### on('pipWindowSizeChange')<sup>15+</sup> 974 975on(type: 'pipWindowSizeChange', callback: Callback<PiPWindowSize>): void 976 977Subscribes to the PiP window size change event. 978 979**Atomic service API**: This API can be used in atomic services since API version 15. 980 981**System capability**: SystemCapability.Window.SessionManager 982 983**Parameters** 984 985| Name | Type | Mandatory | Description | 986|----------|---------------------------------------------|-------|---------------------------------------------------| 987| type | string | Yes | Event type. The value is fixed at **'pipWindowSizeChange'**, indicating the PiP window size change event.| 988| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | Yes | Callback used to return the size of the current PiP window.| 989 990**Error codes** 991 992For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 993 994| ID| Error Message| 995| ------- | -------------------------------------------- | 996| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 997| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 998| 1300014 | PiP internal error. | 999 1000**Example** 1001 1002```ts 1003try { 1004 pipController.on('pipWindowSizeChange', (size: PiPWindow.PiPWindowSize) => { 1005 console.info('Succeeded in enabling the listener for pip window size changes. size: ' + JSON.stringify(size)); 1006 }); 1007} catch (exception) { 1008 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1009} 1010``` 1011 1012### off('pipWindowSizeChange')<sup>15+</sup> 1013 1014off(type: 'pipWindowSizeChange', callback?: Callback<PiPWindowSize>): void 1015 1016Unsubscribes from the PiP window size change event. 1017 1018**Atomic service API**: This API can be used in atomic services since API version 15. 1019 1020**System capability**: SystemCapability.Window.SessionManager 1021 1022**Parameters** 1023 1024| Name | Type | Mandatory| Description | 1025|----------|------------|----|---------------------------------------------------------------------| 1026| type | string | Yes | Event type. The value is fixed at **'pipWindowSizeChange'**, indicating the PiP window size change event. | 1027| 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.| 1028 1029**Error codes** 1030 1031For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1032 1033| ID| Error Message| 1034| ------- | -------------------------------------------- | 1035| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1036| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1037| 1300014 | PiP internal error. | 1038 1039**Example** 1040 1041```ts 1042const callback = (size: PiPWindow.PiPWindowSize) => { 1043 // ... 1044} 1045try { 1046 // Enable listening through the on API. 1047 pipController.on('pipWindowSizeChange', callback); 1048} catch (exception) { 1049 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1050} 1051 1052try { 1053 // Disable the listening of a specified callback. 1054 pipController.off('pipWindowSizeChange', callback); 1055 // Unregister all the callbacks that have been registered through on(). 1056 pipController.off('pipWindowSizeChange'); 1057} catch (exception) { 1058 console.error(`Failed to disable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1059} 1060``` 1061