JavaFX properties, binding and listeners

JavaFX properties are values that tell you when they change. A SimpleIntegerProperty holds an int as a field would, but other code can listen to it or bind to it. Binding keeps one property equal to another, or to an expression of several, with no code that copies values: after total.bind(theory.add(practical)), the total follows both marks by itself. Listeners run your own code when a value changes. An invalidation listener hears that a value may have changed, and a change listener also receives the old and the new value. Use binding for values that follow other values, and use listeners for actions that a change should trigger, such as saving a draft or logging.

This lesson builds a marks model from JavaFX properties and bindings with nothing but the javafx.base module, so every example runs without a window, on Eclipse Temurin 25.0.4.1 with JavaFX 27.

Properties: values that announce their changes

A JavaFX property comes with three methods named after it: theoryProperty() returns the property object, and getTheory() and setTheory(int) read and write its value. Every node exposes its state this way. A label’s text is textProperty(), a node’s width is widthProperty() and a shape’s colour is fillProperty(), so anything on the screen can take part in a binding.

Each value type has its own classes. SimpleIntegerProperty, SimpleDoubleProperty, SimpleStringProperty, SimpleBooleanProperty and SimpleObjectProperty<T> are the ordinary read-write kinds. A ReadOnlyIntegerWrapper lets a class change a value that callers may only read. Giving a property its bean and a name, new SimpleIntegerProperty(this, "theory", 52), costs nothing and makes error messages name it.

Binding one way, both ways, and through expressions

Expressions build the values that bindings follow. Number properties have fluent methods, such as add, multiply, greaterThan and asString. The Bindings class adds factories: Bindings.createStringBinding turns any code into a binding with the dependencies you list, Bindings.when(condition).then(a).otherwise(b) chooses between two values, Bindings.format fills a String.format pattern, and Bindings.size follows the length of a list.

A marks model, run without a window

import javafx.beans.binding.Bindings;
import javafx.beans.binding.NumberBinding;
import javafx.beans.binding.StringBinding;
import javafx.beans.property.IntegerProperty;
import javafx.beans.property.SimpleIntegerProperty;
import javafx.beans.property.SimpleStringProperty;
import javafx.beans.property.StringProperty;

/** A marks model made of properties and bindings: no window, only the javafx.base module. */
public class Marks {
    final IntegerProperty theory = new SimpleIntegerProperty(this, "theory", 52);         // out of 70
    final IntegerProperty practical = new SimpleIntegerProperty(this, "practical", 20);   // out of 30
    final NumberBinding total = theory.add(practical);
    final StringBinding grade = Bindings.createStringBinding(() -> {
        int marks = total.intValue();   // this example's scale: A from 80, B from 70, C from 55
        return marks >= 80 ? "A" : marks >= 70 ? "B" : marks >= 55 ? "C" : "D";
    }, total);
    final StringProperty summary = new SimpleStringProperty(this, "summary");

    Marks() {
        summary.bind(Bindings.format("%d of 100, grade %s", total, grade));
    }

    public static void main(String[] args) {
        Marks marks = new Marks();
        System.out.println("theory 52, practical 20:  " + marks.summary.get());
        marks.theory.set(60);
        System.out.println("theory 60:                " + marks.summary.get());
        try {
            marks.summary.set("100 of 100, grade A");
        } catch (RuntimeException e) {
            System.out.println("summary.set(...) threw    " + e.getClass().getSimpleName() + ": " + e.getMessage());
        }

        StringProperty a = new SimpleStringProperty("typed in a");
        StringProperty b = new SimpleStringProperty("typed in b");
        a.bindBidirectional(b);
        System.out.println("a.bindBidirectional(b):   a = " + a.get() + ", b = " + b.get());
        a.set("from a");
        System.out.println("a.set(\"from a\"):          b = " + b.get());
        b.set("from b");
        System.out.println("b.set(\"from b\"):          a = " + a.get());
    }
}

from session import run, sdk

sdk("27")
run("""
java --module-path javafx-sdk-27/lib --add-modules javafx.base Marks.java
""")

$ java --module-path javafx-sdk-27/lib --add-modules javafx.base Marks.java
theory 52, practical 20:  72 of 100, grade B
theory 60:                80 of 100, grade A
summary.set(...) threw    RuntimeException: Marks.summary : A bound value cannot be set.
a.bindBidirectional(b):   a = typed in b, b = typed in b
a.set("from a"):          b = from a
b.set("from b"):          a = from b

When theory changed from 52 to 60, the total, the grade and the summary followed in one step, and no line of main recomputed them. Setting the bound summary threw a RuntimeException whose message starts with Marks.summary, the bean and the name given to the property, which is the reason to give properties names. The two-way binding started by copying b’s value into a: the property you call bindBidirectional on takes the other one’s value, so call it on the side whose current value may be lost.

Listeners, and when to use one

JavaFX has three kinds of listeners for observable values and lists:

• An InvalidationListener is called when a value may have changed, with the observable and nothing else.
• A ChangeListener is called with the old and the new value, and only when they differ.
• A ListChangeListener receives a description of what an ObservableList added, removed, replaced or reordered.

An observed value keeps each of its listeners reachable, with everything a listener refers to, until the listener is removed. Code stops listening with removeListener, by wrapping the listener in a WeakChangeListener, or with the Subscription that subscribe returns, whose unsubscribe() ends it.

Prefer a binding whenever a value follows other values. A listener that copies values is a binding written by hand, and it can drift: a forgotten field, a missed event, or a value set before the listener was added.

Check yourself

When each listener fires: a lazy binding traced event by event Pro: opens with a Pro, Premium or Ultimate pass

List changes, list bindings and a listener leak, reproduced Pro: opens with a Pro, Premium or Ultimate pass

Exercise: a course-fee model made only of bindings Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• A JavaFX property holds a value and lets other code listen to it or bind to it; nodes expose all their state as properties.
• bind makes a property follow a source and forbids setting it; bindBidirectional copies the argument’s value first and then keeps both in step.
• Bindings and the fluent methods build expressions such as totals, conditions and formatted text.
• Invalidation listeners hear that a value may have changed; change listeners receive old and new values.
• Prefer a binding when a value follows other values, and stop listening when a short-lived object listens to a long-lived value.