JavaFX overview, features, and architecture

Most programs in this course talk to their user through a terminal: print a line, read a line. A JavaFX program opens a window instead, fills it with text, buttons and fields, and then waits for the user to do something. Before any code, this lesson builds the picture you need to read JavaFX code: how a window program runs, where JavaFX came from, what each of its layers does, and the three objects every JavaFX application is made of.

What changes when a program has a window#

Think back to the console programs you wrote with Scanner. Your code was in charge. It printed a prompt, called nextLine(), and stopped dead until the user pressed Enter. Then it decided what to do next. The program asked the questions, in the order it chose.

A window turns this around. Once the window is on screen, the user can click any of ten buttons, type in any field, drag the window, resize it or close it, in any order. A program that stopped to wait for one particular answer would stop everything else too, including redrawing its own window. So a window program never waits for one answer. It leaves instructions in advance, such as “when the Save button is clicked, run this method”, and lets the user act. Each thing the user does is an event (a click, a key press, a resize), and the method you attach to it is an event handler. Programs built this way are called event-driven.

Key idea

In a window program the user acts first and the toolkit calls your code. Your job is to leave handlers in place and let each one finish quickly.

The event loop#

Something has to do the waiting. Inside JavaFX is a loop you never write, the event loop, running on a single thread called the JavaFX Application Thread for as long as the program runs. Each time round, it does this:

1. 1The operating system notices something physical: the left mouse button went down at a point inside your window.
2. 2It delivers that to your window as an event, which joins a queue of events waiting to be handled.
3. 3The loop takes the next event off the queue.
4. 4It works out which part of the window is under that point, say the Save button.
5. 5It calls the handler you attached to the Save button, and waits for that handler to return.
6. 6It redraws whatever the handler changed, then goes back to step 3.

This shape has a name, inversion of control. In a console program your code calls the library when it wants input. In a window program the library calls your code when input arrives.

AWT, Swing and JavaFX#

Java has had three toolkits for building windows. Each one answers a weakness of the one before.

AWT, the Abstract Window Toolkit (package java.awt), came with Java 1.0 in 1996. When you create an AWT button, AWT asks the operating system to create a real native button and keeps a hidden peerobject connected to it. The button looks like every other button on that system, but AWT can only offer widgets that every operating system has, and each system's widgets behave a little differently, so the same program could misbehave on one system and work on another. AWT is fine for a simple interface and weak for a large one.

Swing (package javax.swing, part of Java 1.2 in 1998) took the opposite route. It asks the operating system only for a plain top-level window, then paints every button, list and table itself with Java code. Components drawn this way are called lightweight. Because the drawing is Java's own, they behave the same on every platform and lean far less on native resources. Swing also added the components AWT lacked, such as tables, trees, tabbed panes and sliders.

JavaFXfirst appeared in December 2008, programmed through a separate scripting language called JavaFX Script. In 2011, JavaFX 2.0 rebuilt it as an ordinary Java library, the one you will use. It draws a scene graph through the graphics card and adds CSS styling, FXML, animation, media playback and an embedded web browser. JavaFX 8 shipped inside Oracle's JDK 8 in 2014. From Java 11 it is no longer bundled with the JDK: it is developed as a separate project, OpenJFX, and downloaded from openjfx.io, which is why the next lesson needs a section on compiling.

What JavaFX is#

JavaFX started out as a Java library for building rich internet applications, the 2008 term for programs delivered through the web that felt like desktop software, the territory of Adobe Flash and Microsoft Silverlight. A JavaFX program could run inside a web page through Java's browser plug-in, and JavaFX was promoted for desktops, phones and TVs. Browser plug-ins have since disappeared. Today JavaFX is a library for desktop applications on Windows, macOS and Linux; phones and tablets are reachable only through third-party ports such as Gluon's.

Two of its early promises still hold. First, JavaFX is one library for things that used to need several: media, UI controls, web content, 2D and 3D graphics. Before it, a Java program that wanted a video, a web page and modern controls had to stitch separate libraries together. JavaFX can also use the existing Java libraries, Swing included. Second, JavaFX draws through the GPU (graphics processing unit), the chip in your computer built for drawing. These hardware-accelerated graphics keep animation smooth, and because animation and controls share one system, a button can fade in or slide across the window like any other shape.

What JavaFX offers#

Here is what JavaFX gives you, each with what it means when you sit down to write a program.

• It is written in Java and runs on the JVM, so the same program runs on Windows, macOS and Linux: it is platform independent. One footnote: the lowest layers, the ones that talk to the operating system and the graphics card, are native code built separately for each system, which is why you download JavaFX for your own operating system. Your Java code stays the same.
• FXML is a markup language for describing an interface instead of building it in Java. It is XML, with tags and attributes that look like HTML. A line such as <Button text="Save" onAction="#save"/> declares a button whose click runs a method called save in a Java controller class. The layout lives in the .fxml file and the logic in Java, so each can change without touching the other.
• Scene Builder is a free drag-and-drop designer, now maintained by Gluon: you place controls on a canvas and it writes the FXML for you. It works alongside IntelliJ IDEA, Eclipse, NetBeans and VS Code.
• It works with Swing. SwingNode puts Swing components inside a JavaFX window, and JFXPanel puts JavaFX content inside a Swing window, so an old Swing application can move to JavaFX one screen at a time.
• It has ready-made controls, the parts of a window a user clicks or types into, in javafx.scene.control: Button, Label, TextField, CheckBox, RadioButton, TableView, ComboBox and many more. The controls and layouts lesson covers the ones this track uses.
• You style it with CSS, the same idea as on the web: colours, fonts, borders and backgrounds are set with CSS rules, using JavaFX property names that start with -fx-. The rule .button { -fx-background-color: steelblue; -fx-text-fill: white; } in a stylesheet restyles every button in the program without touching the Java.
• A Canvas is a blank surface you paint on yourself, with calls such as fillRect and strokeLine, for drawings no ready-made node expresses. The printing API (javafx.print) opens the print dialog and sends any node to a printer.
• Its API goes beyond windows and controls, to 2D and 3D graphics, multimedia and web content. It is written in modern Java, so you meet generics (ObservableList<Node>), annotations (@Override), background threads and lambda expressions (button.setOnAction(e -> save())) throughout.
• Shapes are built in: 2D shapes such as Rectangle, Circle and Polygon, and 3D shapes such as Box and Sphere with cameras and lights, all ordinary nodes that sit in a window beside buttons.
• Everything is drawn by Prism, a hardware-accelerated rendering pipeline. It has its own section in the architecture below.

The JavaFX architecture#

JavaFX is built as a stack of layers. Read the diagram from the top, the side your code touches, down to the JVM at the bottom. Each layer uses the one beneath it and hides it from the ones above, so your program only ever talks to the top row.

From the top: the JavaFX API and the scene graph you build with it; the Quantum Toolkit, which connects them to the engine below; the JavaFX graphics engine, with Prism for drawing, Glass for windows and input, WebView for web pages and Media for sound and video, each standing on a native technology; then the JDK API and tools, and the Java Virtual Machine. The sections below take the boxes from the top down.

JavaFX API#

The JavaFX API is the set of classes and methods you write your program with: Stage, Scene, Button, Label, TextField and the rest. Like the Java library you already know, it is organised into packages. These seven are the ones you meet first.

The packages ship in a handful of modules: javafx.base, javafx.graphics, javafx.controls, javafx.fxml, javafx.media, javafx.web and javafx.swing. You will name modules when you compile in the next lesson. For now, it is enough to know that javafx.controls brings in the two modules it is built on, javafx.graphics and javafx.base.

Scene graph#

The scene graph is where every JavaFX interface starts. It is a tree of objects called nodesthat describes everything in the window: what is there, where it sits and what it looks like. You build the tree; JavaFX keeps it in memory and redraws the window from it whenever something in it changes. Change a label's text with setText and the window updates on its own, with no painting code from you.

Key idea

You never paint a JavaFX window. You build a tree of nodes that describes it, and JavaFX turns that tree into pixels every time it changes.

A node is any visual object. Nodes come in four broad kinds:

• shapes, 2D and 3D, such as Circle, Rectangle, Polygon, Box and Sphere;
• controls, such as Button, CheckBox, ChoiceBox and TextArea;
• containers, also called layout panes, which hold other nodes and arrange them, such as BorderPane, GridPane and FlowPane;
• media elements: ImageView shows an image and MediaView shows a video.

The tree follows a few rules:

• Every node has exactly one parent, except one: the root node, which has none.
• A node with children is a branch node; a node with no children is a leaf node. So a node can have any number of children, including none.
• A node instance can be added to a scene graph only once. Add a button that already sits in one container to a second container and JavaFX quietly takes it out of the first: the node moves, it is not copied. Two buttons on screen need two Buttonobjects, and adding the same node twice to one container's children throws an IllegalArgumentException about duplicate children.
• Every node can carry effects (a drop shadow, a blur), an opacity from 0 (invisible) to 1 (solid), transforms (rotate, scale, move), event handlers, and application-specific state: your own data attached to the node, such as an id string or an object stored with setUserData. Effects, opacity and transforms set on a branch apply to its whole subtree: fade a container to half opacity and everything inside it fades with it.

Quantum Toolkit#

Quantum is the middle layer. It connects the higher-level parts of JavaFX, the API and the scene graph, with the graphics and windowing systems underneath, and it is the reason your code never talks to Prism or Glass directly. It coordinates four kinds of work:

• Rendering: getting buttons, labels and shapes drawn on screen, by handing the scene graph's changes to Prism.
• Input events: mouse clicks, key presses and touches arriving from Glass, delivered to the right scene.
• Windowing: opening, closing, sizing and positioning windows, through Glass.
• JavaFX application operations: the rest of the traffic between JavaFX and the system underneath, such as starting the toolkit and shutting it down.

Oracle's own description of the architecture adds one more job: Quantum manages the threading rules that keep rendering and event handling apart.

The JavaFX graphics engine#

The large box in the middle of the diagram holds eight names. Four are parts of JavaFX; the other four are the native technologies those parts stand on.

Prism#

Prism is JavaFX's rendering engine, the part that actually draws. Everything visible goes through it: buttons, text, shapes, images, animations, 2D and 3D graphics. Prism uses the GPU when one is available, which is what keeps graphics and animation smooth. To reach the GPU it uses whichever graphics API the system offers: Direct3D on Windows, OpenGL on Linux, and Apple's Metal on macOS, the default there since JavaFX 27 (earlier releases used OpenGL on macOS too). Where no usable GPU exists, in some virtual machines for instance, Prism falls back to a slower software renderer and the program still runs. It draws on a thread of its own, so one frame can be drawn while the next is being prepared.

Glass#

Glass is JavaFX's low-level windowing toolkit, the bridge between your JavaFX application and the operating system. Its jobs:

• Creates and manages windows.
• Handles keyboard and mouse input.
• Manages screen and display information: how many screens there are, their sizes and resolutions (the class javafx.stage.Screen reports what Glass found).
• Handles window events such as opening, closing, resizing and moving.
• Communicates with the operating system on JavaFX's behalf for all of the above.

A detail from Oracle's architecture notes connects Glass to the event loop. Glass uses the operating system's own event queue and runs on the same thread as your JavaFX code. AWT kept separate native and Java threads; JavaFX does not, which is why every event handler you write runs on the one JavaFX Application Thread.

WebView#

WebView is a JavaFX component that displays web pages and web content inside your application. It is based on the WebKit browser engine, the engine behind Safari. With it you can:

• display HTML web pages;
• load a website from its URL;
• display content written in HTML, CSS and JavaScript;
• let the user interact with the page: follow its links, fill in its forms;
• combine web content with ordinary JavaFX controls in the same window.

The work is split between two classes. WebView is the node that displays the page. WebEngine, which every WebView owns, loads the page and controls it: load takes a URL, and loadContent("<h1>Hello</h1>") shows a string of HTML. Together they make your application a small web browser. Both live in the module javafx.web, which you must name when you compile and run.

A 900 by 600 window titled "Mini Browser" showing the openjfx.io home page
(the computer must be online). Links work: clicking one loads the next page
inside the same WebView. WebView is in the javafx.web module, so the module
list grows to --add-modules javafx.controls,javafx.web

Media engine#

The media engine plays audio and video. It is built on GStreamer, an open-source multimedia framework. Older tutorials list formats such as FLV that current JavaFX no longer plays. This is what it supports today:

The media classes are in the package javafx.scene.media (module javafx.media), in three parts:

• Media represents one media file, created from its location as a URI string.
• MediaPlayer plays the media: play(), pause(), stop(), volume, position.
• MediaView is a node that displays a player's video in the scene graph. Sound needs no view: a MediaPlayer on its own plays an MP3.

A 640 by 360 window titled "Video Demo" playing ooty.mp4 from the folder
the program was started in. Needs the javafx.media module:
--add-modules javafx.controls,javafx.media
Give it an .flv file instead and new Media(...) throws a MediaException,
because the format is not supported.

JDK API and tools, and the JVM#

The bottom two boxes are the Java platform you already know. The JDK API and tools are the standard libraries (java.lang, java.util, threads, files) and the development tools: the compiler javac, the launcher java, the debugger. JavaFX is built on them like any other Java library. The JVM is the foundation: it executes the bytecode, and a JavaFX application runs on it exactly as a console program does. If the line between the JDK and the JVM is hazy, revisit setup and the JVM.

One click through the layers#

To see the layers work together, follow a single click on a Save button whose handler changes a label to “Saved”.

1. 1Operating system. You press the mouse button. The operating system works out which window is under the pointer and sends that window a native message.
2. 2Glass owns that window, so it receives the message, on the JavaFX Application Thread, and turns it into an event JavaFX understands.
3. 3Quantum passes the event to the scene shown in that window, as a MouseEvent carrying the click's coordinates.
4. 4Scene graph. JavaFX finds the topmost node under the point, the Save button, and routes the event down the tree to it and back up. The button recognises a press followed by a release as a click and fires an ActionEvent.
5. 5Your handler, the lambda you gave setOnAction, runs on the same thread and calls label.setText("Saved").
6. 6Back down. The label is marked as changed and a pulse is scheduled. On the pulse, JavaFX recomputes CSS and layout and hands the change to Prism.
7. 7Prism draws the new frame with the GPU, through Direct3D on Windows, and the window shows “Saved”.

The structure of a JavaFX application#

Every JavaFX application is made of three parts: a Stage, a Scene and nodes. The names come from the theatre. The stage is where the play happens, the scene is what is set up on it at the moment, and the nodes are everything in that scene.

Key idea

A Stage shows one Scene at a time, the Scene holds one root node, and every other node hangs somewhere below that root.

Stage#

A stage is a window, and it contains all the objects of a JavaFX application. It is an object of the class Stage in the package javafx.stage. You do not create the first one yourself: the primary stage is created by the platform, the JavaFX runtime, and passed as the argument to the start() method of your Application class. Extra windows, such as a dialog, are further Stage objects you create with new Stage().

A stage is divided into the content area, where your scene is drawn, and the decorations: the title bar and borders, drawn by the operating system. When you give a scene a size, say 600 by 300, that is the content area. The decorations go around it, so the window on screen is a little larger.

A stage has a style that decides its decorations. The styles are the values of the enum StageStyle (package javafx.stage), chosen with the stage's initStyle method. An enum is the natural type here: a fixed set of named choices. These five have been there from the start:

• DECORATED: the default. A white background with the normal title bar and borders, including the minimise, maximise and close buttons.
• UNDECORATED: a white background with no title bar or border at all, as on a splash screen. With no title bar to drag or close it by, your program has to provide a way out.
• TRANSPARENT: no decorations and a transparent background, so only what your nodes draw is visible. Set the scene's fill to Color.TRANSPARENT as well, and a round clock can float on the desktop with no rectangle around it.
• UNIFIED: normal decorations, but no border between the title bar and the content, so the content's background runs up into the title bar. Only some platforms support it; elsewhere it falls back to DECORATED.
• UTILITY: a white background with minimal decorations, typically a slimmer title bar with only a close button, for small tool windows.

A small window, 250 by 150, titled "Tools", with a slim title bar and,
on most systems, only a close button. Moving the initStyle line below
show() makes it throw IllegalStateException: the style can only be
chosen before the stage is first shown.

JavaFX 27 added a sixth value for good, EXTENDED, after trying it out as a preview in JavaFX 25 and 26. It stretches your content up into the title bar area, so your own nodes can sit there, together with a new HeaderBar control. This track sticks to the classic five.

One last point: nothing appears until you call the stage's show() method. Until then the stage is an object in memory and nothing more.

Scene#

A scene represents the physical contents of a JavaFX application: everything in the scene graph. It is an object of the class Scene in the package javafx.scene. At any instant a scene is added to only one stage, though a stage can swap in a different scene at any time with setScene, which is how a login screen gives way to a main screen in the same window.

You create a scene by instantiating Scene, passing it the root node and, if you like, its size: new Scene(root, 600, 300). The constructor takes the width first, so that scene is 600 pixels wide and 300 tall. A scene also has a fill, its background colour, white unless you change it. The next lesson builds scenes line by line.

Scene graph and nodes#

Two words to keep apart: the scene graph is a tree-like, hierarchical data structure representing the contents of a scene. A node is one visual object in it, of the four kinds you met above: geometrical objects, UI controls, containers and media elements. Each of them is a subclass of Node in javafx.scene, the superclass of all nodes. That shared superclass is what lets one container hold a Button, a Rectangle and an ImageView in a single list, the same polymorphism you used with your own class hierarchies.

By their place in the tree, nodes are of three types:

• A root node is the first node of the scene graph, the one at the top with no parent. It is the node you pass to the Scene constructor.
• A branch node, also called a parent node, is a node with child nodes. Their base class is Parent in javafx.scene, an abstract class, so you never write new Parent(); you use one of its kinds, described below.
• A leaf node is a node without child nodes, such as a Rectangle or an Ellipse (2D shapes), a Box (a 3D shape), an ImageView (shows an image) or a MediaView (shows a video).

The parent nodes come in three kinds:

• Group: a collective node that holds a list of children. When the group is rendered, its children are rendered in order, each drawn over the ones before it, and any transform or effect applied to the group applies to all of them. A group does not arrange its children: each one stays at the coordinates you gave it.
• Region: the base class of all the node-based UI controls and layout containers: Chart, Pane (and through it VBox, GridPane and the other panes) and Control (and through it Button, TextField and the other controls). A region has a size of its own, can be resized, and can be styled with CSS.
• WebView: manages a web engine and displays its contents. It extends Parent, but you never add children to it yourself; what it shows comes from the web page.

Notice where the controls sit. Button descends from Region, and so from Parent, because a control draws itself with a few internal nodes. In the tree you build, though, a button has no children you add, so you treat it as a leaf. The controls and layouts lesson draws the whole class hierarchy.

Two more points about the root. First, it is mandatory. The Scene constructor will not work without one, and its parameter type is Parent, so a leaf such as a Rectangle cannot be a root: that call does not compile. Second, the kind of root changes what happens when the window is resized:

Here is the scene graph of a small but real window, with each node's type marked.