RFR: 8369836: Update HeaderBar API [v5]

[Kevin Rushforth]

On Wed, 10 Dec 2025 17:27:25 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:
> 
>   stage doc

I left a few inline comments. If you want to try to get this into 26, I recommend removing the global doc changes to `package-info.java` and filing a follow-up bug.

Then create a CSR with the current docs and "Propose" it to get it looked at. Since this is an incompatible change, make it clear in the CSR that this is a preview feature so incompatible changes are OK.

modules/javafx.graphics/src/main/java/javafx/stage/Stage.java line 100:

> 98:  * <li>{@link StageStyle#UTILITY} - a stage with a solid white background and
> 99:  * minimal platform decorations.</li>
> 100:  * <li>{@link StageStyle#EXTENDED} - a decorated stage with a custom {@link HeaderBar}.</li>

Do you think it would be helpful to indicate that this is a Preview Feature? Maybe by adding a parenthetical `(Preview Features)` somewhere?

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

PR Review: https://git.openjdk.org/jfx/pull/1936#pullrequestreview-3609547580
PR Review Comment: https://git.openjdk.org/jfx/pull/1936#discussion_r2644440914