Google is committed to advancing racial equity for Black communities. See how.

Parallax

abstract class Parallax<PropertyT : Property<Any!, Any!>!>
kotlin.Any
   ↳ androidx.leanback.widget.Parallax

Parallax tracks a list of dynamic Propertys typically representing foreground UI element positions on screen. Parallax keeps a list of ParallaxEffect objects which define rules to mapping property values to ParallaxTarget.

Example: // when Property "var1" changes from 15 to max value, perform parallax effect to // change myView's translationY from 0 to 100. Parallax parallax = new Parallax() {...}; p1 = parallax.addProperty("var1"); parallax.addEffect(p1.at(15), p1.atMax()) .target(myView, PropertyValuesHolder.ofFloat("translationY", 0, 100));

To create a ParallaxEffect, user calls addEffect(PropertyMarkerValue[]) with a list of PropertyMarkerValue which defines the range of Parallax.IntProperty or Parallax.FloatProperty. Then user adds ParallaxTarget into ParallaxEffect.

App may subclass Parallax.IntProperty or Parallax.FloatProperty to supply additional information about how to retrieve Property value. RecyclerViewParallax is a great example of Parallax implementation tracking child view positions on screen.

    Restrictions of properties
  • FloatProperty and IntProperty cannot be mixed in one Parallax
  • Values must be in ascending order.
  • If the UI element is unknown above screen, use UNKNOWN_BEFORE.
  • if the UI element is unknown below screen, use UNKNOWN_AFTER.
  • UNKNOWN_BEFORE and UNKNOWN_AFTER are not allowed to be next to each other.
These rules will be verified at runtime.

Subclass must override updateValues() to update property values and perform ParallaxEffects. Subclass may call updateValues() automatically e.g. RecyclerViewParallax calls updateValues() in RecyclerView scrolling. App might call updateValues() manually when Parallax is unaware of the value change. For example, when a slide transition is running, RecyclerViewParallax is unaware of translation value changes; it's the app's responsibility to call updateValues() in every frame of animation.

Summary

Nested classes
open

FloatProperty provide access to an index based integer type property inside Parallax.
open

IntProperty provide access to an index based integer type property inside Parallax.
open

Class holding a fixed value for a Property in Parallax.

Public constructors

Parallax tracks a list of dynamic Propertys typically representing foreground UI element positions on screen.

Public methods
open ParallaxEffect!

Create a ParallaxEffect object that will track source variable changes within a provided set of ranges.
PropertyT

Add a new IntProperty in the Parallax object.
abstract PropertyT
createProperty(name: String!, index: Int)

Create a new Property object.
open MutableList<ParallaxEffect!>!

Returns a list of ParallaxEffect object which defines rules to perform mapping to multiple ParallaxTargets.
abstract Float

Return the max value which is typically size of parent visible area, e.
MutableList<PropertyT>!

open Unit

Remove all ParallaxEffect objects.
open Unit

Remove the ParallaxEffect object.
open Unit

Update property values and perform ParallaxEffects.

Public constructors

<init>

Parallax()

Parallax tracks a list of dynamic Propertys typically representing foreground UI element positions on screen. Parallax keeps a list of ParallaxEffect objects which define rules to mapping property values to ParallaxTarget.

Example: // when Property "var1" changes from 15 to max value, perform parallax effect to // change myView's translationY from 0 to 100. Parallax parallax = new Parallax() {...}; p1 = parallax.addProperty("var1"); parallax.addEffect(p1.at(15), p1.atMax()) .target(myView, PropertyValuesHolder.ofFloat("translationY", 0, 100));

To create a ParallaxEffect, user calls addEffect(PropertyMarkerValue[]) with a list of PropertyMarkerValue which defines the range of Parallax.IntProperty or Parallax.FloatProperty. Then user adds ParallaxTarget into ParallaxEffect.

App may subclass Parallax.IntProperty or Parallax.FloatProperty to supply additional information about how to retrieve Property value. RecyclerViewParallax is a great example of Parallax implementation tracking child view positions on screen.

    Restrictions of properties
  • FloatProperty and IntProperty cannot be mixed in one Parallax
  • Values must be in ascending order.
  • If the UI element is unknown above screen, use UNKNOWN_BEFORE.
  • if the UI element is unknown below screen, use UNKNOWN_AFTER.
  • UNKNOWN_BEFORE and UNKNOWN_AFTER are not allowed to be next to each other.
These rules will be verified at runtime.

Subclass must override updateValues() to update property values and perform ParallaxEffects. Subclass may call updateValues() automatically e.g. RecyclerViewParallax calls updateValues() in RecyclerView scrolling. App might call updateValues() manually when Parallax is unaware of the value change. For example, when a slide transition is running, RecyclerViewParallax is unaware of translation value changes; it's the app's responsibility to call updateValues() in every frame of animation.

Public methods

addEffect

open fun addEffect(vararg ranges: Parallax.PropertyMarkerValue<Any!>!): ParallaxEffect!

Create a ParallaxEffect object that will track source variable changes within a provided set of ranges.

Parameters
ranges Parallax.PropertyMarkerValue<Any!>!: A list of marker values that defines the ranges.
Return
ParallaxEffect! Newly created ParallaxEffect object.

addProperty

fun addProperty(name: String!): PropertyT

Add a new IntProperty in the Parallax object. App may override createProperty(String, int).

Parameters
name String!: Name of the property.
Return
PropertyT Newly created Property object.

createProperty

abstract fun createProperty(
    name: String!, 
    index: Int
): PropertyT

Create a new Property object. App does not directly call this method. See addProperty(String).

Parameters
index Int: Index of the property in this Parallax object.
Return
PropertyT Newly created Property object.

getEffects

open fun getEffects(): MutableList<ParallaxEffect!>!

Returns a list of ParallaxEffect object which defines rules to perform mapping to multiple ParallaxTargets.

Return
MutableList<ParallaxEffect!>! A list of ParallaxEffect object.

getMaxValue

abstract fun getMaxValue(): Float

Return the max value which is typically size of parent visible area, e.g. RecyclerView's height if we are tracking Y position of a child. The size can be used to calculate marker value using the provided fraction of FloatPropertyMarkerValue.

Return
Float Size of parent visible area.

getProperties

fun getProperties(): MutableList<PropertyT>!
Return
MutableList<PropertyT>! A unmodifiable list of properties.

removeAllEffects

open fun removeAllEffects(): Unit

Remove all ParallaxEffect objects.

removeEffect

open fun removeEffect(effect: ParallaxEffect!): Unit

Remove the ParallaxEffect object.

Parameters
effect ParallaxEffect!: The ParallaxEffect object to remove.

updateValues

@CallSuper open fun updateValues(): Unit

Update property values and perform ParallaxEffects. Subclass may override and call super.updateValues() after updated properties values.