Creating and running a JavaFX application

The last lesson described a JavaFX program from the outside: a Stage holding a Scene holding a tree of nodes. This lesson writes one. You will build two programs, a brown window 600 pixels wide and a window that says “Welcome to Ooty”, then compile and run them yourself from a terminal, knowing what every word of the long javac and java commands does.

Creating a JavaFX application#

Every JavaFX program is built around one library class, Application in the package javafx.application. It is the entry point of a JavaFX application, and your program is a class that inherits from it.

Three pieces turn a class into a JavaFX program:

• extends Application makes your class a JavaFX application.
• start(Stage primaryStage) is the abstract method you must override. JavaFX calls it once, handing it the primary stage it created, and all the code that builds your window goes inside it. The template declares throws Exception because Application declares it that way. If startdoes throw, JavaFX prints “Exception in Application start method” with the stack trace, and the program ends.
• main calls launch(args), a static method Application provides. It starts the JavaFX runtime, creates an instance of your class and calls its start method. It does not return until the application has finished.

This is a template: it compiles once the imports
javafx.application.Application and javafx.stage.Stage are added.
Run as it stands, it shows nothing. start() never calls show(), so no
window appears, and with no window to close, the program waits until
you press Ctrl+C.

Inside start, a typical JavaFX application follows three steps:

1. 1Prepare a scene graph with the required nodes.
2. 2Prepare a Scene with the required dimensions, and add the scene graph to it by passing in its root node.
3. 3Prepare a Stage, add the scene to it, and display the contents of the stage.

Key idea

Every start method does the same three things in the same order: build the tree of nodes, wrap it in a Scene, then put the Scene on the Stage and show it.

Step 1: preparing the scene graph#

A scene graph starts with its root node, since every other node hangs below it. There are three kinds of root to choose from: a Group, a Region (in practice one of its subclasses, a layout pane such as StackPane or GridPane) or a WebView. The controls and layouts lesson goes through the Region family. The examples in this lesson use a Group.

A Group (package javafx.scene) is a node whose only job is to hold other nodes. Creating one is a plain constructor call, Group root = new Group();, and an empty group shows nothing. To put nodes in it, ask for its list of children: getChildren() returns an ObservableList (package javafx.collections) holding the group's nodes, and whatever you add to that list becomes a child of the group.

NodeObject stands for any node you have already created: a Text, a
Rectangle, a Button. After add(), it is a child of root, and it appears
once the scene is shown.

ObservableList is an interface that extends java.util.List, so it has the methods you would expect: add, addAll, remove, get, size. Observable means the group is notified the instant the list changes. That is why adding a node to the list is enough to put it in the window, with no refresh call, and why removing it later makes it disappear.

Two shorter forms reach the same result. The first passes the node to the constructor: Group root = new Group(NodeObject);. That constructor accepts any number of nodes, so new Group(title, photo, button) works too. And you can skip the variable: root.getChildren().add(NodeObject);.

Step 2: preparing the Scene#

A JavaFX scene is an object of the class Scene in the package javafx.scene. Passing the root to the constructor is mandatory; the size is optional.

Two alternatives: a program uses one or the other, since both
declare a variable named scene.

With no size, the scene makes itself just big enough for the root's content, which for an empty group means a tiny window. With a size, the scene is exactly that big, whatever the content.

A scene also has a fill, the colour behind everything in it, white unless you change it. scene.setFill(Color.BROWN) paints it brown. Color lives in javafx.scene.paint. It has a constant for every named web colour (Color.BROWN is #A52A2A, Color.NAVY is #000080), and it builds any other colour with Color.rgb(165, 42, 42) or Color.web("#A52A2A"). One more constructor takes the fill directly: new Scene(root, 600, 300, Color.BROWN).

Step 3: preparing the Stage#

The stage is the container of a JavaFX application: it provides the window. It is an object of the class Stage in the package javafx.stage, and JavaFX passes one to start() as its parameter. With that object you set the window's title with setTitle(), attach the scene with setScene(), and display the stage with show().

A window titled "Sample application" opens, showing the scene.

Two things about show(). Nothing is on screen before it runs; until then the stage is an object in memory. And it does not wait: show() returns at once, start reaches its closing brace, and the window stays open because the JavaFX runtime is still running the event loop on its own thread. A loop added at the end of startto “keep the window open” does the opposite: it blocks that thread and freezes the window.

The lifecycle of a JavaFX application#

The Application class has three lifecycle methods:

• start(): the entry point, where the JavaFX graphics code is written. It is abstract, so you must override it.
• stop(): empty by default. Override it to write the logic that runs when the application stops, such as saving settings or closing a database connection.
• init(): empty by default. Override it for setup that should happen before any window exists, such as reading a configuration file. You cannot create a stage or a scene in it.

Beside them is the static method launch(). Because it is static, you call it from a static context, normally main. Whenever a JavaFX application is launched, these actions happen in this order:

1. 1An instance of your application class is created: its constructor runs.
2. 2init() is called.
3. 3start() is called, with the primary stage.
4. 4The launcher waits for the application to finish, which happens when the last window is closed or the program calls Platform.exit(), and then calls stop(). Only after that does launch return to main.

Which thread runs what#

The lifecycle is spread over three threads. main runs on the main thread, which then sits inside launch until the very end. The constructor, start, stop and every event handler run on the JavaFX Application Thread. init is the odd one out: it runs on a separate launcher thread, named JavaFX-Launcher.

That is the reason behind the rule for init. A Stage and a Scene belong to the JavaFX Application Thread, and the JavaFX documentation states plainly that an application must not construct either one in init. Try to create a Stage there and it fails with IllegalStateException: Not on FX application thread; currentThread = JavaFX-Launcher. Use init for work that does not touch the screen, and build the window in start. This program prints the name of the thread at every stage.

main on main
constructor on JavaFX Application Thread
init on JavaFX-Launcher
start on JavaFX Application Thread
   (a 300 by 150 window titled "Lifecycle" is open; close it)
stop on JavaFX Application Thread
launch returned, main ends

Read the output against the steps. main prints first, on the main thread. The constructor and start share the JavaFX Application Thread, while init runs between them on the launcher thread. Nothing more happens until you close the window. Then stop runs, and only once it has finished does launch return and let main print its last line.

Terminating a JavaFX application#

By default a JavaFX application ends implicitly: when its last window is closed, the launcher calls stop() and the program finishes. You can switch this off by passing false to setImplicitExit().

To end the application explicitly, there are two methods, Platform.exit() and System.exit(int). They do not do the same thing:

Button handlers arrive in the event handling session. Until then,
read Platform.exit() as the call a Quit button should make.

Example: creating an empty window#

Here is one complete program, JavafxSample, built in seven steps. The result is a window titled “Sample Application”, 600 pixels wide and 300 tall, filled brown and otherwise empty.

1. 1Create a class that inherits the Application class of the package javafx.application and implements its start() method: public class JavafxSample extends Application, containing an empty public void start(Stage primaryStage) throws Exception marked @Override.
2. 2Create a Group object inside start(), by instantiating the class Group of the package javafx.scene: Group root = new Group();
3. 3Create a Scene object, passing the group as the root, along with the size: Scene scene = new Scene(root, 600, 300); The two numbers are the width and height of the scene, in that order.
4. 4Set the title of the stage through the primaryStage parameter: primaryStage.setTitle("Sample Application"); JavaFX passes the stage to start in your Application subclass.
5. 5Add the scene to the stage: primaryStage.setScene(scene);
6. 6Display the contents of the stage: primaryStage.show();
7. 7Launch the application by calling the static method launch() from main: public static void main(String args[]){ launch(args); }. The form String args[] is an older way of writing String[] args; both mean the same.

Put together with its imports and one extra line that colours the scene, this is the whole program. The group variable is called group here rather than root; any name works.

A window titled "Sample Application" whose 600 by 300 content area is
filled brown (Color.BROWN, #A52A2A). Nothing is printed by the program
itself. Close the window and the program ends.

Compiling and running from the command line#

Since Java 11, JavaFX is not part of the JDK, so javac and java cannot find it on their own. You download the JavaFX SDK from openjfx.io, choosing version 27 and your own operating system and processor, and unzip it, for example to C:\Program Files\javafx-sdk-27. Its lib folder holds JavaFX's modules as .jar files (javafx.base.jar, javafx.graphics.jar, javafx.controls.jar and the rest), and every command below points at that folder.

PATH_TO_FX and the Command Prompt commands#

The first pair of commands uses %PATH_TO_FX%. PATH_TO_FX is an environment variable, a named value the terminal keeps, which you create so the long path to the lib folder is typed only once. In the Windows Command Prompt, set creates it and %PATH_TO_FX% stands for its value:

javac prints nothing and leaves JavafxSample.class beside the .java file.
java opens the brown window. On JDK 24 or newer it also prints a few
WARNING lines about a restricted method; the VS Code commands below add
the flag that removes them.

The quotes in the set line become part of the value. When %PATH_TO_FX%is expanded, the path arrives with its quotes, so the space in “Program Files” does not split it in two. A variable made with set lasts only as long as that Command Prompt window; open a new window and you must set it again.

The VS Code commands#

In the terminal inside VS Code the commands look different. On Windows that terminal runs PowerShell by default, and PowerShell does not understand %PATH_TO_FX%, so these write the path out in full:

javac creates a folder named out and puts JavafxSample.class in it.
java loads the class from out and opens the brown window, with no warnings.

Every flag in those two commands, and what it is for:

Key idea

Both commands need to know where JavaFX is (--module-path) and which parts of it to load (--add-modules). Give the flags to javac but not to java, and the program compiles and then refuses to run.

On macOS and Linux#

The same commands work with three changes: export instead of set, $PATH_TO_FX instead of %PATH_TO_FX%, and forward slashes in the path.

Assumes the SDK was unzipped into your home folder; change the path if not.
The window opens just as it does on Windows.

What you see when a flag is missing#

Each of these catches someone the first time. The message tells you which command, and which flag, to look at.

In an IDE#

An IDE needs the same two pieces of information, entered once in its settings instead of typed every time.

• VS Code. For compiling, add the jars from the SDK's lib folder under Referenced Libraries in the Java Projects view, which clears the red underlines on the imports. For running, put the flags in .vscode/launch.json as vmArgs, as below, and run with F5.
• IntelliJ IDEA. Add the lib folder as a library under File, Project Structure, Libraries. Then open Run, Edit Configurations, choose Modify options, Add VM options, and paste the flags: --module-path "C:\Program Files\javafx-sdk-27\lib" --add-modules javafx.controls --enable-native-access=javafx.graphics. Alternatively, start from IntelliJ's New Project wizard and pick its JavaFX generator. It creates a Maven project that downloads JavaFX by itself, and you run it with the javafx:run goal in the Maven tool window, or mvn javafx:run in a terminal, with no module path to manage.

Forward slashes work in Java paths on Windows and avoid escaping backslashes
in JSON. The \" marks around the path keep its space from splitting it.

Example: displaying text#

The second example embeds text in the scene. Save it in a file named DisplayingText.java. It follows the same three steps as the empty window, with one node in the group: a Text.

javac compiles it and prints two notes (explained below):
Note: DisplayingText.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

java opens a 600 by 300 window titled "Sample Application" showing
"Welcome to Ooty" in large letters that start 50 pixels from the left
and stand on a line 150 pixels from the top.

Line by line: Text (package javafx.scene.text) is a node that draws a string. It is a shape, a cousin of Rectangle and Circle, so it is placed by coordinates. new Font(45) asks for the default system font at size 45, headline letters in a 300-pixel-tall window. setText supplies the words. The rest is the familiar pattern: the text goes into the group through its list of children, the group into a 600 by 300 scene, and the scene onto the stage.

Why y is the baseline#

Letters stand on an invisible line called the baseline. Most of each letter sits above it, and the tails of letters such as y, g and p hang below. A Text node's x is where its first letter starts, and its y is the height of its baseline, measured down from the top of the scene. So setY(150) stands the words on a line half way down the 300-pixel window, as in the sketch above.

Now leave out the setX and setYlines and run it again. Without them, both values are 0, so the baseline lies along the window's top edge. Every letter is drawn above it, outside the window, and a group does nothing to bring it back into view. All you see is the tail of the y.

Key idea

A Text node's y is its baseline, the line its letters stand on, not its top edge.

Text or Label?#

JavaFX has a second node for words, Label, and the two suit different jobs. Text is a shape: you place it at exact coordinates, fill and outline it like any shape, and it has no padding, background or border of its own. Label (package javafx.scene.control) is a control: a layout pane decides where it goes, CSS can give it padding, a background and a border, it can show an icon beside its words, and it shortens its text with “...” when space runs out. Use Text for words drawn at a chosen point in a Group, as here, and Label for the captions in a form, as the registration form does.

The note javac prints#

Compiling DisplayingText prints two lines that begin with Note:. They come from ObservableList list = root.getChildren();. getChildren() really returns an ObservableList<Node>, a list of nodes, but the variable is declared as a plain ObservableList without the <Node>, which is called a raw type. With a raw type the compiler cannot check that only nodes go into the list, so it flags list.add(text) as unchecked. A note does not stop the build: the class file is written and the program runs. To silence it, give the list its type, ObservableList<Node> list = root.getChildren(); with import javafx.scene.Node;, or skip the variable: root.getChildren().add(text);.

Compile and run it the same way as the first example:

The two Note lines from javac, then the window. In VS Code's terminal use
the full-path form with -d out, -cp out and --enable-native-access=javafx.graphics,
exactly as for JavafxSample.