RFR: 8369836: Update HeaderBar API [v2]

[Michael Strauß]

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

There's another thing that I think will improve the `HeaderBar`API:

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`.

We already have an attached property of this kind: `HeaderBar.getPrefButtonHeight(Stage)`. Having the other three properties defined similarly makes the API more consistent.

It should be noted that this will be the first instance of an _observable_ attached property in JavaFX. So while regular attached properties have a getter/setter pair like this...

class HBox {
    static Insets getMargin(Node);
    static void setMargin(Node, Insets);
}


...an observable attached property will have an observable property getter:

class HeaderBar {
    static ReadOnlyObjectProperty<Dimension2D> leftSystemInsetProperty(Stage);
    static Dimension2D getLeftSystemInset(Stage);
}


The form of the property getter shouldn't be controversial, as it follows the existing getter/setter form for attached properties.

What needs to be clarified, however, is what `getBean()` and `getName()` should return for an attached observable property.
Since an attached property is a part of the object it is attached to, the `getBean()` method should return that object. In our example, this means `HeaderBar.leftSystemInsetProperty(myStage).getBean() == myStage`.

For the `getName()` method, the usual convention is to return the lowerCamelCase name of the property. However, since an attached property is not declared on the object's class to which it is attached, the name shouldn't claim that it is. I propose a naming convention of the form `DeclaringType.myProperty`, that is, the property name is qualified with the declaring type. In our example, the name of the property would be "HeaderBar.leftSystemInset" (instead of just "leftSystemInset").

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

PR Comment: https://git.openjdk.org/jfx/pull/1936#issuecomment-3413572928