Package org.jdesktop.animation.timing.interpolation

# Class PropertySetter

java.lang.Object
org.jdesktop.animation.timing.TimingTargetAdapter
org.jdesktop.animation.timing.interpolation.PropertySetter

All Implemented Interfaces:
  `TimingTarget`

public class PropertySetter extends TimingTargetAdapter
This class enables automating animation of object properties. The class is a TimingTarget, and should be used as a target of timing events from an Animator. These events will be used to change a specified property over time, according to how the PropertySetter is constructed.

For example, here is an animation of the "background" property of some object "obj" from blue to red over a period of one second:

      PropertySetter ps = new PropertySetter(obj, "background", Color.BLUE,
                                             Color.RED);
      Animator anim = new Animator(1000, ps);
      anim.start();

Here is the same animation, created using one of the utility factory methods that returns an animator:

      Animator animator = PropertySetter.createAnimator(1000, obj, "background",
                                                        Color.BLUE, Color.RED);
      anim.start();

More complex animations can be created by passing in multiple values for the property to take on, for example:

      Animator animator = PropertySetter.createAnimator(1000, obj, "background",
                                                        Color.BLUE, Color.RED,
                                                        Color.GREEN);
      anim.start();

It is also possible to define more involved and tightly-controlled steps in the animation, including the times between the values and how the values are interpolated by using the constructor that takes a `KeyFrames` object. KeyFrames defines the fractional times at which an object takes on specific values, the values to assume at those times, and the method of interpolation between those values. For example, here is the same animation as above, specified through KeyFrames, where the RED color will be set 10% of the way through the animation (note that we are not setting an Interpolator, so the timing intervals will use the default LinearInterpolator):

      KeyValues vals = KeyValues.create(Color.BLUE, Color.RED, Color.GREEN);
      KeyTimes times = new KeyTimes(0.0f, .1f, 1.0f);
      KeyFrames frames = new KeyFrames(vals, times);
      Animator animator = PropertySetter.createAnimator(1000, obj, "background",
                                                        frames);
      anim.start();

## Constructor Summary

Constructors
Constructor
Description
`PropertySetter(Object object, String propertyName, Evaluator evaluator, T... params)`
Constructor for a PropertySetter where the values the propert takes on during the animation are specified in a `KeyFrames` object.
`PropertySetter(Object object, String propertyName, KeyFrames keyFrames)`
Constructor for a PropertySetter where the values the propert takes on during the animation are specified in a `KeyFrames` object.
`PropertySetter(Object object, String propertyName, T... params)`
Constructor for a PropertySetter where the values the propert takes on during the animation are specified in a `KeyFrames` object.

## Method Summary

Modifier and Type
Method
Description
`void`
`begin()`
Called by Animator to signal that the timer is about to start.
`static <T> Animator`
`createAnimator(int duration, Object object, String propertyName, Evaluator evaluator, T... params)`
Utility method that constructs a PropertySetter and an Animator using that PropertySetter and returns the Animator
`static Animator`
`createAnimator(int duration, Object object, String propertyName, KeyFrames keyFrames)`
Utility method that constructs a PropertySetter and an Animator using that PropertySetter and returns the Animator
`static <T> Animator`
`createAnimator(int duration, Object object, String propertyName, T... params)`
Utility method that constructs a PropertySetter and an Animator using that PropertySetter and returns the Animator
`void`
`timingEvent(float fraction)`
Called from Animator to signal a timing event.

### Methods inherited from class org.jdesktop.animation.timing.TimingTargetAdapter

`end, repeat`

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

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

## Constructor Details

### PropertySetter

public PropertySetter(Object object, String propertyName, KeyFrames keyFrames)
Constructor for a PropertySetter where the values the propert takes on during the animation are specified in a `KeyFrames` object.

Parameters:
  `object` - the object whose property will be animated
  `propertyName` - the name of the property to be animated. For any propertyName "foo" there must be an accessible "setFoo" method on the object. If only one value is supplied in creating the KeyValues for the keyFrames, the animation will also need a "getFoo" method.
  `keyFrames` - the fractional times, values, and interpolation to be used in calculating the values set on the object's property.
Throws:
  `IllegalArgumentException` - if appropriate set/get methods cannot be found for propertyName.

### PropertySetter

public PropertySetter(Object object, String propertyName, T... params)
Constructor for a PropertySetter where the values the propert takes on during the animation are specified in a `KeyFrames` object.

Parameters:
  `object` - the object whose property will be animated
  `propertyName` - the name of the property to be animated. For any propertyName "foo" there must be an accessible "setFoo" method on the object. If only one value is supplied in params, the animation will also need a "getFoo" method.
  `params` - the values that the object will take on during the animation. Internally, a KeyFrames object will be created that will use times that split the total duration evenly. Supplying only one value for params implies that this is a "to" animation whose intial value will be determined dynamically when the animation starts.
Throws:
  `IllegalArgumentException` - if appropriate set/get methods cannot be found for propertyName.

### PropertySetter

public PropertySetter(Object object, String propertyName, Evaluator evaluator, T... params)
Constructor for a PropertySetter where the values the propert takes on during the animation are specified in a `KeyFrames` object.

Parameters:
  `object` - the object whose property will be animated
  `propertyName` - the name of the property to be animated. For any propertyName "foo" there must be an accessible "setFoo" method on the object. If only one value is supplied in params, the animation will also need a "getFoo" method.
  `evaluator` - KeyValues knows how to calculate intermediate values for many built-in types, but if you want to supply values in types not understood by KeyValues, you will need to supply your own Evaluator.
  `params` - the values that the object will take on during the animation. Internally, a KeyFrames object will be created that will use times that split the total duration evenly. Supplying only one value for params implies that this is a "to" animation whose intial value will be determined dynamically when the animation starts.
Throws:
  `IllegalArgumentException` - if appropriate set/get methods cannot be found for propertyName.

## Method Details

### createAnimator

public static Animator createAnimator(int duration, Object object, String propertyName, KeyFrames keyFrames)
Utility method that constructs a PropertySetter and an Animator using that PropertySetter and returns the Animator

Parameters:
  `duration` - the duration, in milliseconds, of the animation
  `object` - the object whose property will be animated
  `propertyName` - the name of the property to be animated. For any propertyName "foo" there must be an accessible "setFoo" method on the object. If only one value is supplied in creating the KeyValues for the keyFrames, the animation will also need a "getFoo" method.
  `keyFrames` - the fractional times, values, and interpolation to be used in calculating the values set on the object's property.
Throws:
  `IllegalArgumentException` - if appropriate set/get methods cannot be found for propertyName.

### createAnimator

public static <T> Animator createAnimator(int duration, Object object, String propertyName, T... params)
Utility method that constructs a PropertySetter and an Animator using that PropertySetter and returns the Animator

Parameters:
  `duration` - the duration, in milliseconds, of the animation
  `object` - the object whose property will be animated
  `propertyName` - the name of the property to be animated. For any propertyName "foo" there must be an accessible "setFoo" method on the object. If only one value is supplied in creating the KeyValues for the keyFrames, the animation will also need a "getFoo" method.
  `params` - the values that the object will take on during the animation. Internally, a KeyFrames object will be created that will use times that split the total duration evenly. Supplying only one value for params implies that this is a "to" animation whose intial value will be determined dynamically when the animation starts.
Throws:
  `IllegalArgumentException` - if appropriate set/get methods cannot be found for propertyName.

### createAnimator

public static <T> Animator createAnimator(int duration, Object object, String propertyName, Evaluator evaluator, T... params)
Utility method that constructs a PropertySetter and an Animator using that PropertySetter and returns the Animator

Parameters:
  `duration` - the duration, in milliseconds, of the animation
  `object` - the object whose property will be animated
  `propertyName` - the name of the property to be animated. For any propertyName "foo" there must be an accessible "setFoo" method on the object. If only one value is supplied in creating the KeyValues for the keyFrames, the animation will also need a "getFoo" method.
  `evaluator` - KeyValues knows how to calculate intermediate values for many built-in types, but if you want to supply values in types not understood by KeyValues, you will need to supply your own Evaluator.
  `params` - the values that the object will take on during the animation. Internally, a KeyFrames object will be created that will use times that split the total duration evenly. Supplying only one value for params implies that this is a "to" animation whose intial value will be determined dynamically when the animation starts.
Throws:
  `IllegalArgumentException` - if appropriate set/get methods cannot be found for propertyName.

### begin

public void begin()
Called by Animator to signal that the timer is about to start. The only operation performed in this method is setting an initial value for the animation if appropriate; this accounts for "to" animations, which need to start from the current value.

This method is not intended for use by application code.

Specified by:
  `begin` in interface `TimingTarget`
Overrides:
  `begin` in class `TimingTargetAdapter`

### timingEvent

public void timingEvent(float fraction)
Called from Animator to signal a timing event. This causes PropertySetter to invoke the property-setting method (as specified by the propertyName in the constructor) with the appropriate value of the property given the range of values in the KeyValues object and the fraction of the timing cycle that has elapsed.

This method is not intended for use by application code.

Specified by:
  `timingEvent` in interface `TimingTarget`
Overrides:
  `timingEvent` in class `TimingTargetAdapter`
Parameters:
  `fraction` - the fraction of completion between the start and end of the current cycle. Note that on reversing cycles (`Animator.Direction.BACKWARD`) the fraction decreases from 1.0 to 0 on backwards-running cycles. Note also that animations with a duration of `INFINITE` will call timingEvent with an undefined value for fraction, since there is no fraction that makes sense if the animation has no defined length.
See Also:
  - `Animator.Direction`