Package com.castlabs.android.player

# Interface IPlayerView

All Known Implementing Classes:
  `PlayerView`

public interface IPlayerView
This interface describes the visual component of the video player. It is used in conjunction with a `PlayerController`. Once the controller is available, you need to set the view using `PlayerController.setPlayerView(IPlayerView)`.

Since:
  3.0.3

- ## Method Summary

  Modifier and Type
  Method
  Description
  `PlayerViewLifecycleDelegate`
  `getLifecycleDelegate()`
  This method must return an instance of the `PlayerViewLifecycleDelegate`.
  `PlayerController`
  `getPlayerController()`
  Returns the current instance of the `PlayerController` that is used by this view.
  `ViewGroup`
  `getRootView()`
  Retrieve the root view of the current `IPlayerView` implementation.
  `int`
  `getScalingMode()`
  Gets the current scaling mode of the video view.
  `ViewGroup`
  `getVideoView()`
  Retrieve the video container view of the current `IPlayerView` implementation.
  `void`
  `prepareSurface()`
  This method is called by the `PlayerController` once the player and the renderer are available.
  `void`
  `removeSurface()`
  This method is called by the `PlayerController` once the player is released.
  `void`
  `setPlayerController(PlayerController playerController)`
  Set the player controller used by this view.
  `void`
  `setScalingMode(int scalingMode)`
  Sets the scaling mode for the video view.
  `void`
  `setVisible(boolean visible)`
  Allow to show ore hide this player view.
  `PlayerController`
  `tryPlayerController()`
  Returns the current instance of the `PlayerController` that is used by this view.

- ## Method Details

  - ### getRootView

    @NonNull ViewGroup getRootView()
    Retrieve the root view of the current `IPlayerView` implementation. The video container view is added internally to the root view with the index zero. All other child views when added to the root view are on top of video container view and do not respect the video container aspect ratio.
    Returns:
      The root view of the current `IPlayerView` implementation

  - ### getVideoView

    @NonNull ViewGroup getVideoView()
    Retrieve the video container view of the current `IPlayerView` implementation. All the child view when added to the video container view do respect the video container aspect ratio.
    Returns:
      The video container view of the current `IPlayerView` implementation

  - ### setVisible

    void setVisible(boolean visible)
    Allow to show ore hide this player view. This is used by the player controller in case the the player view needs to be made invisible. For example, if a secondary display is connected and content playback should be prevented, playback will stop and this method will be used hide the player view.
    Parameters:
      `visible` - True if the view should be visible

  - ### prepareSurface

    void prepareSurface()
    This method is called by the `PlayerController` once the player and the renderer are available. Implementations should create the video surface here and push it to the controller using `PlayerController.setSurface(Surface)`.

    Please note that you usually also need to setup a listener on the surface and delegate create and destroy events to the underlying player controller also using `PlayerController.setSurface(Surface)`.

  - ### removeSurface

    void removeSurface()
    This method is called by the `PlayerController` once the player is released. Implementations should remove the video surface if it exists.

  - ### getPlayerController

    @NonNull PlayerController getPlayerController()
    Returns the current instance of the `PlayerController` that is used by this view.

    Note that you can create the controller lazily here as well, but the implementation must be able to take a controller instance through `setPlayerController(PlayerController)`. In addition, if you are creating the controller here, make sure that the bi-directional link between the view and the controller is established by calling `PlayerController.setPlayerView(IPlayerView)`.
    Returns:
      The player controller instance that is used to render video to this view

  - ### tryPlayerController

    @Nullable PlayerController tryPlayerController()
    Returns the current instance of the `PlayerController` that is used by this view.

    Note that you do not create the controller lazily here.
    Returns:
      The player controller instance that is used to render video to this view

  - ### setPlayerController

    void setPlayerController(@Nullable PlayerController playerController)
    Set the player controller used by this view.

    The implementation must ensure that the bi-directional link between the controller and this view is established (or reset if a controller already exists). You must call `PlayerController.setPlayerView(IPlayerView)` to establish this link.

    In addition, this method might be called with a `null` argument, which indicates that the view is disposed and should break the relation with the current controller. In that case the implementation must ensure to call `PlayerController.setPlayerView(IPlayerView)` with a `null` argument and remove any listeners that were attached to the controller.

    This is used for example when reattaching to an existing controller.. When you are using a `PlayerService`, the service will automatically reattach the controller and call this method. When you are using the view without a service, the view should create a controller for you automatically when `getPlayerController()` is called the first time.
    Parameters:
      `playerController` - The player controller

  - ### getLifecycleDelegate

    @NonNull PlayerViewLifecycleDelegate getLifecycleDelegate()
    This method must return an instance of the `PlayerViewLifecycleDelegate`. That instance can be used to integrate the view and its controller with an Activity lifecycle. Please note that the returned instance might also be used implicitly when the `PlayerService` is used and the player is send to background.
    Returns:
      The lifecycle delegate that is used to integrate this view into activity life cycles

  - ### getScalingMode

    int getScalingMode()
    Gets the current scaling mode of the video view. The scaling mode determines how the video content is scaled to fit the view.
    Returns:
      The current scaling mode value

  - ### setScalingMode

    void setScalingMode(int scalingMode)
    Sets the scaling mode for the video view. The scaling mode determines how the video content is scaled to fit the view.
    Parameters:
      `scalingMode` - The scaling mode to set