Package icyllis.modernui.animation

# Class PropertyValuesHolder

java.lang.Object
icyllis.modernui.animation.PropertyValuesHolder

All Implemented Interfaces:
  `Cloneable`

public sealed class PropertyValuesHolder extends Object implements Cloneable
This class holds information about a property and the values that that property should take on during an animation. PropertyValuesHolder objects can be used to create animations with ValueAnimator or ObjectAnimator that operate on several properties in parallel.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `PropertyValuesHolder`
  `clone()`
  `void`
  `invert()`
  Inverts all keyframes on the track.
  `static PropertyValuesHolder`
  `ofFloat(float... values)`
  Constructs and returns a PropertyValuesHolder with a given set of float values.
  `static PropertyValuesHolder`
  `ofFloat(FloatProperty<?> property, float... values)`
  Constructs and returns a PropertyValuesHolder with a given property and set of float values.
  `static PropertyValuesHolder`
  `ofInt(int... values)`
  Constructs and returns a PropertyValuesHolder with a given set of int values.
  `static PropertyValuesHolder`
  `ofInt(IntProperty<?> property, int... values)`
  Constructs and returns a PropertyValuesHolder with a given property and set of int values.
  `static PropertyValuesHolder`
  `ofKeyframe(Keyframe... values)`
  Constructs and returns a PropertyValuesHolder object with the specified property name and set of values.
  `static PropertyValuesHolder`
  `ofKeyframe(FloatProperty<?> property, Keyframe... values)`
  Constructs and returns a PropertyValuesHolder object with the specified float property and set of values.
  `static PropertyValuesHolder`
  `ofKeyframe(IntProperty<?> property, Keyframe... values)`
  Constructs and returns a PropertyValuesHolder object with the specified int property and set of values.
  `static PropertyValuesHolder`
  `ofKeyframe(Property<?,?> property, Keyframe... values)`
  Constructs and returns a PropertyValuesHolder object with the specified property and set of values.
  `static <P> PropertyValuesHolder`
  `ofKeyframe(Property<?,P> property, TypeConverter<?,P> converter, Keyframe... values)`
  Constructs and returns a PropertyValuesHolder object with the specified property and set of values.
  `static <V> PropertyValuesHolder`
  `ofObject(TypeEvaluator<V> evaluator, V... values)`
  Constructs and returns a PropertyValuesHolder with a given set of Object values.
  `static <V, P> PropertyValuesHolder`
  `ofObject(Property<?,P> property, TypeConverter<V,P> converter, TypeEvaluator<V> evaluator, V... values)`
  Constructs and returns a PropertyValuesHolder with a given property and set of Object values.
  `static <V> PropertyValuesHolder`
  `ofObject(Property<?,V> property, TypeEvaluator<V> evaluator, V... values)`
  Constructs and returns a PropertyValuesHolder with a given property and set of Object values.
  `void`
  `setConverter(TypeConverter<?,?> converter)`
  Sets the converter to convert from the values type to the setter's parameter type.
  `void`
  `setEvaluator(TypeEvaluator<?> evaluator)`
  The TypeEvaluator will be automatically determined based on the type of values supplied to PropertyValuesHolder.
  `void`
  `setFloatValues(float... values)`
  Set the animated values for this object to this set of floats.
  `void`
  `setIntValues(int... values)`
  Set the animated values for this object to this set of ints.
  `void`
  `setKeyframes(Keyframe... values)`
  Set the animated values for this object to this set of Keyframes.
  `void`
  `setObjectValues(Object... values)`
  Set the animated values for this object to this set of Objects.
  `void`
  `setProperty(Property<?,?> property)`
  Sets the property that will be animated.

  ### Methods inherited from class java.lang.Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### ofInt

    @Nonnull public static PropertyValuesHolder ofInt(@Nonnull int... values)
    Constructs and returns a PropertyValuesHolder with a given set of int values.
    Parameters:
      `values` - The values that the named property will animate between.
    Returns:
      PropertyValuesHolder The constructed PropertyValuesHolder object.

  - ### ofInt

    @Nonnull public static PropertyValuesHolder ofInt(IntProperty<?> property, @Nonnull int... values)
    Constructs and returns a PropertyValuesHolder with a given property and set of int values.
    Parameters:
      `property` - The property being animated.
      `values` - The values that the property will animate between.
    Returns:
      PropertyValuesHolder The constructed PropertyValuesHolder object.

  - ### ofFloat

    @Nonnull public static PropertyValuesHolder ofFloat(@Nonnull float... values)
    Constructs and returns a PropertyValuesHolder with a given set of float values.
    Parameters:
      `values` - The values that the named property will animate between.
    Returns:
      PropertyValuesHolder The constructed PropertyValuesHolder object.

  - ### ofFloat

    @Nonnull public static PropertyValuesHolder ofFloat(FloatProperty<?> property, @Nonnull float... values)
    Constructs and returns a PropertyValuesHolder with a given property and set of float values.
    Parameters:
      `property` - The property being animated.
      `values` - The values that the property will animate between.
    Returns:
      PropertyValuesHolder The constructed PropertyValuesHolder object.

  - ### ofObject

    @Nonnull @SafeVarargs public static <V> PropertyValuesHolder ofObject(TypeEvaluator<V> evaluator, @Nonnull V... values)
    Constructs and returns a PropertyValuesHolder with a given set of Object values. This variant also takes a TypeEvaluator because the system cannot automatically interpolate between objects of unknown type.

    Note: The Object values are stored as references to the original objects, which means that changes to those objects after this method is called will affect the values on the PropertyValuesHolder. If the objects will be mutated externally after this method is called, callers should pass a copy of those objects instead.

    Parameters:
      `evaluator` - A TypeEvaluator that will be called on each animation frame to provide the necessary interpolation between the Object values to derive the animated value.
      `values` - The values that the named property will animate between.
    Returns:
      PropertyValuesHolder The constructed PropertyValuesHolder object.

  - ### ofObject

    @Nonnull @SafeVarargs public static <V> PropertyValuesHolder ofObject(Property<?,V> property, TypeEvaluator<V> evaluator, @Nonnull V... values)
    Constructs and returns a PropertyValuesHolder with a given property and set of Object values. This variant also takes a TypeEvaluator because the system cannot automatically interpolate between objects of unknown type.

    Note: The Object values are stored as references to the original objects, which means that changes to those objects after this method is called will affect the values on the PropertyValuesHolder. If the objects will be mutated externally after this method is called, callers should pass a copy of those objects instead.

    Parameters:
      `property` - The property being animated.
      `evaluator` - A TypeEvaluator that will be called on each animation frame to provide the necessary interpolation between the Object values to derive the animated value.
      `values` - The values that the property will animate between.
    Returns:
      PropertyValuesHolder The constructed PropertyValuesHolder object.

  - ### ofObject

    @Nonnull @SafeVarargs public static <V, P> PropertyValuesHolder ofObject(Property<?,P> property, TypeConverter<V,P> converter, TypeEvaluator<V> evaluator, @Nonnull V... values)
    Constructs and returns a PropertyValuesHolder with a given property and set of Object values. This variant also takes a TypeEvaluator because the system cannot automatically interpolate between objects of unknown type. This variant also takes a `TypeConverter` to convert from animated values to the type of the property. If only one value is supplied, the `TypeConverter` must be a `BidirectionalTypeConverter` to retrieve the current value.

    Note: The Object values are stored as references to the original objects, which means that changes to those objects after this method is called will affect the values on the PropertyValuesHolder. If the objects will be mutated externally after this method is called, callers should pass a copy of those objects instead.

    Parameters:
      `property` - The property being animated.
      `converter` - Converts the animated object to the Property type.
      `evaluator` - A TypeEvaluator that will be called on each animation frame to provide the necessary interpolation between the Object values to derive the animated value.
      `values` - The values that the property will animate between.
    Returns:
      PropertyValuesHolder The constructed PropertyValuesHolder object.
    See Also:
      - `setConverter(TypeConverter)`
      - `TypeConverter`

  - ### ofKeyframe

    @Nonnull public static PropertyValuesHolder ofKeyframe(@Nonnull Keyframe... values)
    Constructs and returns a PropertyValuesHolder object with the specified property name and set of values. These values can be of any type, but the type should be consistent so that an appropriate `TypeEvaluator` can be found that matches the common type.

    If there is only one value, it is assumed to be the end value of an animation, and an initial value will be derived, if possible, by calling a getter function on the object. Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction `ObjectAnimator`, and with a getter function derived automatically from `propertyName`, since otherwise PropertyValuesHolder has no way of determining what the value should be.

    Parameters:
      `values` - The set of values to animate between.

  - ### ofKeyframe

    @Nonnull public static PropertyValuesHolder ofKeyframe(Property<?,?> property, @Nonnull Keyframe... values)
    Constructs and returns a PropertyValuesHolder object with the specified property and set of values. These values can be of any type, but the type should be consistent so that an appropriate `TypeEvaluator` can be found that matches the common type.

    If there is only one value, it is assumed to be the end value of an animation, and an initial value will be derived, if possible, by calling the property's `Property.get(Object)` function. Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction with `ObjectAnimator`, since otherwise PropertyValuesHolder has no way of determining what the value should be.

    Parameters:
      `property` - The property associated with this set of values.
      `values` - The set of values to animate between.

  - ### ofKeyframe

    @Nonnull public static <P> PropertyValuesHolder ofKeyframe(Property<?,P> property, TypeConverter<?,P> converter, @Nonnull Keyframe... values)
    Constructs and returns a PropertyValuesHolder object with the specified property and set of values. These values can be of any type, but the type should be consistent so that an appropriate `TypeEvaluator` can be found that matches the common type.

    If there is only one value, it is assumed to be the end value of an animation, and an initial value will be derived, if possible, by calling the property's `Property.get(Object)` function. Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction with `ObjectAnimator`, since otherwise PropertyValuesHolder has no way of determining what the value should be.

    Parameters:
      `property` - The property associated with this set of values.
      `converter` - Converts the animated object to the Property type.
      `values` - The set of values to animate between.

  - ### ofKeyframe

    @Nonnull public static PropertyValuesHolder ofKeyframe(IntProperty<?> property, @Nonnull Keyframe... values)
    Constructs and returns a PropertyValuesHolder object with the specified int property and set of values.

    Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction with `ObjectAnimator`, since otherwise PropertyValuesHolder has no way of determining what the value should be.

    Parameters:
      `property` - The property associated with this set of values.
      `values` - The set of values to animate between.
    Throws:
      `IllegalArgumentException` - some keyframes are not int keyframes, or less than two
    See Also:
      - `Keyframe.ofInt(float, int)`

  - ### ofKeyframe

    @Nonnull public static PropertyValuesHolder ofKeyframe(FloatProperty<?> property, @Nonnull Keyframe... values)
    Constructs and returns a PropertyValuesHolder object with the specified float property and set of values.

    Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction with `ObjectAnimator`, since otherwise PropertyValuesHolder has no way of determining what the value should be.

    Parameters:
      `property` - The property associated with this set of values.
      `values` - The set of values to animate between.
    Throws:
      `IllegalArgumentException` - some keyframes are not float keyframes, or less than two
    See Also:
      - `Keyframe.ofFloat(float, float)`

  - ### setIntValues

    public void setIntValues(@Nonnull int... values)
    Set the animated values for this object to this set of ints. If there is only one value, it is assumed to be the end value of an animation, and an initial value will be derived, if possible, by calling a getter function on the object. Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction `ObjectAnimator`, and with a getter function derived automatically from `propertyName`, since otherwise PropertyValuesHolder has no way of determining what the value should be.
    Parameters:
      `values` - One or more values that the animation will animate between.

  - ### setFloatValues

    public void setFloatValues(@Nonnull float... values)
    Set the animated values for this object to this set of floats. If there is only one value, it is assumed to be the end value of an animation, and an initial value will be derived, if possible, by calling a getter function on the object. Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction `ObjectAnimator`, and with a getter function derived automatically from `propertyName`, since otherwise PropertyValuesHolder has no way of determining what the value should be.
    Parameters:
      `values` - One or more values that the animation will animate between.

  - ### setKeyframes

    public void setKeyframes(@Nonnull Keyframe... values)
    Set the animated values for this object to this set of Keyframes.
    Parameters:
      `values` - One or more values that the animation will animate between.

  - ### setObjectValues

    public void setObjectValues(@Nonnull Object... values)
    Set the animated values for this object to this set of Objects. If there is only one value, it is assumed to be the end value of an animation, and an initial value will be derived, if possible, by calling a getter function on the object. Also, if any value is null, the value will be filled in when the animation starts in the same way. This mechanism of automatically getting null values only works if the PropertyValuesHolder object is used in conjunction `ObjectAnimator`, and with a getter function derived automatically from `propertyName`, since otherwise PropertyValuesHolder has no way of determining what the value should be.

    Note: The Object values are stored as references to the original objects, which means that changes to those objects after this method is called will affect the values on the PropertyValuesHolder. If the objects will be mutated externally after this method is called, callers should pass a copy of those objects instead.

    Parameters:
      `values` - One or more values that the animation will animate between.

  - ### setConverter

    public void setConverter(TypeConverter<?,?> converter)
    Sets the converter to convert from the values type to the setter's parameter type. If only one value is supplied or target is changeable, converter must be a `BidirectionalTypeConverter`.
    Parameters:
      `converter` - The converter to use to convert values.

  - ### clone

    public PropertyValuesHolder clone()
    Overrides:
      `clone` in class `Object`

  - ### setEvaluator

    public void setEvaluator(TypeEvaluator<?> evaluator)
    The TypeEvaluator will be automatically determined based on the type of values supplied to PropertyValuesHolder. The evaluator can be manually set, however, if so desired. This may be important in cases where either the type of the values supplied do not match the way that they should be interpolated between, or if the values are of a custom type or one not currently understood by the animation system. Currently, only values of type float and int (and their Object equivalents: Float and Integer) are correctly interpolated; all other types require setting a TypeEvaluator.

  - ### invert

    public void invert()
    Inverts all keyframes on the track. This will produce an inverted animation that plays from endValue to startValue. Note that this is different from reversing that plays in reverse order, this operation keeps the order of interpolation and timeline still forwards.

  - ### setProperty

    public void setProperty(Property<?,?> property)
    Sets the property that will be animated.

    Note that if this PropertyValuesHolder object is used with ObjectAnimator, the property must exist on the target object specified in that ObjectAnimator.

    Parameters:
      `property` - The property being animated.