public final class Animator extends Object
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.Modifier and Type | Class and 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.
|
Modifier and Type | Field and Description |
---|---|
static int |
INFINITE
Used to specify unending duration or repeatCount
|
Constructor and 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. |
Modifier and Type | Method and 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 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.
|
public static final int INFINITE
public Animator(int duration)
duration
length of time. This variant takes no
TimingTarget, and is equivalent to calling Animator(int,
TimingTarget)
with a TimingTarget of null
.duration
- The length of time that this will run, in milliseconds.public Animator(int duration, TimingTarget target)
duration
length of time.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)
.public Animator(int duration, double repeatCount, Animator.RepeatBehavior repeatBehavior, TimingTarget target)
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)
.IllegalArgumentException
- if any parameters have invalid
valuesINFINITE
,
Animator.Direction
,
Animator.EndBehavior
public Animator.Direction getStartDirection()
public void setStartDirection(Animator.Direction startDirection)
FORWARD
.startDirection
- initial animation cycle directionIllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
public Interpolator getInterpolator()
public void setInterpolator(Interpolator interpolator)
LinearInterpolator
.interpolator
- the interpolation to use each animation cycleIllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
public void setAcceleration(float acceleration)
acceleration
- value from 0 to 1IllegalArgumentException
- 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 endedisRunning()
,
setDeceleration(float)
public void setDeceleration(float deceleration)
deceleration
- value from 0 to 1IllegalArgumentException
- 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 endedisRunning()
,
setAcceleration(float)
public float getAcceleration()
public float getDeceleration()
public void addTarget(TimingTarget target)
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).target
- TimingTarget to be added to the list of targets that
get notified by this Animator of all timing events. Target cannot
be null.public void removeTarget(TimingTarget target)
target
- TimingTarget to be removed from the list of targets that
get notified by this Animator of all timing events.public int getResolution()
public void setResolution(int resolution)
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.IllegalArgumentException
- resolution must be >= 0IllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
public int getDuration()
INFINITE
duration.public void setDuration(int duration)
duration
- the length of the animation, in milliseconds. This
value can also be INFINITE
, meaning the animation will run
until manually stopped.IllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
,
stop()
public double getRepeatCount()
public void setRepeatCount(double repeatCount)
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.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 endedisRunning()
public int getStartDelay()
start()
.start()
public void setStartDelay(int startDelay)
start()
and the start of the first animation cycle. The default value is 0 (no
delay).startDelay
- the duration, in milliseconds, between the call
to start the animation and the first animation cycle actually
starting. This value must be >= 0.IllegalArgumentException
- if startDelay is < 0IllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
public Animator.RepeatBehavior getRepeatBehavior()
Animator.RepeatBehavior
of the animation. The default
behavior is REVERSE, meaning that the animation will reverse direction
at the end of each cycle.public void setRepeatBehavior(Animator.RepeatBehavior repeatBehavior)
Animator.RepeatBehavior
of the animation.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.IllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
public Animator.EndBehavior getEndBehavior()
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.public void setEndBehavior(Animator.EndBehavior endBehavior)
endBehavior
- the behavior at the end of the animation, either
HOLD or RESET. A null value is equivalent to the default value of
HOLD.IllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
public float getStartFraction()
public void setStartFraction(float startFraction)
startFraction
- IllegalArgumentException
- if startFraction is less than 0
or greater than 1IllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has endedisRunning()
public void start()
IllegalStateException
- if animation is already running; this
command may only be run prior to starting the animation or
after the animation has endedpublic boolean isRunning()
public void stop()
end()
method
of all TimingTargets of this Animator.cancel()
public void cancel()
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.stop()
public void pause()
resume()
method. Pausing a non-running animation has no effect.resume()
,
isRunning()
public void resume()
pause()
public long getTotalElapsedTime(long currentTime)
currentTime
- value of current time to use in calculating
elapsed time.public long getTotalElapsedTime()
public long getCycleElapsedTime(long currentTime)
currentTime
- value of current time to use in calculating
elapsed time.public long getCycleElapsedTime()
public float getTimingFraction()
public void setTimer(TimingSource timer)
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.IllegalStateException
- if animation is already running; this
parameter may only be changed prior to starting the animation or
after the animation has ended.