DetailsFragmentBackgroundController

open class DetailsFragmentBackgroundController
kotlin.Any
   ↳ androidx.leanback.app.DetailsFragmentBackgroundController

Controller for DetailsFragment parallax background and embedded video play.

The parallax background drawable is made of two parts: cover drawable (by default FitWidthBitmapDrawable) above the details overview row and bottom drawable (by default ColorDrawable) below the details overview row. While vertically scrolling rows, the size of cover drawable and bottom drawable will be updated and the cover drawable will by default perform a parallax shift using FitWidthBitmapDrawable#PROPERTY_VERTICAL_OFFSET.

 *************************** * Cover Drawable * * (FitWidthBitmapDrawable)* * * *************************** * DetailsOverviewRow * * * *************************** * Bottom Drawable * * (ColorDrawable) * * Related * * Content * *************************** 
Both parallax background drawable and embedded video play are optional. App must call #enableParallax() and/or #setupVideoPlayback(PlaybackGlue) explicitly. The PlaybackGlue is automatically PlaybackGlue#play() when fragment starts and PlaybackGlue#pause() when fragment stops. When video is ready to play, cover drawable will be faded out. Example:
 DetailsFragmentBackgroundController mController = new DetailsFragmentBackgroundController(this); public void onCreate(Bundle savedInstance) { super.onCreate(savedInstance); MediaPlayerGlue player = new MediaPlayerGlue(..); player.setUrl(...); mController.enableParallax(); mController.setupVideoPlayback(player); } static class MyLoadBitmapTask extends ... { WeakReference mFragmentRef; MyLoadBitmapTask(MyFragment fragment) { mFragmentRef = new WeakReference(fragment); } protected void onPostExecute(Bitmap bitmap) { MyFragment fragment = mFragmentRef.get(); if (fragment != null) { fragment.mController.setCoverBitmap(bitmap); } } } public void onStart() { new MyLoadBitmapTask(this).execute(url); } public void onStop() { mController.setCoverBitmap(null); } 

To customize cover drawable and/or bottom drawable, app should call #enableParallax(Drawable, Drawable, ParallaxTarget.PropertyValuesHolderTarget). If app supplies a custom cover Drawable, it should not call #setCoverBitmap(Bitmap). If app supplies a custom bottom Drawable, it should not call #setSolidColor(int).

To customize playback fragment, app should override #onCreateVideoFragment() and #onCreateGlueHost().

Summary

Public constructors
<init>(fragment: DetailsFragment!)

Creates a DetailsFragmentBackgroundController for a DetailsFragment.

Public methods
Int

Returns Default parallax offset in pixels for bitmap moving vertically.

Drawable!

Returns the cover drawable at top.

Int

Returns color set by #setSolidColor(int).

Fragment!

Adds or gets fragment for rendering video in DetailsFragment.

Unit

Convenient method to set Bitmap in cover drawable.

open PlaybackGlueHost!

Creates a PlaybackGlueHost to host PlaybackGlue.

Unit

Sets default parallax offset in pixels for bitmap moving vertically.

open Boolean

Precondition allows user navigate to video fragment using DPAD.

open Fragment!

Creates a Fragment to host PlaybackGlue.

open Unit

Enables default parallax background using a FitWidthBitmapDrawable as cover drawable and ColorDrawable as bottom drawable.

open Unit
enableParallax(coverDrawable: Drawable, bottomDrawable: Drawable, coverDrawableParallaxTarget: ParallaxTarget.PropertyValuesHolderTarget?)

Enables parallax background using a custom cover drawable at top and a custom bottom drawable.

Unit

Switch to rows fragment.

PlaybackGlue!

Returns current PlaybackGlue or null if not set or cleared.

Unit

Convenient method to set color in bottom drawable.

open Unit

Enable video playback and set proper PlaybackGlueHost.

Drawable!

Returns the drawable at bottom.

Bitmap!

Returns Bitmap set by #setCoverBitmap(Bitmap).

Unit

Switch to video fragment, note that this method is not affected by result of #canNavigateToVideoFragment().

Public constructors

<init>

DetailsFragmentBackgroundController(fragment: DetailsFragment!)

Creates a DetailsFragmentBackgroundController for a DetailsFragment. Note that each DetailsFragment can only associate with one DetailsFragmentBackgroundController.

Parameters
fragment DetailsFragment!: The DetailsFragment to control background and embedded video playing.
Exceptions
IllegalStateException If fragment was already associated with another controller.

Public methods

getParallaxDrawableMaxOffset

fun getParallaxDrawableMaxOffset(): Int

Returns Default parallax offset in pixels for bitmap moving vertically. When 0, a default value would be used.

Return
Int: Default parallax offset in pixels for bitmap moving vertically.

getCoverDrawable

fun getCoverDrawable(): Drawable!

Returns the cover drawable at top. Returns null if #enableParallax() is not called. By default it's a FitWidthBitmapDrawable.

Return
Drawable!: The cover drawable at top.

getSolidColor

fun getSolidColor(): Int

Returns color set by #setSolidColor(int).

Return
Int: Solid color used for bottom drawable.

findOrCreateVideoFragment

fun findOrCreateVideoFragment(): Fragment!

Adds or gets fragment for rendering video in DetailsFragment. A subclass that overrides #onCreateGlueHost() should call this method to get a fragment for creating a PlaybackGlueHost.

Return
Fragment!: Fragment the added or restored fragment responsible for rendering video.

setCoverBitmap

fun setCoverBitmap(bitmap: Bitmap!): Unit

Convenient method to set Bitmap in cover drawable. If app is not using default FitWidthBitmapDrawable, app should not use this method It's safe to call setCoverBitmap() before calling #enableParallax().

Parameters
bitmap Bitmap!: bitmap to set as cover.

onCreateGlueHost

open fun onCreateGlueHost(): PlaybackGlueHost!

Creates a PlaybackGlueHost to host PlaybackGlue. App may override this if it overrides #onCreateVideoFragment(). This method must be called after calling Fragment super.onCreate(). When override this method, app may call #findOrCreateVideoFragment() to get or create a fragment.

Return
PlaybackGlueHost!: A new PlaybackGlueHost to host PlaybackGlue.

setParallaxDrawableMaxOffset

fun setParallaxDrawableMaxOffset(offset: Int): Unit

Sets default parallax offset in pixels for bitmap moving vertically. This method must be called before #enableParallax().

Parameters
offset Int: Offset in pixels (e.g. 120).

canNavigateToVideoFragment

open fun canNavigateToVideoFragment(): Boolean

Precondition allows user navigate to video fragment using DPAD. Default implementation returns true if PlaybackGlue is not null. Subclass may override, e.g. only allow navigation when PlaybackGlue#isPrepared() is true. Note this method does not block app calls #switchToVideo.

Return
Boolean: True allow to navigate to video fragment.

onCreateVideoFragment

open fun onCreateVideoFragment(): Fragment!

Creates a Fragment to host PlaybackGlue. Returns a new VideoFragment by default. App may override and return a different fragment and it also must override #onCreateGlueHost().

Return
Fragment!: A new fragment used in #onCreateGlueHost().

enableParallax

open fun enableParallax(): Unit

Enables default parallax background using a FitWidthBitmapDrawable as cover drawable and ColorDrawable as bottom drawable. A vertical parallax movement will be applied to the FitWidthBitmapDrawable. App may use #setSolidColor(int) and #setCoverBitmap(Bitmap) to change the content of bottom drawable and cover drawable. This method must be called before #setupVideoPlayback(PlaybackGlue).

Exceptions
IllegalStateException If #setupVideoPlayback(PlaybackGlue) was called.

enableParallax

open fun enableParallax(coverDrawable: Drawable, bottomDrawable: Drawable, coverDrawableParallaxTarget: ParallaxTarget.PropertyValuesHolderTarget?): Unit

Enables parallax background using a custom cover drawable at top and a custom bottom drawable. This method must be called before #setupVideoPlayback(PlaybackGlue).

Parameters
coverDrawable Drawable: Custom cover drawable shown at top. #setCoverBitmap(Bitmap) will not work if coverDrawable is not FitWidthBitmapDrawable; in that case it's app's responsibility to set content into coverDrawable.
bottomDrawable Drawable: Drawable shown at bottom. #setSolidColor(int) will not work if bottomDrawable is not ColorDrawable; in that case it's app's responsibility to set content of bottomDrawable.
coverDrawableParallaxTarget Drawable: Target to perform parallax effect within coverDrawable. Use null for no parallax movement effect. Example to move bitmap within FitWidthBitmapDrawable: new ParallaxTarget.PropertyValuesHolderTarget( coverDrawable, PropertyValuesHolder.ofInt( FitWidthBitmapDrawable.PROPERTY_VERTICAL_OFFSET, 0, -120))
Exceptions
IllegalStateException If #setupVideoPlayback(PlaybackGlue) was called.

switchToRows

fun switchToRows(): Unit

Switch to rows fragment.

getPlaybackGlue

fun getPlaybackGlue(): PlaybackGlue!

Returns current PlaybackGlue or null if not set or cleared.

Return
PlaybackGlue!: Current PlaybackGlue or null

setSolidColor

fun setSolidColor(color: Int): Unit

Convenient method to set color in bottom drawable. If app is not using default ColorDrawable, app should not use this method. It's safe to call setSolidColor() before calling #enableParallax().

Parameters
color Int: color for bottom drawable.

setupVideoPlayback

open fun setupVideoPlayback(playbackGlue: PlaybackGlue): Unit

Enable video playback and set proper PlaybackGlueHost. This method by default creates a VideoFragment and VideoFragmentGlueHost to host the PlaybackGlue. This method must be called after calling details Fragment super.onCreate(). This method can be called multiple times to replace existing PlaybackGlue or calling setupVideoPlayback(null) to clear. Note a typical PlaybackGlue subclass releases resources in PlaybackGlue#onDetachedFromHost(), when the PlaybackGlue subclass is not doing that, it's app's responsibility to release the resources.

Parameters
playbackGlue PlaybackGlue: The new PlaybackGlue to set as background or null to clear existing one.

getBottomDrawable

fun getBottomDrawable(): Drawable!

Returns the drawable at bottom. Returns null if #enableParallax() is not called. By default it's a ColorDrawable.

Return
Drawable!: The bottom drawable.

getCoverBitmap

fun getCoverBitmap(): Bitmap!

Returns Bitmap set by #setCoverBitmap(Bitmap).

Return
Bitmap!: Bitmap for cover drawable.

switchToVideo

fun switchToVideo(): Unit

Switch to video fragment, note that this method is not affected by result of #canNavigateToVideoFragment(). If the method is called in DetailsFragment.onCreate() it will make video fragment to be initially focused once it is created.

Calling switchToVideo() in DetailsFragment.onCreate() will clear the activity enter transition and shared element transition.

If switchToVideo() is called after DetailsFragment#prepareEntranceTransition() and before DetailsFragment#onEntranceTransitionEnd(), it will be ignored.

If DetailsFragment#prepareEntranceTransition() is called after switchToVideo(), an IllegalStateException will be thrown.