Mastering FXML


2 FXML—What's New in JavaFX 2.1

This page contains the following sections that describe the FXML enhancements in JavaFX 2.1 and incompatibilities with previous releases:

FXML Enhancements for JavaFX 2.1

The following FXML enhancements have been added in JavaFX 2.1:

  • Support for using a leading backslash as an escape character (RT-18680)

    JavaFX 2.0 used consecutive operator characters such as $$ as escape sequences. JavaFX 2.1 adds support for escape sequences using the backslash character, such as \$. These escape sequences are more similar to Unified Expression Language (UEL), making them more familiar to developers. The JavaFX 2.0 escape sequences are deprecated as of JavaFX 2.1. See Some JavaFX 2.0 FXML Escape Sequences Are Deprecated in JavaFX 2.1 and Backslash Is Now an Escape Character.

  • An implicit variable for the controller to document the namespace

    This new feature facilitates bidirectional binding between the controller and the UI. Bidirectional binding was dropped from JavaFX 2.1, but this feature was retained.

  • Convenience constructors to the FXMLLoader class (RT-16815)

    Several new convenience constructors have been added to the FXMLLoader class. These constructors mirror the static load() methods defined in JavaFX 2.0, but make it easier to access the document's controller from the calling code.

  • Customizable controller instantiation (RT-16724, RT-17268)

    In JavaFX 2.0, the calling code did not have any control over controller creation. This prevented an application from using a dependency injection system such as Google Guice or the Spring Framework to manage controller initialization. JavaFX 2.1 adds a Callback interface to facilitate delegation of controller construction:

    public interface Callback {
        public Object getController(Class<?> type);

    When a controller factory is provided to the FXMLLoader object, the loader will delegate controller construction to the factory. An implementation might return a null value to indicate that it does not or cannot create a controller of the given type; in this case, the default controller construction mechanism will be employed by the loader. Implementations might also "recycle" controllers such that controller instances can be shared by multiple FXML documents. However, developers must be aware of the implications of doing this: primarily, that controller field injection should not be used in this case because it will result in the controller fields containing values from only the most recently loaded document.

  • Easier style sheets to work with (RT-18299, RT-15524)

    In JavaFX 2.0, applying style sheets in FXML was not very convenient. In JavaFX 2.1, it is much simpler. Style sheets can be specified as an attribute of a root <Scene> element as follows:

    <Scene stylesheets="/com/foo/stylesheet1.css, /com/foo/stylesheet2.css">

    Style classes on individual nodes can now be applied as follows:

    <Label styleClass="heading, firstPage" text="First Page Heading"/>
  • Caller-specified no-arg controller method as an event handler (RT-18229)

    In JavaFX 2.0, controller-based event handlers must adhere to the method signature defined by an event handler. They must accept a single argument of a type that extends the Event class and return void. In JavaFX 2.1, the argument restriction has been lifted, and it is now possible to write a controller event handler that takes no arguments.

FXML Loader Incompatibilities with Previous JavaFX Releases

The following sections contain compatibility issues that users might encounter if they load a JavaFX 2.0 FXML file with a JavaFX 2.1 FXML loader:

Some JavaFX 2.0 FXML Escape Sequences Are Deprecated in JavaFX 2.1

Table 2-1 shows the double-character escape sequences that were used in FXML in JavaFX 2.0, but are deprecated in JavaFX 2.1. Instead, use a backslash as the escape character.

Table 2-1 Deprecated and Current Escape Sequences

JavaFX 2.0 Escape Sequence JavaFX 2.1 Escape Sequence







If Scene Builder encounters any of these deprecated escape sequences, then the console displays a warning, but loads the FXML anyway. The next time the file is saved, Scene Builder automatically replaces the deprecated escape characters with the new syntax.

Backslash Is Now an Escape Character

In JavaFX 2.1, the backslash \ is an escape character in FXML. As a result, JavaFX 2.0 applications with FXML files that contain FXML string attributes starting with a backslash might prevent the FXML from loading, or it might cause the FXML loader to misinterpret the string.

Solution: For any FXML backslash text in a JavaFX 2.0 application, add an additional backslash to escape the character.


Remove this line of code:

<Button text="\"/>

Replace it with this line of code:

<Button text="\\"/>