added in version 25.4.0
belongs to Maven artifact com.android.support:leanback-v17:28.0.0-alpha1
Deprecated since version 27.1.0

DetailsFragmentBackgroundController

public class DetailsFragmentBackgroundController
extends Object

java.lang.Object
   ↳ android.support.v17.leanback.app.DetailsFragmentBackgroundController


This class was deprecated in API level 27.1.0.
use DetailsSupportFragmentBackgroundController

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 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 play() when fragment starts and 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

DetailsFragmentBackgroundController(DetailsFragment fragment)

Creates a DetailsFragmentBackgroundController for a DetailsFragment.

Public methods

boolean canNavigateToVideoFragment()

Precondition allows user navigate to video fragment using DPAD.

void enableParallax(Drawable coverDrawable, Drawable bottomDrawable, ParallaxTarget.PropertyValuesHolderTarget coverDrawableParallaxTarget)

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

void enableParallax()

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

final Fragment findOrCreateVideoFragment()

Adds or gets fragment for rendering video in DetailsFragment.

final Drawable getBottomDrawable()

Returns the drawable at bottom.

final Bitmap getCoverBitmap()

Returns Bitmap set by setCoverBitmap(Bitmap).

final Drawable getCoverDrawable()

Returns the cover drawable at top.

final int getParallaxDrawableMaxOffset()

Returns Default parallax offset in pixels for bitmap moving vertically.

final PlaybackGlue getPlaybackGlue()

Returns current PlaybackGlue or null if not set or cleared.

final int getSolidColor()

Returns color set by setSolidColor(int).

PlaybackGlueHost onCreateGlueHost()

Creates a PlaybackGlueHost to host PlaybackGlue.

Fragment onCreateVideoFragment()

Creates a Fragment to host PlaybackGlue.

final void setCoverBitmap(Bitmap bitmap)

Convenient method to set Bitmap in cover drawable.

final void setParallaxDrawableMaxOffset(int offset)

Sets default parallax offset in pixels for bitmap moving vertically.

final void setSolidColor(int color)

Convenient method to set color in bottom drawable.

void setupVideoPlayback(PlaybackGlue playbackGlue)

Enable video playback and set proper PlaybackGlueHost.

final void switchToRows()

Switch to rows fragment.

final void switchToVideo()

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

Inherited methods

From class java.lang.Object

Public constructors

DetailsFragmentBackgroundController

added in version 25.4.0
DetailsFragmentBackgroundController (DetailsFragment fragment)

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.

Throws
IllegalStateException If fragment was already associated with another controller.

Public methods

canNavigateToVideoFragment

added in version 25.4.0
boolean canNavigateToVideoFragment ()

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 isPrepared() is true. Note this method does not block app calls switchToVideo().

Returns
boolean True allow to navigate to video fragment.

enableParallax

added in version 25.4.0
void enableParallax (Drawable coverDrawable, 
                Drawable bottomDrawable, 
                ParallaxTarget.PropertyValuesHolderTarget coverDrawableParallaxTarget)

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 ParallaxTarget.PropertyValuesHolderTarget: 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))

Throws
IllegalStateException If setupVideoPlayback(PlaybackGlue) was called.

enableParallax

added in version 25.4.0
void enableParallax ()

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

Throws
IllegalStateException If setupVideoPlayback(PlaybackGlue) was called.

findOrCreateVideoFragment

added in version 25.4.0
Fragment findOrCreateVideoFragment ()

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.

Returns
Fragment Fragment the added or restored fragment responsible for rendering video.

See also:

getBottomDrawable

added in version 25.4.0
Drawable getBottomDrawable ()

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

Returns
Drawable The bottom drawable.

getCoverBitmap

added in version 25.4.0
Bitmap getCoverBitmap ()

Returns Bitmap set by setCoverBitmap(Bitmap).

Returns
Bitmap Bitmap for cover drawable.

getCoverDrawable

added in version 25.4.0
Drawable getCoverDrawable ()

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

Returns
Drawable The cover drawable at top.

getParallaxDrawableMaxOffset

added in version 25.4.0
int getParallaxDrawableMaxOffset ()

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

Returns
int Default parallax offset in pixels for bitmap moving vertically.

See also:

getPlaybackGlue

added in version 25.4.0
PlaybackGlue getPlaybackGlue ()

Returns current PlaybackGlue or null if not set or cleared.

Returns
PlaybackGlue Current PlaybackGlue or null

getSolidColor

added in version 25.4.0
int getSolidColor ()

Returns color set by setSolidColor(int).

Returns
int Solid color used for bottom drawable.

onCreateGlueHost

added in version 25.4.0
PlaybackGlueHost onCreateGlueHost ()

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.

Returns
PlaybackGlueHost A new PlaybackGlueHost to host PlaybackGlue.

onCreateVideoFragment

added in version 25.4.0
Fragment onCreateVideoFragment ()

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

Returns
Fragment A new fragment used in onCreateGlueHost().

setCoverBitmap

added in version 25.4.0
void setCoverBitmap (Bitmap bitmap)

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.

setParallaxDrawableMaxOffset

added in version 25.4.0
void setParallaxDrawableMaxOffset (int offset)

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

See also:

setSolidColor

added in version 25.4.0
void setSolidColor (int color)

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

added in version 25.4.0
void setupVideoPlayback (PlaybackGlue playbackGlue)

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

switchToRows

added in version 25.4.0
void switchToRows ()

Switch to rows fragment.

switchToVideo

added in version 25.4.0
void switchToVideo ()

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 prepareEntranceTransition() and before onEntranceTransitionEnd(), it will be ignored.

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