## org.jdesktop.animation.timing
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
`static class` `Animator.Direction` Direction is used to set the initial direction in which the animation starts.
`static class` `Animator.EndBehavior` EndBehavior determines what happens at the end of the animation.
`static class` `Animator.RepeatBehavior` RepeatBehavior determines how each successive cycle will flow.

Field Summary
`static int` `INFINITE` Used to specify unending duration or repeatCount

Constructor Summary
`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
`void` `addTarget(TimingTarget target)` Adds a TimingTarget to the list of targets that get notified of each timingEvent.
`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.
`float` `getAcceleration()` Returns the current value of acceleration property
`long` `getCycleElapsedTime()` Returns the elapsed time for the current animation cycle.
`long` `getCycleElapsedTime(long currentTime)` Returns the elapsed time for the current animation cycle.
`float` `getDeceleration()` Returns the current value of deceleration property
`int` `getDuration()` Returns the duration of the animation.
`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.
`Interpolator` `getInterpolator()` Returns the interpolator for the animation.
`Animator.RepeatBehavior` `getRepeatBehavior()` Returns the `Animator.RepeatBehavior` of the animation.
`double` `getRepeatCount()` Returns the number of times the animation cycle will repeat.
`int` `getResolution()` Returns the current resolution of the animation.
`int` `getStartDelay()` Returns the amount of delay prior to starting the first animation cycle after the call to `start()`.
`Animator.Direction` `getStartDirection()` Returns the initial direction for the animation.
`float` `getStartFraction()` Returns the fraction that the first cycle will start at.
`float` `getTimingFraction()` This method calculates and returns the fraction elapsed of the current cycle based on the current time
`long` `getTotalElapsedTime()` Returns the total elapsed time for the current animation.
`long` `getTotalElapsedTime(long currentTime)` Returns the total elapsed time for the current animation.
`boolean` `isRunning()` Returns whether this Animator object is currently running
`void` `pause()` This method pauses a running animation.
`void` `removeTarget(TimingTarget target)` Removes the specified TimingTarget from the list of targets that get notified of each timingEvent.
`void` `resume()` 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` `setEndBehavior(Animator.EndBehavior endBehavior)` Sets the behavior at the end of the animation.
`void` `setInterpolator(Interpolator interpolator)` Sets the interpolator for the animation cycle.
`void` `setRepeatBehavior(Animator.RepeatBehavior repeatBehavior)` 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` `setStartDirection(Animator.Direction startDirection)` 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` `setTimer(TimingSource timer)` Sets a new TimingSource that will supply the timing events to this Animator.
`void` `start()` Starts the animation
`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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### INFINITE

    public static final int INFINITE

  Used to specify unending duration or repeatCount

  See Also:
    `setDuration(int)`, `setRepeatCount(double)`, Constant Field Values

Constructor Detail

### 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:
    `INFINITE`, `Animator.Direction`, `Animator.EndBehavior`

Method Detail

### 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:
    `isRunning()`

### 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:
    `isRunning()`

### 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:
    `isRunning()`, `setDeceleration(float)`

### 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:
    `isRunning()`, `setAcceleration(float)`

### 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:
    `isRunning()`

### 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:
    `isRunning()`, `stop()`

### 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:
    `isRunning()`

### 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:
    `start()`

### 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:
    `isRunning()`

### 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:
    `isRunning()`

### 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:
    `isRunning()`

### 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:
    `isRunning()`

### 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()`

### 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:
    `stop()`

### 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()`, `isRunning()`

### resume

    public void resume()

  This method resumes a paused animation. Resuming an animation that is not paused has no effect.

  See Also:
    `pause()`

### 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.