How to setup the Java SDK and use JavaFX with macOS/Windows
Software engineer and entrepreneur based in San Francisco.
Software engineer and entrepreneur based in San Francisco.
This guide focuses on setting up a JavaFX development environment. Key parts:
JAVA_HOME
setup, refer to the Core Java Setup Guide.This section assumes your JDK is installed and JAVA_HOME
is configured as per the Core Java Guide. We'll focus on IDE integration for JavaFX.
JavaFX is a toolkit for developing graphical (GUI) applications in Java. Since Java 11, it's no longer bundled with the JDK. It's best managed as a project dependency via Maven or Gradle. Avoid installing JavaFX system-wide.
Ensure you have the Extension Pack for Java installed in VS Code.
IntelliJ IDEA has excellent built-in support for Java and JavaFX projects.
Use the latest Long-Term Support (LTS) versions consistently. For example:
pom.xml
or build.gradle
reflects these versions. See Part 5.1 for a pom.xml
example.Scene Builder is a visual layout tool for designing JavaFX UIs (.fxml files).
Visit the Gluon Scene Builder website to download the latest version (LTS recommended, e.g., 23). Install it.
/Applications/SceneBuilder.app
on macOS, or C:\Program Files\SceneBuilder\SceneBuilder.exe
on Windows).Configure Scene Builder path
and press enter.fxml
file in the VS Code explorer and choose "Open in Scene Builder". We'll cover how to create the project and open it in Scene Builder in the next step below.Scene Builder is self-contained and doesn't need JAVA_HOME
. It edits .fxml
files directly. You only need to configure the path within your IDE to enable direct opening of FXML files.
With your JDK and Scene Builder configured, create a new JavaFX project.
Java: Create Java Project
and press EnterApp.java
file (usually under src/main/java/com/example/
).main
method or press F5.primary.fxml
, etc.): XML for GUI layout.pom.xml
/ build.gradle
): Manages JavaFX library dependencies.
FXML promotes separation of UI design from application logic.Once your project is open and Scene Builder path is configured (Part 2), edit FXML files from your IDE.
src/main/resources/com/example/hello-view.fxml
).src/main/resources/com/example/primary.fxml
).Scene Builder launches as a separate application, loading your FXML file for visual editing (component hierarchy, drag-and-drop, property inspection).
Changes saved in Scene Builder are written back to the .fxml
file in your project.
pom.xml
or build.gradle
) is compatible with your project's JDK. For JDK 21, use JavaFX 21+.
<!-- Maven pom.xml example for JavaFX 21 with JDK 21 -->
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.release>21</maven.compiler.release> <!-- Corresponds to JDK version -->
<javafx.version>21.0.2</javafx.version> <!-- Or latest compatible JavaFX 21+ version -->
</properties>
<dependencies>
<dependency>
<groupId>org.openjfx</groupId>
<artifactId>javafx-controls</artifactId>
<version>${javafx.version}</version>
</dependency>
<dependency>
<groupId>org.openjfx</groupId>
<artifactId>javafx-fxml</artifactId>
<version>${javafx.version}</version>
</dependency>
<!-- Add other JavaFX modules as needed: javafx-graphics, javafx-media, etc. -->
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version> <!-- Or newer -->
<configuration>
<release>${maven.compiler.release}</release>
</configuration>
</plugin>
<plugin>
<groupId>org.openjfx</groupId>
<artifactId>javafx-maven-plugin</artifactId>
<version>0.0.8</version> <!-- Or newer -->
<configuration>
<!-- Ensure this matches your main application class -->
<mainClass>com.example.yourproject.YourMainAppClass</mainClass>
</configuration>
<executions>
<execution>
<!-- Default configuration for running via IDE -->
<id>default-cli</id>
<configuration>
<mainClass>com.example.yourproject.YourMainAppClass</mainClass>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
JAVA_HOME
, multiple Java versions, and build system (Maven/Gradle) setup, refer to the Core Java, Maven & Gradle Setup Guide.javafx.fxml.LoadException
, InvocationTargetException
, ClassNotFoundException
.fx:controller
in FXML must be fully qualified (e.g., com.example.yourproject.MyController
).
<VBox xmlns:fx="http://javafx.com/fxml/1" fx:controller="com.example.yourproject.PrimaryController">...</VBox>
@FXML
Annotations: UI elements in FXML with fx:id
need corresponding @FXML
annotated fields in the controller.
// PrimaryController.java
public class PrimaryController {
@FXML private Label myLabel; // fx:id="myLabel"
@FXML private void initialize() { /* ... */ }
}
src/main/resources/com/example/yourproject/
) and loaded correctly:
Parent root = FXMLLoader.load(getClass().getResource("primary.fxml")); // Relative to class
// Or: FXMLLoader.load(getClass().getResource("/com/example/yourproject/primary.fxml")); // Absolute from classpath root
./mvnw clean install
or ./gradlew clean build
.pom.xml
file or the project root in IntelliJ IDEA, you get a Maven-specific context menu. Here's what the common options do:pom.xml
file and updates IntelliJ IDEA's project structure, dependencies, and settings to match. Use this after making changes to the pom.xml
or if you suspect the IDE is out of sync.pom.xml
file remains, but IDEA will no longer manage dependencies or build configurations through Maven for this project until you re-import it.settings.xml
file in your user's .m2
directory (~/.m2/settings.xml
) if one doesn't exist. This file allows you to configure user-specific Maven settings like custom repository locations, proxy settings, or server credentials..java
files) or Javadoc documentation for your project's dependencies from the Maven repositories. This allows you to navigate into library code or view documentation directly within the IDE. "Download Sources and Documentation" does both.