Animating View Properties with Dynamic Props

caution

Deprecated: The Java Spec API is no longer supported and should not be used for new development. For current best practices and supported approaches, please refer to the Animating View Properties with Dynamic Props page.

note

Dynamic props are properties that are applied directly to a View or Drawable. They are updated without computing a layout or remounting. This makes them efficient for use in animations or other dynamic UIs. Dynamic props are initialised and updated using DynamicValue.

DynamicValue

To control a dynamic prop, you should create a DynamicValue and assign it to that prop. You can then keep a reference to the DynamicValue and use it to directly set values (such as in a callback or an Animator). Use the set() function to set new values from the main thread.

caution

DynamicValues should only be updated on the main thread.

Common Dynamic Props

The dynamic properties that are available for all Components are:

• Alpha
• Scale X/Y
• Translation X/Y
• Background Color
• Foreground Color
• Rotation
• Elevation

To use these, create and pass a DynamicValue<T> object to the component.

For Spec components these props can be set in the builder:

import com.facebook.litho.DynamicValue

MyComponent.create(c).alpha(dynamicAlpha).build()

The DynamicValue can be updated by calling its set() function.

The following short animation illustrates the component in action.

To see how other common dynamic props can be modified, see the All Common Dynamic Props example in the Sample app, which is illustrated in the following animation.

Custom Dynamic Props for MountSpecs

MountSpecs can define custom dynamic props. Props annotated with @Prop(dynamic = true) can be set to a DynamicValue. Setting this value will trigger a custom @OnBindDynamicValue function in the component.

Consider a MountSpec that renders a clock face:

@ExcuseMySpec(reason = Reason.LEGACY)
@MountSpec
object ClockFaceSpec {

  @OnCreateMountContent
  fun onCreateMountContent(androidContext: Context): SimpleClockView {
    return SimpleClockView(androidContext)
  }

  @OnBindDynamicValue
  fun onBindTime(simpleClockView: SimpleClockView, @Prop(dynamic = true) time: Long) {
    simpleClockView.time = time
  }
}

Here, the MountSpec delegates the drawing of a clock face to SimpleClockView. Marking the time prop with @Prop(dynamic = true) will cause an additional method to be generated in the builder that accepts a DynamicValue. The method to set a static value will also remain available. When set() is called on the DynamicValue, the @OnBindDynamicValue function will be executed. In this example, the new time is passed to the ClockView to draw the updated clock face.

This is illustrated in the following short animation.

Animating Dynamic Props

Dynamic Props values can be used with Android Animators to create custom animations using DynamicValue objects with Android's ValueAnimator.

A DynamicValue can be passed to a component as a prop and updated in animations. In a click event, a ValueAnimator can be set up that updates the DynamicValue each frame. The ValueAnimator is stored in a reference so that it can be cancelled if necessary.

For more examples of animating dynamic props, run the [KComponent] Animated Dynamic Props and All Common Dynamic Props demos in the Sample App (Kotlin API Demos → Animations).