org.jdesktop.animation.timing
Class Animator

java.lang.Object
  extended by 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.