FXML <opaqueInsets> tag

Question

I'm experimenting with FXML layouts to get an understanding of how to layout nodes with margins, borders and paddings. Using SceneBuilder I've created a dummy FXML layout:

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.geometry.Insets?>
<?import javafx.scene.layout.AnchorPane?>
<?import javafx.scene.layout.HBox?>


<HBox maxHeight="-Infinity" maxWidth="-Infinity" minHeight="-Infinity" minWidth="-Infinity" prefHeight="400.0" prefWidth="600.0" xmlns="http://javafx.com/javafx/8.0.111" xmlns:fx="http://javafx.com/fxml/1">
   <children>
      <AnchorPane prefWidth="180.0" style="-fx-border-width: 5; -fx-border-color: blue;">
         <HBox.margin>
            <Insets bottom="2.0" left="2.0" right="2.0" top="2.0" />
         </HBox.margin>
         <children>
            <AnchorPane layoutY="8.0" style="-fx-background-color: orange;" AnchorPane.bottomAnchor="0.0" AnchorPane.leftAnchor="0.0" AnchorPane.rightAnchor="0.0" AnchorPane.topAnchor="0.0" />
         </children>
         <padding>
            <Insets bottom="5.0" left="5.0" right="5.0" top="5.0" />
         </padding>
         <opaqueInsets>
            <Insets bottom="20.0" left="20.0" right="20.0" top="20.0" />
         </opaqueInsets>
      </AnchorPane>
      <AnchorPane prefHeight="200.0" prefWidth="200.0" style="-fx-border-color: red; -fx-border-width: 10;" />
      <AnchorPane prefHeight="200.0" prefWidth="200.0" style="-fx-border-color: gold; -fx-border-width: 15;">
         <children>
            <AnchorPane layoutX="-14.0" layoutY="100.0" />
         </children>
      </AnchorPane>
   </children>
</HBox>

However in SceneBuilder there are 'Opaque Insets' value boxes:

And I have added them in the above FXML.

But what are they for? They appear to have no effect on the visual appearance of the layout and I do not find any reference to them in Introduction to FXML. Are they perhaps a 'left-over' from FXML 1.0?

Answer 1

The opaqueInsets property is defined in Region. Quoting directly from the documentation:

Defines the area of the region within which completely opaque pixels are drawn. This is used for various performance optimizations. The pixels within this area MUST BE fully opaque, or rendering artifacts will result. It is the responsibility of the application, either via code or via CSS, to ensure that the opaqueInsets is correct for a Region based on the backgrounds and borders of that region. The values for each of the insets must be real numbers, not NaN or Infinity. If no known insets exist, then the opaqueInsets should be set to null.

The way I read this is that you can define opaqueInsets on a Region in order to give a rendering hint that the area within those insets is entirely opaque. This is provided as a performance hint - presumably the idea is that the renderer can ignore any nodes with lower z-order within that region.