Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.
Android 0.0.0 Developer Preview
belongs to Maven artifact androidx.leanback:leanback:1.1.0-alpha01

BackgroundManager

public final class BackgroundManager
extends Object

java.lang.Object
   ↳ androidx.leanback.app.BackgroundManager


Supports background image continuity between multiple Activities.

An Activity should instantiate a BackgroundManager and attach(Window) to the Activity's window. When the Activity is started, the background is initialized to the current background values stored in a continuity service. The background continuity service is updated as the background is updated.

At some point, for example when it is stopped, the Activity may release its background state.

When an Activity is resumed, if the BackgroundManager has not been released, the continuity service is updated from the BackgroundManager state. If the BackgroundManager was released, the BackgroundManager inherits the current state from the continuity service.

When the last Activity is destroyed, the background state is reset.

Backgrounds consist of several layers, from back to front:

BackgroundManager holds references to potentially large bitmap Drawables. Call release() to release these references when the Activity is not visible.

Summary

Public methods

void attach(Window window)

Makes the background visible on the given Window.

void attachToView(View sceneRoot)

Adds the composite drawable to the given view.

void clearDrawable()

Clears the Drawable set by setDrawable(Drawable) or setBitmap(Bitmap).

int getColor()

Returns the current background color.

Drawable getDefaultDimLayer()

This method was deprecated in API level 0.0.0. No longer support dim layer.

Drawable getDimLayer()

This method was deprecated in API level 0.0.0. No longer support dim layer.

Drawable getDrawable()

Returns the current background Drawable.

static BackgroundManager getInstance(Activity activity)

Returns the BackgroundManager associated with the given Activity.

boolean isAttached()

Returns true if the background manager is currently attached; false otherwise.

boolean isAutoReleaseOnStop()
void release()

Release references to Drawable/Bitmap.

void setAutoReleaseOnStop(boolean autoReleaseOnStop)

Enable or disable call release() in Activity onStop().

void setBitmap(Bitmap bitmap)

Sets the given bitmap into the background.

void setColor(int color)

Sets the background to the given color.

void setDimLayer(Drawable drawable)

This method was deprecated in API level 0.0.0. No longer support dim layer.

void setDrawable(Drawable drawable)

Sets the given drawable into the background.

void setThemeDrawableResourceId(int resourceId)

Sets the resource id for the drawable to be shown when there is no background set.

Inherited methods

Public methods

attach

public void attach (Window window)

Makes the background visible on the given Window. The background manager must be attached when the background is set.

Parameters
window Window

attachToView

public void attachToView (View sceneRoot)

Adds the composite drawable to the given view.

Parameters
sceneRoot View

clearDrawable

public void clearDrawable ()

Clears the Drawable set by setDrawable(Drawable) or setBitmap(Bitmap). BackgroundManager will show a solid color set by setColor(int) or theme drawable if color is not provided.

getColor

public int getColor ()

Returns the current background color.

Returns
int

getDefaultDimLayer

public Drawable getDefaultDimLayer ()

This method was deprecated in API level 0.0.0.
No longer support dim layer.

Returns the default drawable used as a dim layer.

Returns
Drawable

getDimLayer

public Drawable getDimLayer ()

This method was deprecated in API level 0.0.0.
No longer support dim layer.

Returns the drawable used as a dim layer.

Returns
Drawable

getDrawable

public Drawable getDrawable ()

Returns the current background Drawable.

Returns
Drawable

getInstance

public static BackgroundManager getInstance (Activity activity)

Returns the BackgroundManager associated with the given Activity.

The BackgroundManager will be created on-demand for each individual Activity. Subsequent calls will return the same BackgroundManager created for this Activity.

Parameters
activity Activity

Returns
BackgroundManager

isAttached

public boolean isAttached ()

Returns true if the background manager is currently attached; false otherwise.

Returns
boolean

isAutoReleaseOnStop

public boolean isAutoReleaseOnStop ()

Returns
boolean True if release() in Activity.onStop(), false otherwise.

release

public void release ()

Release references to Drawable/Bitmap. Typically called in Activity onStop() to reduce memory overhead when not visible. It's app's responsibility to restore the drawable/bitmap in Activity onStart(). The method is automatically called in onStop() when isAutoReleaseOnStop() is true.

setAutoReleaseOnStop

public void setAutoReleaseOnStop (boolean autoReleaseOnStop)

Enable or disable call release() in Activity onStop(). Default is true.

Parameters
autoReleaseOnStop boolean: True to call release() in Activity onStop(), false otherwise.

setBitmap

public void setBitmap (Bitmap bitmap)

Sets the given bitmap into the background. When using setCoverImageBitmap to set the background, the provided bitmap will be scaled and cropped to correctly fit within the dimensions of the view. The timing for when this becomes visible in the app is undefined and may take place after a small delay.

Parameters
bitmap Bitmap

setColor

public void setColor (int color)

Sets the background to the given color. The timing for when this becomes visible in the app is undefined and may take place after a small delay.

Parameters
color int

setDimLayer

public void setDimLayer (Drawable drawable)

This method was deprecated in API level 0.0.0.
No longer support dim layer.

Sets the drawable used as a dim layer.

Parameters
drawable Drawable

setDrawable

public void setDrawable (Drawable drawable)

Sets the given drawable into the background. The provided Drawable will be used unmodified as the background, without any scaling or cropping applied to it. The timing for when this becomes visible in the app is undefined and may take place after a small delay.

Parameters
drawable Drawable

setThemeDrawableResourceId

public void setThemeDrawableResourceId (int resourceId)

Sets the resource id for the drawable to be shown when there is no background set. Overrides the window background drawable from the theme. This should be called before attaching.

Parameters
resourceId int