RFR: 8369836: Update HeaderBar API [v2]

[Andy Goryachev]

On Fri, 17 Oct 2025 02:22:04 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

>> The `HeaderBar` control currently has three areas: `leading`, `center`, and `trailing`. Additionally, there's `leftSystemInset` and `rightSystemInset`, which are not RTL adjusted. I'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.
>> 
>> With this in mind, there are three changes for the `HeaderBar` control:
>> 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`.
>
> Michael Strauß has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Make leftSystemInset/rightSystemInset/minSystemHeight attached properties

modules/javafx.graphics/src/main/java/javafx/scene/layout/HeaderBar.java line 70:

> 68:  * <p>
> 69:  * {@code HeaderBar} is a layout container that allows applications to place scene graph nodes in three areas:
> 70:  * {@link #leftProperty() left}, {@link #centerProperty() center}, and {@link #rightProperty() right}.

perhaps there should be a separate section explaining that the left/right nodes get switched visually in the RTL mode?  And/or mention that "left" really means "leading", and "right" really means "trailing"?

modules/javafx.graphics/src/main/java/javafx/scene/layout/HeaderBar.java line 465:

> 463: 
> 464:     /**
> 465:      * The right area of the {@code HeaderBar}.

please explain RTL behavior, also for "right".

modules/javafx.graphics/src/test/java/test/javafx/scene/layout/HeaderBarTest.java line 187:

> 185:             "BOTTOM_RIGHT, 890, 40, 100, 50"
> 186:         })
> 187:         void alignmentOfRightChildOnly_notResizable(Pos pos, double x, double y, double width, double height) {

FYI, `@CsvSource` also accepts a `textBlock` attribute:


        @ParameterizedTest
        @CsvSource(textBlock = """
            TOP_LEFT, 890, 10, 100, 50
            TOP_CENTER, 890, 10, 100, 50
            TOP_RIGHT, 890, 10, 100, 50
            CENTER_LEFT, 890, 25, 100, 50
            CENTER, 890, 25, 100, 50
            CENTER_RIGHT, 890, 25, 100, 50
            BOTTOM_LEFT, 890, 40, 100, 50
            BOTTOM_CENTER, 890, 40, 100, 50
            BOTTOM_RIGHT, 890, 40, 100, 50
            """
        )

-------------

PR Review Comment: https://git.openjdk.org/jfx/pull/1936#discussion_r2528493574
PR Review Comment: https://git.openjdk.org/jfx/pull/1936#discussion_r2528533628
PR Review Comment: https://git.openjdk.org/jfx/pull/1936#discussion_r2528561154