RFR: 8369836: Update HeaderBar API [v2]

[Thiago Milczarek Sayao]

On Thu, 4 Dec 2025 14:40:43 GMT, Alessadro Parisi <duke at openjdk.org> wrote:

>> 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.
> 
> Edit: btw this is quite the issue because I can't achieve a consistent look across the various systems. The only solution is to use a `TRANSPARENT` Stage and make my own window buttons, losing a ton of features though (resize, drag, snap assistants, etc.)

@palexdev 
In the case of linux, the decorations are a JavaFX overlay, the window manager (at least mutter) will not draw over the window.

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

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