Class 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​(java.lang.Object object, java.lang.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​(java.lang.Object object, java.lang.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​(java.lang.Object object, java.lang.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

      All Methods Static Methods Instance Methods Concrete Methods 
      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, java.lang.Object object, java.lang.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, java.lang.Object object, java.lang.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, java.lang.Object object, java.lang.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 java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • PropertySetter

        public PropertySetter​(java.lang.Object object,
                              java.lang.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:
        java.lang.IllegalArgumentException - if appropriate set/get methods cannot be found for propertyName.
      • PropertySetter

        public PropertySetter​(java.lang.Object object,
                              java.lang.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:
        java.lang.IllegalArgumentException - if appropriate set/get methods cannot be found for propertyName.
      • PropertySetter

        public PropertySetter​(java.lang.Object object,
                              java.lang.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:
        java.lang.IllegalArgumentException - if appropriate set/get methods cannot be found for propertyName.
    • Method Detail

      • createAnimator

        public static Animator createAnimator​(int duration,
                                              java.lang.Object object,
                                              java.lang.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:
        java.lang.IllegalArgumentException - if appropriate set/get methods cannot be found for propertyName.
      • createAnimator

        public static <T> Animator createAnimator​(int duration,
                                                  java.lang.Object object,
                                                  java.lang.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:
        java.lang.IllegalArgumentException - if appropriate set/get methods cannot be found for propertyName.
      • createAnimator

        public static <T> Animator createAnimator​(int duration,
                                                  java.lang.Object object,
                                                  java.lang.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:
        java.lang.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