JavaFX Controls, Layouts & FXML

Designing with Scene Builder

18 min Lesson 8 of 12

Designing with Scene Builder

In every lesson so far you have assembled your UI by writing Java or FXML by hand. That approach is clear for learning, but on a real project — a form with twenty fields, a toolbar, a split-pane layout — hand-writing FXML quickly becomes error-prone. Scene Builder is Gluon's free, standalone visual editor that lets you drag controls onto a canvas and see the resulting FXML in real time. It does not replace knowledge of FXML; it complements it by letting you work faster and catch layout mistakes before you run the application.

What Scene Builder Actually Is

Scene Builder is a design-time tool. It reads and writes standard FXML files — the same files your FXMLLoader reads at runtime. There is no hidden framework, no code generation step, and no lock-in: every pixel you arrange visually is expressed as plain XML that you can read, diff, and commit to version control like any other source file.

Scene Builder vs. IntelliJ/Eclipse designers: JetBrains and Eclipse both have basic FXML form editors, but they lag far behind Scene Builder in features and polish. Scene Builder is the community standard; use it.

Installing Scene Builder

Download the installer for your OS from gluonhq.com/products/scene-builder. IntelliJ IDEA can also download it for you: go to Settings → Languages & Frameworks → JavaFX and click Download Scene Builder. Once installed, point IntelliJ at the executable so it can open .fxml files with a single click.

The Scene Builder Interface

When you open Scene Builder you see four main regions:

Library panel (left): all available controls grouped by category — Layout, Controls, Charts, etc. Type in the search box to filter.
Document / Hierarchy panel (left, lower half): the tree structure of your scene. Selecting a node here selects it on the canvas too — essential for clicking deeply nested elements.
Canvas (centre): the live preview of your scene. Drag controls from the Library and drop them here.
Inspector panel (right): three tabs — Properties (visual appearance), Layout (size, margin, alignment), and Code (fx:id, event handler names). This is where you wire the UI to your controller.

A Typical Scene Builder Workflow

The workflow fits naturally into a short loop:

Create or open an FXML file. In IntelliJ, right-click a package → New → FXML File, or open an existing one and click Open in Scene Builder at the top of the editor.
Set the root container. In the Hierarchy panel, the root node is already set (e.g. AnchorPane). You can change it via right-click → Wrap In.
Drag controls from the Library onto the canvas. Scene Builder places each control at the nearest valid insertion point inside the current container's rules (e.g., a VBox stacks them vertically).
Set properties in the Inspector. Click a control → Properties tab to set its text, font, fill, or style class. Use the Layout tab to set preferred width, height, margin, and alignment.
Assign fx:id and handler names in the Code tab. Every control you need to reference from Java gets a unique fx:id. Every button that triggers an action gets an onAction handler name — conventionally #handleSomething.
Set the controller class in the Document panel. Expand the Controller section and type the fully-qualified class name (e.g. com.example.FormController). Scene Builder uses this to validate that the fx:id values and handler names actually exist in that class.
Save (Ctrl+S / Cmd+S). Scene Builder writes the FXML file. Switch back to IntelliJ — the source is updated immediately.

Use CSS style classes, not inline style. In the Properties tab you can set an inline Style string, but this is hard to maintain. Instead, add a Style Class (e.g. form-field) and define the rules in a separate .css file loaded by your scene. Scene Builder respects your stylesheets if you add them via View → Scene Style Sheets.

Reading the Generated FXML

After placing a TextField and a Button inside a VBox and assigning them ids, Scene Builder produces something like this:

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.Button?>
<?import javafx.scene.control.TextField?>
<?import javafx.scene.layout.VBox?>

<VBox alignment="CENTER" spacing="12.0" xmlns="http://javafx.com/javafx/21"
      xmlns:fx="http://javafx.com/fxml/1"
      fx:controller="com.example.FormController">

    <TextField fx:id="nameField" promptText="Enter your name" />
    <Button fx:id="submitBtn" text="Submit" onAction="#handleSubmit" />

</VBox>

Notice that Scene Builder wrote the ?import processing instructions, the xmlns attributes, and the fx:controller binding automatically — boilerplate that would have taken time to write by hand.

Connecting to a Controller

Once the FXML is saved, your controller must declare matching fields and methods:

package com.example;

import javafx.fxml.FXML;
import javafx.scene.control.Button;
import javafx.scene.control.TextField;

public class FormController {

    @FXML
    private TextField nameField;   // matches fx:id="nameField"

    @FXML
    private Button submitBtn;      // matches fx:id="submitBtn"

    @FXML
    private void handleSubmit() {  // matches onAction="#handleSubmit"
        String name = nameField.getText().trim();
        if (!name.isEmpty()) {
            System.out.println("Hello, " + name + "!");
        }
    }
}

If the fx:id in the FXML does not match the field name in the controller, FXMLLoader throws an IllegalAccessException or silently leaves the field null — a common beginner mistake. Scene Builder's Code tab validation (the green/red icons next to each id) catches these mismatches before you run the app.

Always verify the controller class path. Scene Builder stores the controller class name as a plain string. If you rename or move the class in IntelliJ without updating the FXML's fx:controller attribute, the app will throw a ClassNotFoundException at runtime. Refactor through IntelliJ's FXML-aware rename (right-click → Refactor → Rename) to keep them in sync.

Practical Tips for Working with Scene Builder Daily

Preview live (Ctrl+P / Cmd+P): Scene Builder's Preview menu lets you render the scene as it will look at runtime, including your CSS. Use this before switching back to IntelliJ.
Wrap / Unwrap: right-click any node in the Hierarchy → Wrap In to add a parent container (e.g., wrap a bare Button in an HBox) without deleting and recreating it.
Undo is deep: Ctrl+Z works reliably across multiple property changes, so experiment freely.
View → Show Sample Data: for TableView and ListView, Scene Builder can populate a few fake rows so the layout looks realistic while you design.
Custom components: if you have a reusable widget built as an FXML + controller pair, you can import its JAR into Scene Builder's Library panel and drag it onto the canvas just like a built-in control.

Summary

Scene Builder is a WYSIWYG FXML editor that speaks the same file format your application loads at runtime. The core workflow is: drag controls → set properties → assign fx:id and handler names in the Code tab → set the controller class → save. The output is a clean FXML file that your FXMLLoader reads without modification. In the next lesson you will finish the picture by styling that FXML with CSS and see how the complete controller-FXML-CSS triad works together in a finished screen.