PlaybackControlGlue

public abstract class PlaybackControlGlue extends PlaybackGlue implements OnActionClickedListener, View.OnKeyListener


A helper class for managing a PlaybackControlsRow and PlaybackGlueHost that implements a recommended approach to handling standard playback control actions such as play/pause, fast forward/rewind at progressive speed levels, and skip to next/previous. This helper class is a glue layer in that manages the configuration of and interaction between the leanback UI components by defining a functional interface to the media player.

You can instantiate a concrete subclass such as MediaPlayerGlue or you must subclass this abstract helper. To create a subclass you must implement all of the abstract methods and the subclass must invoke onMetadataChanged and onStateChanged appropriately.

To use an instance of the glue layer, first construct an instance. Constructor parameters inform the glue what speed levels are supported for fast forward/rewind.

You may override onCreateControlsRowAndPresenter which will create a PlaybackControlsRow and a PlaybackControlsRowPresenter. You may call setControlsRow and setPlaybackRowPresenter to customize your own row and presenter.

The helper sets a SparseArrayObjectAdapter on the controls row as the primary actions adapter, and adds actions to it. You can provide additional actions by overriding onCreatePrimaryActions. This helper does not deal in secondary actions so those you may add separately.

Provide a click listener on your fragment and if an action is clicked, call onActionClicked.

This helper implements a key event handler. If you pass a PlaybackGlueHost, it will configure its fragment to intercept all key events. Otherwise, you should set the glue object as key event handler to the ViewHolder when bound by your row presenter; see setOnKeyListener.

To update the controls row progress during playback, override enableProgressUpdating to manage the lifecycle of a periodic callback to updateProgress. getUpdatePeriod provides a recommended update period.

Summary

Constants

static final int

The adapter key for the first custom control on the left side of the predefined primary controls.

static final int

The adapter key for the first custom control on the right side of the predefined primary controls.

static final int

The adapter key for the fast forward control.

static final int

The adapter key for the play/pause control.

static final int

The adapter key for the rewind control.

static final int

The adapter key for the skip to next control.

static final int

The adapter key for the skip to previous control.

static final int

The initial (level 0) fast forward playback speed.

static final int

The level 1 fast forward playback speed.

static final int

The level 2 fast forward playback speed.

static final int

The level 3 fast forward playback speed.

static final int

The level 4 fast forward playback speed.

static final int

Invalid playback speed.

static final int

Speed representing playback state that is playing normally.

static final int

Speed representing playback state that is paused.

Public constructors

PlaybackControlGlue(Context context, int[] seekSpeeds)

Constructor for the glue.

PlaybackControlGlue(
    Context context,
    int[] fastForwardSpeeds,
    int[] rewindSpeeds
)

Constructor for the glue.

Public methods

void
enableProgressUpdating(boolean enable)

Override this to start/stop a runnable to call updateProgress at an interval such as getUpdatePeriod.

PlaybackControlsRow

Returns the playback controls row managed by the glue layer.

PlaybackControlsRowPresenter

This method is deprecated.

PlaybackControlGlue supports any PlaybackRowPresenter, use getPlaybackRowPresenter.

abstract int

Returns the current position of the media item in milliseconds.

abstract int

Returns the current playback speed.

int[]

Returns the fast forward speeds.

abstract Drawable

Returns a bitmap of the art for the media item.

abstract int

Returns the duration of the media item in milliseconds.

abstract CharSequence

Returns the subtitle of the media item.

abstract CharSequence

Returns the title of the media item.

PlaybackRowPresenter

Returns the playback row Presenter to be passed to PlaybackGlueHost in onAttachedToHost.

int[]

Returns the rewind speeds.

abstract long

Returns a bitmask of actions supported by the media player.

int

Returns the time period in milliseconds that should be used to update the progress.

abstract boolean

Returns true if there is a valid media item.

boolean

Returns true if controls are set to fade when media is playing.

abstract boolean

Returns true if media is currently playing.

boolean

Returns true if media is currently playing.

void

Handles action clicks.

boolean
onKey(View v, int keyCode, KeyEvent event)

Handles key events and returns true if handled.

final void

Starts the media player.

void
play(int speed)

Start playback at the given speed.

void

Sets the controls row to be managed by the glue layer.

void

This method is deprecated.

PlaybackControlGlue supports any PlaybackRowPresenter, use setPlaybackRowPresenter.

void
setFadingEnabled(boolean enable)

Sets the controls to fade after a timeout when media is playing.

void

Sets the controls row Presenter to be passed to PlaybackGlueHost in onAttachedToHost.

void

Updates the progress bar based on the current media playback position.

Protected methods

void

This method is called attached to associated PlaybackGlueHost.

void

Instantiating a PlaybackControlsRow and corresponding PlaybackControlsRowPresenter.

void

May be overridden to add primary actions to the adapter.

void

May be overridden to add secondary actions to the adapter.

void

This method is called when current associated PlaybackGlueHost is attached to a different PlaybackGlue or PlaybackGlueHost is destroyed .

void

This method is called when PlaybackGlueHost is started.

void

This method is called when PlaybackGlueHost is stopped.

void

Must be called appropriately by a subclass when the metadata state has changed.

void

Must be called appropriately by a subclass when the playback state has changed.

Inherited methods

From androidx.leanback.media.PlaybackGlue
void

Add a PlayerCallback.

@NonNull Context

Returns the context.

@Nullable PlaybackGlueHost
@Nullable List<PlaybackGlue.PlayerCallback>
boolean

Returns true when the media player is prepared to start media playback.

void

Goes to the next media item.

void

This method is called when PlaybackGlueHost is paused.

void

This method is called when PlaybackGlueHost is resumed.

void

Pauses the media player.

void

Starts play when isPrepared becomes true.

void

Goes to the previous media item.

void

Remove a PlayerCallback.

final void

This method is used to associate a PlaybackGlue with the PlaybackGlueHost which provides UI and optional SurfaceHolderGlueHost.

Constants

ACTION_CUSTOM_LEFT_FIRST

Added in 1.1.0
public static final int ACTION_CUSTOM_LEFT_FIRST = 1

The adapter key for the first custom control on the left side of the predefined primary controls.

ACTION_CUSTOM_RIGHT_FIRST

Added in 1.1.0
public static final int ACTION_CUSTOM_RIGHT_FIRST = 4096

The adapter key for the first custom control on the right side of the predefined primary controls.

ACTION_FAST_FORWARD

Added in 1.1.0
public static final int ACTION_FAST_FORWARD = 128

The adapter key for the fast forward control.

ACTION_PLAY_PAUSE

Added in 1.1.0
public static final int ACTION_PLAY_PAUSE = 64

The adapter key for the play/pause control.

ACTION_REWIND

Added in 1.1.0
public static final int ACTION_REWIND = 32

The adapter key for the rewind control.

ACTION_SKIP_TO_NEXT

Added in 1.1.0
public static final int ACTION_SKIP_TO_NEXT = 256

The adapter key for the skip to next control.

ACTION_SKIP_TO_PREVIOUS

Added in 1.1.0
public static final int ACTION_SKIP_TO_PREVIOUS = 16

The adapter key for the skip to previous control.

PLAYBACK_SPEED_FAST_L0

Added in 1.1.0
public static final int PLAYBACK_SPEED_FAST_L0 = 10

The initial (level 0) fast forward playback speed. The negative of this value is for rewind at the same speed.

PLAYBACK_SPEED_FAST_L1

Added in 1.1.0
public static final int PLAYBACK_SPEED_FAST_L1 = 11

The level 1 fast forward playback speed. The negative of this value is for rewind at the same speed.

PLAYBACK_SPEED_FAST_L2

Added in 1.1.0
public static final int PLAYBACK_SPEED_FAST_L2 = 12

The level 2 fast forward playback speed. The negative of this value is for rewind at the same speed.

PLAYBACK_SPEED_FAST_L3

Added in 1.1.0
public static final int PLAYBACK_SPEED_FAST_L3 = 13

The level 3 fast forward playback speed. The negative of this value is for rewind at the same speed.

PLAYBACK_SPEED_FAST_L4

Added in 1.1.0
public static final int PLAYBACK_SPEED_FAST_L4 = 14

The level 4 fast forward playback speed. The negative of this value is for rewind at the same speed.

PLAYBACK_SPEED_INVALID

Added in 1.1.0
public static final int PLAYBACK_SPEED_INVALID = -1

Invalid playback speed.

PLAYBACK_SPEED_NORMAL

Added in 1.1.0
public static final int PLAYBACK_SPEED_NORMAL = 1

Speed representing playback state that is playing normally.

PLAYBACK_SPEED_PAUSED

Added in 1.1.0
public static final int PLAYBACK_SPEED_PAUSED = 0

Speed representing playback state that is paused.

Public constructors

PlaybackControlGlue

Added in 1.1.0
public PlaybackControlGlue(Context context, int[] seekSpeeds)

Constructor for the glue.

Parameters
Context context
int[] seekSpeeds

Array of seek speeds for fast forward and rewind.

PlaybackControlGlue

Added in 1.1.0
public PlaybackControlGlue(
    Context context,
    int[] fastForwardSpeeds,
    int[] rewindSpeeds
)

Constructor for the glue.

Parameters
Context context
int[] fastForwardSpeeds

Array of seek speeds for fast forward.

int[] rewindSpeeds

Array of seek speeds for rewind.

Public methods

enableProgressUpdating

Added in 1.1.0
public void enableProgressUpdating(boolean enable)

Override this to start/stop a runnable to call updateProgress at an interval such as getUpdatePeriod.

getControlsRow

Added in 1.1.0
public PlaybackControlsRow getControlsRow()

Returns the playback controls row managed by the glue layer.

getControlsRowPresenter

Added in 1.1.0
Deprecated in 1.1.0
public PlaybackControlsRowPresenter getControlsRowPresenter()

Returns the playback controls row Presenter managed by the glue layer.

getCurrentPosition

Added in 1.1.0
public abstract int getCurrentPosition()

Returns the current position of the media item in milliseconds.

getCurrentSpeedId

Added in 1.1.0
public abstract int getCurrentSpeedId()

Returns the current playback speed. When playing normally, PLAYBACK_SPEED_NORMAL should be returned.

getFastForwardSpeeds

Added in 1.1.0
public int[] getFastForwardSpeeds()

Returns the fast forward speeds.

getMediaArt

Added in 1.1.0
public abstract Drawable getMediaArt()

Returns a bitmap of the art for the media item.

getMediaDuration

Added in 1.1.0
public abstract int getMediaDuration()

Returns the duration of the media item in milliseconds.

getMediaSubtitle

Added in 1.1.0
public abstract CharSequence getMediaSubtitle()

Returns the subtitle of the media item.

getMediaTitle

Added in 1.1.0
public abstract CharSequence getMediaTitle()

Returns the title of the media item.

getPlaybackRowPresenter

Added in 1.1.0
public PlaybackRowPresenter getPlaybackRowPresenter()

Returns the playback row Presenter to be passed to PlaybackGlueHost in onAttachedToHost.

getRewindSpeeds

Added in 1.1.0
public int[] getRewindSpeeds()

Returns the rewind speeds.

getSupportedActions

Added in 1.1.0
public abstract long getSupportedActions()

Returns a bitmask of actions supported by the media player.

getUpdatePeriod

Added in 1.1.0
public int getUpdatePeriod()

Returns the time period in milliseconds that should be used to update the progress. See updateProgress.

hasValidMedia

Added in 1.1.0
public abstract boolean hasValidMedia()

Returns true if there is a valid media item.

isFadingEnabled

Added in 1.1.0
public boolean isFadingEnabled()

Returns true if controls are set to fade when media is playing.

isMediaPlaying

Added in 1.1.0
public abstract boolean isMediaPlaying()

Returns true if media is currently playing.

isPlaying

public boolean isPlaying()

Returns true if media is currently playing.

onActionClicked

Added in 1.2.0-alpha04
public void onActionClicked(Action action)

Handles action clicks. A subclass may override this add support for additional actions.

onKey

Added in 1.1.0
public boolean onKey(View v, int keyCode, KeyEvent event)

Handles key events and returns true if handled. A subclass may override this to provide additional support.

play

Added in 1.2.0-alpha04
public final void play()

Starts the media player. Does nothing if isPrepared is false. To wait isPrepared to be true before playing, use playWhenPrepared.

play

Added in 1.1.0
public void play(int speed)

Start playback at the given speed.

Parameters
int speed

The desired playback speed. For normal playback this will be PLAYBACK_SPEED_NORMAL; higher positive values for fast forward, and negative values for rewind.

setControlsRow

Added in 1.1.0
public void setControlsRow(PlaybackControlsRow controlsRow)

Sets the controls row to be managed by the glue layer. The primary actions and playback state related aspects of the row are updated by the glue.

setControlsRowPresenter

Added in 1.1.0
Deprecated in 1.1.0
public void setControlsRowPresenter(PlaybackControlsRowPresenter presenter)

Sets the controls row Presenter to be managed by the glue layer.

setFadingEnabled

Added in 1.1.0
public void setFadingEnabled(boolean enable)

Sets the controls to fade after a timeout when media is playing.

setPlaybackRowPresenter

Added in 1.1.0
public void setPlaybackRowPresenter(PlaybackRowPresenter presenter)

Sets the controls row Presenter to be passed to PlaybackGlueHost in onAttachedToHost.

updateProgress

Added in 1.1.0
public void updateProgress()

Updates the progress bar based on the current media playback position.

Protected methods

onAttachedToHost

protected void onAttachedToHost(@NonNull PlaybackGlueHost host)

This method is called attached to associated PlaybackGlueHost. Subclass may override and call super.onAttachedToHost().

onCreateControlsRowAndPresenter

Added in 1.1.0
protected void onCreateControlsRowAndPresenter()

Instantiating a PlaybackControlsRow and corresponding PlaybackControlsRowPresenter. Subclass may override.

onCreatePrimaryActions

Added in 1.1.0
protected void onCreatePrimaryActions(SparseArrayObjectAdapter primaryActionsAdapter)

May be overridden to add primary actions to the adapter.

Parameters
SparseArrayObjectAdapter primaryActionsAdapter

The adapter to add primary Actions.

onCreateSecondaryActions

Added in 1.1.0
protected void onCreateSecondaryActions(ArrayObjectAdapter secondaryActionsAdapter)

May be overridden to add secondary actions to the adapter.

Parameters
ArrayObjectAdapter secondaryActionsAdapter

The adapter you need to add the Actions to.

onDetachedFromHost

protected void onDetachedFromHost()

This method is called when current associated PlaybackGlueHost is attached to a different PlaybackGlue or PlaybackGlueHost is destroyed . Subclass may override and call super.onDetachedFromHost() at last. A typical PlaybackGlue will release resources (e.g. MediaPlayer or connection to playback service) in this method.

onHostStart

protected void onHostStart()

This method is called when PlaybackGlueHost is started. Subclass may override.

onHostStop

protected void onHostStop()

This method is called when PlaybackGlueHost is stopped. Subclass may override.

onMetadataChanged

Added in 1.1.0
protected void onMetadataChanged()

Must be called appropriately by a subclass when the metadata state has changed.

onStateChanged

Added in 1.1.0
protected void onStateChanged()

Must be called appropriately by a subclass when the playback state has changed. It updates the playback state displayed on the media player.