RFR: 8369836: Update HeaderBar API [v3]

[Kevin Rushforth]

On Mon, 17 Nov 2025 20:05:00 GMT, Andy Goryachev <angorya at openjdk.org> wrote:

>> Michael Strauß has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains four additional commits since the last revision:
>> 
>>  - documentation
>>  - Merge branch 'master' into headerbar-update
>>  - Make leftSystemInset/rightSystemInset/minSystemHeight attached properties
>>  - Update HeaderBar API
>
> modules/javafx.graphics/src/main/java/javafx/scene/layout/package-info.java line 208:
> 
>> 206:  * <p>
>> 207:  * For layout containers, the layout orientation determines the visual order of their children. If a layout container
>> 208:  * has named areas, the names always retain their default meaning. For example, the {@code left} and {@code right}
> 
> It might be just me, but I still find this explanation very confusing (what is the default meaning of left?).
> 
> Could we just say that for historical reasons, "left" and "right" in reality mean "leading" and "trailing", or maybe that in the RTL mode the left/right are swapped, with the "left" nodes appearing on the leading (visually right) side, and the "right" ones are on the trailing (visually left) side?
> 
> Also, do you think we should explicitly mention entities where this logic applies  (`BorderPane`, `HeaderBar`)?

I'll take a look at this as well.

One thing I do note is that it might be helpful if this doc clarification had a separate doc issue to track it -- even if it goes in as part of this PR -- since it is independent from what is otherwise a preview feature.

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

PR Review Comment: https://git.openjdk.org/jfx/pull/1936#discussion_r2535876092