javafx.animation

Class Animation

java.lang.Object

javafx.animation.Animation

Direct Known Subclasses:

Timeline, Transition

public abstract class Animation
extends Object

The class Animation provides the core functionality of all animations used in the JavaFX runtime.

An animation can run in a loop by setting cycleCount. To make an animation run back and forth while looping, set the autoReverse -flag.

Call play() or playFromStart() to play an Animation . The Animation progresses in the direction and speed specified by rate, and stops when its duration is elapsed. An Animation with indefinite duration (a cycleCount of INDEFINITE) runs repeatedly until the stop() method is explicitly called, which will stop the running Animation and reset its play head to the initial position.

An Animation can be paused by calling pause(), and the next play() call will resume the Animation from where it was paused.

An Animation's play head can be randomly positioned, whether it is running or not. If the Animation is running, the play head jumps to the specified position immediately and continues playing from new position. If the Animation is not running, the next play() will start the Animation from the specified position.

Inverting the value of rate toggles the play direction.

Since:

JavaFX 2.0

See Also:

Timeline, Transition

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Animation.Status The possible states for status.

Field Summary

Fields

Modifier and Type	Field and Description
static int	INDEFINITE Used to specify an animation that repeats indefinitely, until the stop() method is called.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Animation() The constructor of Animation.
protected	Animation(double targetFramerate) The constructor of Animation.

Method Summary

Modifier and Type	Method and Description
BooleanProperty	autoReverseProperty()
ReadOnlyDoubleProperty	currentRateProperty()
ReadOnlyObjectProperty<Duration>	currentTimeProperty()
IntegerProperty	cycleCountProperty()
ReadOnlyObjectProperty<Duration>	cycleDurationProperty()
ObjectProperty<Duration>	delayProperty()
ObservableMap<String,Duration>	getCuePoints() The cue points can be used to mark important positions of the Animation.
double	getCurrentRate()
Duration	getCurrentTime()
int	getCycleCount()
Duration	getCycleDuration()
Duration	getDelay()
EventHandler<ActionEvent>	getOnFinished()
double	getRate()
Animation.Status	getStatus()
double	getTargetFramerate() The target framerate is the maximum framerate at which this Animation will run, in frames per second.
Duration	getTotalDuration()
boolean	isAutoReverse()
void	jumpTo(Duration time) Jumps to a given position in this Animation.
void	jumpTo(String cuePoint) Jumps to a predefined position in this Animation.
ObjectProperty<EventHandler<ActionEvent>>	onFinishedProperty()
void	pause() Pauses the animation.
void	play() Plays Animation from current position in the direction indicated by rate.
void	playFrom(Duration time) A convenience method to play this Animation from a specific position.
void	playFrom(String cuePoint) A convenience method to play this Animation from a predefined position.
void	playFromStart() Plays an Animation from initial position in forward direction.
DoubleProperty	rateProperty()
void	setAutoReverse(boolean value)
void	setCycleCount(int value)
protected void	setCycleDuration(Duration value)
void	setDelay(Duration value)
void	setOnFinished(EventHandler<ActionEvent> value)
void	setRate(double value)
protected void	setStatus(Animation.Status value)
ReadOnlyObjectProperty<Animation.Status>	statusProperty()
void	stop() Stops the animation and resets the play head to its initial position.
ReadOnlyObjectProperty<Duration>	totalDurationProperty()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INDEFINITE

public static final int INDEFINITE

Used to specify an animation that repeats indefinitely, until the stop() method is called.

See Also:

Constant Field Values

Constructor Detail

Animation

protected Animation(double targetFramerate)

The constructor of Animation. This constructor allows to define a target framerate.

Parameters:

targetFramerate - The custom target frame rate for this Animation

See Also:

getTargetFramerate()

Animation

protected Animation()

The constructor of Animation.

Method Detail

setRate

public final void setRate(double value)

getRate

public final double getRate()

rateProperty

public final DoubleProperty rateProperty()

getCurrentRate

public final double getCurrentRate()

currentRateProperty

public final ReadOnlyDoubleProperty currentRateProperty()

setCycleDuration

protected final void setCycleDuration(Duration value)

getCycleDuration

public final Duration getCycleDuration()

cycleDurationProperty

public final ReadOnlyObjectProperty<Duration> cycleDurationProperty()

getTotalDuration

public final Duration getTotalDuration()

totalDurationProperty

public final ReadOnlyObjectProperty<Duration> totalDurationProperty()

getCurrentTime

public final Duration getCurrentTime()

currentTimeProperty

public final ReadOnlyObjectProperty<Duration> currentTimeProperty()

setDelay

public final void setDelay(Duration value)

getDelay

public final Duration getDelay()

delayProperty

public final ObjectProperty<Duration> delayProperty()

setCycleCount

public final void setCycleCount(int value)

getCycleCount

public final int getCycleCount()

cycleCountProperty

public final IntegerProperty cycleCountProperty()

setAutoReverse

public final void setAutoReverse(boolean value)

isAutoReverse

public final boolean isAutoReverse()

autoReverseProperty

public final BooleanProperty autoReverseProperty()

setStatus

protected final void setStatus(Animation.Status value)

getStatus

public final Animation.Status getStatus()

statusProperty

public final ReadOnlyObjectProperty<Animation.Status> statusProperty()

getTargetFramerate

public final double getTargetFramerate()

The target framerate is the maximum framerate at which this Animation will run, in frames per second. This can be used, for example, to keep particularly complex Animations from over-consuming system resources. By default, an Animation's framerate is not explicitly limited, meaning the Animation will run at an optimal framerate for the underlying platform.

Returns:

the target framerate

setOnFinished

public final void setOnFinished(EventHandler<ActionEvent> value)

getOnFinished

public final EventHandler<ActionEvent> getOnFinished()

onFinishedProperty

public final ObjectProperty<EventHandler<ActionEvent>> onFinishedProperty()

getCuePoints

public final ObservableMap<String,Duration> getCuePoints()

The cue points can be used to mark important positions of the Animation. Once a cue point was defined, it can be used as an argument of jumpTo() and playFrom() to move to the associated position quickly.

Every Animation has two predefined cue points "start" and "end", which are set at the start respectively the end of the Animation. The predefined cuepoints do not appear in the map, attempts to override them have no effect.

Another option to define a cue point in a Animation is to set the KeyFrame.name property of a KeyFrame.

Returns:

ObservableMap of cue points

jumpTo

public void jumpTo(Duration time)

Jumps to a given position in this Animation. If the given time is less than Duration.ZERO, this method will jump to the start of the animation. If the given time is larger than the duration of this Animation, this method will jump to the end.

Parameters:

time - the new position

Throws:

NullPointerException - if time is null

IllegalArgumentException - if time is Duration.UNKNOWN

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition

jumpTo

public void jumpTo(String cuePoint)

Jumps to a predefined position in this Animation. This method looks for an entry in cue points and jumps to the associated position, if it finds one.

If the cue point is behind the end of this Animation, calling jumpTo will result in a jump to the end. If the cue point has a negative Duration it will result in a jump to the beginning. If the cue point has a value of Duration.UNKNOWN calling jumpTo will have no effect for this cue point.

There are two predefined cue points "start" and "end" which are defined to be at the start respectively the end of this Animation.

Parameters:

cuePoint - the name of the cue point

Throws:

NullPointerException - if cuePoint is null

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition

See Also:

getCuePoints()

playFrom

public void playFrom(String cuePoint)

A convenience method to play this Animation from a predefined position. The position has to be predefined in cue points. Calling this method is equivalent to

 
 animation.jumpTo(cuePoint);
 animation.play();
 
 

Note that unlike playFromStart() calling this method will not change the playing direction of this Animation.

Parameters:

cuePoint - name of the cue point

Throws:

NullPointerException - if cuePoint is null

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition

See Also:

getCuePoints()

playFrom

public void playFrom(Duration time)

A convenience method to play this Animation from a specific position. Calling this method is equivalent to

 
 animation.jumpTo(time);
 animation.play();
 
 

Note that unlike playFromStart() calling this method will not change the playing direction of this Animation.

Parameters:

time - position where to play from

Throws:

NullPointerException - if time is null

IllegalArgumentException - if time is Duration.UNKNOWN

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition

play

public void play()

Plays Animation from current position in the direction indicated by rate. If the Animation is running, it has no effect.

When rate > 0 (forward play), if an Animation is already positioned at the end, the first cycle will not be played, it is considered to have already finished. This also applies to a backward ( rate < 0) cycle if an Animation is positioned at the beginning. However, if the Animation has cycleCount > 1, following cycle(s) will be played as usual.

When the Animation reaches the end, the Animation is stopped and the play head remains at the end.

To play an Animation backwards from the end:
animation.setRate(negative rate);
animation.jumpTo(overall duration of animation);
animation.play();


Note:

• play() is an asynchronous call, the Animation may not start immediately.

Throws:

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition

playFromStart

public void playFromStart()

Plays an Animation from initial position in forward direction.

It is equivalent to

animation.stop();
animation.setRate = setRate(Math.abs(animation.getRate()));
animation.jumpTo(Duration.ZERO);
animation.play();


Note:

• playFromStart() is an asynchronous call, Animation may not start immediately.

Throws:

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition

stop

public void stop()

Stops the animation and resets the play head to its initial position. If the animation is not currently running, this method has no effect.

Note:

• stop() is an asynchronous call, the Animation may not stop immediately.

Throws:

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition

pause

public void pause()

Pauses the animation. If the animation is not currently running, this method has no effect.

Note:

• pause() is an asynchronous call, the Animation may not pause immediately.

Throws:

IllegalStateException - if embedded in another animation, such as SequentialTransition or ParallelTransition