RFR: 8369836: Update HeaderBar API [v2]

[Alessadro Parisi]

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

>> 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").

@mstr2 are there any plans to look at this:
<img width="908" height="508" alt="IMG_20251204_153610" src="https://github.com/user-attachments/assets/6306c678-38f3-4e8c-bcf1-933536403933" />

On Linux Min 22.2 with Cinnamon I get a rectangular window no matter what. I also tried setting the root's background color and radius, as well as the scene's fill to `TRANSPARENT` but nothing works.

One thing I'm curious about is why it was implemented this way. I mean, if the native decorations are just rendered on top of JavaFX nodes, then why I'm not able to set the scene's fill to `TRANSPARENT` and let the developer handle the rest.

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

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