@ohos.PiPWindow (PiP Window)

The 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.

NOTE

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.

This module must be used on the device that supports the SystemCapability.Window.SessionManager capability. For details, see SystemCapability.

Modules to Import

import pipWindow from '@ohos.PiPWindow';

pipWindow.isPiPEnabled

isPiPEnabled(): boolean

Checks whether the PiP feature is enabled.

System capability: SystemCapability.Window.SessionManager

Return value

Example

let enable: boolean = pipWindow.isPiPEnabled();
console.info('isPipEnabled:' + enable);

pipWindow.create

create(config: PiPConfiguration): Promise<PiPController>

Creates a PiP controller. This API uses a promise to return the result.

System capability: SystemCapability.Window.SessionManager

Parameters

Return value

Example

import { BusinessError } from '@ohos.base';
let pipController: pipWindow.PiPController | undefined = undefined;
let 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.
let 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.
let contentWidth: number = 800; // The content width is 800 px.
let contentHeight: number = 600; // The content height is 600 px.
let config: pipWindow.PiPConfiguration = {
  context: getContext(this),
  componentController: mXComponentController,
  navigationId: navId,
  templateType: pipWindow.PiPTemplateType.VIDEO_PLAY,
  contentWidth: contentWidth,
  contentHeight: contentHeight,
};

let promise : Promise<pipWindow.PiPController> = pipWindow.create(config);
promise.then((data : pipWindow.PiPController) => {
  pipController = data;
  console.info(`Succeeded in creating pip controller. Data:${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`);
});

PiPConfiguration

Defines the parameters for creating a PiP controller.

System capability: SystemCapability.Window.SessionManager

PiPTemplateType

Enumerates the PIP template types.

System capability: SystemCapability.Window.SessionManager

PiPState

Enumerates the PiP states.

System capability: SystemCapability.Window.SessionManager

PiPActionEventType

Enumerates the PiP action event types.

System capability: SystemCapability.Window.SessionManager

PiPVideoActionEvent

Defines the PiP action event during video playback.

System capability: SystemCapability.Window.SessionManager

PiPCallActionEvent

Defines the PiP action event in a video call.

System capability: SystemCapability.Window.SessionManager

PiPMeetingActionEvent

Defines the PiP action event in a video meeting.

System capability: SystemCapability.Window.SessionManager

PiPLiveActionEvent

Defines the PiP action event in a live.

System capability: SystemCapability.Window.SessionManager

PiPController

Implements a PiP controller that starts, stops, or updates a PiP window and registers callbacks.

Before calling any of the following APIs, you must use pipWindow.create() to create a PiPController instance.

System capability: SystemCapability.Window.SessionManager

startPiP

startPiP(): Promise<void>

Starts a PiP window. This API uses a promise to return the result.

System capability: SystemCapability.Window.SessionManager

Return value

Error codes

For details about the error codes, see Window Error Codes.

Example

let promise : Promise<void> = pipController.startPiP();
promise.then(() => {
  console.info(`Succeeded in starting pip.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`);
});

stopPiP

stopPiP(): Promise<void>

Stops a PiP window. This API uses a promise to return the result.

System capability: SystemCapability.Window.SessionManager

Return value

Error codes

For details about the error codes, see Window Error Codes.

Example

let promise : Promise<void> = pipController.stopPiP();
promise.then(() => {
  console.info(`Succeeded in stopping pip.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`);
});

setAutoStartEnabled

setAutoStartEnabled(enable: boolean): void

Sets whether to automatically start a PiP window when the user returns to the home screen.

System capability: SystemCapability.Window.SessionManager

Parameters

let enable: boolean = true;
pipController.setAutoStartEnabled(enable);

updateContentSize

updateContentSize(width: number, height: number): void

Updates the media content size when the media content is switched.

System capability: SystemCapability.Window.SessionManager

Parameters

let width: number = 540; // The content width changes to 540 px.
let height: number = 960; // The content height changes to 960 px.
pipController.updateContentSize(width, height);

on('stateChange')

on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void

Subscribes to PiP state events.

System capability: SystemCapability.Window.SessionManager

Parameters

pipController.on('stateChange', (state: pipWindow.PiPState, reason: string) => {
  let curState: string = '';
  switch (state) {
    case pipWindow.PiPState.ABOUT_TO_START:
      curState = 'ABOUT_TO_START';
      break;
    case pipWindow.PiPState.STARTED:
      curState = 'STARTED';
      break;
    case pipWindow.PiPState.ABOUT_TO_STOP:
      curState = 'ABOUT_TO_STOP';
      break;
    case pipWindow.PiPState.STOPPED:
      curState = 'STOPPED';
      break;
    case pipWindow.PiPState.ABOUT_TO_RESTORE:
      curState = 'ABOUT_TO_RESTORE';
      break;
    case pipWindow.PiPState.ERROR:
      curState = 'ERROR';
      break;
    default:
      break;
  }
  console.info('stateChange:' + curState + ' reason:' + reason);
});

off('stateChange')

off(type: 'stateChange'): void

Unsubscribes from PiP state events.

System capability: SystemCapability.Window.SessionManager

Parameters

Example

pipController.off('stateChange');

on('controlPanelActionEvent')

on(type: 'controlPanelActionEvent', callback: (event: PiPActionEventType) => void): void

Subscribes to PiP action events.

System capability: SystemCapability.Window.SessionManager

Parameters

pipController.on('controlPanelActionEvent', (event: pipWindow.PiPActionEventType) => {
  switch (event) {
    case 'playbackStateChanged':
      // Start or stop the video.
      break;
    case 'nextVideo':
      // Switch to the next video.
      break;
    case 'previousVideo':
      // Switch to the previous video.
      break;
    default:
      break;
  }
  console.info('registerActionEventCallback, event:' + event);
});

off('controlPanelActionEvent')

off(type: 'controlPanelActionEvent'): void

Unsubscribes from PiP action events.

System capability: SystemCapability.Window.SessionManager

Parameters

Example

pipController.off('controlPanelActionEvent');