[Request] Advanced JavaFX content

[delabassee]

Request Issue

No response

Website Section

No response

Proposal Details

No response

Author References

No response

[SquidXTV]

Hi,

I recently wrote some introduction to javafx.animation, which summarizes the whole package with a few examples.
It probably needs some refining and going deeper into the topic but already covers a lot about Animation, Timeline, Transitions etc. I would really like to share it here and think this fits into this request.

[carimura]

Cool! Care to share and allow us to review the content to see if it'll work?

[SquidXTV]

Should I share it here before starting to make a PR?
Otherwise, I would follow README.md

[carimura]

here works! Or you can send to java_devrel_grp@oracle.com

[SquidXTV]

Ok so I am still unsure about the structure, but I want to at least mention every concept because this package is not that big.

It currently includes some GIFs and screenshots because it was initially intended to share on discord, this would need some updates. The transition description might need some updates as well, because they are currently just copied from the Javadoc description.

---

Introduction to javafx.animation

The javafx.animation package in JavaFX offers a simple framework for creating animations and transitions in a JavaFX application. It operates on the principle of WritableValue<T> which are used across JavaFX. It additionally provides a variety of built-in transitions for common effects, support for parallel and sequential transitions, and the ability to handle events upon animation completion.

Animation

The Animation abstract class provides the core functionality of all animations. An Animation can be in 3 states: [PAUSED, RUNNING, STOPPED]. It provides multiple play()/playFrom(), a stop() and a pause() method to control its flow. You can additionally set the cycle count which say how often the animation repeats, auto reverse to make an animation run back and forth while looping, and so on. A quick look into the Javadocs provide a great overview of its functionalities.

KeyValue.java

A KeyValue establishes a mapping between a WritableValue<T> to a target value of type T. This is used to define the change of a value. Interpolator can be additionally defined to change the behavior over time.

KeyFrame

A KeyFrame represents a specific moment in an animation sequence (Cue Point) and comprises a collection of KeyValue instances that change over the given Duration. The KeyFrame ensures a smooth transition using the internal interpolator of these KeyValue instances, mapping the property values over the specified duration to reach their target values upon completion. A KeyFrame can have a name which then can be used to identify this KeyFrame in an animation, or even start from this specific KeyFrame.

Timeline

A Timeline defines an Animation as a sequential series of KeyFrame instances. Each KeyFrame encapsulates a moment in time (Cue Point), and collectively specify how target properties evolve over the entire duration.

Warning: A running Timeline is being referenced from the FX runtime. Infinite Timeline might result in a memory leak if not stopped properly. All the objects with animated properties would not be garbage collected.

Example

This one basically moves the Circle 200px in x direction over the duration of 5 seconds:

Circle object = new Circle(50, 150, 10, Color.GREEN);

KeyValue x = new KeyValue(object.translateXProperty(), 200);
KeyFrame frame = new KeyFrame(Duration.seconds(5), x);
Timeline timeline = new Timeline(frame);
timeline.play();

Transition

The Transition abstract class serves as the foundational class for all transitions, presenting an alternative form of the Animation. JavaFX provides a variety of built-in transitions:

• FadeTransition: This Transition creates a fade effect animation that spans its duration. This is done by updating the opacity variable of the node at regular interval.
• FillTransition: This Transition creates an animation, that changes the filling of a shape over a duration. This is done by updating the fill variable of the shape at regular intervals.
• ParallelTransition: This Transition plays a list of Animations in parallel.
• PathTransition: This Transition creates a path animation that spans its duration. The translation along the path is done by updating the translateX and translateY variables of the node, and the rotate variable will get updated if orientation is set to OrientationType.ORTHOGONAL_TO_TANGENT, at regular interval.
• PauseTransition: This Transition executes an Animation.onFinished at the end of its duration.
• RotateTransition: This Transition creates a rotation animation that spans its duration. This is done by updating the rotate variable of the node at regular interval. The angle value is specified in degrees.
• ScaleTransition: This Transition creates a scale animation that spans its duration. This is done by updating the scaleX, scaleY and scaleZ variables of the node at regular interval.
• SequentialTransition: This Transition plays a list of Animations in sequential order.
• StrokeTransition: This Transition creates an animation, that changes the stroke color of a shape over a duration. This is done by updating the stroke variable of the shape at regular intervals.
• TranslateTransition: This Transition creates a move/translate animation that spans its duration. This is done by updating the translateX, translateY and translateZ variables of the node at regular interval.

Interpolator

The Interpolator abstract class defines the rate of change of animated values over time, influencing the smoothness of animations. It provides various built-in implementations:

• Interpolator.DISCRETE
• Interpolator.LINEAR
• Interpolator.EASE_IN
• Interpolator.EASE_OUT
• Interpolator.EASE_BOTH

Here is a visualization of the Interpolator using the example from Timeline:

Discrete

Linear

Ease In

Ease Out

Ease Both

Additionally, there are two static factory methods for SPLINE and TANGENT interpolation.

Conclusion

The javafx.animation package provides a simple framework for creating and managing animations in a JavaFX application. It includes classes like Animation, KeyValue, KeyFrame, Timeline, Transition and Interpolator that offer a wide range of features for controlling animation flow. Furthermore, it provides built-in transitions for common effects and allows handling events upon animation completion.

[nipafx]

Hey @SquidXTV, thank you for the proposal! I really like the clear and well-structured approach to the topic. I didn't know anything about it before and now feel like I have a basic understanding; definitely enough to start creating some animations. 😃

• Most paragraphs could do with a bit more details, e.g. on Interpolater in the KeyValue section (or a note that more detail is explained below) or in what sense a Transition is "an alternative form of the Animation".
• It's a matter of personal preference but maybe show the first example code and GIF (the wandering circle) before starting to explain the concepts? Along the lines of "look how cool this is, let's figure out how it works".
• Definitely keep the GIFs, they're great! In fact, maybe add more, e.g. for color or size changes? 😁
• Instead of just listing what was explained, the conclusion should summarize it.

[SquidXTV]

Hey @SquidXTV, thank you for the proposal! I really like the clear and well-structured approach to the topic. I didn't know anything about it before and now feel like I have a basic understanding; definitely enough to start creating some animations. 😃

• Most paragraphs could do with a bit more details, e.g. on Interpolater in the KeyValue section (or a note that more detail is explained below) or in what sense a Transition is "an alternative form of the Animation".
• It's a matter of personal preference but maybe show the first example code and GIF (the wandering circle) before starting to explain the concepts? Along the lines of "look how cool this is, let's figure out how it works".
• Definitely keep the GIFs, they're great! In fact, maybe add more, e.g. for color or size changes? 😁
• Instead of just listing what was explained, the conclusion should summarize it.

Thanks a lot for the feedback, I can just agree. :D

I would structure the explanation for each built-in Interpolator like I did with the built-in Transition.

I am not sure about the extra GIFs, I definitely would like to add more, but if I create an example for just FillTransition, then I am kinda missing an example GIF for every other Transition, which would kinda make it incomplete. It is not much work to create an GIF example for all built-in Transition and it would add a better overview to what they do. It is also easier for the reader as they do not need to read the explanation for each Transition to have a quick understanding. Would it be too much though?

I am also unsure about the Java Docs screenshots. I included them because the initial idea was to post it on discord. Should I do that differently for the website? If so, how would I do it?

[SquidXTV]

My progress for today. Still missing some stuff.

I now included most of the built-in transition examples. It kinda feels too much though, I might drop some of them in the future. What do you think about it?

---

Introduction to javafx.animation

The javafx.animation package in JavaFX offers a simple framework for creating animations and transitions in a JavaFX application. It operates on the principle of WritableValue<T> which are used across JavaFX. It additionally provides a variety of built-in transitions for common effects, support for parallel and sequential transitions, and the ability to handle events upon animation completion.

Animation

The Animation abstract class provides the core functionality of all animations. An Animation can be in 3 states: [PAUSED, RUNNING, STOPPED]. It provides multiple play()/playFrom(), a stop() and a pause() method to control its flow. You can additionally set the cycle count which say how often the animation repeats, auto reverse to make an animation run back and forth while looping, and so on. A quick look into the Javadocs provide a great overview of its functionalities.

KeyValue.java

A KeyValue establishes a mapping between a WritableValue<T> to a target value of type T. This is used to define the change of a value. Interpolator can be additionally defined to change the behavior over time.

KeyFrame

A KeyFrame represents a specific moment in an animation sequence (Cue Point) and comprises a collection of KeyValue instances that change over the given Duration. The KeyFrame ensures a smooth transition using the internal interpolator of these KeyValue instances, mapping the property values over the specified duration to reach their target values upon completion. A KeyFrame can have a name which then can be used to identify this KeyFrame in an animation, or even start from this specific KeyFrame.

Timeline

A Timeline defines an Animation as a sequential series of KeyFrame instances. Each KeyFrame encapsulates a moment in time (Cue Point), and collectively specify how target properties evolve over the entire duration.

Warning: A running Timeline is being referenced from the FX runtime. Infinite Timeline might result in a memory leak if not stopped properly. All the objects with animated properties would not be garbage collected.

Example

This one basically moves the Circle 200px in x direction over the duration of 5 seconds:

Circle object = new Circle(50, 150, 10, Color.GREEN);

KeyValue x = new KeyValue(object.translateXProperty(), 200);
KeyFrame frame = new KeyFrame(Duration.seconds(5), x);
Timeline timeline = new Timeline(frame);
timeline.play();

Transition

The Transition abstract class serves as the foundational class for all transitions, presenting an alternative form of the Animation. JavaFX provides a variety of built-in transitions:

• FadeTransition: This Transition creates a fade effect animation that spans its duration. This is done by updating the opacity variable of the node at regular interval.
• FillTransition: This Transition creates an animation, that changes the filling of a shape over a duration. This is done by updating the fill variable of the shape at regular intervals.
• ParallelTransition: This Transition plays a list of Animations in parallel.
• PathTransition: This Transition creates a path animation that spans its duration. The translation along the path is done by updating the translateX and translateY variables of the node, and the rotate variable will get updated if orientation is set to OrientationType.ORTHOGONAL_TO_TANGENT, at regular interval.
• PauseTransition: This Transition executes an Animation.onFinished at the end of its duration.
• RotateTransition: This Transition creates a rotation animation that spans its duration. This is done by updating the rotate variable of the node at regular interval. The angle value is specified in degrees.
• ScaleTransition: This Transition creates a scale animation that spans its duration. This is done by updating the scaleX, scaleY and scaleZ variables of the node at regular interval.
• SequentialTransition: This Transition plays a list of Animations in sequential order.
• StrokeTransition: This Transition creates an animation, that changes the stroke color of a shape over a duration. This is done by updating the stroke variable of the shape at regular intervals.
• TranslateTransition: This Transition creates a move/translate animation that spans its duration. This is done by updating the translateX, translateY and translateZ variables of the node at regular interval.

Note: By default, all transitions, excluding ParallelTransition and SequentialTransition, utilize the Interpolator#EASE_BOTH.

Here is a visualization of most built-in transitions:

Fade Transition

FadeTransition transition = new FadeTransition(Duration.seconds(5), object);
transition.setFromValue(1.0);
transition.setToValue(0);
transition.setInterpolator(Interpolator.LINEAR);

Fill Transition

FillTransition transition = new FillTransition(Duration.seconds(5), object);
transition.setFromValue(Color.GREEN);
transition.setToValue(Color.BLACK);
transition.setInterpolator(Interpolator.LINEAR);

Path Transition

Path path = new Path();
path.getElements().add(new MoveTo(50, 50)); // starting point
path.getElements().add(new LineTo(250, 250));

PathTransition transition = new PathTransition(Duration.seconds(5), path, object);
transition.setInterpolator(Interpolator.LINEAR);

Rotate Transition

RotateTransition transition = new RotateTransition(Duration.seconds(5), object);
transition.setFromAngle(0);
transition.setToAngle(360);
transition.setInterpolator(Interpolator.LINEAR);

Scale Transition

ScaleTransition transition = new ScaleTransition(Duration.seconds(5), object);
transition.setToX(0.1);
transition.setToY(0.1);
transition.setInterpolator(Interpolator.LINEAR);

Stroke Transition

StrokeTransition transition = new StrokeTransition(Duration.seconds(5), object);
transition.setFromValue(Color.GREEN);
transition.setToValue(Color.BLACK);
transition.setInterpolator(Interpolator.LINEAR);

Translate Transition

TranslateTransition transition = new TranslateTransition(Duration.seconds(5), object);
transition.setToX(200);
transition.setToY(200);
transition.setInterpolator(Interpolator.LINEAR);

Interpolator

The Interpolator abstract class defines the rate of change of animated values over time, influencing the smoothness of animations. It provides various built-in implementations:

• Interpolator.DISCRETE: The DISCRETE interpolator creates a sudden transition between values without any intermediate steps.
• Interpolator.LINEAR: The LINEAR interpolator produces a constant rate of change between values over time.
• Interpolator.EASE_IN: The EASE_IN interpolator starts the animation slowly and accelerates as it progresses.
• Interpolator.EASE_OUT: The EASE_OUT interpolator starts quickly and slows down as it progresses.
• Interpolator.EASE_BOTH: The EASE_BOTH interpolator starts slowly, accelerates in the middle and slows down towards the end. It combines the characteristics of EASE_IN and EASE_OUT.

Here is a visualization of the Interpolator using the example from Timeline:

Discrete

Linear

Ease In

Ease Out

Ease Both

Additionally, there are two static factory methods for SPLINE and TANGENT interpolation.

Conclusion

The javafx.animation package provides a simple framework for creating and managing animations in a JavaFX application. It includes classes like Animation, KeyValue, KeyFrame, Timeline, Transition and Interpolator that offer a wide range of features for controlling animation flow. Furthermore, it provides built-in transitions for common effects and allows handling events upon animation completion.

[nipafx]

Hey @SquidXTV, sorry that I didn't get back to you sooner. I like the addition of code and animations for the transitions. My other points above still apply, though, right? And I came up with two more changes that I think would make this even better:

• Explain towards the end of the introduction that you will go over the API type by type. (It's always nice for the user to know what's happening.)
• Don't link the headers. We don't do that elsewhere on dev.java and it will be missed because it's unexpected (or stand out if noticed). Instead, link the first mention of the word in the text.

I am also unsure about the Java Docs screenshots

Yeah, those work better in Discord than on dev.java. 😉 I think the sections containing them could do with a bit more explanation and maybe an example or two, anyway. There's no need to list, e.g., all constructors of a class but seeing how one or two of them work can be helpful.

[SquidXTV]

Hey @SquidXTV, sorry that I didn't get back to you sooner. I like the addition of code and animations for the transitions. My other points above still apply, though, right? And I came up with two more changes that I think would make this even better:

• Explain towards the end of the introduction that you will go over the API type by type. (It's always nice for the user to know what's happening.)
• Don't link the headers. We don't do that elsewhere on dev.java and it will be missed because it's unexpected (or stand out if noticed). Instead, link the first mention of the word in the text.

I am also unsure about the Java Docs screenshots

Yeah, those work better in Discord than on dev.java. 😉 I think the sections containing them could do with a bit more explanation and maybe an example or two, anyway. There's no need to list, e.g., all constructors of a class but seeing how one or two of them work can be helpful.

All good, didn't have the time myself. Going to improve it over the next days.

[SquidXTV]

Ok I have done some bigger revamp of the structure and changes to the text in general,
I am quite happy with the current result, though I might be bad at writing conclusions, haha.

---

Introduction to javafx.animation

The javafx.animation package in JavaFX offers a simple framework for creating animations and transitions in a JavaFX application. It operates on the principle of WritableValue<T> which are used across JavaFX. It additionally provides a variety of built-in transitions for common effects, support for parallel and sequential transitions, and the ability to handle events upon animation completion. I will go through all types of animations, including AnimationTimer, Animation, Transition and Timeline.

AnimationTimer

The AnimationTimer abstract class provides the lowest level option to create an animation. The handle(long now) method gets called in each frame while it is active. The timestamp long now is the nanoseconds time of the current frame and will be the same for all AnimationTimer called during that frame. Additionally, the AnimationTimer adds the start() and stop() to handle the lifetime of the animation.

Note that the handle implementation will be called on the JavaFX Application Thread and thus shouldn't do heavy computations.

Animation

The Animation abstract class provides the core functionality of all other animations. An Animation consists of multiple properties:

• The targetFramerate is the maximum framerate (frames per second) at which this Animation will run.
• The currentTime is the current Duration point of the Animation.
• The rate defines the direction and speed at which the Animation is expected to be played. It supports both positive and negative numbers.
• The cycleCount defines the number of cycles of this Animation. It can't be changed while running and must be positive.
• The cycleDuration is the Duration of one cycle of this Animation. It is the time it takes to play from start to end of the Animation at the default rate of 1.0.
• The totalDuration indicates the total duration of this Animation, including repeats. It is the result of cycleDuration * cycleCount or possibly Duration.INDEFINITE.
• The delay is the Duration that delays the Animation when starting.
• The autoReverse property defines if the Animation will reverse direction on alternating cycles.
• The onFinished event handler is used to define additional behavior when the Animation finished.
• The status represents the current state of the Animation, possible states are PAUSED, RUNNING and STOPPED.

Additionally, it provides multiple play()/playFrom(String cuePoint), a stop() and a pause() method to control its flow.
A quick look into the Javadocs provides a great overview of its functionalities.

Transition

The Transition abstract class serves as the foundational class for all transitions, presenting a common form of Animation.

JavaFX provides a variety of built-in transitions:

• The FadeTransition creates a fade effect over a duration. This is done by updating the opacity property of the Node at regular intervals.
• The FillTransition creates an animation, that changes the filling of a shape over a duration. This is done by updating the fill property of the Shape at regular intervals.
• The ParallelTransition plays a list of Animations in parallel.
• The PathTransition creates a path animation that spans its duration. The translation along the path is done by updating the translateX and translateY properties of the Node, and the rotate variable will get updated if orientation is set to OrientationType.ORTHOGONAL_TO_TANGENT, at regular interval.
• The PauseTransition executes an Animation.onFinished at the end of its duration.
• The RotateTransition creates a rotation animation that spans its duration. This is done by updating the rotate property of the Node at regular interval. The angle value is specified in degrees.
• The ScaleTransition creates a scale animation over a duration. This is done by updating the scaleX, scaleY and scaleZ properties of the Node at regular interval.
• The SequentialTransition plays a list of Animations in sequential order. It is not recommended to contain an Animation, which is not the last one, with Duration.INDEFINITE as this will block all later animations in the sequence.
• The StrokeTransition creates an animation, that changes the stroke color of a shape over a duration. This is done by updating the stroke property of the Shape at regular intervals.
• The TranslateTransition creates a move/translate animation that spans its duration. This is done by updating the translateX, translateY and translateZ properties of the Node at regular interval.

Note: By default, all transitions, excluding ParallelTransition and SequentialTransition, utilize the Interpolator#EASE_BOTH.

Here is a visualization of most built-in transitions:

Fade Transition

FadeTransition transition = new FadeTransition(Duration.seconds(5), object);
transition.setFromValue(1.0);
transition.setToValue(0);
transition.setInterpolator(Interpolator.LINEAR);

Fill Transition

FillTransition transition = new FillTransition(Duration.seconds(5), object);
transition.setFromValue(Color.GREEN);
transition.setToValue(Color.BLACK);
transition.setInterpolator(Interpolator.LINEAR);

Path Transition

Path path = new Path();
path.getElements().add(new MoveTo(50, 50)); // starting point
path.getElements().add(new LineTo(250, 250));

PathTransition transition = new PathTransition(Duration.seconds(5), path, object);
transition.setInterpolator(Interpolator.LINEAR);

Rotate Transition

RotateTransition transition = new RotateTransition(Duration.seconds(5), object);
transition.setFromAngle(0);
transition.setToAngle(360);
transition.setInterpolator(Interpolator.LINEAR);

Scale Transition

ScaleTransition transition = new ScaleTransition(Duration.seconds(5), object);
transition.setToX(0.1);
transition.setToY(0.1);
transition.setInterpolator(Interpolator.LINEAR);

Stroke Transition

StrokeTransition transition = new StrokeTransition(Duration.seconds(5), object);
transition.setFromValue(Color.GREEN);
transition.setToValue(Color.BLACK);
transition.setInterpolator(Interpolator.LINEAR);

Translate Transition

TranslateTransition transition = new TranslateTransition(Duration.seconds(5), object);
transition.setToX(200);
transition.setToY(200);
transition.setInterpolator(Interpolator.LINEAR);

Timeline

A Timeline is used to define a free form Animation of any WritableValue<T>. It is helpful if none of the built-in transitions operate on the required properties.

It consists of a sequential series of KeyFrame. Each KeyFrame encapsulates a moment in time (Cue Point), and collectively specify how target properties evolve over the entire duration.

Warning: A running Timeline is being referenced from the FX runtime. Infinite Timeline might result in a memory leak if not stopped properly. All the objects with animated properties would not be garbage collected.

KeyFrame

A KeyFrame represents a specific moment in an animation sequence (Cue Point) and comprises a collection of KeyValue instances that change from start to the given Duration.

A KeyFrame can have a name which then can be used to identify this KeyFrame in an animation, for example for starting from this specific KeyFrame. It is also possible to provide an onFinished implementation, which will be invoked when hitting this cue point.

KeyValue

A KeyValue establishes a mapping between a WritableValue<T> and a target value of type T. This is used to define the change of a value. An Interpolator can be additionally defined to change the rate of change for this value. The KeyValue class is immutable.

Example

This example of Timeline creates a Circle which moves 200px in x direction over the duration of 5 seconds:

Circle object = new Circle(50, 150, 10, Color.GREEN);

KeyValue x = new KeyValue(object.translateXProperty(), 200);
KeyFrame frame = new KeyFrame(Duration.seconds(5), x);
Timeline timeline = new Timeline(frame);
timeline.play();

Interpolator

The Interpolator abstract class defines the rate of change at which values change over time, influencing the smoothness of animations.

It provides several built-in implementations:

• Interpolator.DISCRETE: The DISCRETE interpolator creates a sudden transition between values without any intermediate steps.
• Interpolator.LINEAR: The LINEAR interpolator produces a constant rate of change between values over time.
• Interpolator.EASE_IN: The EASE_IN interpolator starts the animation slowly and accelerates as it progresses.
• Interpolator.EASE_OUT: The EASE_OUT interpolator starts quickly and slows down as it progresses.
• Interpolator.EASE_BOTH: The EASE_BOTH interpolator starts slowly, accelerates in the middle and slows down towards the end. It combines the characteristics of EASE_IN and EASE_OUT.

Additionally, there are two static factory methods for SPLINE and TANGENT interpolation.

Here is a visualization of the Interpolator using the example from Timeline:

Discrete

Linear

Ease In

Ease Out

Ease Both

Conclusion

The javafx.animation package offers a simple framework for creating dynamic animations within JavaFX applications.
From the foundational AnimationTimer and Animation classes to the more specialized Transition and Timeline classes,
each component provides unique capabilities for creating animations. Additionally, you are provided with various
common Interpolator implementations.