JEP: JavaFX controls in the title bar

[Kevin Rushforth]

On 10/23/2024 8:00 AM, Michael Strauß wrote:
>> I presume that the preferred width and height of HeaderBarBase is the
>> width of the window and the height of the system-reserved area for
>> window buttons?
> HeaderBarBase is a resizable `Region`, and as such has no preferred
> width or height. It is an abstract base class that is only intended to
> provide very basic functionality.
> HeaderBar is only realistically useful when contained in another root
> container, since otherwise your application won't have a useful client
> area where child nodes can be placed. The root container then
> determines the size and location of the HeaderBar.

Let's consider the typical case of a root container that is either a 
BorderPane or a VBox, with a HeaderBar in the top portion of the 
BorderPane or as the first (top) child of the VBox. In that case, the 
root container will size the HeaderBar to its preferred height. If there 
are no children of the HeaderBar, will its preferred height then be the 
height of the system-reserved area for window buttons?

>> What is the behavior if an application adds more than one HeaderBar?
>> What if they add a HeaderBar that isn't positioned at the top of the
>> Stage? What is the behavior if an app adds a HeaderBar to a DECORATED or
>> UNDECORATED Stage?
> More than one HeaderBar:
> The window will have two header bars, both working basically as one
> would expect.

How do you figure out which one gets the system-reserved area, and thus 
the window buttons? The one whose "y" value is lowest (i.e., the 
top-most one)? The first one encountered in scene graph traversal order 
(typically, but not necessarily, the same)? Something else?

> HeaderBar not at top:
> The header bar will work as expected. However, the
> leftSystemInset/rightSystemInset will (perhaps unexpectedly) still
> contain the dimensions of the system-reserved window button area at
> the top of the window. The meaning of those properties is not "the
> size of the area that is geometrically obscured by window buttons on
> this concrete HeaderBar, given its non-standard placement", but it's
> literally just the size of the system insets on the window.

That's sort of what I guessed. I think it might be a good idea to add an 
API note suggesting that an application have only one HeaderBar 
positioned at the top of the Scene.

> HeaderBar in DECORATED/UNDECORATED stage:
> The header bar will still be a regular layout container, and the user
> interface will still appear as expected. However, leftSystemInset and
> rightSystemInset will both be empty. Dragging and double-click to
> maximize will not work.
> This essentially means that an EXTENDED stage with HeaderBar can
> gracefully downgrade to DECORATED without exhibiting weird behaviors.

Good.

>> I want to make sure I understand the centering policy: To my eyes, the
>> text field in the macOS example is not horizontally centered in the
>> window. Is this a bug or am I misunderstanding something?
> Yes, it's not centered because there's not enough available space in
> the header bar, given the minimum size of the text field.
> HeaderBar will try to keep it centered, but only while it can still
> honor its minimum size; after that, the content will be shifted.
> It is a bit difficult to easily describe the behavior, but it's
> obvious when you see it working.

It might be a good idea to make the standard examples that you include 
in the docs show the case where it isn't over-constrained, and then 
maybe have an example where it is.


>> As Andy already mentioned in the PR, the `EXTENDED` StageStyle should be
>> a ConditionalFeature, similar to TRANSPARENT or UNIFIED. Oh, I see from
>> the PR that you already did this. Can you update the JEP to indicate this?
> Done. I've also added that the system insets will be empty when
> HeaderBar is used with a stage style other than `EXTENDED`.

Perfect.

>> And speaking of UNIFIED, it might be worth mentioning the differences
>> between EXTENDED and UNIFIED. Somewhat related to this, we have talked
>> about deprecating (not for removal) UNIFIED and always returning `false`
>> from `ConditionalFeature.isSupported(UNIFIED_WINDOW)`.
> UNIFIED doesn't seem to be usefully working on any platform, does it?
> It might be hard to explain the difference to a feature that doesn't
> really work. I'll think about it.

Maybe it isn't worth saying anything then. Especially in light of the 
possible deprecation of UNIFIED.

-- Kevin