BackgroundManager

class BackgroundManager

Supports background image continuity between multiple Activities.

An Activity should instantiate a BackgroundManager and attach 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:

  • the background Drawable of the theme
  • a solid color (set via setColor)
  • two Drawables, previous and current (set via setBitmap or setDrawable), which may be in transition

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

Summary

Public functions
Unit
attach(window: Window!)

Makes the background visible on the given Window.
Unit
attachToView(sceneRoot: View!)

Adds the composite drawable to the given view.
Unit

Clears the Drawable set by setDrawable or setBitmap.
@ColorInt Int

Returns the current background color.
Drawable!

This function is deprecated.

No longer support dim layer.
Drawable!

This function is deprecated.

No longer support dim layer.
Drawable!

Returns the current background Drawable.
java-static BackgroundManager!
getInstance(activity: Activity!)

Returns the BackgroundManager associated with the given Activity.
Boolean

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

Release references to Drawable/Bitmap.
Unit
setAutoReleaseOnStop(autoReleaseOnStop: Boolean)

Enable or disable call release() in Activity onStop().
Unit
setBitmap(bitmap: Bitmap!)

Sets the given bitmap into the background.
Unit

Sets the background to the given color.
Unit
setDimLayer(drawable: Drawable!)

This function is deprecated.

No longer support dim layer.
Unit
setDrawable(drawable: Drawable!)

Sets the given drawable into the background.
Unit

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

Public functions

attach

Added in 1.1.0
fun attach(window: Window!): Unit

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

attachToView

Added in 1.1.0
fun attachToView(sceneRoot: View!): Unit

Adds the composite drawable to the given view.

clearDrawable

Added in 1.1.0
fun clearDrawable(): Unit

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

getColor

Added in 1.1.0
fun getColor(): @ColorInt Int

Returns the current background color.

getDefaultDimLayer

Added in 1.1.0
Deprecated in 1.1.0
fun getDefaultDimLayer(): Drawable!

Returns the default drawable used as a dim layer.

getDimLayer

Added in 1.1.0
Deprecated in 1.1.0
fun getDimLayer(): Drawable!

Returns the drawable used as a dim layer.

getDrawable

Added in 1.1.0
fun getDrawable(): Drawable!

Returns the current background Drawable.

getInstance

Added in 1.1.0
java-static fun getInstance(activity: Activity!): BackgroundManager!

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.

isAttached

Added in 1.1.0
fun isAttached(): Boolean

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

isAutoReleaseOnStop

Added in 1.1.0
fun isAutoReleaseOnStop(): Boolean
Returns
Boolean

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

release

Added in 1.1.0
fun release(): Unit

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.

See also
setAutoReleaseOnStop

setAutoReleaseOnStop

Added in 1.1.0
fun setAutoReleaseOnStop(autoReleaseOnStop: Boolean): Unit

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

Parameters
autoReleaseOnStop: Boolean

True to call release() in Activity onStop(), false otherwise.

setBitmap

Added in 1.1.0
fun setBitmap(bitmap: Bitmap!): Unit

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.

setColor

Added in 1.1.0
fun setColor(color: @ColorInt Int): Unit

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.

setDimLayer

Added in 1.1.0
Deprecated in 1.1.0
fun setDimLayer(drawable: Drawable!): Unit

Sets the drawable used as a dim layer.

setDrawable

Added in 1.1.0
fun setDrawable(drawable: Drawable!): Unit

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.

setThemeDrawableResourceId

Added in 1.1.0
fun setThemeDrawableResourceId(resourceId: Int): Unit

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.