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### updateContentNode<sup>16+</sup> 691updateContentNode(contentNode: typeNode.XComponent): Promise<void> 692 693Updates the PiP node content. 694 695**Atomic service API**: This API can be used in atomic services since API version 16. 696 697**System capability**: SystemCapability.Window.SessionManager 698 699**Parameters** 700 701| Name | Type | Mandatory | Description | 702|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 703| contentNode | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12) | Yes | Content to be rendered in the PiP window. The parameter value cannot be empty. | 704 705**Return value** 706 707| Type | Description | 708|----------------------|---------------------| 709| Promise<void> | Promise that returns no value. | 710 711**Error codes** 712 713For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 714 715| ID| Error Message | 716|-------|-------------------------------------------------------------------------------------------------------------| 717| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed | 718| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 719| 1300014 | PiP internal error. | 720 721**Example** 722 723```ts 724import { typeNode, UIContext } from '@kit.ArkUI'; 725 726let context: UIContext | undefined = undefined; // You can pass UIContext or use this.getUIContext() in the layout to assign a valid value to context. 727 728try { 729 let contentNode = typeNode.createNode(context, "XComponent"); 730 pipcontroller.updateContentNode(contentNode); 731} catch (exception) { 732 console.error(`Failed to update content node. Cause: ${exception.code}, message: ${exception.message}`); 733} 734``` 735 736### setPiPControlEnabled<sup>12+</sup> 737setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void 738 739Sets the enabled status for a component displayed on the PiP controller. 740 741**Atomic service API**: This API can be used in atomic services since API version 12. 742 743**System capability**: SystemCapability.Window.SessionManager 744 745**Parameters** 746 747| Name | Type | Mandatory | Description | 748|-------------|--------|-----|----------------------------------------| 749| controlType | [PiPControlType](#pipcontroltype12) | Yes | Type of the component displayed on the PiP controller. | 750| 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. | 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 760**Example** 761 762```ts 763let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // Play/Pause component displayed on the video playback control panel. 764let enabled: boolean = false; // The Play/Pause component displayed on the video playback control panel is in the disabled state. 765pipController.setPiPControlEnabled(controlType, enabled); 766``` 767### getPiPWindowInfo<sup>15+</sup> 768getPiPWindowInfo(): Promise<[PiPWindowInfo](#pipwindowinfo15)> 769 770Obtains the PIP window information. 771 772**Atomic service API**: This API can be used in atomic services since API version 15. 773 774**System capability**: SystemCapability.Window.SessionManager 775 776**Return value** 777 778| Type | Description | 779|----------------------|---------------------| 780| Promise<[PiPWindowInfo](#pipwindowinfo15)> | Promise used to return the information about the current PIP window.| 781 782**Error codes** 783 784For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 785 786| ID| Error Message | 787|-------|-------------------------------------------------------------------------------------------------------------| 788| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 789| 1300014 | PiP internal error. | 790 791**Example** 792 793```ts 794let pipWindowInfo: PiPWindow.PiPWindowInfo | undefined = undefined; 795try { 796 let promise : Promise<PiPWindow.PiPWindowInfo> = pipController.getPiPWindowInfo(); 797 promise.then((data) => { 798 pipWindowInfo = data; 799 console.info('Success in get pip window info. Info: ' + JSON.stringify(data)); 800 }).catch((err: BusinessError) => { 801 console.error(`Failed to get pip window info. Cause code: ${err.code}, message: ${err.message}`); 802 }); 803} catch (exception) { 804 console.error(`Failed to get pip window info. Cause code: ${exception.code}, message: ${exception.message}`); 805} 806``` 807 808### on('stateChange') 809 810on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void 811 812Subscribes to PiP state events. 813 814**Atomic service API**: This API can be used in atomic services since API version 12. 815 816**System capability**: SystemCapability.Window.SessionManager 817 818**Parameters** 819 820| Name | Type | Mandatory | Description | 821|------------|-----------|------|---------------------------------------------------------------------------------------------------| 822| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 823| 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. | 824 825**Example** 826 827```ts 828pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => { 829 let curState: string = ''; 830 switch (state) { 831 case PiPWindow.PiPState.ABOUT_TO_START: 832 curState = 'ABOUT_TO_START'; 833 break; 834 case PiPWindow.PiPState.STARTED: 835 curState = 'STARTED'; 836 break; 837 case PiPWindow.PiPState.ABOUT_TO_STOP: 838 curState = 'ABOUT_TO_STOP'; 839 break; 840 case PiPWindow.PiPState.STOPPED: 841 curState = 'STOPPED'; 842 break; 843 case PiPWindow.PiPState.ABOUT_TO_RESTORE: 844 curState = 'ABOUT_TO_RESTORE'; 845 break; 846 case PiPWindow.PiPState.ERROR: 847 curState = 'ERROR'; 848 break; 849 default: 850 break; 851 } 852 console.info('stateChange:' + curState + ' reason:' + reason); 853}); 854``` 855 856### off('stateChange') 857 858off(type: 'stateChange'): void 859 860Unsubscribes from PiP state events. 861 862**Atomic service API**: This API can be used in atomic services since API version 12. 863 864**System capability**: SystemCapability.Window.SessionManager 865 866**Parameters** 867 868| Name | Type | Mandatory | Description | 869|-----------|---------------|-------|----------------------------------------| 870| type | string | Yes | Event type. The event **'stateChange'** is triggered when the PiP state changes. | 871 872**Example** 873 874```ts 875pipController.off('stateChange'); 876``` 877 878### on('controlPanelActionEvent') 879 880on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void 881 882Subscribes to PiP action events. The [on('controlEvent')](#oncontrolevent12) API is preferred. 883 884**Atomic service API**: This API can be used in atomic services since API version 12. 885 886**System capability**: SystemCapability.Window.SessionManager 887 888**Parameters** 889 890| Name | Type | Mandatory | Description | 891|----------|------------|-------|---------------------------------------------------| 892| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event.| 893| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12) | Yes | Action event callback of the PiP controller. | 894 895**Example** 896 897```ts 898pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => { 899 switch (event) { 900 case 'playbackStateChanged': 901 if (status === 0) { 902 // Stop the video. 903 } else if (status === 1) { 904 // Play the video. 905 } 906 break; 907 case 'nextVideo': 908 // Switch to the next video. 909 break; 910 case 'previousVideo': 911 // Switch to the previous video. 912 break; 913 case 'fastForward': 914 // Fast forward the video. 915 break; 916 case 'fastBackward': 917 // Rewind the video. 918 break; 919 default: 920 break; 921 } 922 console.info('registerActionEventCallback, event:' + event); 923}); 924``` 925 926### on('controlEvent')<sup>12+</sup> 927 928on(type: 'controlEvent', callback: Callback<ControlEventParam>): void 929 930Subscribes to PiP action events. 931 932**Atomic service API**: This API can be used in atomic services since API version 12. 933 934**System capability**: SystemCapability.Window.SessionManager 935 936**Parameters** 937 938| Name | Type | Mandatory | Description | 939|----------|-----------------------------------------------------|-------|----------------------------------------| 940| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event.| 941| callback | Callback<[ControlEventParam](#controleventparam12)> | Yes | Action event callback of the PiP controller. | 942 943**Example** 944 945```ts 946pipController.on('controlEvent', (control) => { 947 switch (control.controlType) { 948 case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE: 949 if (control.status === PiPWindow.PiPControlStatus.PAUSE) { 950 // Stop the video. 951 } else if (control.status === PiPWindow.PiPControlStatus.PLAY) { 952 // Play the video. 953 } 954 break; 955 case PiPWindow.PiPControlType.VIDEO_NEXT: 956 // Switch to the next video. 957 break; 958 case PiPWindow.PiPControlType.VIDEO_PREVIOUS: 959 // Switch to the previous video. 960 break; 961 case PiPWindow.PiPControlType.FAST_FORWARD: 962 // Fast forward the video. 963 break; 964 case PiPWindow.PiPControlType.FAST_BACKWARD: 965 // Rewind the video. 966 break; 967 default: 968 break; 969 } 970 console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status); 971}); 972``` 973 974### off('controlPanelActionEvent') 975 976off(type: 'controlPanelActionEvent'): void 977 978Unsubscribes from PiP action events. The **[off('controlEvent')](#offcontrolevent12)** API is preferred. 979 980**Atomic service API**: This API can be used in atomic services since API version 12. 981 982**System capability**: SystemCapability.Window.SessionManager 983 984**Parameters** 985 986| Name | Type | Mandatory | Description | 987|------------|------------------------------|------|-----------------------------------------------| 988| type | string | Yes | Event type. The value **'controlPanelActionEvent'** indicates the PiP action event. | 989 990**Example** 991 992```ts 993pipController.off('controlPanelActionEvent'); 994``` 995 996### off('controlEvent')<sup>12+</sup> 997 998off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void 999 1000Unsubscribes from PiP action events. 1001 1002**Atomic service API**: This API can be used in atomic services since API version 12. 1003 1004**System capability**: SystemCapability.Window.SessionManager 1005 1006**Parameters** 1007 1008| Name | Type | Mandatory| Description | 1009|------------|-----------------------------------------------------|----|--------------------------------------------------------| 1010| type | string | Yes | Event type. The value **'controlEvent'** indicates the PiP action event. | 1011| 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.| 1012 1013**Example** 1014 1015```ts 1016pipController.off('controlEvent', () => {}); 1017``` 1018 1019### on('pipWindowSizeChange')<sup>15+</sup> 1020 1021on(type: 'pipWindowSizeChange', callback: Callback<PiPWindowSize>): void 1022 1023Subscribes to the PiP window size change event. 1024 1025**Atomic service API**: This API can be used in atomic services since API version 15. 1026 1027**System capability**: SystemCapability.Window.SessionManager 1028 1029**Parameters** 1030 1031| Name | Type | Mandatory | Description | 1032|----------|---------------------------------------------|-------|---------------------------------------------------| 1033| type | string | Yes | Event type. The value is fixed at **'pipWindowSizeChange'**, indicating the PiP window size change event.| 1034| callback | Callback<[PiPWindowSize](#pipwindowsize15)> | Yes | Callback used to return the size of the current PiP window.| 1035 1036**Error codes** 1037 1038For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1039 1040| ID| Error Message| 1041| ------- | -------------------------------------------- | 1042| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1043| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1044| 1300014 | PiP internal error. | 1045 1046**Example** 1047 1048```ts 1049try { 1050 pipController.on('pipWindowSizeChange', (size: PiPWindow.PiPWindowSize) => { 1051 console.info('Succeeded in enabling the listener for pip window size changes. size: ' + JSON.stringify(size)); 1052 }); 1053} catch (exception) { 1054 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1055} 1056``` 1057 1058### off('pipWindowSizeChange')<sup>15+</sup> 1059 1060off(type: 'pipWindowSizeChange', callback?: Callback<PiPWindowSize>): void 1061 1062Unsubscribes from the PiP window size change event. 1063 1064**Atomic service API**: This API can be used in atomic services since API version 15. 1065 1066**System capability**: SystemCapability.Window.SessionManager 1067 1068**Parameters** 1069 1070| Name | Type | Mandatory| Description | 1071|----------|------------|----|---------------------------------------------------------------------| 1072| type | string | Yes | Event type. The value is fixed at **'pipWindowSizeChange'**, indicating the PiP window size change event. | 1073| 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.| 1074 1075**Error codes** 1076 1077For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Window Error Codes](errorcode-window.md). 1078 1079| ID| Error Message| 1080| ------- | -------------------------------------------- | 1081| 401 | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1082| 801 | Capability not supported.Failed to call the API due to limited device capabilities. | 1083| 1300014 | PiP internal error. | 1084 1085**Example** 1086 1087```ts 1088const callback = (size: PiPWindow.PiPWindowSize) => { 1089 // ... 1090} 1091try { 1092 // Enable listening through the on API. 1093 pipController.on('pipWindowSizeChange', callback); 1094} catch (exception) { 1095 console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1096} 1097 1098try { 1099 // Disable the listening of a specified callback. 1100 pipController.off('pipWindowSizeChange', callback); 1101 // Unregister all the callbacks that have been registered through on(). 1102 pipController.off('pipWindowSizeChange'); 1103} catch (exception) { 1104 console.error(`Failed to disable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 1105} 1106``` 1107