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.
A basic image-pattern requires that developers define only one parameter
|Image Location||The location of an image file specified as a String. The |
To customise the display of the image pattern, additional parameters can be provided:
|Anchor X||The x-offset of the tile pattern from the left edge of the container|
|Anchor Y||The y-offset of the tile pattern from the top edge of the container|
|Tile width||The width of the tile.|
|Tile height||The height of the tile.|
|Proportionality Flag||Whether 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.
*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.
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.
The only required parameter of the
image-pattern() method is the location of an image, specified as a URI string.
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‘).
> 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.
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
The size and position of the tile pattern can be specified using either absolute or 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.).
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
-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.
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.
/*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);