Value coercion

If a literal value is assigned to a property in an FXML 2.0 document, the literal value is automatically converted to the type of its property. This process, called value coercion, is supported in the following scenarios:

1. Primitive types and primitive boxes, for example:

    <!-- Converting "true" to a boolean value -->
    <Button visible="true"/>
       
    <!-- Converting "10" to a double value -->
    <Button lineSpacing="10"/>
   

2. Enum constants, for example:

    <!-- Converting "LEFT" to the enum constant ContentDisplay.LEFT -->
    <Button contentDisplay="LEFT"/>
   

3. Static fields on the declaring class, for example:

    <!-- Converting "UNCONSTRAINED_RESIZE_POLICY" to the value of
         the static field TableView.UNCONSTRAINED_RESIZE_POLICY -->
    <TableView columnResizePolicy="UNCONSTRAINED_RESIZE_POLICY"/>
   

4. Color values, for example:

    <Button textFill="RED"/>
    <Button textFill="#FF0000"/>
   

   Any color literal that is accepted by the Color.web method is also accepted by FXML.

Values that use markup extension syntax are not treated as literals and therefore do not participate in literal value coercion. This includes both the standard attribute form such as {StaticResource greeting} and a prefix shorthand such as %greeting after a matching <?prefix?> declaration.

Implicit constructor coercion

An object instance can also be created implicitly from a literal value, provided that the literal value can be coerced to the type of the constructor argument. This conversion only works for constructors where the parameter is annotated with @NamedArg.

For example, the javafx.geometry.Insets class declares a constructor that accepts a double value:

public class Insets {
    public Insets(@NamedArg("topRightBottomLeft") double topRightBottomLeft);
}

An Insets instance would normally be created like this:

<Button>
    <padding>
        <Insets topLeftBottomRight="10"/>
    </padding>
</Button>

However, since the literal 10 can be coerced to the named constructor argument topLeftBottomRight, the Insets object can also be created implicitly:

<Button padding="10"/>

Implicit constructor coercion with multiple arguments

Implicit constructor coercion also works for constructors with multiple parameters, provided that all parameters are annotated with @NamedArg. For example, we can create an instance of Insets with multiple arguments:

<Button>
    <padding>
        <Insets top="10" left="20" bottom="10" right="20"/>
    </padding>
</Button>

This also works with implicit coercion by separating the arguments with commas:

<Button padding="10,20,10,20"/>

A comma-separated list can only contain literal values, it cannot contain other types of expressions.