Package org.jdesktop.animation.timing
Class Animator
- java.lang.Object
-
- org.jdesktop.animation.timing.Animator
-
public final class Animator extends java.lang.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 yourTimingTarget
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 asacceleration
andsetDeceleration(float)
. More automated animations can be created and run using thetriggers
package to control animations through events andPropertySetter
to handle animating object properties.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description 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
Fields Modifier and Type Field Description static int
INFINITE
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 forduration
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 forduration
length of time.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addTarget(TimingTarget target)
Adds a TimingTarget to the list of targets that get notified of each timingEvent.void
cancel()
This method is like thestop()
method, only this one will not result in a calls to theend()
method in all TimingTargets of this Animation; it simply cancels the Animator immediately.float
getAcceleration()
Returns the current value of acceleration propertylong
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 propertyint
getDuration()
Returns the duration of the animation.Animator.EndBehavior
getEndBehavior()
Returns theAnimator.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 theAnimator.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 tostart()
.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 timelong
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 runningvoid
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 animationvoid
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 theAnimator.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 animationvoid
setStartDelay(int startDelay)
Sets the duration of the initial delay between callingstart()
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 animationvoid
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.
-
-
-
Constructor Detail
-
Animator
public Animator(int duration)
Constructor: this is a utility constructor for a simple timing sequence that will run forduration
length of time. This variant takes no TimingTarget, and is equivalent to callingAnimator(int, TimingTarget)
with a TimingTarget ofnull
.- 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 forduration
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 toaddTarget(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 beINFINITE
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 beINFINITE
, 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 toaddTarget(org.jdesktop.animation.timing.TimingTarget)
.- Throws:
java.lang.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 isFORWARD
.- Parameters:
startDirection
- initial animation cycle direction- Throws:
java.lang.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 isLinearInterpolator
.- Parameters:
interpolator
- the interpolation to use each animation cycle- Throws:
java.lang.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:
java.lang.IllegalArgumentException
- acceleration value must be between 0 and 1, inclusive.java.lang.IllegalArgumentException
- acceleration cannot be greater than (1 - deceleration)java.lang.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:
java.lang.IllegalArgumentException
- deceleration value must be between 0 and 1, inclusive.java.lang.IllegalArgumentException
- deceleration cannot be greater than (1 - acceleration)java.lang.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. Iftarget
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:
java.lang.IllegalArgumentException
- resolution must be >= 0java.lang.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 beINFINITE
, meaning the animation will run until manually stopped.- Throws:
java.lang.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 orINFINITE
for animations that repeat indefinitely. The value may be fractional if the animation should stop at some fractional point.- Throws:
java.lang.IllegalArgumentException
- if repeatCount is not >=1 or INFINITE.java.lang.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 tostart()
.- 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 callingstart()
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:
java.lang.IllegalArgumentException
- if startDelay is < 0java.lang.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 theAnimator.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 theAnimator.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:
java.lang.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 theAnimator.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:
java.lang.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:
java.lang.IllegalArgumentException
- if startFraction is less than 0 or greater than 1java.lang.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:
java.lang.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 theend()
method of all TimingTargets of this Animator.- See Also:
cancel()
-
cancel
public void cancel()
This method is like thestop()
method, only this one will not result in a calls to theend()
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 theresume()
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 ofnull
is equivalent to telling Animator to use its default internal TimingSource object.- Throws:
java.lang.IllegalStateException
- if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended.
-
-