- Direct Known Subclasses:
Timeline
,Transition
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:
-
Property Summary
TypePropertyDescriptionfinal BooleanProperty
Defines whether thisAnimation
reverses direction on alternating cycles.final ReadOnlyDoubleProperty
Read-only variable to indicate current direction/speed at which theAnimation
is being played.final ReadOnlyObjectProperty<Duration>
Defines theAnimation
's play head position.final IntegerProperty
Defines the number of cycles in this animation.final ReadOnlyObjectProperty<Duration>
Read-only variable to indicate the duration of one cycle of thisAnimation
: the time it takes to play from time 0 to the end of the Animation (at the defaultrate
of 1.0).final ObjectProperty<Duration>
Delays the start of an animation.final ObjectProperty<EventHandler<ActionEvent>>
The action to be executed at the conclusion of thisAnimation
.final DoubleProperty
Defines the direction/speed at which theAnimation
is expected to be played.The status of theAnimation
.final ReadOnlyObjectProperty<Duration>
Read-only variable to indicate the total duration of thisAnimation
, including repeats. -
Nested Class Summary
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Used as a value forcycleCount
to specify an animation that repeats indefinitely, until thestop()
method is called. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionfinal BooleanProperty
Defines whether thisAnimation
reverses direction on alternating cycles.final ReadOnlyDoubleProperty
Read-only variable to indicate current direction/speed at which theAnimation
is being played.final ReadOnlyObjectProperty<Duration>
Defines theAnimation
's play head position.final IntegerProperty
Defines the number of cycles in this animation.final ReadOnlyObjectProperty<Duration>
Read-only variable to indicate the duration of one cycle of thisAnimation
: the time it takes to play from time 0 to the end of the Animation (at the defaultrate
of 1.0).final ObjectProperty<Duration>
Delays the start of an animation.final ObservableMap<String,
Duration> The cue points can be used to mark important positions of theAnimation
.final double
Gets the value of thecurrentRate
property.final Duration
Gets the value of thecurrentTime
property.final int
Gets the value of thecycleCount
property.final Duration
Gets the value of thecycleDuration
property.final Duration
getDelay()
Gets the value of thedelay
property.final EventHandler<ActionEvent>
Gets the value of theonFinished
property.final double
getRate()
Gets the value of therate
property.final Animation.Status
Gets the value of thestatus
property.final double
The target framerate is the maximum framerate at which thisAnimation
will run, in frames per second.final Duration
Gets the value of thetotalDuration
property.final boolean
Gets the value of theautoReverse
property.void
Jumps to a predefined position in thisAnimation
.void
Jumps to a given position in thisAnimation
.final ObjectProperty<EventHandler<ActionEvent>>
The action to be executed at the conclusion of thisAnimation
.void
pause()
Pauses the animation.void
play()
PlaysAnimation
from current position in the direction indicated byrate
.void
A convenience method to play thisAnimation
from a predefined position.void
A convenience method to play thisAnimation
from a specific position.void
Plays anAnimation
from initial position in forward direction.final DoubleProperty
Defines the direction/speed at which theAnimation
is expected to be played.final void
setAutoReverse
(boolean value) Sets the value of theautoReverse
property.final void
setCycleCount
(int value) Sets the value of thecycleCount
property.protected final void
setCycleDuration
(Duration value) Sets the value of thecycleDuration
property.final void
Sets the value of thedelay
property.final void
setOnFinished
(EventHandler<ActionEvent> value) Sets the value of theonFinished
property.final void
setRate
(double value) Sets the value of therate
property.protected final void
setStatus
(Animation.Status value) Sets the value of thestatus
property.The status of theAnimation
.void
stop()
Stops the animation and resets the play head to its initial position.final ReadOnlyObjectProperty<Duration>
Read-only variable to indicate the total duration of thisAnimation
, including repeats.
-
Property Details
-
rate
Defines the direction/speed at which theAnimation
is expected to be played.The absolute value of
rate
indicates the speed at which theAnimation
is to be played, while the sign ofrate
indicates the direction. A positive value ofrate
indicates forward play, a negative value indicates backward play and0.0
to stop a runningAnimation
.Rate
1.0
is normal play,2.0
is 2 time normal,-1.0
is backwards, etc.Inverting the rate of a running
Animation
will cause theAnimation
to reverse direction in place and play back over the portion of theAnimation
that has already elapsed.- Default value:
- 1.0
- See Also:
-
currentRate
Read-only variable to indicate current direction/speed at which theAnimation
is being played.currentRate
is not necessarily equal torate
.currentRate
is set to0.0
when animation is paused or stopped.currentRate
may also point in the opposite direction ofrate
during reverse cycles whenautoReverse
istrue
.- Default value:
- 0.0
- See Also:
-
cycleDuration
Read-only variable to indicate the duration of one cycle of thisAnimation
: the time it takes to play from time 0 to the end of the Animation (at the defaultrate
of 1.0).- Default value:
- 0ms
- See Also:
-
totalDuration
Read-only variable to indicate the total duration of thisAnimation
, including repeats. AnAnimation
with acycleCount
ofAnimation.INDEFINITE
will have atotalDuration
ofDuration.INDEFINITE
.This is set to cycleDuration * cycleCount.
- Default value:
- 0ms
- See Also:
-
currentTime
Defines theAnimation
's play head position.- Default value:
- 0ms
- See Also:
-
delay
Delays the start of an animation. Cannot be negative. Setting to a negative number will result inIllegalArgumentException
.- Default value:
- 0ms
- See Also:
-
cycleCount
Defines the number of cycles in this animation. ThecycleCount
may beINDEFINITE
for animations that repeat indefinitely, but must otherwise be > 0.It is not possible to change the
cycleCount
of a runningAnimation
. If the value ofcycleCount
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value.- Default value:
- 1
- See Also:
-
autoReverse
Defines whether thisAnimation
reverses direction on alternating cycles. Iftrue
, theAnimation
will proceed forward on the first cycle, then reverses on the second cycle, and so on. Otherwise, animation will loop such that each cycle proceeds forward from the start. It is not possible to change theautoReverse
flag of a runningAnimation
. If the value ofautoReverse
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value.- Default value:
- false
- See Also:
-
status
The status of theAnimation
. AnAnimation
can be in one of three states:Animation.Status.STOPPED
,Animation.Status.PAUSED
orAnimation.Status.RUNNING
. -
onFinished
The action to be executed at the conclusion of thisAnimation
.- Default value:
- null
- See Also:
-
-
Field Details
-
INDEFINITE
public static final int INDEFINITEUsed as a value forcycleCount
to specify an animation that repeats indefinitely, until thestop()
method is called.- See Also:
-
-
Constructor Details
-
Animation
protected Animation(double targetFramerate) The constructor ofAnimation
. This constructor allows to define a target framerate.- Parameters:
targetFramerate
- The custom target frame rate for thisAnimation
- See Also:
-
Animation
protected Animation()The constructor ofAnimation
.
-
-
Method Details
-
setRate
public final void setRate(double value) Sets the value of therate
property.- Property description:
- Defines the direction/speed at which the
Animation
is expected to be played.The absolute value of
rate
indicates the speed at which theAnimation
is to be played, while the sign ofrate
indicates the direction. A positive value ofrate
indicates forward play, a negative value indicates backward play and0.0
to stop a runningAnimation
.Rate
1.0
is normal play,2.0
is 2 time normal,-1.0
is backwards, etc.Inverting the rate of a running
Animation
will cause theAnimation
to reverse direction in place and play back over the portion of theAnimation
that has already elapsed. - Default value:
- 1.0
- Parameters:
value
- the value for therate
property- See Also:
-
getRate
public final double getRate()Gets the value of therate
property.- Property description:
- Defines the direction/speed at which the
Animation
is expected to be played.The absolute value of
rate
indicates the speed at which theAnimation
is to be played, while the sign ofrate
indicates the direction. A positive value ofrate
indicates forward play, a negative value indicates backward play and0.0
to stop a runningAnimation
.Rate
1.0
is normal play,2.0
is 2 time normal,-1.0
is backwards, etc.Inverting the rate of a running
Animation
will cause theAnimation
to reverse direction in place and play back over the portion of theAnimation
that has already elapsed. - Default value:
- 1.0
- Returns:
- the value of the
rate
property - See Also:
-
rateProperty
Defines the direction/speed at which theAnimation
is expected to be played.The absolute value of
rate
indicates the speed at which theAnimation
is to be played, while the sign ofrate
indicates the direction. A positive value ofrate
indicates forward play, a negative value indicates backward play and0.0
to stop a runningAnimation
.Rate
1.0
is normal play,2.0
is 2 time normal,-1.0
is backwards, etc.Inverting the rate of a running
Animation
will cause theAnimation
to reverse direction in place and play back over the portion of theAnimation
that has already elapsed.- Default value:
- 1.0
- Returns:
- the
rate
property - See Also:
-
getCurrentRate
public final double getCurrentRate()Gets the value of thecurrentRate
property.- Property description:
- Read-only variable to indicate current direction/speed at which the
Animation
is being played.currentRate
is not necessarily equal torate
.currentRate
is set to0.0
when animation is paused or stopped.currentRate
may also point in the opposite direction ofrate
during reverse cycles whenautoReverse
istrue
. - Default value:
- 0.0
- Returns:
- the value of the
currentRate
property - See Also:
-
currentRateProperty
Read-only variable to indicate current direction/speed at which theAnimation
is being played.currentRate
is not necessarily equal torate
.currentRate
is set to0.0
when animation is paused or stopped.currentRate
may also point in the opposite direction ofrate
during reverse cycles whenautoReverse
istrue
.- Default value:
- 0.0
- Returns:
- the
currentRate
property - See Also:
-
setCycleDuration
Sets the value of thecycleDuration
property.- Property description:
- Read-only variable to indicate the duration of one cycle of this
Animation
: the time it takes to play from time 0 to the end of the Animation (at the defaultrate
of 1.0). - Default value:
- 0ms
- Parameters:
value
- the value for thecycleDuration
property- See Also:
-
getCycleDuration
Gets the value of thecycleDuration
property.- Property description:
- Read-only variable to indicate the duration of one cycle of this
Animation
: the time it takes to play from time 0 to the end of the Animation (at the defaultrate
of 1.0). - Default value:
- 0ms
- Returns:
- the value of the
cycleDuration
property - See Also:
-
cycleDurationProperty
Read-only variable to indicate the duration of one cycle of thisAnimation
: the time it takes to play from time 0 to the end of the Animation (at the defaultrate
of 1.0).- Default value:
- 0ms
- Returns:
- the
cycleDuration
property - See Also:
-
getTotalDuration
Gets the value of thetotalDuration
property.- Property description:
- Read-only variable to indicate the total duration of this
Animation
, including repeats. AnAnimation
with acycleCount
ofAnimation.INDEFINITE
will have atotalDuration
ofDuration.INDEFINITE
.This is set to cycleDuration * cycleCount.
- Default value:
- 0ms
- Returns:
- the value of the
totalDuration
property - See Also:
-
totalDurationProperty
Read-only variable to indicate the total duration of thisAnimation
, including repeats. AnAnimation
with acycleCount
ofAnimation.INDEFINITE
will have atotalDuration
ofDuration.INDEFINITE
.This is set to cycleDuration * cycleCount.
- Default value:
- 0ms
- Returns:
- the
totalDuration
property - See Also:
-
getCurrentTime
Gets the value of thecurrentTime
property.- Property description:
- Defines the
Animation
's play head position. - Default value:
- 0ms
- Returns:
- the value of the
currentTime
property - See Also:
-
currentTimeProperty
Defines theAnimation
's play head position.- Default value:
- 0ms
- Returns:
- the
currentTime
property - See Also:
-
setDelay
Sets the value of thedelay
property.- Property description:
- Delays the start of an animation.
Cannot be negative. Setting to a negative number will result in
IllegalArgumentException
. - Default value:
- 0ms
- Parameters:
value
- the value for thedelay
property- See Also:
-
getDelay
Gets the value of thedelay
property.- Property description:
- Delays the start of an animation.
Cannot be negative. Setting to a negative number will result in
IllegalArgumentException
. - Default value:
- 0ms
- Returns:
- the value of the
delay
property - See Also:
-
delayProperty
Delays the start of an animation. Cannot be negative. Setting to a negative number will result inIllegalArgumentException
.- Default value:
- 0ms
- Returns:
- the
delay
property - See Also:
-
setCycleCount
public final void setCycleCount(int value) Sets the value of thecycleCount
property.- Property description:
- Defines the number of cycles in this animation. The
cycleCount
may beINDEFINITE
for animations that repeat indefinitely, but must otherwise be > 0.It is not possible to change the
cycleCount
of a runningAnimation
. If the value ofcycleCount
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value. - Default value:
- 1
- Parameters:
value
- the value for thecycleCount
property- See Also:
-
getCycleCount
public final int getCycleCount()Gets the value of thecycleCount
property.- Property description:
- Defines the number of cycles in this animation. The
cycleCount
may beINDEFINITE
for animations that repeat indefinitely, but must otherwise be > 0.It is not possible to change the
cycleCount
of a runningAnimation
. If the value ofcycleCount
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value. - Default value:
- 1
- Returns:
- the value of the
cycleCount
property - See Also:
-
cycleCountProperty
Defines the number of cycles in this animation. ThecycleCount
may beINDEFINITE
for animations that repeat indefinitely, but must otherwise be > 0.It is not possible to change the
cycleCount
of a runningAnimation
. If the value ofcycleCount
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value.- Default value:
- 1
- Returns:
- the
cycleCount
property - See Also:
-
setAutoReverse
public final void setAutoReverse(boolean value) Sets the value of theautoReverse
property.- Property description:
- Defines whether this
Animation
reverses direction on alternating cycles. Iftrue
, theAnimation
will proceed forward on the first cycle, then reverses on the second cycle, and so on. Otherwise, animation will loop such that each cycle proceeds forward from the start. It is not possible to change theautoReverse
flag of a runningAnimation
. If the value ofautoReverse
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value. - Default value:
- false
- Parameters:
value
- the value for theautoReverse
property- See Also:
-
isAutoReverse
public final boolean isAutoReverse()Gets the value of theautoReverse
property.- Property description:
- Defines whether this
Animation
reverses direction on alternating cycles. Iftrue
, theAnimation
will proceed forward on the first cycle, then reverses on the second cycle, and so on. Otherwise, animation will loop such that each cycle proceeds forward from the start. It is not possible to change theautoReverse
flag of a runningAnimation
. If the value ofautoReverse
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value. - Default value:
- false
- Returns:
- the value of the
autoReverse
property - See Also:
-
autoReverseProperty
Defines whether thisAnimation
reverses direction on alternating cycles. Iftrue
, theAnimation
will proceed forward on the first cycle, then reverses on the second cycle, and so on. Otherwise, animation will loop such that each cycle proceeds forward from the start. It is not possible to change theautoReverse
flag of a runningAnimation
. If the value ofautoReverse
is changed for a runningAnimation
, the animation has to be stopped and started again to pick up the new value.- Default value:
- false
- Returns:
- the
autoReverse
property - See Also:
-
setStatus
Sets the value of thestatus
property.- Property description:
- The status of the
Animation
. AnAnimation
can be in one of three states:Animation.Status.STOPPED
,Animation.Status.PAUSED
orAnimation.Status.RUNNING
. - Parameters:
value
- the value for thestatus
property- See Also:
-
getStatus
Gets the value of thestatus
property.- Property description:
- The status of the
Animation
. AnAnimation
can be in one of three states:Animation.Status.STOPPED
,Animation.Status.PAUSED
orAnimation.Status.RUNNING
. - Returns:
- the value of the
status
property - See Also:
-
statusProperty
The status of theAnimation
. AnAnimation
can be in one of three states:Animation.Status.STOPPED
,Animation.Status.PAUSED
orAnimation.Status.RUNNING
.- Returns:
- the
status
property - See Also:
-
setOnFinished
Sets the value of theonFinished
property.- Property description:
- The action to be executed at the conclusion of this
Animation
. - Default value:
- null
- Parameters:
value
- the value for theonFinished
property- See Also:
-
getOnFinished
Gets the value of theonFinished
property.- Property description:
- The action to be executed at the conclusion of this
Animation
. - Default value:
- null
- Returns:
- the value of the
onFinished
property - See Also:
-
onFinishedProperty
The action to be executed at the conclusion of thisAnimation
.- Default value:
- null
- Returns:
- the
onFinished
property - See Also:
-
getCuePoints
The cue points can be used to mark important positions of theAnimation
. Once a cue point was defined, it can be used as an argument ofjumpTo()
andplayFrom()
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 theAnimation
. 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 thename
property of aKeyFrame
.- Returns:
ObservableMap
of cue points
-
jumpTo
Jumps to a given position in thisAnimation
. If the given time is less thanDuration.ZERO
, this method will jump to the start of the animation. If the given time is larger than the duration of thisAnimation
, this method will jump to the end.- Parameters:
time
- the new position- Throws:
NullPointerException
- iftime
isnull
IllegalArgumentException
- iftime
isDuration.UNKNOWN
IllegalStateException
- if embedded in another animation, such asSequentialTransition
orParallelTransition
-
jumpTo
Jumps to a predefined position in thisAnimation
. 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
, callingjumpTo
will result in a jump to the end. If the cue point has a negativeDuration
it will result in a jump to the beginning. If the cue point has a value ofDuration.UNKNOWN
callingjumpTo
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 thisAnimation
.- Parameters:
cuePoint
- the name of the cue point- Throws:
NullPointerException
- ifcuePoint
isnull
IllegalStateException
- if embedded in another animation, such asSequentialTransition
orParallelTransition
- See Also:
-
playFrom
A convenience method to play thisAnimation
from a predefined position. The position has to be predefined in cue points. Calling this method is equivalent toanimation.jumpTo(cuePoint); animation.play();
playFromStart()
calling this method will not change the playing direction of thisAnimation
.- Parameters:
cuePoint
- name of the cue point- Throws:
NullPointerException
- ifcuePoint
isnull
IllegalStateException
- if embedded in another animation, such asSequentialTransition
orParallelTransition
- See Also:
-
playFrom
A convenience method to play thisAnimation
from a specific position. Calling this method is equivalent toanimation.jumpTo(time); animation.play();
playFromStart()
calling this method will not change the playing direction of thisAnimation
.- Parameters:
time
- position where to play from- Throws:
NullPointerException
- iftime
isnull
IllegalArgumentException
- iftime
isDuration.UNKNOWN
IllegalStateException
- if embedded in another animation, such asSequentialTransition
orParallelTransition
-
playFromStart
public void playFromStart()Plays anAnimation
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 asSequentialTransition
orParallelTransition
-
play
public void play()PlaysAnimation
from current position in the direction indicated byrate
. If theAnimation
is running, it has no effect.When
rate
> 0 (forward play), if anAnimation
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 anAnimation
is positioned at the beginning. However, if theAnimation
hascycleCount
> 1, following cycle(s) will be played as usual.When the
Animation
reaches the end, theAnimation
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, theAnimation
may not start immediately.
- Throws:
IllegalStateException
- if embedded in another animation, such asSequentialTransition
orParallelTransition
-
stop
public void stop()Stops the animation and resets the play head to its initial position. If the animation is already stopped, this method has no effect.Note:
stop()
is an asynchronous call, theAnimation
may not stop immediately.
- Throws:
IllegalStateException
- if embedded in another animation, such asSequentialTransition
orParallelTransition
-
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, theAnimation
may not pause immediately.
- Throws:
IllegalStateException
- if embedded in another animation, such asSequentialTransition
orParallelTransition
-
getTargetFramerate
public final double getTargetFramerate()The target framerate is the maximum framerate at which thisAnimation
will run, in frames per second. This can be used, for example, to keep particularly complexAnimations
from over-consuming system resources. By default, anAnimation
's framerate is not explicitly limited, meaning theAnimation
will run at an optimal framerate for the underlying platform.- Returns:
- the target framerate
-