lightbulb_outline Please take our October 2018 developer survey. Start survey
added in version 1.0.0
belongs to Maven artifact androidx.leanback:leanback:1.0.0

PlaybackControlGlue

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

java.lang.Object
   ↳ androidx.leanback.media.PlaybackGlue
     ↳ androidx.leanback.media.PlaybackControlGlue


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(PlaybackControlsRow) and setPlaybackRowPresenter(PlaybackRowPresenter) 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(SparseArrayObjectAdapter). 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(Action).

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 RowPresenter.ViewHolder.setOnKeyListener(android.view.View.OnKeyListener).

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

Summary

Constants

int ACTION_CUSTOM_LEFT_FIRST

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

int ACTION_CUSTOM_RIGHT_FIRST

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

int ACTION_FAST_FORWARD

The adapter key for the fast forward control.

int ACTION_PLAY_PAUSE

The adapter key for the play/pause control.

int ACTION_REWIND

The adapter key for the rewind control.

int ACTION_SKIP_TO_NEXT

The adapter key for the skip to next control.

int ACTION_SKIP_TO_PREVIOUS

The adapter key for the skip to previous control.

int PLAYBACK_SPEED_FAST_L0

The initial (level 0) fast forward playback speed.

int PLAYBACK_SPEED_FAST_L1

The level 1 fast forward playback speed.

int PLAYBACK_SPEED_FAST_L2

The level 2 fast forward playback speed.

int PLAYBACK_SPEED_FAST_L3

The level 3 fast forward playback speed.

int PLAYBACK_SPEED_FAST_L4

The level 4 fast forward playback speed.

int PLAYBACK_SPEED_INVALID

Invalid playback speed.

int PLAYBACK_SPEED_NORMAL

Speed representing playback state that is playing normally.

int PLAYBACK_SPEED_PAUSED

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 getControlsRow()

Returns the playback controls row managed by the glue layer.

PlaybackControlsRowPresenter getControlsRowPresenter()

This method was deprecated in API level 1.0.0. PlaybackControlGlue supports any PlaybackRowPresenter, use getPlaybackRowPresenter().

abstract int getCurrentPosition()

Returns the current position of the media item in milliseconds.

abstract int getCurrentSpeedId()

Returns the current playback speed.

int[] getFastForwardSpeeds()

Returns the fast forward speeds.

abstract Drawable getMediaArt()

Returns a bitmap of the art for the media item.

abstract int getMediaDuration()

Returns the duration of the media item in milliseconds.

abstract CharSequence getMediaSubtitle()

Returns the subtitle of the media item.

abstract CharSequence getMediaTitle()

Returns the title of the media item.

PlaybackRowPresenter getPlaybackRowPresenter()

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

int[] getRewindSpeeds()

Returns the rewind speeds.

abstract long getSupportedActions()

Returns a bitmask of actions supported by the media player.

int getUpdatePeriod()

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

abstract boolean hasValidMedia()

Returns true if there is a valid media item.

boolean isFadingEnabled()

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

abstract boolean isMediaPlaying()

Returns true if media is currently playing.

boolean isPlaying()

Returns true if media is currently playing.

void onActionClicked(Action action)

Handles action clicks.

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

Handles key events and returns true if handled.

void play(int speed)

Start playback at the given speed.

final void play()

Starts the media player.

void setControlsRow(PlaybackControlsRow controlsRow)

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

void setControlsRowPresenter(PlaybackControlsRowPresenter presenter)

This method was deprecated in API level 1.0.0. PlaybackControlGlue supports any PlaybackRowPresenter, use setPlaybackRowPresenter(PlaybackRowPresenter).

void setFadingEnabled(boolean enable)

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

void setPlaybackRowPresenter(PlaybackRowPresenter presenter)

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

void updateProgress()

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

Protected methods

void onAttachedToHost(PlaybackGlueHost host)

This method is called attached to associated PlaybackGlueHost.

void onCreateControlsRowAndPresenter()

Instantiating a PlaybackControlsRow and corresponding PlaybackControlsRowPresenter.

void onCreatePrimaryActions(SparseArrayObjectAdapter primaryActionsAdapter)

May be overridden to add primary actions to the adapter.

void onCreateSecondaryActions(ArrayObjectAdapter secondaryActionsAdapter)

May be overridden to add secondary actions to the adapter.

void onDetachedFromHost()

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

void onHostStart()

This method is called when {@link PlaybackGlueHost is started.

void onHostStop()

This method is called when {@link PlaybackGlueHost is stopped.

void onMetadataChanged()

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

void onStateChanged()

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

Inherited methods

Constants

ACTION_CUSTOM_LEFT_FIRST

added in version 1.0.0
public static final int ACTION_CUSTOM_LEFT_FIRST

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

Constant Value: 1 (0x00000001)

ACTION_CUSTOM_RIGHT_FIRST

added in version 1.0.0
public static final int ACTION_CUSTOM_RIGHT_FIRST

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

Constant Value: 4096 (0x00001000)

ACTION_FAST_FORWARD

added in version 1.0.0
public static final int ACTION_FAST_FORWARD

The adapter key for the fast forward control.

Constant Value: 128 (0x00000080)

ACTION_PLAY_PAUSE

added in version 1.0.0
public static final int ACTION_PLAY_PAUSE

The adapter key for the play/pause control.

Constant Value: 64 (0x00000040)

ACTION_REWIND

added in version 1.0.0
public static final int ACTION_REWIND

The adapter key for the rewind control.

Constant Value: 32 (0x00000020)

ACTION_SKIP_TO_NEXT

added in version 1.0.0
public static final int ACTION_SKIP_TO_NEXT

The adapter key for the skip to next control.

Constant Value: 256 (0x00000100)

ACTION_SKIP_TO_PREVIOUS

added in version 1.0.0
public static final int ACTION_SKIP_TO_PREVIOUS

The adapter key for the skip to previous control.

Constant Value: 16 (0x00000010)

PLAYBACK_SPEED_FAST_L0

added in version 1.0.0
public static final int PLAYBACK_SPEED_FAST_L0

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

Constant Value: 10 (0x0000000a)

PLAYBACK_SPEED_FAST_L1

added in version 1.0.0
public static final int PLAYBACK_SPEED_FAST_L1

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

Constant Value: 11 (0x0000000b)

PLAYBACK_SPEED_FAST_L2

added in version 1.0.0
public static final int PLAYBACK_SPEED_FAST_L2

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

Constant Value: 12 (0x0000000c)

PLAYBACK_SPEED_FAST_L3

added in version 1.0.0
public static final int PLAYBACK_SPEED_FAST_L3

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

Constant Value: 13 (0x0000000d)

PLAYBACK_SPEED_FAST_L4

added in version 1.0.0
public static final int PLAYBACK_SPEED_FAST_L4

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

Constant Value: 14 (0x0000000e)

PLAYBACK_SPEED_INVALID

added in version 1.0.0
public static final int PLAYBACK_SPEED_INVALID

Invalid playback speed.

Constant Value: -1 (0xffffffff)

PLAYBACK_SPEED_NORMAL

added in version 1.0.0
public static final int PLAYBACK_SPEED_NORMAL

Speed representing playback state that is playing normally.

Constant Value: 1 (0x00000001)

PLAYBACK_SPEED_PAUSED

added in version 1.0.0
public static final int PLAYBACK_SPEED_PAUSED

Speed representing playback state that is paused.

Constant Value: 0 (0x00000000)

Public constructors

PlaybackControlGlue

added in version 1.0.0
public PlaybackControlGlue (Context context, 
                int[] seekSpeeds)

Constructor for the glue.

Parameters
seekSpeeds int: Array of seek speeds for fast forward and rewind.

PlaybackControlGlue

added in version 1.0.0
public PlaybackControlGlue (Context context, 
                int[] fastForwardSpeeds, 
                int[] rewindSpeeds)

Constructor for the glue.

Parameters
fastForwardSpeeds int: Array of seek speeds for fast forward.

rewindSpeeds int: Array of seek speeds for rewind.

Public methods

enableProgressUpdating

added in version 1.0.0
public void enableProgressUpdating (boolean enable)

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

Parameters
enable boolean

getControlsRow

added in version 1.0.0
public PlaybackControlsRow getControlsRow ()

Returns the playback controls row managed by the glue layer.

Returns
PlaybackControlsRow

getControlsRowPresenter

added in version 1.0.0
public PlaybackControlsRowPresenter getControlsRowPresenter ()

This method was deprecated in API level 1.0.0.
PlaybackControlGlue supports any PlaybackRowPresenter, use getPlaybackRowPresenter().

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

Returns
PlaybackControlsRowPresenter

getCurrentPosition

added in version 1.0.0
public abstract int getCurrentPosition ()

Returns the current position of the media item in milliseconds.

Returns
int

getCurrentSpeedId

added in version 1.0.0
public abstract int getCurrentSpeedId ()

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

Returns
int

getFastForwardSpeeds

added in version 1.0.0
public int[] getFastForwardSpeeds ()

Returns the fast forward speeds.

Returns
int[]

getMediaArt

added in version 1.0.0
public abstract Drawable getMediaArt ()

Returns a bitmap of the art for the media item.

Returns
Drawable

getMediaDuration

added in version 1.0.0
public abstract int getMediaDuration ()

Returns the duration of the media item in milliseconds.

Returns
int

getMediaSubtitle

added in version 1.0.0
public abstract CharSequence getMediaSubtitle ()

Returns the subtitle of the media item.

Returns
CharSequence

getMediaTitle

added in version 1.0.0
public abstract CharSequence getMediaTitle ()

Returns the title of the media item.

Returns
CharSequence

getPlaybackRowPresenter

added in version 1.0.0
public PlaybackRowPresenter getPlaybackRowPresenter ()

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

Returns
PlaybackRowPresenter

getRewindSpeeds

added in version 1.0.0
public int[] getRewindSpeeds ()

Returns the rewind speeds.

Returns
int[]

getSupportedActions

added in version 1.0.0
public abstract long getSupportedActions ()

Returns a bitmask of actions supported by the media player.

Returns
long

getUpdatePeriod

added in version 1.0.0
public int getUpdatePeriod ()

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

Returns
int

hasValidMedia

added in version 1.0.0
public abstract boolean hasValidMedia ()

Returns true if there is a valid media item.

Returns
boolean

isFadingEnabled

added in version 1.0.0
public boolean isFadingEnabled ()

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

Returns
boolean

isMediaPlaying

added in version 1.0.0
public abstract boolean isMediaPlaying ()

Returns true if media is currently playing.

Returns
boolean

isPlaying

added in version 1.0.0
public boolean isPlaying ()

Returns true if media is currently playing.

Returns
boolean

onActionClicked

added in version 1.0.0
public void onActionClicked (Action action)

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

Parameters
action Action

onKey

added in version 1.0.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.

Parameters
v View

keyCode int

event KeyEvent

Returns
boolean

play

added in version 1.0.0
public void play (int speed)

Start playback at the given speed.

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

play

added in version 1.0.0
public final void play ()

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

setControlsRow

added in version 1.0.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.

Parameters
controlsRow PlaybackControlsRow

setControlsRowPresenter

added in version 1.0.0
public void setControlsRowPresenter (PlaybackControlsRowPresenter presenter)

This method was deprecated in API level 1.0.0.
PlaybackControlGlue supports any PlaybackRowPresenter, use setPlaybackRowPresenter(PlaybackRowPresenter).

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

Parameters
presenter PlaybackControlsRowPresenter

setFadingEnabled

added in version 1.0.0
public void setFadingEnabled (boolean enable)

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

Parameters
enable boolean

setPlaybackRowPresenter

added in version 1.0.0
public void setPlaybackRowPresenter (PlaybackRowPresenter presenter)

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

Parameters
presenter PlaybackRowPresenter

updateProgress

added in version 1.0.0
public void updateProgress ()

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

Protected methods

onAttachedToHost

added in version 1.0.0
protected void onAttachedToHost (PlaybackGlueHost host)

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

Parameters
host PlaybackGlueHost

onCreateControlsRowAndPresenter

added in version 1.0.0
protected void onCreateControlsRowAndPresenter ()

Instantiating a PlaybackControlsRow and corresponding PlaybackControlsRowPresenter. Subclass may override.

onCreatePrimaryActions

added in version 1.0.0
protected void onCreatePrimaryActions (SparseArrayObjectAdapter primaryActionsAdapter)

May be overridden to add primary actions to the adapter.

Parameters
primaryActionsAdapter SparseArrayObjectAdapter: The adapter to add primary Actions.

onCreateSecondaryActions

added in version 1.0.0
protected void onCreateSecondaryActions (ArrayObjectAdapter secondaryActionsAdapter)

May be overridden to add secondary actions to the adapter.

Parameters
secondaryActionsAdapter ArrayObjectAdapter: The adapter you need to add the Actions to.

onDetachedFromHost

added in version 1.0.0
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

added in version 1.0.0
protected void onHostStart ()

This method is called when {@link PlaybackGlueHost is started. Subclass may override.

onHostStop

added in version 1.0.0
protected void onHostStop ()

This method is called when {@link PlaybackGlueHost is stopped. Subclass may override.

onMetadataChanged

added in version 1.0.0
protected void onMetadataChanged ()

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

onStateChanged

added in version 1.0.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.