The image-pattern() JavaFX CSS function is used to generate an <image-pattern> object, which represents a texture consisting of a series of repeating images that stretch across a container.

Patterns can be defined either absolutely (e.g. tile = 10px × 10px) or proportionally (e.g. tile = 0.2 × 0.2, on a scale of 0 to 1). This affects how the image is displayed and scaled when the container is resized.

Required Parameters:

A basic image-pattern requires that developers define only one parameter

ParameterDescriptionValue
Image LocationThe location of an image file specified as a String. The url() function should not be used to define the URI string, it should be entered as a String object such as “tile.png”<uri-string>

Example:

-fx-background-color:
        image-pattern("EdenCodingIcon.png");
This will generate an image pattern that stretches to fit the dimensions of its container. This is not always desired.

Optional Parameters:

To customise the display of the image pattern, additional parameters can be provided:

ParameterDescriptionValue
Anchor XThe x-offset of the tile pattern from the left edge of the container<size>*
Anchor YThe y-offset of the tile pattern from the top edge of the container<size>*
Tile widthThe width of the tile.<size>*
Tile heightThe height of the tile.<size>*
Proportionality FlagWhether size parameters provided should be interpreted as having an absolute or proportional meaning with respect to the size and position of the tile pattern.
If true, sizes are interpreted proportionally on a scale between 0 and 1 with respect to the container size. If false, sizes are interpreted as absolute in units of pixels.
In both cases any stated units (e.g. 12pt or 8em) are ignored.
Default value: true.
<boolean>**

*Important: While the JavaFX CSS Reference officially declares these parameters as <size> objects, units are currently ignored by the CSS parser, and the only acceptable units are pixel or proportional dimensions. Size parameters must be specified together (all four parameters together).

**Important: While the JavaFX CSS Reference officially declares this as optional, the default value of the proportional flag is true. Size parameters provided in the absence of a flag will be interpreted as proportional, even if units are specified otherwise.

Parameter definition

In the following sections, the required and optional parameters are defined in detail. Please note the limitations on image URI and proportionality flag, which are critical in producing meaningful image patterns.

1. Image Location

The only required parameter of the image-pattern() method is the location of an image, specified as a URI string.

Warning

Use of the image-pattern() function comes with two warnings:

Warning 1: There are significant inconsistencies in the way JavaFX currently resolves errors in loading images. Different errors and program behaviour result from different sources of the image specified (e.g. file vs URL, see ‘Errors associated with loading images‘)

Warning 2: The URI can be specified as a URL, or as a file reference, although the current CSS Parser (as of JavaFX 15) has significant problems navigating to images that are specified as a local file (see ‘Limitations on Image Location‘).

1. Errors associated with loading images

> Local files:

If a local file is specified, but cannot be found, a NullPointerException will be thrown with the message URL must not be null.

  • Program execution will not be stopped
  • Any other <paint> objects specified will be loaded.

This last point is useful, as multiple background fills can be specified in a comma specified list, allowing for back-up fills to be created.

> Online files:

If a valid URL is provided, but the URL cannot be reached, or an image is not present at that URL, (for examole http://google.com/anIcon.png), an IllegalArgumentException will be thrown with the message Image must be non-null and program execution will halt.

> Invalid URLs:

If a non-sensical URL is specified, for example “http://anIcon.png”, the program may hang without throwing an error.

2. Limitations on Image Location:

The image-pattern() function in all versions of JavaFX (tested to JavaFX 15) is limited in its ability to navigate to an image through a directory tree.

In other situations, where the url() function is used, developers are free to navigate to resources relative to the location of the CSS file or resources root.

This is not true in the image-pattern() function as far as I am aware. An images specified as “EdenCodingIcon.png” must be located in the root of the project directory above the package directory as below:

Directory
│   pom.xml //I use Maven
└───src
    └───main
        ├───java
        │   │   module-info.java
        │   │   
        │   └───com
        │       └───edencoding
        │               App.java
        │               PrimaryController.java
        │               
        └───resources
            │   EdenCodingIcon.png                             
            │   
            └───com
                └───edencoding
                        primary.fxml
                        styles.css

In testing, attempts to navigate through the directories, as specified in the JavaFX CSS Reference.
For example, specifying “images/EdenCodingIcon.png” with the resource in either of the below positions will result in an error NullPointerException: URL must not be null

Directory
│   pom.xml //I use Maven
└───src
    └───main
        ├───java
        │   │   module-info.java
        │   │   
        │   └   //Java Files as above  
        │               
        └───resources
            ├───com
            │   └───edencoding
            │       │   primary.fxml
            │       │   styles.css
            │       │   
            │       └───images
            │               EdenCodingIcon.png                 
            │               
            └───images
                     EdenCodingIcon.png                        

Have you tested the feature above and got it to work?

Please let me know so I can update this article and better help developers. You will be credited in the corrected entry.

Get in touch

2. Size and Position

The size and position of the tile pattern can be specified using either absolute or proportional units.

Proportional units

In the absence of a proportionality flag, units for Anchor X, Anchor Y, x-Width and y-Width will be interpreted as proportional with respect to the size of the container.

Values should be specified on a scale between 0 and 1, with 1 representing 100% of the corresponding dimension of the container.

-fx-background-color:
        image-pattern("EdenCodingIcon.png", 0, 0, 0.1, 0.1);
-fx-background-color: 
        image-pattern("EdenCodingIcon.png", 0, 0, 0.1, 0.1, true);

Note that exactly 10 tiles are present in both horizontal and vertical directions, because the proportional value of 0.1 was used to specify tile size. The aspect ratio of the parent image is not respected.

Important: Proportionality is interpreted on a scale between 0 and 1. If values in percent are used, this will lead to very large tiles (20% is interpreted as 20 times the size of the parent container. Units are ignored.).

Absolute units

Both the size and position of tile patterns can be specified in absolute units of pixels. Note: In order to specify the size of a tile pattern in absolute units, a proportionality flag must be provided and set to false

-fx-background-color: 
        image-pattern("EdenCodingIcon.png", 10, 10, 32, 32, false);

Important: Because a square parent image was selected, the tile dimensions ‘look’ correct. If absolute units are specified, they will be used as specified with no regard to the aspect ratio of the parent image.

3. Proportionality Flag

In the absence of a proportionality flag, values provided are assumed to be proportional.

Important: It is strongly advised that the final boolean parameter is used. Because the JavaFX CSS Reference specifies that <percentage> units are appropriate, it is tempting to think that units effect the <image-pattern> object generated. Up to JavaFX 15, they do not.

Syntax

/*Image pattern used to color the background of a container 
   In this case, it produces a grid of 10px x 10px EdenCoding icons.
   The tiled pattern will not deform as the container is resized
   as the proportional flag is set to 'false'*/
image-pattern("EdenCodingIcon.png", 0, 0, 10, 10, false);

/*Image pattern used tile the background of a container 
   In this case, it produces a 10 x 10 grid of EdenCoding icons.
   The tiled pattern will deform as the container is resized because
   the proportional flag is set to 'true'*/
image-pattern("EdenCodingIcon.png", 0, 0, 0.1, 0.1, true);

See Also