Summary

Improve the API of HeaderBar (Preview) to incorporate things we've learned in the preview period, making it more consistent with other layout containers and easier to use.

Problem

The HeaderBar control currently has three areas: leading, center, and trailing, which use a different terminology than the closely-related BorderPane. Additionally, there's leftSystemInset and rightSystemInset, which are not RTL-adjusted. We've come to the understanding that there is no particularly good reason for this, because every time you would want to use this information for layout purposes, it should also be adjusted for RTL.

Furthermore, the leftSystemInset, rightSystemInset, and minSystemHeight properties shouldn't be normal properties, but attached properties for Stage. If you think about it, these aren't really properties of HeaderBar, but properties of Stage that are used in the context of HeaderBar.

In addition, HeaderBar allows users to configure its draggable area by marking descendants with HeaderDragType.DRAGGABLE or HeaderDragType.DRAGGABLE_SUBTREE using the HeaderBar.setDragType(Node, HeaderDragType) method. However, sometimes it can be necessary to also configure non-descendants (for example, siblings) to allow draggable-area hit testing to "fall through": consider an application that uses a pane to temporarily cover the entire client area to block user input while some process is runnnig. In this case, it is not desirable to also block the draggable area of the HeaderBar from receiving mouse events, as this would make the window immovable.

Solution

1. Rename leading to left, and trailing to right, which aligns the terminology with BorderPane.
2. Adjust leftSystemInset and rightSystemInset for RTL.
3. Make leftSystemInset, rightSystemInset, and minSystemHeight attached properties for Stage.

With this change, the HeaderBar control is more semantically consistent and easier to use, and the renamed left and right areas now show its close relationship with BorderPane.

To address the problem of blocking the draggable area of the HeaderBar from receiving mouse events, we add two new constants to the HeaderDragType enum:

• TRANSPARENT: excludes a node from draggable-area hit testing
• TRANSPARENT_SUBTREE: the same, but also applies to the subtree of the node

Consider again a pane that covers the entire client area to temporarily block user input. If HeaderDragType.TRANSPARENT is set on that pane, it will not prevent users from interacting with the draggable area of the HeaderBar below.

Specification

HeaderBar:

--- a/javafx/scene/layout/HeaderBar.java
+++ b/javafx/scene/layout/HeaderBar.java

@@ class HeaderBar @@
  * <em>double-click to maximize</em> behaviors that are usually afforded by system-provided header bars.
  * The entire {@code HeaderBar} background is draggable by default, but its content is not. Applications
- * can specify draggable content nodes of the {@code HeaderBar} with the {@link #setDragType(Node, HeaderDragType)}
- * method.
+ * can specify draggable content nodes of the {@code HeaderBar} with the {@link #dragTypeProperty(Node) dragType}
+ * property.
  * <p>
  * {@code HeaderBar} is a layout container that allows applications to place scene graph nodes in three areas:
- * {@link #leadingProperty() leading}, {@link #centerProperty() center}, and {@link #trailingProperty() trailing}.
+ * {@link #leftProperty() left}, {@link #centerProperty() center}, and {@link #rightProperty() right}.
  * All areas can be {@code null}. The default {@link #minHeightProperty() minHeight} of the {@code HeaderBar} is
  * set to match the height of the platform-specific default header buttons.
  *
  * <h2>Single header bar</h2>
  * Most applications should only add a single {@code HeaderBar} to the scene graph, placed at the top of the
  * scene and extending its entire width. This ensures that the reported values for
- * {@link #leftSystemInsetProperty() leftSystemInset} and {@link #rightSystemInsetProperty() rightSystemInset},
+ * {@link #leftSystemInsetProperty(Stage) leftSystemInset} and {@link #rightSystemInsetProperty(Stage) rightSystemInset},
  * which describe the area reserved for the system-provided window buttons, correctly align with the location
  * of the {@code HeaderBar} and are taken into account when the contents of the {@code HeaderBar} are laid out.
  *
  * <h2>Multiple header bars</h2>
  * Applications that use multiple header bars might need to configure the additional padding inserted into the
  * layout to account for the system-reserved areas. For example, when two header bars are placed next to each
  * other in the horizontal direction, the default configuration incorrectly adds additional padding between the
- * two header bars. In this case, the {@link #leadingSystemPaddingProperty() leadingSystemPadding} and
- * {@link #trailingSystemPaddingProperty() trailingSystemPadding} properties can be used to remove the padding
+ * two header bars. In this case, the {@link #leftSystemPaddingProperty() leftSystemPadding} and
+ * {@link #rightSystemPaddingProperty() rightSystemPadding} properties can be used to remove the padding
  * that is not needed.
  *
  * <h2>Header button height</h2>
- * Applications can specify the preferred height for system-provided header buttons by setting the static
- * {@link #setPrefButtonHeight(Stage, double)} property on the {@code Stage} associated with the header bar.
-  * This can be used to achieve a more cohesive visual appearance by having the system-provided header buttons
-  * match the height of the client-area header bar.
+ * Applications can specify the preferred height for system-provided header buttons by setting the
+ * {@link #prefButtonHeightProperty(Stage) prefButtonHeight} property on the {@code Stage} associated with
+ * the header bar. This can be used to achieve a more cohesive visual appearance by having the system-provided
+ * header buttons match the height of the client-area header bar.
  *
+ * <h2>Color scheme</h2>
+ * The color scheme of the default header buttons is automatically adjusted to remain easily recognizable
+ * by inspecting the {@link Scene#fillProperty() Scene.fill} property to gauge the brightness of the user
+ * interface. Applications should set the scene fill to a color that matches the user interface of the header
+ * bar area, even if the scene fill is not visible because it is obscured by other controls.
+ *
  * <h2>Custom header buttons</h2>
  * If more control over the header buttons is desired, applications can opt out of the system-provided header
- * buttons by setting {@link #setPrefButtonHeight(Stage, double)} to zero and place custom header buttons in
- * the JavaFX scene graph instead. Any JavaFX control can be used as a custom header button by setting its
- * semantic type with the {@link #setButtonType(Node, HeaderButtonType)} method.
+ * buttons by setting the {@link #prefButtonHeightProperty(Stage) prefButtonHeight} property on the {@code Stage}
+ * associated with the header bar to zero and place custom header buttons in the JavaFX scene graph instead.
+ * Any JavaFX control can be used as a custom header button by specifying its semantic type with the
+ * {@link #buttonTypeProperty(Node) buttonType} property.
  *
  * <h2>System menu</h2>
  * Some platforms support a system menu that can be summoned by right-clicking the draggable area.
  * The system menu will not be shown when:
  * <ol>
  *     <li>the {@code Stage} is in {@link Stage#fullScreenProperty() full-screen mode}, or
  *     <li>the {@code HeaderBar} has {@link Event#consume() consumed} the
  *         {@link ContextMenuEvent#CONTEXT_MENU_REQUESTED} event.
  * </ol>
  *
  * <h2>Layout constraints</h2>
- * The {@code leading} and {@code trailing} children will be resized to their preferred widths and extend the
+ * The {@code left} and {@code right} children will be resized to their preferred widths and extend the
  * height of the {@code HeaderBar}. The {@code center} child will be resized to fill the available space.
  * {@code HeaderBar} honors the minimum, preferred, and maximum sizes of its children. If a child's resizable


@@ property dragType @@
     /**
-     * Specifies the {@code HeaderDragType} of the child, indicating whether it is a draggable
-     * part of the {@code HeaderBar}.
-     * <p>
-     * Setting the value to {@code null} will remove the flag.
+     * Sets the value of the {@link #dragTypeProperty(Node) dragType} property for the specified child.
      *
      * @param child the child node
      * @param value the {@code HeaderDragType}, or {@code null} to remove the flag
      */
     public static void setDragType(Node child, HeaderDragType value);
...
     /**
-     * Returns the {@code HeaderDragType} of the specified child.
+     * Gets the value of the {@link #dragTypeProperty(Node) dragType} property of the specified child.
      *
      * @param child the child node
      * @return the {@code HeaderDragType}, or {@code null} if not set
      */
     public static HeaderDragType getDragType(Node child);
...
+    /**
+     * Specifies the {@code HeaderDragType} of the child, indicating whether it is a draggable part
+     * of the {@code HeaderBar}. A value of {@code null} indicates that the drag type is not set.
+     *
+     * @param child the child node
+     * @return the {@code dragType} property
+     * @defaultValue {@code null}
+     * @since 26
+     */
+    public static ObjectProperty<HeaderDragType> dragTypeProperty(Node child);


@@ property buttonType @@
     /**     
-     * Specifies the {@code HeaderButtonType} of the child, indicating its semantic use in the header bar.
-     * <p>
-     * This property can be set on any {@link Node}. Specifying a header button type also provides the behavior
-     * associated with the button type. If the default behavior is not desired, applications can register an
-     * event filter on the child node that consumes the {@link MouseEvent#MOUSE_RELEASED} event.
+     * Sets the value of the {@link #buttonTypeProperty(Node) buttonType} property for the specified child.
      *
      * @param child the child node
      * @param value the {@code HeaderButtonType}, or {@code null}
      */
     public static void setButtonType(Node child, HeaderButtonType value);
...
     /**
-      * Returns the {@code HeaderButtonType} of the specified child.
+     * Gets the value of the {@link #buttonTypeProperty(Node) buttonType} property of the specified child.
      *
      * @param child the child node
      * @return the {@code HeaderButtonType}, or {@code null}
      */
     public static HeaderButtonType getButtonType(Node child);
...
+    /**
+     * Specifies the {@code HeaderButtonType} of the child, indicating its semantic use in the header bar.
+     * <p>
+     * This property can be set on any {@link Node}. Specifying a header button type also provides the behavior
+     * associated with the button type. If the default behavior is not desired, applications can register an
+     * event filter on the child node that consumes the {@link MouseEvent#MOUSE_RELEASED} event.
+     *
+     * @param child the child node
+     * @return the {@code buttonType} property
+     * @defaultValue {@code null}
+     * @since 26
+     */
+    public static ObjectProperty<HeaderButtonType> buttonTypeProperty(Node child);


@@ field USE_DEFAULT_SIZE @@
     /**
-     * Sentinel value that can be used for {@link #setPrefButtonHeight(Stage, double)} to indicate that
-     * the platform should choose the platform-specific default button height.
+     * Sentinel value that can be used for the {@link #prefButtonHeightProperty(Stage) prefButtonHeight}
+     * property to indicate that the platform should choose the platform-specific default button height.
      */
     public static final double USE_DEFAULT_SIZE = -1;


@@ property prefButtonHeight @@
     /**
-     * Specifies the preferred height of the system-provided header buttons of the specified stage.
-     * <p>
-     * Any value except zero and {@link #USE_DEFAULT_SIZE} is only a hint for the platform window toolkit.
-     * The platform might accommodate the preferred height in various ways, such as by stretching the header
-     * buttons (fully or partially) to fill the preferred height, or centering the header buttons (fully or
-     * partially) within the preferred height. Some platforms might only accommodate the preferred height
-     * within platform-specific constraints, or ignore it entirely.
-     * <p>
-     * Setting the preferred height to zero hides the system-provided header buttons, allowing applications to
-     * use custom header buttons instead (see {@link #setButtonType(Node, HeaderButtonType)}).
-     * <p>
-     * The default value {@code USE_DEFAULT_SIZE} indicates that the platform should choose the button height.
+     * Sets the value of the {@link #prefButtonHeightProperty(Stage) prefButtonHeight} property
+     * for the specified {@code Stage}.
      *
      * @param stage the {@code Stage}
      * @param height the preferred height, or 0 to hide the system-provided header buttons
      */
     public static void setPrefButtonHeight(Stage stage, double height);
...
     /**
-     * Returns the preferred height of the system-provided header buttons of the specified stage.
+     * Gets the value of the {@link #prefButtonHeightProperty(Stage) prefButtonHeight} property
+     * of the specified {@code Stage}.
      *
      * @param stage the {@code Stage}
      * @return the preferred height of the system-provided header buttons
      */
     public static double getPrefButtonHeight(Stage stage);
...
+    /**
+     * Specifies the preferred height of the system-provided header buttons of the specified {@code Stage}.
+     * <p>
+     * Any value except zero and {@link #USE_DEFAULT_SIZE} is only a hint for the platform window toolkit.
+     * The platform might accommodate the preferred height in various ways, such as by stretching the header
+     * buttons (fully or partially) to fill the preferred height, or centering the header buttons (fully or
+     * partially) within the preferred height. Some platforms might only accommodate the preferred height
+     * within platform-specific constraints, or ignore it entirely.
+     * <p>
+     * Setting the preferred height to zero hides the system-provided header buttons, allowing applications to
+     * use custom header buttons instead (see {@link #setButtonType(Node, HeaderButtonType)}).
+     * <p>
+     * The default value {@code USE_DEFAULT_SIZE} indicates that the platform should choose the button height.
+     *
+     * @param stage the {@code Stage}
+     * @return the {@code prefButtonHeight} property
+     * @defaultValue {@code USE_DEFAULT_SIZE}
+     * @since 26
+     */
+    public static DoubleProperty prefButtonHeightProperty(Stage stage);


@@ property leftSystemInset @@
-    /**
-     * Describes the size of the left system-reserved inset, which is an area reserved for the iconify, maximize,
-     * and close window buttons. If there are no window buttons on the left side of the window, the returned area
-     * is an empty {@code Dimension2D}.
-     * <p>
-     * Note that the left system inset refers to the left side of the window, independent of layout orientation.
-     */
-    private final ReadOnlyObjectWrapper<Dimension2D> leftSystemInset;
...
-    public final ReadOnlyObjectProperty<Dimension2D> leftSystemInsetProperty();
...
-    public final Dimension2D getLeftSystemInset();
...
+    /**
+     * Describes the size of the left system-reserved inset of the specified {@code Stage}, which is an area
+     * reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the left
+     * side of the window, the returned area is an empty {@code Dimension2D}.
+     *
+     * @param stage the {@code Stage}
+     * @return the {@code leftSystemInset} property
+     * @since 26
+     */
+    public static ReadOnlyObjectProperty<Dimension2D> leftSystemInsetProperty(Stage stage);
...
+    /**
+     * Gets the value of the {@link #leftSystemInsetProperty(Stage) leftSystemInset} property
+     * of the specified {@code Stage}.
+     *
+     * @param stage the {@code Stage}
+     * @return the size of the left system-reserved inset
+     * @since 26
+     */
+    public static Dimension2D getLeftSystemInset(Stage stage);


@@ property rightSystemInset @@
-    /**
-     * Describes the size of the right system-reserved inset, which is an area reserved for the iconify, maximize,
-     * and close window buttons. If there are no window buttons on the right side of the window, the returned area
-     * is an empty {@code Dimension2D}.
-     * <p>
-     * Note that the right system inset refers to the right side of the window, independent of layout orientation.
-     */
-    private final ReadOnlyObjectWrapper<Dimension2D> rightSystemInset;
...
-    public final ReadOnlyObjectProperty<Dimension2D> rightSystemInsetProperty();
...
-    public final Dimension2D getRightSystemInset();
...
+    /**
+     * Describes the size of the right system-reserved inset of the specified {@code Stage}, which is an area
+     * reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the right
+     * side of the window, the returned area is an empty {@code Dimension2D}.
+     *
+     * @param stage the {@code Stage}
+     * @return the {@code rightSystemInset} property
+     * @since 26
+     */
+    public static ReadOnlyObjectProperty<Dimension2D> rightSystemInsetProperty(Stage stage);
...
+    /**
+     * Gets the value of the {@link #rightSystemInsetProperty(Stage) rightSystemInset} property
+     * of the specified {@code Stage}.
+     *
+     * @param stage the {@code Stage}
+     * @return the size of the right system-reserved inset
+     * @since 26
+     */
+    public static Dimension2D getRightSystemInset(Stage stage);


@@ property minSystemHeight @@
-    /**
-     * The system-provided minimum recommended height for the {@code HeaderBar}, which usually corresponds
-     * to the height of the default header buttons. Applications can use this value as a sensible lower limit
-     * for the height of the {@code HeaderBar}.
-     * <p>
-     * By default, {@link #minHeightProperty() minHeight} is set to the value of {@code minSystemHeight},
-     * unless {@code minHeight} is explicitly set by a stylesheet or application code.
-     */
-    private final ReadOnlyDoubleWrapper minSystemHeight;
...
-    public final ReadOnlyDoubleProperty minSystemHeightProperty();
...
-    public final double getMinSystemHeight();
...
+    /**
+     * The system-provided minimum recommended height for the {@code HeaderBar} of the specified {@code Stage},
+     * which usually corresponds to the height of the default header buttons. Applications can use this value
+     * as a sensible lower limit for the height of the {@code HeaderBar}.
+     * <p>
+     * By default, {@code HeaderBar}.{@link #minHeightProperty() minHeight} is set to the value of
+     * {@code minSystemHeight}, unless {@code minHeight} is explicitly set by a stylesheet or application code.
+     *
+     * @param stage the {@code Stage}
+     * @return the {@code minSystemHeight} property
+     * @since 26
+     */
+    public static ReadOnlyDoubleProperty minSystemHeightProperty(Stage stage);
...
+    /**
+     * Gets the value of the {@link #minSystemHeightProperty(Stage) minSystemHeight} property
+     * of the specified {@code Stage}.
+     *
+     * @param stage the {@code Stage}
+     * @return the system-provided minimum recommended height for the {@code HeaderBar}
+     * @since 26
+     */
+    public static double getMinSystemHeight(Stage stage);

@@ property leading => left @@
     /**
-     * The leading area of the {@code HeaderBar}.
-     * <p>
-     * The leading area corresponds to the left area in a left-to-right layout, and to the right area
-     * in a right-to-left layout.
+     * The left area of the {@code HeaderBar}.
      *
      * @defaultValue {@code null}
+     * @since 26
      */
-    private final ObjectProperty<Node> leading;
+    private final ObjectProperty<Node> left;
...
-    public final ObjectProperty<Node> leadingProperty();
+    public final ObjectProperty<Node> leftProperty();
...
-    public final Node getLeading();
+    public final Node getLeft();
...
-    public final void setLeading(Node value);
+    public final void setLeft(Node value);


@@ property trailing => right @@
     /**
-     * The trailing area of the {@code HeaderBar}.
-     * <p>
-     * The trailing area corresponds to the right area in a left-to-right layout, and to the left area
-     * in a right-to-left layout.
+     * The right area of the {@code HeaderBar}.
      *
      * @defaultValue {@code null}
+     * @since 26
      */
-     private final ObjectProperty<Node> trailing;
+     private final ObjectProperty<Node> right;
...
-    public final ObjectProperty<Node> trailingProperty();
+    public final ObjectProperty<Node> rightProperty();
...
-    public final Node getTrailing();
+    public final Node getRight();
...
-    public final void setTrailing(Node value);
+    public final void setRight(Node value);


@@ property leadingSystemPadding => leftSystemPadding @@
     /**
-     * Specifies whether additional padding should be added to the leading side of the {@code HeaderBar}.
+     * Specifies whether additional padding should be added to the left side of the {@code HeaderBar}.
      * The size of the additional padding corresponds to the size of the system-reserved area that contains
      * the default header buttons (iconify, maximize, and close). If the system-reserved area contains no
-     * header buttons, no additional padding is added to the leading side of the {@code HeaderBar}.
+     * header buttons, no additional padding is added to the left side of the {@code HeaderBar}.
      * <p>
      * Applications that use a single {@code HeaderBar} extending the entire width of the window should
      * set this property to {@code true} to prevent the header buttons from overlapping the content of the
      * {@code HeaderBar}.
      *
      * @defaultValue {@code true}
-     * @see #trailingSystemPaddingProperty() trailingSystemPadding
+     * @see #rightSystemPaddingProperty() rightSystemPadding
+     * @since 26
      */
-    private final BooleanProperty leadingSystemPadding;
+    private final BooleanProperty leftSystemPadding;
...
-    public final BooleanProperty leadingSystemPaddingProperty();
+    public final BooleanProperty leftSystemPaddingProperty();
...
-    public final boolean isLeadingSystemPadding();
+    public final boolean isLeftSystemPadding();
...
-    public final void setLeadingSystemPadding(boolean value);
+    public final void setLeftSystemPadding(boolean value);


@@ property trailingSystemPadding => rightSystemPadding @@
     /**
-     * Specifies whether additional padding should be added to the trailing side of the {@code HeaderBar}.
+     * Specifies whether additional padding should be added to the right side of the {@code HeaderBar}.
      * The size of the additional padding corresponds to the size of the system-reserved area that contains
      * the default header buttons (iconify, maximize, and close). If the system-reserved area contains no
-     * header buttons, no additional padding is added to the trailing side of the {@code HeaderBar}.
+     * header buttons, no additional padding is added to the right side of the {@code HeaderBar}.
      * <p>
      * Applications that use a single {@code HeaderBar} extending the entire width of the window should
      * set this property to {@code true} to prevent the header buttons from overlapping the content of the
      * {@code HeaderBar}.
      *
      * @defaultValue {@code true}
-     * @see #leadingSystemPaddingProperty() leadingSystemPadding
+     * @see #leftSystemPaddingProperty() leftSystemPadding
+     * @since 26
      */
-    private final BooleanProperty trailingSystemPadding;
+    private final BooleanProperty rightSystemPadding;
...
-    public final BooleanProperty trailingSystemPaddingProperty();
+    public final BooleanProperty rightSystemPaddingProperty();
...
-    public final boolean isTrailingSystemPadding();
+    public final boolean isRightSystemPadding();
...
-    public final void setTrailingSystemPadding(boolean value);
+    public final void setRightSystemPadding(boolean value);

HeaderDragType:

--- a/modules/javafx.graphics/src/main/java/javafx/scene/layout/HeaderDragType.java
+++ b/modules/javafx.graphics/src/main/java/javafx/scene/layout/HeaderDragType.java
@@ -38,10 +38,11 @@
 public enum HeaderDragType {
 
     /**
-     * The node is not a draggable part of the {@code HeaderBar}.
+     * The node is not a draggable part of the {@code HeaderBar}, and not transparent in regard to
+     * draggable-area hit testing.
      * <p>
-     * If the node inherits {@link #DRAGGABLE_SUBTREE} from its parent, the inheritance stops and
-     * descendants of the node will not inherit {@code DRAGGABLE_SUBTREE}.
+     * If the node inherits {@link #DRAGGABLE_SUBTREE} or {@link #TRANSPARENT_SUBTREE} from its parent,
+     * the inheritance stops and descendants of the node will not inherit either drag type.
      */
     NONE,
 
@@ -48,8 +49,12 @@
     /**
      * The node is a draggable part of the {@code HeaderBar}.
      * <p>
-     * This drag type does not apply to descendants of the node. However, it does not stop an inherited
-     * {@link #DRAGGABLE_SUBTREE} drag type from being inherited by descendants of the node.
+     * This drag type is only relevant for nodes that are descendants of the header bar. When set on a node,
+     * the node participates in draggable-area hit testing. If the node extends beyond the header bar, the
+     * effective draggable area is extended accordingly.
+     * <p>
+     * This drag type does not apply to descendants of the node on which it is set. However, it does not stop
+     * an inherited {@link #DRAGGABLE_SUBTREE} drag type from being inherited by descendants of the node.
      */
     DRAGGABLE,
 
@@ -56,8 +61,51 @@
     /**
      * The node and its descendants are a draggable part of the {@code HeaderBar}.
      * <p>
+     * This drag type is only relevant for nodes that are descendants of the header bar. When set on a node,
+     * the node and its descendants participate in draggable-area hit testing. If the node or its descendants
+     * extend beyond the header bar, the effective draggable area is extended accordingly.
+     * <p>
+     * This drag type is inherited by descendants of the node until a descendant specifies {@link #NONE}.
+     */
+    DRAGGABLE_SUBTREE,
+
+    /**
+     * The node is transparent in regard to draggable-area hit testing.
+     * <p>
+     * In contrast to {@link #DRAGGABLE}, which positively identifies a node as a draggable part of the
+     * {@code HeaderBar}, this option excludes a node from draggable-area hit testing: the header bar
+     * behaves as if the node was not present and continues hit testing unimpeded.
+     * <p>
+     * This drag type can be used not only on descendants of the header bar, but also on other nodes that
+     * may overlap it (for example, a sibling shown on top of the header bar). In that case, the overlapping
+     * node behaves as if it were draggable, but only where it overlaps a draggable area of the header bar;
+     * it does not create any additional draggable area.
+     * <p>
+     * This drag type does not apply to descendants of the node on which it is set. However, it does
+     * not stop an inherited {@link #TRANSPARENT_SUBTREE} drag type from being inherited by descendants
+     * of the node.
+     *
+     * @since 26
+     */
+    TRANSPARENT,
+
+    /**
+     * The node and its descendants are transparent in regard to draggable-area hit testing.
+     * <p>
+     * In contrast to {@link #DRAGGABLE_SUBTREE}, which positively identifies a node and its descendants
+     * as a draggable part of the {@code HeaderBar}, this option excludes a node and its descendants from
+     * draggable-area hit testing: the header bar behaves as if the node and its descendants were not
+     * present and continues hit testing unimpeded.
+     * <p>
+     * This drag type can be used not only on descendants of the header bar, but also on other nodes that
+     * may overlap it (for example, a sibling shown on top of the header bar). In that case, the overlapping
+     * node and its descendants behave as if they were draggable, but only where they overlap a draggable
+     * area of the header bar; they do not create any additional draggable area.
+     * <p>
      * This drag type is inherited by descendants of the node until a descendant specifies {@link #NONE}.
+     *
+     * @since 26
      */
-    DRAGGABLE_SUBTREE
+    TRANSPARENT_SUBTREE
 }