Class Animator

java.lang.Object
org.jdesktop.animation.timing.Animator

public final class Animator extends Object
This class controls animations. Its constructors and various set methods control the parameters under which animations are run, and the other methods support starting and stopping the animation. The parameters of this class use the concepts of a "cycle" (the base animation) and an "envelope" that controls how the cycle is started, ended, and repeated.

Most of the methods here are simle getters/setters for the properties used by Animator. Typical animations will simply use one of the two constructors (depending on whether you are constructing a repeating animation), optionally call any of the set* methods to alter any of the other parameters, and then call start() to run the animation. For example, this animation will run for 1 second, calling your TimingTarget with timing events when the animation is started, running, and stopped:

  Animator animator = new Animator(1000, myTarget);
  animator.start();
 
The following variation will run a half-second animation 4 times, reversing direction each time:
  Animator animator = new Animator(500, 4, RepeatBehavior.REVERSE, myTarget);
  animator.start();
 
More complex animations can be created through using the properties in Animator, such as acceleration and setDeceleration(float). More automated animations can be created and run using the triggers package to control animations through events and PropertySetter to handle animating object properties.
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Direction is used to set the initial direction in which the animation starts.
    static enum 
    EndBehavior determines what happens at the end of the animation.
    static enum 
    RepeatBehavior determines how each successive cycle will flow.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Used to specify unending duration or repeatCount
  • Constructor Summary

    Constructors
    Constructor
    Description
    Animator(int duration)
    Constructor: this is a utility constructor for a simple timing sequence that will run for duration length of time.
    Animator(int duration, double repeatCount, Animator.RepeatBehavior repeatBehavior, TimingTarget target)
    Constructor that sets the most common properties of a repeating animation.
    Animator(int duration, TimingTarget target)
    Constructor: this is a utility constructor for a simple timing sequence that will run for duration length of time.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Adds a TimingTarget to the list of targets that get notified of each timingEvent.
    void
    This method is like the stop() method, only this one will not result in a calls to the end() method in all TimingTargets of this Animation; it simply cancels the Animator immediately.
    float
    Returns the current value of acceleration property
    long
    Returns the elapsed time for the current animation cycle.
    long
    getCycleElapsedTime(long currentTime)
    Returns the elapsed time for the current animation cycle.
    float
    Returns the current value of deceleration property
    int
    Returns the duration of the animation.
    Returns the Animator.EndBehavior of the animation, either HOLD to retain the final value or RESET to take on the initial value.
    Returns the interpolator for the animation.
    Returns the Animator.RepeatBehavior of the animation.
    double
    Returns the number of times the animation cycle will repeat.
    int
    Returns the current resolution of the animation.
    int
    Returns the amount of delay prior to starting the first animation cycle after the call to start().
    Returns the initial direction for the animation.
    float
    Returns the fraction that the first cycle will start at.
    float
    This method calculates and returns the fraction elapsed of the current cycle based on the current time
    long
    Returns the total elapsed time for the current animation.
    long
    getTotalElapsedTime(long currentTime)
    Returns the total elapsed time for the current animation.
    boolean
    Returns whether this Animator object is currently running
    void
    This method pauses a running animation.
    void
    Removes the specified TimingTarget from the list of targets that get notified of each timingEvent.
    void
    This method resumes a paused animation.
    void
    setAcceleration(float acceleration)
    Sets the fraction of the timing cycle that will be spent accelerating at the beginning.
    void
    setDeceleration(float deceleration)
    Sets the fraction of the timing cycle that will be spent decelerating at the end.
    void
    setDuration(int duration)
    Sets the duration for the animation
    void
    Sets the behavior at the end of the animation.
    void
    Sets the interpolator for the animation cycle.
    void
    Sets the Animator.RepeatBehavior of the animation.
    void
    setRepeatCount(double repeatCount)
    Sets the number of times the animation cycle will repeat.
    void
    setResolution(int resolution)
    Sets the resolution of the animation
    void
    setStartDelay(int startDelay)
    Sets the duration of the initial delay between calling start() and the start of the first animation cycle.
    void
    Sets the startDirection for the initial animation cycle.
    void
    setStartFraction(float startFraction)
    Sets the initial fraction at which the first animation cycle will begin.
    void
    Sets a new TimingSource that will supply the timing events to this Animator.
    void
    Starts the animation
    void
    This method is optional; animations will always stop on their own if Animator is provided with appropriate values for duration and repeatCount in the constructor.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

  • Constructor Details

    • Animator

      public Animator(int duration)
      Constructor: this is a utility constructor for a simple timing sequence that will run for duration length of time. This variant takes no TimingTarget, and is equivalent to calling Animator(int, TimingTarget) with a TimingTarget of null.
      Parameters:
      duration - The length of time that this will run, in milliseconds.
    • Animator

      public Animator(int duration, TimingTarget target)
      Constructor: this is a utility constructor for a simple timing sequence that will run for duration length of time.
      Parameters:
      duration - The length of time that this will run, in milliseconds.
      target - TimingTarget object that will be called with all timing events. Null is acceptable, but no timingEvents will be sent to any targets without future calls to addTarget(org.jdesktop.animation.timing.TimingTarget).
    • Animator

      public Animator(int duration, double repeatCount, Animator.RepeatBehavior repeatBehavior, TimingTarget target)
      Constructor that sets the most common properties of a repeating animation.
      Parameters:
      duration - the length of each animation cycle, in milliseconds. This value can also be INFINITE for animations that have no end. Note that fractions sent out with such unending animations will be undefined since there is no fraction of an infinitely long cycle.
      repeatCount - the number of times the animation cycle will repeat. This is a positive value, which allows a non-integral number of repetitions (allowing an animation to stop mid-cycle, for example). This value can also be INFINITE, indicating that the animation will continue repeating forever, or until manually stopped.
      repeatBehavior - Animator.RepeatBehavior of each successive cycle. A value of null is equivalent to RepeatBehavior.REVERSE.
      target - TimingTarget object that will be called with all timing events. Null is acceptable, but no timingEvents will be sent to any targets without future calls to addTarget(org.jdesktop.animation.timing.TimingTarget).
      Throws:
      IllegalArgumentException - if any parameters have invalid values
      See Also:
  • Method Details

    • getStartDirection

      public Animator.Direction getStartDirection()
      Returns the initial direction for the animation.
      Returns:
      direction that the initial animation cycle will be moving
    • setStartDirection

      public void setStartDirection(Animator.Direction startDirection)
      Sets the startDirection for the initial animation cycle. The default startDirection is FORWARD.
      Parameters:
      startDirection - initial animation cycle direction
      Throws:
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getInterpolator

      public Interpolator getInterpolator()
      Returns the interpolator for the animation.
      Returns:
      interpolator that the initial animation cycle uses
    • setInterpolator

      public void setInterpolator(Interpolator interpolator)
      Sets the interpolator for the animation cycle. The default interpolator is LinearInterpolator.
      Parameters:
      interpolator - the interpolation to use each animation cycle
      Throws:
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • setAcceleration

      public void setAcceleration(float acceleration)
      Sets the fraction of the timing cycle that will be spent accelerating at the beginning. The default acceleration value is 0 (no acceleration).
      Parameters:
      acceleration - value from 0 to 1
      Throws:
      IllegalArgumentException - acceleration value must be between 0 and 1, inclusive.
      IllegalArgumentException - acceleration cannot be greater than (1 - deceleration)
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • setDeceleration

      public void setDeceleration(float deceleration)
      Sets the fraction of the timing cycle that will be spent decelerating at the end. The default deceleration value is 0 (no deceleration).
      Parameters:
      deceleration - value from 0 to 1
      Throws:
      IllegalArgumentException - deceleration value must be between 0 and 1, inclusive.
      IllegalArgumentException - deceleration cannot be greater than (1 - acceleration)
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getAcceleration

      public float getAcceleration()
      Returns the current value of acceleration property
      Returns:
      acceleration value
    • getDeceleration

      public float getDeceleration()
      Returns the current value of deceleration property
      Returns:
      deceleration value
    • addTarget

      public void addTarget(TimingTarget target)
      Adds a TimingTarget to the list of targets that get notified of each timingEvent. This can be done at any time before, during, or after the animation has started or completed; the new target will begin having its TimingTarget methods called as soon as it is added. If target is already on the list of targets in this Animator, it is not added again (there will be only one instance of any given target in any Animator's list of targets).
      Parameters:
      target - TimingTarget to be added to the list of targets that get notified by this Animator of all timing events. Target cannot be null.
    • removeTarget

      public void removeTarget(TimingTarget target)
      Removes the specified TimingTarget from the list of targets that get notified of each timingEvent. This can be done at any time before, during, or after the animation has started or completed; the target will cease having its TimingTarget methods called as soon as it is removed.
      Parameters:
      target - TimingTarget to be removed from the list of targets that get notified by this Animator of all timing events.
    • getResolution

      public int getResolution()
      Returns the current resolution of the animation. This helps determine the maximum frame rate at which the animation will run.
      Returns:
      the resolution, in milliseconds, of the timer
    • setResolution

      public void setResolution(int resolution)
      Sets the resolution of the animation
      Parameters:
      resolution - the amount of time between timing events of the animation, in milliseconds. Note that the actual resolution may vary, according to the resolution of the timer used by the framework as well as system load and configuration; this value should be seen more as a minimum resolution than a guaranteed resolution.
      Throws:
      IllegalArgumentException - resolution must be >= 0
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getDuration

      public int getDuration()
      Returns the duration of the animation.
      Returns:
      the length of the animation, in milliseconds. A return value of -1 indicates an INFINITE duration.
    • setDuration

      public void setDuration(int duration)
      Sets the duration for the animation
      Parameters:
      duration - the length of the animation, in milliseconds. This value can also be INFINITE, meaning the animation will run until manually stopped.
      Throws:
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getRepeatCount

      public double getRepeatCount()
      Returns the number of times the animation cycle will repeat.
      Returns:
      the number of times the animation cycle will repeat.
    • setRepeatCount

      public void setRepeatCount(double repeatCount)
      Sets the number of times the animation cycle will repeat. The default value is 1.
      Parameters:
      repeatCount - Number of times the animation cycle will repeat. This value may be >= 1 or INFINITE for animations that repeat indefinitely. The value may be fractional if the animation should stop at some fractional point.
      Throws:
      IllegalArgumentException - if repeatCount is not >=1 or INFINITE.
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getStartDelay

      public int getStartDelay()
      Returns the amount of delay prior to starting the first animation cycle after the call to start().
      Returns:
      the duration, in milliseconds, between the call to start the animation and the first animation cycle actually starting.
      See Also:
    • setStartDelay

      public void setStartDelay(int startDelay)
      Sets the duration of the initial delay between calling start() and the start of the first animation cycle. The default value is 0 (no delay).
      Parameters:
      startDelay - the duration, in milliseconds, between the call to start the animation and the first animation cycle actually starting. This value must be >= 0.
      Throws:
      IllegalArgumentException - if startDelay is < 0
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getRepeatBehavior

      public Animator.RepeatBehavior getRepeatBehavior()
      Returns the Animator.RepeatBehavior of the animation. The default behavior is REVERSE, meaning that the animation will reverse direction at the end of each cycle.
      Returns:
      whether the animation will repeat in the same direction or will reverse direction each time.
    • setRepeatBehavior

      public void setRepeatBehavior(Animator.RepeatBehavior repeatBehavior)
      Sets the Animator.RepeatBehavior of the animation.
      Parameters:
      repeatBehavior - the behavior for each successive cycle in the animation. A null behavior is equivalent to specifying the default: REVERSE. The default behaviors is HOLD.
      Throws:
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getEndBehavior

      public Animator.EndBehavior getEndBehavior()
      Returns the Animator.EndBehavior of the animation, either HOLD to retain the final value or RESET to take on the initial value. The default behavior is HOLD.
      Returns:
      the behavior at the end of the animation
    • setEndBehavior

      public void setEndBehavior(Animator.EndBehavior endBehavior)
      Sets the behavior at the end of the animation.
      Parameters:
      endBehavior - the behavior at the end of the animation, either HOLD or RESET. A null value is equivalent to the default value of HOLD.
      Throws:
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • getStartFraction

      public float getStartFraction()
      Returns the fraction that the first cycle will start at.
      Returns:
      fraction between 0 and 1 at which the first cycle will start.
    • setStartFraction

      public void setStartFraction(float startFraction)
      Sets the initial fraction at which the first animation cycle will begin. The default value is 0.
      Parameters:
      startFraction -
      Throws:
      IllegalArgumentException - if startFraction is less than 0 or greater than 1
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended
      See Also:
    • start

      public void start()
      Starts the animation
      Throws:
      IllegalStateException - if animation is already running; this command may only be run prior to starting the animation or after the animation has ended
    • isRunning

      public boolean isRunning()
      Returns whether this Animator object is currently running
    • stop

      public void stop()
      This method is optional; animations will always stop on their own if Animator is provided with appropriate values for duration and repeatCount in the constructor. But if the application wants to stop the timer mid-stream, this is the method to call. This call will result in calls to the end() method of all TimingTargets of this Animator.
      See Also:
    • cancel

      public void cancel()
      This method is like the stop() method, only this one will not result in a calls to the end() method in all TimingTargets of this Animation; it simply cancels the Animator immediately.
      See Also:
    • pause

      public void pause()
      This method pauses a running animation. No further events are sent to TimingTargets. A paused animation may be d again by calling the resume() method. Pausing a non-running animation has no effect.
      See Also:
    • resume

      public void resume()
      This method resumes a paused animation. Resuming an animation that is not paused has no effect.
      See Also:
    • getTotalElapsedTime

      public long getTotalElapsedTime(long currentTime)
      Returns the total elapsed time for the current animation.
      Parameters:
      currentTime - value of current time to use in calculating elapsed time.
      Returns:
      the total time elapsed between the time the Animator started and the supplied currentTime.
    • getTotalElapsedTime

      public long getTotalElapsedTime()
      Returns the total elapsed time for the current animation. Calculates current time.
      Returns:
      the total time elapsed between the time the Animator started and the current time.
    • getCycleElapsedTime

      public long getCycleElapsedTime(long currentTime)
      Returns the elapsed time for the current animation cycle.
      Parameters:
      currentTime - value of current time to use in calculating elapsed time.
      Returns:
      the time elapsed between the time this cycle started and the supplied currentTime.
    • getCycleElapsedTime

      public long getCycleElapsedTime()
      Returns the elapsed time for the current animation cycle. Calculates current time.
      Returns:
      the time elapsed between the time this cycle started and the current time.
    • getTimingFraction

      public float getTimingFraction()
      This method calculates and returns the fraction elapsed of the current cycle based on the current time
      Returns:
      fraction elapsed of the current animation cycle
    • setTimer

      public void setTimer(TimingSource timer)
      Sets a new TimingSource that will supply the timing events to this Animator. Animator uses an internal TimingSource by default and most developers will probably not need to change this default behavior. But for those wishing to supply their own timer, this method can be called to tell Animator to use a different TimingSource instead. Setting a new TimingSource implicitly removes this Animator as a listener to any previously-set TimingSource object.
      Parameters:
      timer - the object that will provide the timing events to Animator. A value of null is equivalent to telling Animator to use its default internal TimingSource object.
      Throws:
      IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended.