On Fri, 17 Oct 2025 02:22:04 GMT, Michael Strauß <[email protected]> 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
